Building a Videoconference App

// All settings come from the environment so the same image runs locally and in production.
const env = process.env;

export const config = {
  port: Number(env.HTTP_PORT ?? 3000),
  rtcPort: Number(env.RTC_PORT ?? 40000),
  // The address browsers must use to reach mediasoup (the host's LAN or public IP, not the container's).
  announcedAddress: env.ANNOUNCED_ADDRESS ?? '127.0.0.1',
  allowedOrigins: (env.ALLOWED_ORIGINS ?? 'http://localhost:3000').split(','),
  ticketSecret: env.HUDDLE_TICKET_SECRET ?? 'change-me-ticket-secret',
  turn: {
    host: env.TURN_HOST ?? '127.0.0.1',
    port: Number(env.TURN_PORT ?? 3478),
    secret: env.TURN_SHARED_SECRET ?? 'example-shared-secret-change-me',
    ttlSeconds: Number(env.TURN_TTL_SECONDS ?? 3600),
  },
  // Which backends this process serves: mesh needs nothing, sfu starts a mediasoup worker, livekit talks to a LiveKit server.
  modes: (env.HUDDLE_MODES ?? 'mesh,sfu').split(','),
  livekit: {
    url: env.LIVEKIT_URL ?? 'http://localhost:7880', // used by this server (REST and Egress)
    publicUrl: env.LIVEKIT_PUBLIC_URL ?? 'ws://localhost:7880', // used by browsers
    apiKey: env.LIVEKIT_API_KEY ?? 'huddle-dev-key',
    apiSecret: env.LIVEKIT_API_SECRET ?? 'change-me-change-me-change-me-32chars',
  },
  maxMeshRoom: 4,
  recordingsDir: env.RECORDINGS_DIR ?? './recordings',
};

// Short-lived, single-use WebSocket tickets and HMAC-signed upload tokens.
import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
import { config } from './config.mjs';

const TICKET_TTL_MS = 30_000;
const used = new Map(); // nonce -> expiry, so that a ticket works exactly once

const sign = (body) => createHmac('sha256', config.ticketSecret).update(body).digest('base64url');

function verify(parts, mac) {
  const expected = Buffer.from(sign(parts));
  const given = Buffer.from(mac);
  return given.length === expected.length && timingSafeEqual(given, expected);
}

/** Called by an authenticated HTTP endpoint; `user` comes from your login session. */
export function issueTicket(user) {
  const body = `${user}.${Date.now() + TICKET_TTL_MS}.${randomBytes(8).toString('hex')}`;
  return `${body}.${sign(body)}`;
}

/** Returns the user name, or null for a malformed, forged, expired or replayed ticket. */
export function redeemTicket(ticket) {
  const parts = String(ticket ?? '').split('.');
  if (parts.length !== 4) return null;
  const [user, expires, nonce, mac] = parts;
  if (!verify(`${user}.${expires}.${nonce}`, mac)) return null;
  const now = Date.now();
  for (const [n, exp] of used) if (exp < now) used.delete(n);
  if (Number(expires) < now || used.has(nonce)) return null;
  used.set(nonce, Number(expires));
  return user;
}

/** An upload token binds one participant to one room for the recording endpoint. */
export const issueUploadToken = (room, peerId) => `${room}.${peerId}.${sign(`upload:${room}.${peerId}`)}`;

export function checkUploadToken(token, room, peerId) {
  const mac = String(token ?? '').split('.')[2];
  return Boolean(mac) && verify(`upload:${room}.${peerId}`, mac);
}

// Ephemeral TURN credentials (the "TURN REST API" convention used by coturn's use-auth-secret).
import { createHmac } from 'node:crypto';
import { config } from './config.mjs';

export function iceServersFor(userId, now = Date.now()) {
  const { host, port, secret, ttlSeconds } = config.turn;
  const username = `${Math.floor(now / 1000) + ttlSeconds}:${userId}`;
  const credential = createHmac('sha1', secret).update(username).digest('base64');
  return [
    { urls: `stun:${host}:${port}` },
    { urls: [`turn:${host}:${port}?transport=udp`, `turn:${host}:${port}?transport=tcp`], username, credential },
  ];
}

// Request/response plus notifications over one WebSocket:
//   client -> server  {id, method, data}      server -> client  {id, data} | {id, error}
//   server -> client  {notify, data}
export function rpc(ws, handlers) {
  ws.on('message', async (raw, isBinary) => {
    if (isBinary) return ws.close(1003, 'text only');
    let msg;
    try { msg = JSON.parse(raw.toString()); } catch { return ws.close(1007, 'invalid JSON'); }
    const handler = Object.hasOwn(handlers, msg.method) ? handlers[msg.method] : null;
    try {
      if (!handler) throw new Error(`unknown method ${msg.method}`);
      ws.send(JSON.stringify({ id: msg.id, data: (await handler(msg.data ?? {})) ?? {} }));
    } catch (err) {
      ws.send(JSON.stringify({ id: msg.id, error: err.message }));
    }
  });
  return (notify, data) => ws.readyState === ws.OPEN && ws.send(JSON.stringify({ notify, data }));
}

export const validRoom = (name) => /^[a-z0-9-]{1,64}$/.test(String(name ?? ''));

// Mesh mode: the server only relays opaque signalling messages between members of one room.
import { randomUUID } from 'node:crypto';
import { config } from './config.mjs';
import { issueUploadToken } from './auth.mjs';
import { rpc, validRoom } from './rpc.mjs';

const rooms = new Map(); // room name -> Map(peerId -> peer)

export function onConnection(ws, user) {
  const peer = { id: `p_${randomUUID().slice(0, 8)}`, name: user, room: null };
  let notifyMe;

  const others = () => [...(rooms.get(peer.room)?.values() ?? [])].filter((p) => p !== peer);

  function leave() {
    if (!peer.room) return;
    const members = rooms.get(peer.room);
    members.delete(peer.id);
    for (const p of members.values()) p.notify('peerLeft', { peerId: peer.id });
    if (members.size === 0) rooms.delete(peer.room);
    peer.room = null;
  }

  notifyMe = rpc(ws, {
    join({ room }) {
      if (peer.room) throw new Error('already joined');
      if (!validRoom(room)) throw new Error('bad room name');
      const members = rooms.get(room) ?? new Map();
      if (members.size >= config.maxMeshRoom) throw new Error('room_full'); // mesh does not scale past four
      const peers = [...members.values()].map((p) => ({ id: p.id, name: p.name }));
      members.set(peer.id, peer);
      rooms.set(room, members);
      peer.room = room;
      for (const p of peers) members.get(p.id).notify('peerJoined', { peer: { id: peer.id, name: peer.name } });
      return { peerId: peer.id, peers, uploadToken: issueUploadToken(room, peer.id) };
    },
    signal({ to, data }) {
      const target = others().find((p) => p.id === to); // only members of the same room are reachable
      if (!target) throw new Error('not_found');
      target.notify('signal', { from: peer.id, data }); // the payload is opaque to the server
    },
    leave,
  });
  peer.notify = notifyMe;
  ws.on('close', leave);
}

// SFU mode: one mediasoup worker, one router per room, the browser talks to it through this signalling layer.
import { randomUUID } from 'node:crypto';
import * as mediasoup from 'mediasoup';
import { config } from './config.mjs';
import { issueUploadToken } from './auth.mjs';
import { rpc, validRoom } from './rpc.mjs';

const mediaCodecs = [
  { kind: 'audio', mimeType: 'audio/opus', clockRate: 48000, channels: 2 },
  { kind: 'video', mimeType: 'video/VP8', clockRate: 90000 },
  { kind: 'video', mimeType: 'video/H264', clockRate: 90000,
    parameters: { 'packetization-mode': 1, 'profile-level-id': '42e01f', 'level-asymmetry-allowed': 1 } },
];

const worker = await mediasoup.createWorker({ logLevel: 'warn' });
worker.on('died', (err) => { console.error('mediasoup worker died', err); process.exit(1); });

// One UDP and one TCP port serve every transport of this worker.
const webRtcServer = await worker.createWebRtcServer({
  listenInfos: ['udp', 'tcp'].map((protocol) => ({
    protocol, ip: '0.0.0.0', announcedAddress: config.announcedAddress, port: config.rtcPort,
  })),
});

const rooms = new Map(); // name -> { name, router, peers: Map, speakers }

async function getRoom(name) {
  let room = rooms.get(name);
  if (room) return room;
  const router = await worker.createRouter({ mediaCodecs });
  const speakers = await router.createActiveSpeakerObserver({ interval: 300 });
  room = { name, router, speakers, peers: new Map() };
  speakers.on('dominantspeaker', ({ producer }) => broadcast(room, null, 'activeSpeaker', { peerId: producer.appData.peerId }));
  rooms.set(name, room);
  return room;
}

function broadcast(room, exceptId, notify, data) {
  for (const p of room.peers.values()) if (p.id !== exceptId) p.notify(notify, data);
}

export function onConnection(ws, user) {
  const peer = {
    id: `p_${randomUUID().slice(0, 8)}`, name: user, room: null,
    transports: new Map(), producers: new Map(), consumers: new Map(), dataProducers: new Map(), dataConsumers: new Map(),
  };
  const need = (map, id) => { const v = map.get(id); if (!v) throw new Error('not_found'); return v; };

  peer.notify = rpc(ws, {
    async join({ room: name }) {
      if (peer.room) throw new Error('already joined');
      if (!validRoom(name)) throw new Error('bad room name');
      const room = await getRoom(name);
      peer.room = room;
      room.peers.set(peer.id, peer);
      const existing = [];
      const existingData = [];
      for (const other of room.peers.values()) {
        for (const p of other.producers.values()) {
          existing.push({ producerId: p.id, peerId: other.id, kind: p.kind, source: p.appData.source, paused: p.paused });
        }
        for (const d of other.dataProducers.values()) existingData.push({ dataProducerId: d.id, peerId: other.id });
      }
      broadcast(room, peer.id, 'peerJoined', { peer: { id: peer.id, name: peer.name } });
      return {
        peerId: peer.id, uploadToken: issueUploadToken(name, peer.id),
        peers: [...room.peers.values()].filter((p) => p !== peer).map((p) => ({ id: p.id, name: p.name })),
        routerRtpCapabilities: room.router.rtpCapabilities, existing, existingData,
      };
    },

    async createTransport() {
      const transport = await peer.room.router.createWebRtcTransport({
        webRtcServer, enableUdp: true, enableTcp: true, preferUdp: true,
        enableSctp: true, numSctpStreams: { OS: 256, MIS: 256 }, // SCTP carries the chat data channel
      });
      peer.transports.set(transport.id, transport);
      return {
        id: transport.id, iceParameters: transport.iceParameters, iceCandidates: transport.iceCandidates,
        dtlsParameters: transport.dtlsParameters, sctpParameters: transport.sctpParameters,
      };
    },
    async connectTransport({ transportId, dtlsParameters }) {
      await need(peer.transports, transportId).connect({ dtlsParameters });
    },
    async restartIce({ transportId }) {
      return { iceParameters: await need(peer.transports, transportId).restartIce() };
    },

    async produce({ transportId, kind, rtpParameters, source }) {
      const producer = await need(peer.transports, transportId)
        .produce({ kind, rtpParameters, appData: { peerId: peer.id, source } });
      peer.producers.set(producer.id, producer);
      producer.on('transportclose', () => peer.producers.delete(producer.id));
      if (kind === 'audio') await peer.room.speakers.addProducer({ producerId: producer.id });
      broadcast(peer.room, peer.id, 'newProducer', { producerId: producer.id, peerId: peer.id, kind, source, paused: false });
      return { id: producer.id };
    },
    async closeProducer({ producerId }) {
      need(peer.producers, producerId).close();
      peer.producers.delete(producerId);
      broadcast(peer.room, peer.id, 'producerClosed', { peerId: peer.id, producerId });
    },
    async pauseProducer({ producerId }) {
      await need(peer.producers, producerId).pause();
      broadcast(peer.room, peer.id, 'producerPaused', { peerId: peer.id, producerId, paused: true });
    },
    async resumeProducer({ producerId }) {
      await need(peer.producers, producerId).resume();
      broadcast(peer.room, peer.id, 'producerPaused', { peerId: peer.id, producerId, paused: false });
    },

    async consume({ transportId, producerId, rtpCapabilities }) {
      if (!peer.room.router.canConsume({ producerId, rtpCapabilities })) throw new Error('cannot_consume');
      const consumer = await need(peer.transports, transportId)
        .consume({ producerId, rtpCapabilities, paused: true }); // resumed once the client has the track
      peer.consumers.set(consumer.id, consumer);
      const gone = () => { peer.consumers.delete(consumer.id); peer.notify('consumerClosed', { consumerId: consumer.id }); };
      consumer.on('producerclose', gone);
      consumer.on('transportclose', () => peer.consumers.delete(consumer.id));
      return { id: consumer.id, producerId, kind: consumer.kind, rtpParameters: consumer.rtpParameters };
    },
    async resumeConsumer({ consumerId }) { await need(peer.consumers, consumerId).resume(); },
    async setPreferredLayers({ consumerId, spatialLayer, temporalLayer }) {
      await need(peer.consumers, consumerId).setPreferredLayers({ spatialLayer, temporalLayer });
    },

    async produceData({ transportId, sctpStreamParameters, label }) {
      const dp = await need(peer.transports, transportId).produceData({ sctpStreamParameters, label, appData: { peerId: peer.id } });
      peer.dataProducers.set(dp.id, dp);
      broadcast(peer.room, peer.id, 'newDataProducer', { dataProducerId: dp.id, peerId: peer.id });
      return { id: dp.id };
    },
    async consumeData({ transportId, dataProducerId }) {
      const dc = await need(peer.transports, transportId).consumeData({ dataProducerId });
      peer.dataConsumers.set(dc.id, dc);
      return { id: dc.id, dataProducerId, sctpStreamParameters: dc.sctpStreamParameters, label: dc.label };
    },
  });

  ws.on('close', () => {
    for (const t of peer.transports.values()) t.close(); // also closes this peer's producers and consumers
    if (!peer.room) return;
    peer.room.peers.delete(peer.id);
    broadcast(peer.room, peer.id, 'peerLeft', { peerId: peer.id });
    if (peer.room.peers.size === 0) { peer.room.router.close(); rooms.delete(peer.room.name); }
  });
}

// POST /api/recordings?room=&peer=&part=<n>: appends MediaRecorder chunks to one file per recording.
import { createWriteStream, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import { pipeline } from 'node:stream/promises';
import { checkUploadToken } from './auth.mjs';
import { config } from './config.mjs';
import { validRoom } from './rpc.mjs';

const MAX_CHUNK = 8 * 1024 * 1024;

export async function handleUpload(req, res, url) {
  const room = url.searchParams.get('room');
  const peer = url.searchParams.get('peer');
  const recording = url.searchParams.get('rec');
  const token = (req.headers.authorization ?? '').replace(/^Bearer /, '');
  if (!validRoom(room) || !/^p_[0-9a-f]{8}$/.test(peer ?? '') || !/^[0-9]{10,}$/.test(recording ?? '')) {
    return res.writeHead(400).end();
  }
  if (!checkUploadToken(token, room, peer)) return res.writeHead(401).end();
  if (Number(req.headers['content-length'] ?? 0) > MAX_CHUNK) return res.writeHead(413).end();

  const dir = join(config.recordingsDir, room);
  mkdirSync(dir, { recursive: true });
  // Chunks arrive in order on one connection at a time; "a" appends to the same file.
  await pipeline(req, createWriteStream(join(dir, `${peer}-${recording}.webm`), { flags: 'a' }));
  res.writeHead(204).end();
}

// Huddle server: static files, session endpoint, recording upload and the two signalling WebSockets.
import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';
import { extname, join, normalize } from 'node:path';
import { fileURLToPath } from 'node:url';
import { WebSocketServer } from 'ws';
import { config } from './config.mjs';
import { issueTicket, redeemTicket } from './auth.mjs';
import { iceServersFor } from './turn.mjs';
import { handleUpload } from './recordings.mjs';
import * as mesh from './mesh.mjs';

// Backends are loaded on demand: importing sfu.mjs starts a mediasoup worker.
const sfu = config.modes.includes('sfu') ? await import('./sfu.mjs') : null;
const livekit = config.modes.includes('livekit') ? await import('./livekit.mjs') : null;

const PUBLIC = fileURLToPath(new URL('../public/', import.meta.url));
const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css' };
const USER = /^[a-z0-9-]{1,32}$/;

const server = createServer(async (req, res) => {
  const url = new URL(req.url, 'http://localhost');
  try {
    if (url.pathname === '/api/session' && req.method === 'POST') {
      // Demo login: a real application authenticates the request and takes `user` from the session.
      const user = url.searchParams.get('user') ?? '';
      if (!USER.test(user)) return res.writeHead(400).end();
      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
      return res.end(JSON.stringify({ ticket: issueTicket(user), iceServers: iceServersFor(user) }));
    }
    if (url.pathname === '/api/config') {
      res.writeHead(200, { 'content-type': 'application/json' });
      return res.end(JSON.stringify({ modes: ['mesh', ...config.modes.filter((m) => m !== 'mesh')] }));
    }
    if (livekit && url.pathname.startsWith('/api/livekit/') && await livekit.handle(req, res, url)) return;
    if (url.pathname === '/favicon.ico') return res.writeHead(204).end();
    if (url.pathname === '/api/recordings' && req.method === 'POST') return await handleUpload(req, res, url);

    const file = normalize(url.pathname === '/' ? '/index.html' : url.pathname);
    const type = TYPES[extname(file)];
    if (!type || file.includes('..')) return res.writeHead(404).end();
    res.writeHead(200, { 'content-type': type, 'cache-control': 'no-cache' });
    res.end(await readFile(join(PUBLIC, file)));
  } catch (err) {
    if (!res.headersSent) res.writeHead(err.code === 'ENOENT' ? 404 : 500);
    res.end();
  }
});

const wss = new WebSocketServer({ noServer: true, maxPayload: 64 * 1024 });
const modes = { '/ws/mesh': mesh, ...(sfu && { '/ws/sfu': sfu }) };

server.on('upgrade', (req, socket, head) => {
  const url = new URL(req.url, 'http://localhost');
  const reject = (status, text) => { socket.write(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\n\r\n`); socket.destroy(); };
  const mode = modes[url.pathname];
  if (!mode) return reject(404, 'Not Found');
  // Browsers do not apply the same-origin policy to WebSockets: check Origin ourselves.
  if (!config.allowedOrigins.includes(req.headers.origin)) return reject(403, 'Forbidden');
  const user = redeemTicket(url.searchParams.get('ticket'));
  if (!user) return reject(401, 'Unauthorized');
  wss.handleUpgrade(req, socket, head, (ws) => {
    ws.isAlive = true;
    ws.on('pong', () => { ws.isAlive = true; });
    mode.onConnection(ws, user);
  });
});

// Ping every 20 s; terminate connections that missed the previous pong (load balancers drop idle sockets).
setInterval(() => {
  for (const ws of wss.clients) {
    if (!ws.isAlive) { ws.terminate(); continue; }
    ws.isAlive = false;
    ws.ping();
  }
}, 20_000).unref();

server.listen(config.port, () => console.log(`huddle http://localhost:${config.port} (rtc ${config.rtcPort})`));
process.on('SIGTERM', () => process.exit(0));

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Huddle</title>
<style>
  :root { color-scheme: light dark; --bg: #f6f7f9; --fg: #1b1f24; --card: #ffffff; --line: #c9ced6; --accent: #2457c5; --good: #1a7f37; --fair: #9a6700; --poor: #cf222e; }
  @media (prefers-color-scheme: dark) { :root { --bg: #14171c; --fg: #e8eaee; --card: #1d2229; --line: #39414d; --accent: #7aa2f7; --good: #3fb950; --fair: #d29922; --poor: #f85149; } }
  * { box-sizing: border-box; }
  body { margin: 0; font: 16px/1.4 system-ui, sans-serif; background: var(--bg); color: var(--fg); }
  main { max-width: 1200px; margin: 0 auto; padding: 16px; }
  form, .panel { background: var(--card); border: 1px solid var(--line); border-radius: 8px; padding: 12px; }
  label { display: block; margin: 8px 0 2px; font-size: 14px; }
  input, select, button { font: inherit; padding: 6px 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--card); color: var(--fg); }
  button { cursor: pointer; }
  button[aria-pressed="true"] { background: var(--accent); color: #fff; border-color: var(--accent); }
  button:focus-visible, input:focus-visible, select:focus-visible { outline: 3px solid var(--accent); outline-offset: 2px; }
  #stage { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 8px; margin-bottom: 12px; }
  .tile { position: relative; margin: 0; background: #000; border: 3px solid transparent; border-radius: 8px; overflow: hidden; aspect-ratio: 16 / 9; }
  .tile.screen { grid-column: 1 / -1; }
  .tile.speaking { border-color: var(--good); }
  .tile video { width: 100%; height: 100%; object-fit: contain; }
  .tile figcaption { position: absolute; left: 0; bottom: 0; right: 0; padding: 2px 8px; color: #fff; background: rgba(0,0,0,.55); font-size: 14px; }
  .badge { margin-left: 8px; color: #ffb4b4; }
  #controls { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 12px; }
  #quality { font-variant-numeric: tabular-nums; padding: 2px 8px; border-radius: 6px; border: 1px solid var(--line); }
  #quality[data-score="good"] { color: var(--good); } #quality[data-score="fair"] { color: var(--fair); } #quality[data-score="poor"] { color: var(--poor); }
  .sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
  #log { list-style: none; margin: 0 0 8px; padding: 0; max-height: 180px; overflow: auto; }
  #log .mine { color: var(--accent); }
  #chatForm { display: flex; gap: 8px; } #chatText { flex: 1; }
</style>
</head>
<body>
<main>
  <h1>Huddle</h1>
  <form id="lobby" onsubmit="return false">
    <label for="name">Your name (a-z, 0-9, dash)</label>
    <input id="name" pattern="[a-z0-9-]{1,32}" required autocomplete="off">
    <label for="room">Room</label>
    <input id="room" pattern="[a-z0-9-]{1,64}" required autocomplete="off">
    <label for="mode">Mode</label>
    <select id="mode"></select>
    <label for="passphrase">End-to-end passphrase (optional, shared out of band)</label>
    <input id="passphrase" type="password" autocomplete="off">
    <label><input id="relay" type="checkbox"> Mesh: force TURN relay</label>
    <p><button id="join" type="button">Join</button></p>
  </form>

  <section id="call" hidden>
    <div id="stage" role="group" aria-label="Participants"></div>
    <div id="controls">
      <button id="muteMic" type="button" aria-pressed="false">Mute microphone</button>
      <button id="muteCam" type="button" aria-pressed="false">Turn camera off</button>
      <button id="share" type="button" aria-pressed="false">Share screen</button>
      <button id="recordButton" type="button" aria-pressed="false">Record</button><span id="recordState" aria-live="polite">idle</span>
      <label for="mic" class="sr">Microphone</label><select id="mic"></select>
      <label for="cam" class="sr">Camera</label><select id="cam"></select>
      <button id="leave" type="button">Leave</button>
      <span id="quality" data-score="unknown" role="status">quality: measuring</span>
    </div>
    <div class="panel">
      <ul id="log" aria-live="polite" aria-label="Chat"></ul>
      <form id="chatForm"><input id="chatText" aria-label="Message" autocomplete="off" maxlength="2000"><button>Send</button></form>
    </div>
  </section>
  <p id="status" role="status" aria-live="polite"></p>
</main>
<script type="module" src="/main.js"></script>
</body>
</html>

// Request/response plus notifications over the signalling WebSocket (see server/rpc.mjs).
export async function openSignaling(mode, user) {
  // 1. The authenticated HTTP call returns a single-use ticket and the ICE servers (with ephemeral TURN credentials).
  const res = await fetch(`/api/session?user=${encodeURIComponent(user)}`, { method: 'POST' });
  if (!res.ok) throw new Error(`login failed (${res.status})`);
  const { ticket, iceServers } = await res.json();

  // 2. The browser cannot set headers on a WebSocket, so the ticket travels in the query string.
  const scheme = location.protocol === 'https:' ? 'wss' : 'ws';
  const ws = new WebSocket(`${scheme}://${location.host}/ws/${mode}?ticket=${encodeURIComponent(ticket)}`);
  await new Promise((resolve, reject) => {
    ws.onopen = resolve;
    ws.onerror = () => reject(new Error('the signalling handshake was rejected'));
  });

  const pending = new Map();
  const listeners = new Map();
  let seq = 0;

  ws.onmessage = ({ data }) => {
    const msg = JSON.parse(data);
    if (msg.notify) return listeners.get(msg.notify)?.(msg.data);
    const call = pending.get(msg.id);
    pending.delete(msg.id);
    if (!call) return;
    msg.error ? call.reject(new Error(msg.error)) : call.resolve(msg.data);
  };
  ws.onclose = (event) => {
    for (const call of pending.values()) call.reject(new Error('signalling connection closed'));
    pending.clear();
    listeners.get('close')?.(event);
  };

  return {
    iceServers,
    request: (method, data) => new Promise((resolve, reject) => {
      const id = ++seq;
      pending.set(id, { resolve, reject });
      ws.send(JSON.stringify({ id, method, data }));
    }),
    on: (name, fn) => listeners.set(name, fn),
    close: () => ws.close(1000, 'bye'),
  };
}

// Local media: camera and microphone, device switching, mute and screen sharing.
export class LocalMedia {
  tracks = { audio: null, video: null, screen: null };
  stream = new MediaStream(); // microphone + camera, the stream that is shown in the local tile
  screenStream = null;
  onScreenEnded = () => {};

  async start({ audioDeviceId, videoDeviceId, width = 1280, height = 720, frameRate = 30 } = {}) {
    const media = await navigator.mediaDevices.getUserMedia({
      audio: { echoCancellation: true, noiseSuppression: true, ...(audioDeviceId && { deviceId: { exact: audioDeviceId } }) },
      video: { width: { ideal: width }, height: { ideal: height }, frameRate: { ideal: frameRate },
        ...(videoDeviceId && { deviceId: { exact: videoDeviceId } }) },
    });
    this.tracks.audio = media.getAudioTracks()[0];
    this.tracks.video = media.getVideoTracks()[0];
    media.getTracks().forEach((t) => this.stream.addTrack(t));
  }

  /** Labels are empty until permission is granted, so call this after start(). */
  async devices() {
    const all = await navigator.mediaDevices.enumerateDevices();
    const pick = (kind) => all.filter((d) => d.kind === kind).map((d, i) => ({ id: d.deviceId, label: d.label || `${kind} ${i + 1}` }));
    return { audio: pick('audioinput'), video: pick('videoinput') };
  }

  /** Opens another device and returns the new track; the caller swaps it into the connections. */
  async switchDevice(kind, deviceId) {
    const media = await navigator.mediaDevices.getUserMedia({ [kind]: { deviceId: { exact: deviceId } } });
    const track = media.getTracks()[0];
    const old = this.tracks[kind];
    track.enabled = old ? old.enabled : true; // keep the mute state
    if (old) { this.stream.removeTrack(old); old.stop(); }
    this.stream.addTrack(track);
    this.tracks[kind] = track;
    return track;
  }

  /** Must run inside a user gesture (a click handler). */
  async startScreen() {
    const media = await navigator.mediaDevices.getDisplayMedia({ video: { frameRate: { ideal: 15, max: 30 } }, audio: false });
    const track = media.getVideoTracks()[0];
    track.contentHint = 'detail'; // favour sharp text over frame rate
    track.onended = () => this.stopScreen(); // the browser's own "Stop sharing" button
    this.tracks.screen = track;
    this.screenStream = media;
    return track;
  }

  stopScreen() {
    if (!this.tracks.screen) return;
    this.tracks.screen.onended = null;
    this.tracks.screen.stop();
    this.tracks.screen = null;
    this.screenStream = null;
    this.onScreenEnded();
  }

  stopAll() {
    this.stopScreen();
    for (const t of this.stream.getTracks()) t.stop();
  }
}

// Mesh mode: one RTCPeerConnection per remote participant, negotiated with the perfect negotiation pattern.
const MAX_VIDEO_BITRATE = 1_500_000; // total upload budget, shared by every outgoing video stream

class Link {
  #pc; #polite; #makingOffer = false; #ignoreOffer = false; #watchdog = null; #prepared = false;
  remoteScreenStreamId = null;
  senders = {};

  constructor(session, peer, initiator) {
    this.session = session;
    this.peer = peer;
    this.#polite = session.peerId < peer.id; // any rule works if both sides compute opposite answers
    const pc = (this.#pc = new RTCPeerConnection({
      iceServers: session.iceServers,
      iceTransportPolicy: session.relayOnly ? 'relay' : 'all',
    }));

    pc.onicecandidate = ({ candidate }) => { if (candidate) this.signal({ candidate }); };
    pc.ontrack = (event) => this.#onTrack(event);
    pc.onconnectionstatechange = () => session.on.linkState?.(peer.id, pc.connectionState);
    pc.oniceconnectionstatechange = () => {
      clearTimeout(this.#watchdog);
      if (pc.iceConnectionState === 'failed') pc.restartIce();
      // A link that stays disconnected or never connects (an unresolved mDNS name, a blocked path) gets a fresh ICE attempt.
      else if (pc.iceConnectionState !== 'connected' && pc.iceConnectionState !== 'completed') this.#armWatchdog();
    };
    this.#armWatchdog();

    pc.onnegotiationneeded = async () => {
      try {
        this.#makingOffer = true;
        await pc.setLocalDescription(); // creates the right description for the current signalling state
        this.signal({ description: pc.localDescription });
      } catch (err) {
        console.error('negotiation failed', err);
      } finally {
        this.#makingOffer = false;
      }
    };

    // The newcomer offers and the existing participant answers, so a join never produces glare. The answerer adds
    // its tracks after it has seen the offer (see handleSignal). Perfect negotiation still covers later changes.
    if (initiator) this.#prepare();
  }

  // Creating the first data channel or the first sender triggers negotiationneeded, so the answerer does both only
  // after the offer arrived, and the offer's m-lines are reused.
  #prepare() {
    this.#prepared = true;
    // A pre-negotiated channel (same id on both sides) avoids deciding who creates it.
    const channel = (this.channel = this.#pc.createDataChannel('huddle', { negotiated: true, id: 0 }));
    channel.binaryType = 'arraybuffer';
    channel.onopen = () => this.session.sendStateTo(this);
    channel.onmessage = ({ data }) => this.session.receiveData(this.peer.id, data);
    this.#addLocalTracks();
  }

  #armWatchdog() {
    clearTimeout(this.#watchdog);
    this.#watchdog = setTimeout(() => {
      if (!['connected', 'completed'].includes(this.#pc.iceConnectionState)) this.#pc.restartIce(); // fires negotiationneeded
    }, 8000);
  }

  get pc() { return this.#pc; }
  signal(data) { return this.session.sig.request('signal', { to: this.peer.id, data }).catch(() => {}); }

  #addLocalTracks() {
    const { local, e2ee } = this.session;
    for (const kind of ['audio', 'video']) {
      const track = local.tracks[kind];
      if (!track) continue;
      this.senders[kind] = this.#pc.addTrack(track, local.stream);
      this.#protect(this.senders[kind]);
    }
    if (e2ee) this.#preferVp8();
    if (local.tracks.screen) this.addScreen(local.tracks.screen, local.screenStream);
    this.applyBitrate();
  }

  // Install both transforms as soon as the transceiver exists. Chrome 155 delivers no frames to a receiver transform
  // that is assigned in ontrack on a transceiver created by addTrack, so doing it here is not just tidier.
  #protect(sender) {
    const e2ee = this.session.e2ee;
    if (!e2ee) return;
    e2ee.protect(sender);
    const { receiver } = this.#pc.getTransceivers().find((t) => t.sender === sender);
    if (!receiver.transform) e2ee.unprotect(receiver);
  }

  #preferVp8() {
    const tr = this.#pc.getTransceivers().find((t) => t.sender.track?.kind === 'video');
    const vp8 = RTCRtpReceiver.getCapabilities('video').codecs.filter((c) => c.mimeType === 'video/VP8');
    tr?.setCodecPreferences(vp8); // the encrypted frame layout assumes VP8 headers
  }

  addScreen(track, stream) {
    // Tell the peer which stream is the screen *before* the offer that contains it (same ordered WebSocket).
    this.signal({ meta: { screenStreamId: stream.id } });
    this.senders.screen = this.#pc.addTrack(track, stream);
    this.#protect(this.senders.screen);
    this.applyBitrate();
  }

  removeScreen() {
    this.signal({ meta: { screenStreamId: null } });
    if (this.senders.screen) this.#pc.removeTrack(this.senders.screen);
    delete this.senders.screen;
  }

  async applyBitrate() {
    const links = this.session.links.size || 1;
    for (const [name, sender] of Object.entries(this.senders)) {
      if (name === 'audio') continue;
      const params = sender.getParameters();
      if (!params.encodings?.length) continue; // not negotiated yet
      params.encodings[0].maxBitrate = Math.floor(MAX_VIDEO_BITRATE / links);
      await sender.setParameters(params).catch(() => {});
    }
  }

  #onTrack({ track, streams: [stream], receiver }) {
    if (this.session.e2ee && !receiver.transform) this.session.e2ee.unprotect(receiver);
    const source = stream && stream.id === this.remoteScreenStreamId ? 'screen' : 'camera';
    this.session.on.track?.({ peerId: this.peer.id, source, track });
    track.onended = () => this.session.on.trackEnded?.({ peerId: this.peer.id, source, kind: track.kind });
  }

  // Everything received from the signalling channel for this peer goes through here.
  async handleSignal({ description, candidate, meta }) {
    const pc = this.#pc;
    if (meta) {
      this.remoteScreenStreamId = meta.screenStreamId;
      if (!meta.screenStreamId) this.session.on.trackEnded?.({ peerId: this.peer.id, source: 'screen', kind: 'video' });
      return;
    }
    try {
      if (description) {
        const collision = description.type === 'offer' && (this.#makingOffer || pc.signalingState !== 'stable');
        this.#ignoreOffer = !this.#polite && collision; // the impolite peer ignores the colliding offer
        if (this.#ignoreOffer) return;
        await pc.setRemoteDescription(description); // the polite peer rolls back implicitly
        if (description.type === 'offer') {
          if (!this.#prepared) this.#prepare(); // reuses the m-lines created by the offer
          await pc.setLocalDescription();
          this.signal({ description: pc.localDescription });
        }
      } else if (candidate) {
        try { await pc.addIceCandidate(candidate); } catch (err) { if (!this.#ignoreOffer) throw err; }
      }
    } catch (err) {
      console.error('signal handling failed', err);
    }
  }

  close() { clearTimeout(this.#watchdog); this.#pc.close(); }
}

export class MeshSession {
  mode = 'mesh';
  links = new Map();
  muted = { audio: false, video: false };

  constructor({ sig, local, e2ee, relayOnly, on }) {
    Object.assign(this, { sig, local, e2ee, relayOnly, on });
    this.iceServers = sig.iceServers;
  }

  async join(room) {
    this.sig.on('peerJoined', ({ peer }) => this.#addLink(peer, false));
    this.sig.on('peerLeft', ({ peerId }) => this.#removeLink(peerId));
    this.sig.on('signal', ({ from, data }) => this.links.get(from)?.handleSignal(data));
    const joined = await this.sig.request('join', { room });
    Object.assign(this, { peerId: joined.peerId, uploadToken: joined.uploadToken, room });
    for (const peer of joined.peers) this.#addLink(peer, true);
    return joined;
  }

  #addLink(peer, initiator) {
    this.links.set(peer.id, new Link(this, peer, initiator));
    this.on.peer?.(peer);
    this.links.forEach((l) => l.applyBitrate()); // each link gets a smaller share of the upload budget
  }

  #removeLink(peerId) {
    this.links.get(peerId)?.close();
    this.links.delete(peerId);
    this.on.peerLeft?.(peerId);
    this.links.forEach((l) => l.applyBitrate());
  }

  setMuted(kind, muted) {
    this.muted[kind] = muted;
    this.local.tracks[kind].enabled = !muted; // a disabled track sends silence or black frames
    for (const link of this.links.values()) this.sendStateTo(link);
  }

  async replaceTrack(kind, track) {
    await Promise.all([...this.links.values()].map((l) => l.senders[kind]?.replaceTrack(track)));
  }

  async startScreen(track, stream) { this.links.forEach((l) => l.addScreen(track, stream)); }
  async stopScreen() { this.links.forEach((l) => l.removeScreen()); }

  // ----- data channel: chat and mute state -----
  async #encode(msg) { return this.e2ee ? this.e2ee.seal(msg) : JSON.stringify(msg); }

  sendStateTo(link) {
    if (link.channel?.readyState !== 'open') return;
    for (const kind of ['audio', 'video']) {
      this.#encode({ t: 'state', kind, muted: this.muted[kind] }).then((d) => link.channel.send(d));
    }
  }

  async sendChat(text) {
    const data = await this.#encode({ t: 'chat', text, ts: Date.now() });
    for (const link of this.links.values()) if (link.channel?.readyState === 'open') link.channel.send(data);
  }

  async receiveData(peerId, data) {
    try {
      const msg = this.e2ee ? await this.e2ee.open(data) : JSON.parse(data);
      if (msg.t === 'chat') this.on.chat?.({ peerId, text: String(msg.text).slice(0, 2000), ts: msg.ts });
      else if (msg.t === 'state') this.on.state?.({ peerId, kind: msg.kind, muted: Boolean(msg.muted) });
    } catch { /* malformed or undecryptable message: ignore */ }
  }

  statsSources() { return [...this.links].map(([id, l]) => ({ id, getStats: () => l.pc.getStats() })); }
  iceRestart() { this.links.forEach((l) => l.pc.restartIce()); }
  close() { this.links.forEach((l) => l.close()); this.links.clear(); this.sig.close(); }
}

// SFU mode: one send transport, one receive transport, one producer per local track, one consumer per remote track.
import { Device } from 'mediasoup-client';

const CAMERA_ENCODINGS = [ // three simulcast layers, each with three temporal layers
  { maxBitrate: 150_000, scaleResolutionDownBy: 4, scalabilityMode: 'L1T3' },
  { maxBitrate: 500_000, scaleResolutionDownBy: 2, scalabilityMode: 'L1T3' },
  { maxBitrate: 1_500_000, scalabilityMode: 'L1T3' },
];

export class SfuSession {
  mode = 'sfu';
  producers = {}; // 'audio' | 'video' | 'screen' -> Producer
  consumers = new Map(); // consumerId -> { consumer, peerId, source }
  muted = { audio: false, video: false };

  constructor({ sig, local, e2ee, on }) {
    Object.assign(this, { sig, local, e2ee, on });
  }

  async join(room) {
    const { sig } = this;
    sig.on('peerJoined', ({ peer }) => this.on.peer?.(peer));
    sig.on('peerLeft', ({ peerId }) => this.#peerLeft(peerId));
    sig.on('newProducer', (p) => this.#consume(p));
    sig.on('producerClosed', ({ peerId, producerId }) => this.#producerClosed(peerId, producerId));
    sig.on('producerPaused', ({ peerId, producerId, paused }) => this.#remotePaused(peerId, producerId, paused));
    sig.on('consumerClosed', ({ consumerId }) => this.#dropConsumer(consumerId));
    sig.on('activeSpeaker', ({ peerId }) => this.on.speaker?.(peerId));
    sig.on('newDataProducer', (d) => this.#consumeData(d));

    const joined = await sig.request('join', { room });
    Object.assign(this, { peerId: joined.peerId, uploadToken: joined.uploadToken, room });
    this.device = await Device.factory();
    await this.device.load({ routerRtpCapabilities: joined.routerRtpCapabilities });
    this.sendTransport = await this.#transport('send');
    this.recvTransport = await this.#transport('recv');

    for (const peer of joined.peers) this.on.peer?.(peer);
    await this.#publish();
    for (const p of joined.existing) await this.#consume(p);
    for (const d of joined.existingData) await this.#consumeData(d);
    return joined;
  }

  async #transport(direction) {
    const params = await this.sig.request('createTransport');
    const transport = direction === 'send' ? this.device.createSendTransport(params) : this.device.createRecvTransport(params);
    transport.on('connect', ({ dtlsParameters }, ok, fail) =>
      this.sig.request('connectTransport', { transportId: transport.id, dtlsParameters }).then(ok, fail));
    if (direction === 'send') {
      transport.on('produce', ({ kind, rtpParameters, appData }, ok, fail) =>
        this.sig.request('produce', { transportId: transport.id, kind, rtpParameters, source: appData.source })
          .then(({ id }) => ok({ id }), fail));
      transport.on('producedata', ({ sctpStreamParameters, label }, ok, fail) =>
        this.sig.request('produceData', { transportId: transport.id, sctpStreamParameters, label })
          .then(({ id }) => ok({ id }), fail));
    }
    transport.on('connectionstatechange', async (state) => {
      this.on.linkState?.(direction, state);
      if (state === 'failed') await this.#restartIce(transport); // network change: new ICE credentials, same DTLS session
    });
    return transport;
  }

  async #restartIce(transport) {
    const { iceParameters } = await this.sig.request('restartIce', { transportId: transport.id });
    await transport.restartIce({ iceParameters });
  }
  iceRestart() { return Promise.all([this.sendTransport, this.recvTransport].map((t) => this.#restartIce(t))); }

  // ----- publishing -----
  async #publish() {
    const { local, e2ee } = this;
    const onRtpSender = e2ee ? (sender) => e2ee.protect(sender) : undefined; // runs before the first frame is sent
    const vp8 = e2ee && this.device.rtpCapabilities.codecs.find((c) => c.mimeType.toLowerCase() === 'video/vp8');
    this.producers.audio = await this.sendTransport.produce({
      track: local.tracks.audio, appData: { source: 'mic' }, onRtpSender,
      codecOptions: { opusDtx: true, opusFec: true },
    });
    this.producers.video = await this.sendTransport.produce({
      track: local.tracks.video, appData: { source: 'camera' }, encodings: CAMERA_ENCODINGS, onRtpSender, ...(vp8 && { codec: vp8 }),
    });
    this.dataProducer = await this.sendTransport.produceData({ label: 'huddle', ordered: true });
    if (local.tracks.screen) await this.startScreen(local.tracks.screen);
  }

  async startScreen(track) {
    const { e2ee } = this;
    this.producers.screen = await this.sendTransport.produce({
      track, appData: { source: 'screen' }, encodings: [{ maxBitrate: 2_500_000 }],
      onRtpSender: e2ee ? (sender) => e2ee.protect(sender) : undefined,
      ...(e2ee && { codec: this.device.rtpCapabilities.codecs.find((c) => c.mimeType.toLowerCase() === 'video/vp8') }),
    });
  }

  async stopScreen() {
    const producer = this.producers.screen;
    if (!producer) return;
    delete this.producers.screen;
    producer.close();
    await this.sig.request('closeProducer', { producerId: producer.id });
  }

  async setMuted(kind, muted) {
    this.muted[kind] = muted;
    const producer = this.producers[kind];
    muted ? producer.pause() : producer.resume(); // stops or restarts the sender locally
    await this.sig.request(muted ? 'pauseProducer' : 'resumeProducer', { producerId: producer.id });
  }

  replaceTrack(kind, track) { return this.producers[kind].replaceTrack({ track }); }

  // ----- consuming -----
  async #consume({ producerId, peerId, kind, source, paused }) {
    const info = await this.sig.request('consume', {
      transportId: this.recvTransport.id, producerId, rtpCapabilities: this.device.recvRtpCapabilities,
    });
    const consumer = await this.recvTransport.consume({
      id: info.id, producerId, kind: info.kind, rtpParameters: info.rtpParameters,
      onRtpReceiver: this.e2ee ? (receiver) => this.e2ee.unprotect(receiver) : undefined,
    });
    this.consumers.set(consumer.id, { consumer, peerId, source, producerId });
    this.on.track?.({ peerId, source: source === 'screen' ? 'screen' : 'camera', track: consumer.track });
    if (paused) this.on.state?.({ peerId, kind: kind === 'audio' ? 'audio' : 'video', muted: true });
    await this.sig.request('resumeConsumer', { consumerId: consumer.id }); // the server created it paused
  }

  #dropConsumer(consumerId) {
    const entry = this.consumers.get(consumerId);
    if (!entry) return;
    this.consumers.delete(consumerId);
    entry.consumer.close();
    this.on.trackEnded?.({ peerId: entry.peerId, source: entry.source === 'screen' ? 'screen' : 'camera', kind: entry.consumer.kind });
  }

  #producerClosed(peerId, producerId) {
    for (const [id, e] of this.consumers) if (e.producerId === producerId) this.#dropConsumer(id);
  }

  #remotePaused(peerId, producerId, paused) {
    const entry = [...this.consumers.values()].find((e) => e.producerId === producerId);
    if (entry) this.on.state?.({ peerId, kind: entry.consumer.kind === 'audio' ? 'audio' : 'video', muted: paused });
  }

  #peerLeft(peerId) {
    for (const [id, e] of this.consumers) {
      if (e.peerId !== peerId) continue;
      this.consumers.delete(id);
      e.consumer.close();
    }
    this.on.peerLeft?.(peerId);
  }

  /** Ask for the simulcast layer that matches the size of the tile (called from a ResizeObserver). */
  setTileWidth(peerId, width) {
    const spatialLayer = width < 240 ? 0 : width < 480 ? 1 : 2;
    for (const { consumer, peerId: owner, source } of this.consumers.values()) {
      if (owner === peerId && consumer.kind === 'video' && source !== 'screen') {
        this.sig.request('setPreferredLayers', { consumerId: consumer.id, spatialLayer, temporalLayer: 2 }).catch(() => {});
      }
    }
  }

  // ----- data (chat) -----
  async #consumeData({ dataProducerId, peerId }) {
    const info = await this.sig.request('consumeData', { transportId: this.recvTransport.id, dataProducerId });
    const dc = await this.recvTransport.consumeData({
      id: info.id, dataProducerId, sctpStreamParameters: info.sctpStreamParameters, label: info.label,
    });
    dc.binaryType = 'arraybuffer';
    dc.on('message', (data) => this.receiveData(peerId, data));
  }

  async sendChat(text) {
    const msg = { t: 'chat', text, ts: Date.now() };
    this.dataProducer.send(this.e2ee ? await this.e2ee.seal(msg) : JSON.stringify(msg));
  }

  async receiveData(peerId, data) {
    try {
      const msg = this.e2ee ? await this.e2ee.open(data) : JSON.parse(data);
      if (msg.t === 'chat') this.on.chat?.({ peerId, text: String(msg.text).slice(0, 2000), ts: msg.ts });
    } catch { /* ignore malformed messages */ }
  }

  statsSources() {
    return [this.sendTransport, this.recvTransport].filter(Boolean).map((t, i) => ({ id: i ? 'recv' : 'send', getStats: () => t.getStats() }));
  }

  close() {
    this.sendTransport?.close();
    this.recvTransport?.close();
    this.sig.close();
  }
}

// Mesh mode has no server in the media path, so the browser measures audio levels itself.
export class SpeakerDetector {
  #ctx = new AudioContext();
  #inputs = new Map(); // peer id -> { analyser, data, level }
  #current = null;
  #timer = null;

  constructor(onChange) { this.onChange = onChange; }

  /** Pass the stream that a media element plays: Chromium feeds Web Audio from a remote stream only then. */
  add(peerId, stream) {
    if (this.#inputs.has(peerId) || !stream.getAudioTracks().length) return;
    const analyser = this.#ctx.createAnalyser();
    analyser.fftSize = 2048; // about 43 ms of samples per reading
    this.#ctx.createMediaStreamSource(stream).connect(analyser); // not connected to the speakers: the <video> plays the sound
    this.#inputs.set(peerId, { analyser, data: new Float32Array(analyser.fftSize), level: 0 });
    this.#timer ??= setInterval(() => this.#tick(), 100);
  }

  remove(peerId) {
    this.#inputs.delete(peerId);
    if (this.#current === peerId) this.#current = null;
    if (!this.#inputs.size) { clearInterval(this.#timer); this.#timer = null; }
  }

  #tick() {
    let best = null, bestLevel = 0.02; // below this smoothed RMS nobody is speaking
    for (const [id, input] of this.#inputs) {
      input.analyser.getFloatTimeDomainData(input.data);
      const rms = Math.sqrt(input.data.reduce((sum, v) => sum + v * v, 0) / input.data.length);
      input.level = Math.max(rms, input.level * 0.9); // fast attack, slow release (about one second)
      if (input.level > bestLevel) { best = id; bestLevel = input.level; }
    }
    // Hysteresis: keep the current speaker unless somebody is clearly louder.
    const currentLevel = this.#inputs.get(this.#current)?.level ?? 0;
    if (best && best !== this.#current && bestLevel > currentLevel * 1.5) {
      this.#current = best;
      this.onChange(best);
    }
  }

  close() { clearInterval(this.#timer); this.#ctx.close(); }
}

// Call-quality indicator: samples getStats() and turns the deltas into good, fair or poor.
export class QualityMonitor {
  #prev = new Map();
  #timer = null;

  constructor(getSources, onSample, intervalMs = 2000) {
    this.getSources = getSources;
    this.onSample = onSample;
    this.intervalMs = intervalMs;
  }

  start() { this.#timer = setInterval(() => this.sample().catch(() => {}), this.intervalMs); }
  stop() { clearInterval(this.#timer); }

  async sample() {
    const out = { rttMs: null, inKbps: 0, outKbps: 0, lossPct: 0, jitterMs: 0, limitation: null };
    let packets = 0, lost = 0;
    for (const { id, getStats } of this.getSources()) {
      const report = await getStats();
      const transport = [...report.values()].find((s) => s.type === 'transport');
      for (const s of report.values()) {
        if (s.type === 'candidate-pair' && s.state === 'succeeded' && (s.nominated || s.id === transport?.selectedCandidatePairId)
            && s.currentRoundTripTime != null) {
          out.rttMs = Math.max(out.rttMs ?? 0, s.currentRoundTripTime * 1000);
        }
        const key = `${id}:${s.id}`;
        const prev = this.#prev.get(key);
        this.#prev.set(key, s);
        if (!prev || s.timestamp <= prev.timestamp) continue;
        const seconds = (s.timestamp - prev.timestamp) / 1000;
        if (s.type === 'inbound-rtp') {
          out.inKbps += ((s.bytesReceived - prev.bytesReceived) * 8) / seconds / 1000;
          packets += s.packetsReceived - prev.packetsReceived;
          lost += Math.max(0, s.packetsLost - prev.packetsLost);
          out.jitterMs = Math.max(out.jitterMs, (s.jitter ?? 0) * 1000);
        } else if (s.type === 'outbound-rtp') {
          out.outKbps += ((s.bytesSent - prev.bytesSent) * 8) / seconds / 1000;
          if (s.kind === 'video' && s.qualityLimitationReason && s.qualityLimitationReason !== 'none') out.limitation = s.qualityLimitationReason;
        }
      }
    }
    out.lossPct = packets + lost > 0 ? (100 * lost) / (packets + lost) : 0;
    out.score = QualityMonitor.score(out);
    this.onSample(out);
    return out;
  }

  static score({ rttMs, lossPct, jitterMs, limitation }) {
    if (rttMs == null) return 'unknown';
    if (lossPct > 8 || rttMs > 400 || jitterMs > 80) return 'poor';
    if (lossPct > 2 || rttMs > 200 || jitterMs > 30 || limitation === 'bandwidth') return 'fair';
    return 'good';
  }
}

// Records the local camera and microphone with MediaRecorder and uploads a chunk every two seconds.
export class LocalRecorder {
  #recorder = null;
  #queue = Promise.resolve();
  state = 'idle';

  constructor({ stream, room, peerId, token, onState }) {
    Object.assign(this, { stream, room, peerId, token, onState });
  }

  start() {
    const mimeType = ['video/webm;codecs=vp8,opus', 'video/webm'].find((t) => MediaRecorder.isTypeSupported(t));
    if (!mimeType) throw new Error('MediaRecorder cannot produce WebM here');
    const recording = Date.now().toString().padStart(10, '0');
    const url = `/api/recordings?room=${this.room}&peer=${this.peerId}&rec=${recording}`;
    this.#recorder = new MediaRecorder(this.stream, { mimeType, videoBitsPerSecond: 1_500_000 });
    this.#recorder.ondataavailable = ({ data }) => {
      if (!data.size) return;
      // Upload chunks strictly one after another so the file is appended in order.
      this.#queue = this.#queue.then(() => fetch(url, { method: 'POST', body: data, headers: { authorization: `Bearer ${this.token}` } }))
        .then((res) => { if (!res.ok) throw new Error(`upload failed (${res.status})`); })
        .catch((err) => this.#set(`error: ${err.message}`));
    };
    this.#recorder.onstop = () => this.#queue.then(() => this.#set('idle'));
    this.#recorder.start(2000);
    this.#set('recording');
  }

  stop() { this.#recorder?.state !== 'inactive' && this.#recorder?.stop(); }
  #set(state) { this.state = state; this.onState?.(state); }
}

// Optional end-to-end encryption with a passphrase shared out of band (see the End-to-End Encryption page for real key exchange).
export async function deriveKey(passphrase, room) {
  const material = await crypto.subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, ['deriveKey']);
  return crypto.subtle.deriveKey(
    { name: 'PBKDF2', hash: 'SHA-256', iterations: 310_000, salt: new TextEncoder().encode(`huddle:${room}`) },
    material, { name: 'AES-GCM', length: 128 }, false, ['encrypt', 'decrypt'],
  );
}

export class E2ee {
  constructor(key) { this.key = key; }

  #worker(operation) {
    const worker = new Worker('/e2ee-worker.js');
    worker.postMessage({ type: 'key', key: this.key });
    return new RTCRtpScriptTransform(worker, { operation });
  }

  protect(sender) { sender.transform = this.#worker('encrypt'); }
  unprotect(receiver) { receiver.transform = this.#worker('decrypt'); }

  // Data-channel messages: [12-byte IV][AES-GCM ciphertext].
  async seal(value) {
    const iv = crypto.getRandomValues(new Uint8Array(12));
    const data = new TextEncoder().encode(JSON.stringify(value));
    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, this.key, data));
    const out = new Uint8Array(12 + ct.length);
    out.set(iv);
    out.set(ct, 12);
    return out.buffer;
  }

  async open(buffer) {
    const bytes = new Uint8Array(buffer);
    const plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: bytes.subarray(0, 12) }, this.key, bytes.subarray(12));
    return JSON.parse(new TextDecoder().decode(plain));
  }
}

// Runs one RTCRtpScriptTransform. Frame layout on the wire: [clear header][AES-GCM ciphertext + tag][12-byte IV].
let key = null;
let counter = 0n;
const prefix = crypto.getRandomValues(new Uint8Array(4)); // distinguishes the senders that share one key

onmessage = (event) => { if (event.data.type === 'key') key = event.data.key; };

// Bytes left in the clear so the SFU can still read the codec payload header and detect key frames.
// VP8: 10 bytes on key frames and 3 on delta frames. Opus (audio frames have no type): 1 byte.
const clearBytes = (frame) => (frame.type === 'key' ? 10 : frame.type === 'delta' ? 3 : 1);

async function encryptFrame(frame, controller) {
  if (!key) return; // drop instead of leaking plaintext while no key is installed
  const data = new Uint8Array(frame.data);
  const n = Math.min(clearBytes(frame), data.length);
  const iv = new Uint8Array(12);
  iv.set(prefix);
  new DataView(iv.buffer).setBigUint64(4, counter++);
  const body = new Uint8Array(await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv, additionalData: data.subarray(0, n) }, key, data.subarray(n)));
  const out = new Uint8Array(n + body.length + 12);
  out.set(data.subarray(0, n));
  out.set(body, n);
  out.set(iv, n + body.length);
  frame.data = out.buffer;
  controller.enqueue(frame);
}

async function decryptFrame(frame, controller) {
  if (!key) return;
  const data = new Uint8Array(frame.data);
  const n = clearBytes(frame);
  if (data.length < n + 16 + 12) return; // too short to be one of ours
  const iv = data.subarray(data.length - 12);
  try {
    const plain = new Uint8Array(await crypto.subtle.decrypt(
      { name: 'AES-GCM', iv, additionalData: data.subarray(0, n) }, key, data.subarray(n, data.length - 12)));
    const out = new Uint8Array(n + plain.length);
    out.set(data.subarray(0, n));
    out.set(plain, n);
    frame.data = out.buffer;
    controller.enqueue(frame);
  } catch {
    // Authentication failed: wrong passphrase or tampered frame. Drop it.
  }
}

onrtctransform = ({ transformer }) => {
  const transform = transformer.options.operation === 'encrypt' ? encryptFrame : decryptFrame;
  transformer.readable.pipeThrough(new TransformStream({ transform })).pipeTo(transformer.writable);
};

// DOM helpers: the tile grid, the chat log and the quality badge.
const $ = (id) => document.getElementById(id);

export class Stage {
  tiles = new Map(); // key -> { el, video, stream, name }
  onTileResize = () => {};
  #observer = new ResizeObserver((entries) => {
    for (const { target, contentRect } of entries) this.onTileResize(target.dataset.peer, contentRect.width);
  });

  /** key is "<peerId>:camera" or "<peerId>:screen". */
  tile(key, { name, local = false }) {
    let tile = this.tiles.get(key);
    if (tile) return tile;
    const [peerId, source] = key.split(':');
    const el = document.createElement('figure');
    el.className = `tile ${source}`;
    el.dataset.peer = peerId;
    const video = document.createElement('video');
    video.autoplay = true;
    video.playsInline = true;
    video.muted = local; // never play your own microphone back
    video.setAttribute('aria-label', `${name} ${source === 'screen' ? 'screen' : 'camera'}`);
    const caption = document.createElement('figcaption');
    caption.textContent = source === 'screen' ? `${name} (screen)` : name;
    const badge = document.createElement('span');
    badge.className = 'badge';
    badge.hidden = true;
    caption.append(badge);
    el.append(video, caption);
    $('stage').append(el);
    this.#observer.observe(el);
    tile = { el, video, badge, stream: new MediaStream(), name };
    video.srcObject = tile.stream;
    this.tiles.set(key, tile);
    return tile;
  }

  addTrack(key, track, opts) {
    const tile = this.tile(key, opts);
    tile.stream.addTrack(track);
    tile.video.play().catch(() => {});
  }

  removeTrack(key, kind) {
    const tile = this.tiles.get(key);
    if (!tile) return;
    for (const t of tile.stream.getTracks()) if (t.kind === kind) tile.stream.removeTrack(t);
    if (!tile.stream.getTracks().length) this.removeTile(key);
  }

  removeTile(key) {
    const tile = this.tiles.get(key);
    if (!tile) return;
    this.#observer.unobserve(tile.el);
    tile.el.remove();
    this.tiles.delete(key);
  }

  removePeer(peerId) {
    for (const key of [...this.tiles.keys()]) if (key.startsWith(`${peerId}:`)) this.removeTile(key);
  }

  setMutedBadge(peerId, audioMuted, videoMuted) {
    const tile = this.tiles.get(`${peerId}:camera`);
    if (!tile) return;
    const parts = [audioMuted && 'mic off', videoMuted && 'camera off'].filter(Boolean);
    tile.badge.textContent = parts.join(', ');
    tile.badge.hidden = parts.length === 0;
  }

  setSpeaker(peerId) {
    for (const [key, { el }] of this.tiles) el.classList.toggle('speaking', key === `${peerId}:camera`);
  }
}

export function appendChat(who, text, mine) {
  const li = document.createElement('li');
  li.className = mine ? 'mine' : '';
  const strong = document.createElement('strong');
  strong.textContent = `${who}: `;
  li.append(strong, document.createTextNode(text)); // textContent only: never innerHTML for remote text
  $('log').append(li);
  li.scrollIntoView({ block: 'end' });
}

export function fillSelect(select, devices, current) {
  select.replaceChildren(...devices.map((d) => {
    const option = new Option(d.label, d.id, false, d.id === current);
    return option;
  }));
}

export function showQuality(sample) {
  const el = $('quality');
  el.dataset.score = sample.score;
  const parts = [`quality: ${sample.score === 'unknown' ? 'measuring' : sample.score}`];
  if (sample.rttMs != null) parts.push(`rtt ${Math.round(sample.rttMs)} ms`, `loss ${sample.lossPct.toFixed(1)}%`, `jitter ${Math.round(sample.jitterMs)} ms`);
  if (sample.inKbps != null) parts.push(`down ${Math.round(sample.inKbps)} kbps`, `up ${Math.round(sample.outKbps)} kbps`);
  if (sample.limitation) parts.push(`limited by ${sample.limitation}`);
  el.textContent = parts.join(' | ');
}

export { $ };

// Huddle browser entry point: wires the form, the session (mesh or SFU), the controls and the indicators.
import { openSignaling } from './signaling.js';
import { LocalMedia } from './media.js';
import { MeshSession } from './mesh.js';
import { SfuSession } from './sfu.js';
import { QualityMonitor } from './quality.js';
import { SpeakerDetector } from './speaker.js';
import { LocalRecorder } from './recorder.js';
import { E2ee, deriveKey } from './e2ee.js';
import { Stage, $, appendChat, fillSelect, showQuality } from './ui.js';

const stage = new Stage();
const names = new Map(); // peer id -> display name
const muteState = new Map(); // peer id -> { audio, video }
let session, local, recorder, monitor, speakers;

const params = new URLSearchParams(location.search);
$('name').value = params.get('name') ?? '';
$('room').value = params.get('room') ?? 'standup';
const { modes } = await (await fetch('/api/config')).json();
const LABELS = { mesh: 'Mesh (peer to peer, up to 4)', sfu: 'SFU (mediasoup)', livekit: 'LiveKit' };
$('mode').replaceChildren(...modes.map((m) => new Option(LABELS[m], m)));
$('mode').value = modes.includes(params.get('mode')) ? params.get('mode') : 'mesh';
$('relay').checked = params.get('relay') === '1';
$('passphrase').value = decodeURIComponent(location.hash.replace(/^#key=/, '')); // the fragment never reaches the server

const nameOf = (id) => names.get(id) ?? id;
const setStatus = (text) => { $('status').textContent = text; };

function renderMute(peerId) {
  const s = muteState.get(peerId) ?? {};
  stage.setMutedBadge(peerId, s.audio, s.video);
}

const handlers = {
  peer: (peer) => names.set(peer.id, peer.name),
  peerLeft: (peerId) => {
    stage.removePeer(peerId);
    speakers?.remove(peerId);
    setStatus(`${nameOf(peerId)} left`);
  },
  track: ({ peerId, source, track }) => {
    stage.addTrack(`${peerId}:${source}`, track, { name: nameOf(peerId) });
    if (source === 'camera') {
      renderMute(peerId);
      // Pass the stream that the <video> plays: Chromium feeds Web Audio from a remote stream only then.
      if (track.kind === 'audio') speakers?.add(peerId, stage.tiles.get(`${peerId}:camera`).stream);
    }
  },
  trackEnded: ({ peerId, source, kind }) => stage.removeTrack(`${peerId}:${source}`, kind),
  state: ({ peerId, kind, muted }) => {
    muteState.set(peerId, { ...muteState.get(peerId), [kind]: muted });
    renderMute(peerId);
  },
  speaker: (peerId) => stage.setSpeaker(peerId === session?.peerId ? 'me' : peerId), // the local tile is keyed 'me'
  chat: ({ peerId, text }) => appendChat(nameOf(peerId), text, false),
  linkState: (who, state) => setStatus(`${who}: ${state}`),
  quality: showQuality,
};

async function join() {
  const name = $('name').value.trim();
  const room = $('room').value.trim();
  const mode = $('mode').value;
  $('join').disabled = true;
  try {
    local = new LocalMedia();
    // In a mesh every participant encodes one copy per peer, so ask for a smaller picture.
    await local.start(mode === 'mesh' ? { width: 640, height: 360, frameRate: 24 } : {});
    wireScreenEnd();
    // LiveKit brings its own signalling; the other modes use this application's WebSocket.
    const sig = mode === 'livekit' ? null : await openSignaling(mode, name);
    sig?.on('close', () => setStatus('disconnected from the signalling server: reload to rejoin'));

    const passphrase = $('passphrase').value;
    const e2ee = passphrase ? new E2ee(await deriveKey(passphrase, room)) : null;
    const options = { sig, local, e2ee, on: handlers };
    if (mode === 'sfu') session = new SfuSession(options);
    else if (mode === 'livekit') {
      const { LiveKitSession } = await import('./session-livekit.js'); // loaded on demand: livekit-client is large
      session = new LiveKitSession({ ...options, user: name, passphrase });
    } else session = new MeshSession({ ...options, relayOnly: $('relay').checked });
    if (mode === 'mesh') {
      speakers = new SpeakerDetector((id) => stage.setSpeaker(id));
      speakers.add('me', local.stream);
    }
    stage.onTileResize = (peerId, width) => session.setTileWidth?.(peerId, width);

    names.set('me', name);
    stage.addTrack('me:camera', local.tracks.video, { name: `${name} (you)`, local: true });
    stage.addTrack('me:camera', local.tracks.audio, { name: `${name} (you)`, local: true });
    const joined = await session.join(room);
    names.set(joined.peerId, name);
    $('lobby').hidden = true;
    $('call').hidden = false;
    $('recordButton').disabled = Boolean(e2ee); // a recording would hold plaintext, which defeats E2EE
    setStatus(`in ${room} (${mode}${e2ee ? ', end-to-end encrypted' : ''})`);

    const devices = await local.devices();
    fillSelect($('mic'), devices.audio, local.tracks.audio.getSettings().deviceId);
    fillSelect($('cam'), devices.video, local.tracks.video.getSettings().deviceId);

    if (session.statsSources) {
      monitor = new QualityMonitor(() => session.statsSources(), showQuality);
      monitor.start();
    }
    Object.assign(window, { huddle: { session, local, stage, handlers } }); // handles for debugging and tests
  } catch (err) {
    console.error(err);
    setStatus(`could not join: ${err.message}`);
    $('join').disabled = false;
  }
}

$('join').onclick = join;

for (const kind of ['audio', 'video']) {
  const button = $(kind === 'audio' ? 'muteMic' : 'muteCam');
  button.onclick = async () => {
    const muted = button.getAttribute('aria-pressed') !== 'true';
    button.setAttribute('aria-pressed', String(muted));
    await session.setMuted(kind, muted);
    muteState.set('me', { ...muteState.get('me'), [kind]: muted });
    renderMute('me');
  };
}

async function switchDevice(kind, deviceId) {
  const track = await local.switchDevice(kind === 'audio' ? 'audio' : 'video', deviceId);
  await session.replaceTrack(kind, track);
  stage.removeTrack('me:camera', track.kind);
  stage.addTrack('me:camera', track, { name: names.get('me'), local: true });
}
$('mic').onchange = (e) => switchDevice('audio', e.target.value);
$('cam').onchange = (e) => switchDevice('video', e.target.value);

$('share').onclick = async () => {
  if (local.tracks.screen) return local.stopScreen();
  try {
    const track = await local.startScreen(); // getDisplayMedia needs this click as its user gesture
    stage.addTrack('me:screen', track, { name: names.get('me'), local: true });
    await session.startScreen(track, local.screenStream);
    $('share').setAttribute('aria-pressed', 'true');
  } catch (err) {
    setStatus(`screen sharing failed: ${err.name}`); // NotAllowedError when the picker is dismissed
  }
};
// Fires for the "Stop sharing" button of the browser as well as for our own button.
function wireScreenEnd() {
  local.onScreenEnded = async () => {
    stage.removeTile('me:screen');
    $('share').setAttribute('aria-pressed', 'false');
    await session.stopScreen();
  };
}

$('chatForm').onsubmit = async (event) => {
  event.preventDefault();
  const text = $('chatText').value.trim();
  if (!text) return;
  $('chatText').value = '';
  appendChat('you', text, true);
  await session.sendChat(text);
};

$('recordButton').onclick = async () => {
  if (session.startRecording) { // LiveKit: Egress records on the server
    const on = $('recordButton').getAttribute('aria-pressed') !== 'true';
    await (on ? session.startRecording() : session.stopRecording());
    $('recordButton').setAttribute('aria-pressed', String(on));
    $('recordState').textContent = on ? 'recording' : 'idle';
    return;
  }
  if (recorder?.state === 'recording') return recorder.stop();
  recorder = new LocalRecorder({
    stream: local.stream, room: session.room, peerId: session.peerId, token: session.uploadToken,
    onState: (state) => {
      $('recordButton').setAttribute('aria-pressed', String(state === 'recording'));
      $('recordState').textContent = state;
    },
  });
  recorder.start();
};

$('leave').onclick = () => {
  recorder?.stop();
  monitor?.stop();
  speakers?.close();
  local.stopAll();
  session.close();
  location.reload();
};
window.addEventListener('pagehide', () => session?.close());

FROM node:24-bookworm AS build
# mediasoup compiles its C++ worker when no prebuilt binary runs on the base image, which needs pip and a compiler.
RUN apt-get update && apt-get install -y --no-install-recommends python3-pip build-essential \
    && rm -rf /var/lib/apt/lists/*
ENV PIP_BREAK_SYSTEM_PACKAGES=1
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund
COPY src ./src
COPY public ./public
RUN npm run build && npm prune --omit=dev

FROM node:24-bookworm-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/public ./public
COPY package.json ./
COPY server ./server
# The named volume copies this ownership on first use, so the unprivileged user can write recordings.
RUN mkdir -p /data/recordings && chown node:node /data/recordings
USER node
CMD ["node", "server/main.mjs"]

# Start with:  HOST_IP=<your LAN IP> docker compose up --build
# Stop with:   docker compose down -v
name: huddle

services:
  huddle:
    build: .
    environment:
      HTTP_PORT: "3000"
      RTC_PORT: ${RTC_PORT:-40000}
      ANNOUNCED_ADDRESS: ${HOST_IP:?set HOST_IP to the LAN address of this machine}
      ALLOWED_ORIGINS: http://localhost:${HTTP_PORT:-3000}
      TURN_HOST: ${HOST_IP}
      TURN_PORT: ${TURN_PORT:-3478}
      TURN_SHARED_SECRET: ${TURN_SHARED_SECRET:-example-shared-secret-change-me}
      HUDDLE_TICKET_SECRET: ${HUDDLE_TICKET_SECRET:-change-me-ticket-secret}
      RECORDINGS_DIR: /data/recordings
    volumes:
      - recordings:/data/recordings
    ports:
      - "${HTTP_PORT:-3000}:3000"
      - "${RTC_PORT:-40000}:${RTC_PORT:-40000}/udp"
      - "${RTC_PORT:-40000}:${RTC_PORT:-40000}/tcp"
    restart: unless-stopped

  coturn:
    image: coturn/coturn:4.18.0
    command:
      - "-c"
      - "/etc/coturn/turnserver.conf"
      - "--listening-port=${TURN_PORT:-3478}"
      - "--min-port=${RELAY_MIN:-49160}"
      - "--max-port=${RELAY_MAX:-49200}"
      - "--static-auth-secret=${TURN_SHARED_SECRET:-example-shared-secret-change-me}"
    volumes:
      - ./turnserver.conf:/etc/coturn/turnserver.conf:ro
    ports:
      - "${TURN_PORT:-3478}:${TURN_PORT:-3478}/udp"
      - "${TURN_PORT:-3478}:${TURN_PORT:-3478}/tcp"
      - "${RELAY_MIN:-49160}-${RELAY_MAX:-49200}:${RELAY_MIN:-49160}-${RELAY_MAX:-49200}/udp"
    restart: unless-stopped

volumes:
  recordings:

# coturn 4.18.0 for Huddle. Ports and the shared secret come from the command line (see compose.yaml).
use-auth-secret
realm=huddle.example.test
fingerprint
no-tls
log-file=stdout
simple-log

# A relay must never reach internal services (SSRF protection).
no-multicast-peers
denied-peer-ip=0.0.0.0-0.255.255.255
denied-peer-ip=127.0.0.0-127.255.255.255
denied-peer-ip=169.254.0.0-169.254.255.255
denied-peer-ip=100.64.0.0-100.127.255.255
denied-peer-ip=192.168.0.0-192.168.255.255
denied-peer-ip=10.0.0.0-10.255.255.255
# 172.16.0.0/12 is NOT denied in this lab: the relayed addresses of two browsers live in the Docker network.
# In production add: denied-peer-ip=172.16.0.0-172.31.255.255 and external-ip=<public IP>/<private IP>

user-quota=12
total-quota=1200
max-bps=3000000
stale-nonce=600