@tribe-nest/media-client 0.1.0

package/src/core/signal.ts

@@ -0,0 +1,527 @@
+import {
+  MEDIA_PROTOCOL_VERSION,
+  MediaError,
+  isEvent,
+  serverFrameSchema,
+  type EventFrame,
+  type EventName,
+  type MediaErrorCode,
+  type RequestFrame,
+  type ServerFrame,
+} from "@tribe-nest/media-protocol";
+
+import { SOCKET_OPEN, defaultWebSocketFactory, type MediaWebSocketFactory, type WebSocketLike } from "./socket";
+
+/**
+ * The headless signalling client: one socket, media-protocol frames, nothing
+ * else.
+ *
+ * It owns exactly three things the wire specifies and no policy beyond them:
+ *
+ * 1. **Request/reply correlation.** A request carries an `id` and gets exactly
+ *    one reply with that `id`; an event carries no `id` and is never replied
+ *    to. That is the whole protocol, so it is the whole of this class.
+ * 2. **The handshake.** `join` is the FIRST frame on the socket and carries the
+ *    token. Nothing else may be sent before it.
+ * 3. **Why the connection ended**, as a `DisconnectCause` the reconnect policy
+ *    can decide on. A socket that just closes tells the caller nothing, and
+ *    "the node is draining" and "the room ended" need opposite responses.
+ *
+ * It deliberately does NOT reconnect, hold room state or know what a track is.
+ * Those are `core/reconnect.ts`, `core/state.ts` and P3b's room API.
+ */
+
+/** What a caller must supply to open a connection. Fetched fresh EVERY attempt. */
+export type MediaCoreCredentials = {
+  /** `MEDIA_URL`. The load balancer, never a node address the client picked. */
+  mediaUrl: string;
+  /** A join ticket, minted per attempt. */
+  token: string;
+};
+
+export type SignalLogLevel = "debug" | "warn" | "error";
+
+export type MediaSignalOptions = {
+  /**
+   * Called before EVERY connection attempt, never once at construction.
+   *
+   * A join ticket expires in minutes and a call lasts an hour, so a token
+   * handed over once is a defect rather than a naming choice: the first
+   * reconnect after a network blip would present an expired token.
+   */
+  getCredentials: () => Promise<MediaCoreCredentials> | MediaCoreCredentials;
+  /** Defaults to `globalThis.WebSocket`, resolved lazily. */
+  webSocket?: MediaWebSocketFactory;
+  requestTimeoutMs?: number;
+  joinTimeoutMs?: number;
+  /**
+   * Overridable only so a spec can drive a mismatch. Production always sends
+   * `MEDIA_PROTOCOL_VERSION`.
+   */
+  protocolVersion?: number;
+  onLog?: (level: SignalLogLevel, message: string, detail?: unknown) => void;
+};
+
+export type SignalPhase = "idle" | "connecting" | "joining" | "joined" | "closed";
+
+/**
+ * Why the connection ended.
+ *
+ * The distinctions are the ones a reconnect decision actually turns on: a
+ * drained node must not be retried, a closed room must not be rejoined, and a
+ * refusal carries the code the caller has to show a human.
+ */
+export type DisconnectCause =
+  | { type: "closed_by_client" }
+  | { type: "room_closed"; reason: string }
+  | { type: "draining"; reconnectAfterMs: number }
+  | { type: "refused"; code: MediaErrorCode; message?: string }
+  | { type: "socket_closed"; code?: number; reason?: string };
+
+type JoinedFrame = Extract<EventFrame, { event: "joined" }>;
+
+/** `Omit` over a union collapses it to the common keys, which for a frame union
+ * is just `method`. Distributing keeps every variant's payload. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+
+/**
+ * Everything a caller may send. `join` is absent on purpose: the handshake
+ * belongs to `connect()`, and a second join on a live socket is not something
+ * the protocol has an answer for.
+ */
+export type SignalRequest = DistributiveOmit<Exclude<RequestFrame, { method: "join" }>, "id">;
+
+type Pending = {
+  resolve: (data: unknown) => void;
+  reject: (error: unknown) => void;
+  timer: ReturnType<typeof setTimeout> | null;
+  method: string;
+};
+
+type AnyHandler = (frame: EventFrame) => void;
+type CloseHandler = (cause: DisconnectCause) => void;
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_JOIN_TIMEOUT_MS = 10_000;
+
+/**
+ * A join ticket in a URL is a join ticket in every access log between the
+ * client and the node, and load balancers log query strings by default. The
+ * contract puts the token in the first frame; this refuses a URL that looks
+ * like someone routed around that.
+ */
+export function assertTokenNotInUrl(mediaUrl: string): void {
+  let url: URL;
+  try {
+    url = new URL(mediaUrl);
+  } catch {
+    throw new Error(`mediaUrl is not a URL: ${mediaUrl}`);
+  }
+  for (const key of url.searchParams.keys()) {
+    if (/token|jwt|ticket|auth/i.test(key)) {
+      throw new Error(`refusing to connect: mediaUrl carries "${key}" in the query string. The token goes in the first frame.`);
+    }
+  }
+}
+
+/** Maps a thrown error back to the cause the reconnect policy decides on. */
+export function causeFromError(error: unknown): DisconnectCause {
+  if (error instanceof MediaError) {
+    return { type: "refused", code: error.code, message: error.message };
+  }
+  return { type: "socket_closed", reason: error instanceof Error ? error.message : String(error) };
+}
+
+export class MediaSignal {
+  private readonly options: MediaSignalOptions;
+  private socket: WebSocketLike | null = null;
+  private nextId = 0;
+  private readonly pending = new Map<number, Pending>();
+  private readonly handlers = new Map<EventName, Set<(frame: EventFrame) => void>>();
+  private readonly anyHandlers = new Set<AnyHandler>();
+  private readonly closeHandlers = new Set<CloseHandler>();
+  /** Set by the events that explain a close BEFORE the socket goes away. */
+  private terminalCause: DisconnectCause | null = null;
+  private phaseValue: SignalPhase = "idle";
+  private identityValue: string | null = null;
+  private joinedResolve: ((frame: JoinedFrame) => void) | null = null;
+  private connectReject: ((error: unknown) => void) | null = null;
+  /**
+   * Which connection attempt is the current one.
+   *
+   * `connect()` awaits `getCredentials()` before it has a socket, and until that
+   * socket exists there is nothing for `close()` to close: it flips the phase
+   * and returns. So the attempt is stamped and re-checked, and an attempt that
+   * is no longer the current one abandons itself instead of opening a socket
+   * and JOINING with a live token that nothing then holds a reference to.
+   */
+  private attempt = 0;
+  private boundClose: ((event: { code?: number; reason?: string }) => void) | null = null;
+
+  constructor(options: MediaSignalOptions) {
+    this.options = options;
+  }
+
+  get phase(): SignalPhase {
+    return this.phaseValue;
+  }
+
+  /** Our own identity, as the node reported it in `joined`. */
+  get identity(): string | null {
+    return this.identityValue;
+  }
+
+  /**
+   * Opens the socket, sends `join` as the first frame, and resolves once BOTH
+   * the join reply and the `joined` event have arrived.
+   *
+   * Waiting for both is deliberate. The reply says the node accepted the token;
+   * the event carries `routerRtpCapabilities`, the peer snapshot and the
+   * recording flag. A caller that resolved on the reply alone would be handed a
+   * room it knows nothing about, and the contract fixes no order between the
+   * two frames, so neither may be assumed to arrive first.
+   */
+  async connect(): Promise<JoinedFrame> {
+    if (this.phaseValue === "connecting" || this.phaseValue === "joining" || this.phaseValue === "joined") {
+      throw new Error("connect() called on a signal that is already connecting or connected");
+    }
+    this.resetForConnect();
+    const attempt = ++this.attempt;
+    this.phaseValue = "connecting";
+
+    const credentials = await this.options.getCredentials();
+    // Fetching a ticket is a network round trip of its own, so this window is
+    // seconds wide and a caller giving up inside it is ordinary. Every later
+    // step has a socket and is cancelled by `handleClose`; this one is the only
+    // part of a connect that a `close()` could not reach.
+    this.assertAttemptIsCurrent(attempt);
+    assertTokenNotInUrl(credentials.mediaUrl);
+
+    const factory = this.options.webSocket ?? defaultWebSocketFactory;
+    const socket = factory(credentials.mediaUrl);
+    this.socket = socket;
+    this.bind(socket);
+
+    try {
+      await this.waitForOpen(socket);
+      this.phaseValue = "joining";
+      const joined = await this.performJoin(credentials.token);
+      this.phaseValue = "joined";
+      this.identityValue = joined.identity;
+      return joined;
+    } catch (error) {
+      // A failed handshake leaves nothing worth keeping open, and the cause is
+      // recorded first so close handlers see the refusal rather than a bare
+      // socket close.
+      if (!this.terminalCause) this.terminalCause = causeFromError(error);
+      this.closeSocket();
+      throw error;
+    }
+  }
+
+  /**
+   * Sends a request and resolves with its `data`.
+   *
+   * `unknown`, not a guessed shape: the wire declares `data: unknown` because
+   * most of it is mediasoup's, and a client that pretends otherwise is asserting
+   * a contract this package does not hold.
+   */
+  request(frame: SignalRequest, timeoutMs?: number): Promise<unknown> {
+    const socket = this.socket;
+    if (!socket || this.phaseValue === "closed" || this.phaseValue === "idle") {
+      return Promise.reject(new MediaError("internal", `cannot send ${frame.method}: the signal connection is ${this.phaseValue}`));
+    }
+    const id = this.nextId++;
+    const promise = this.track(id, frame.method, timeoutMs ?? this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+    try {
+      this.send({ ...frame, id } as RequestFrame);
+    } catch (error) {
+      // A socket that died between the check and the send must reject this
+      // call, not throw past a `.catch()` the caller reasonably attached.
+      this.settle(id, error);
+    }
+    return promise;
+  }
+
+  /**
+   * Best-effort `leave` then close.
+   *
+   * Best-effort because the node tears the session down on socket close anyway.
+   * A leave that hangs must not stop a user closing a tab.
+   */
+  async leave(): Promise<void> {
+    if (this.phaseValue === "joined") {
+      try {
+        await this.request({ method: "leave" });
+      } catch (error) {
+        this.log("debug", "leave was not acknowledged; closing anyway", error);
+      }
+    }
+    this.close();
+  }
+
+  /** Closes the socket. Idempotent. */
+  close(): void {
+    if (!this.terminalCause) this.terminalCause = { type: "closed_by_client" };
+    this.closeSocket();
+  }
+
+  on<K extends EventName>(event: K, handler: (frame: Extract<EventFrame, { event: K }>) => void): () => void {
+    const set = this.handlers.get(event) ?? new Set();
+    const erased = handler as (frame: EventFrame) => void;
+    set.add(erased);
+    this.handlers.set(event, set);
+    return () => {
+      set.delete(erased);
+    };
+  }
+
+  /** Every event, in arrival order. This is what the state reducer is fed. */
+  onAny(handler: AnyHandler): () => void {
+    this.anyHandlers.add(handler);
+    return () => {
+      this.anyHandlers.delete(handler);
+    };
+  }
+
+  onClose(handler: CloseHandler): () => void {
+    this.closeHandlers.add(handler);
+    return () => {
+      this.closeHandlers.delete(handler);
+    };
+  }
+
+  // ---------------------------------------------------------------- internals
+
+  /**
+   * Throws when this attempt has been overtaken: either `close()` ran, or a
+   * second `connect()` started (which the entry guard permits once the phase is
+   * `closed`, so an abandoned attempt must not go on to open a second socket).
+   */
+  private assertAttemptIsCurrent(attempt: number): void {
+    if (attempt === this.attempt && this.phaseValue !== "closed") return;
+    throw new MediaError("internal", "connect() was abandoned: the connection was closed before the socket was opened");
+  }
+
+  private resetForConnect(): void {
+    this.terminalCause = null;
+    this.identityValue = null;
+    this.joinedResolve = null;
+    this.connectReject = null;
+    this.pending.clear();
+    this.nextId = 0;
+  }
+
+  private bind(socket: WebSocketLike): void {
+    socket.addEventListener("message", (event) => this.handleMessage(event.data));
+    socket.addEventListener("error", (event) => this.log("warn", "signal socket error", event.error));
+    const onClose = (event: { code?: number; reason?: string }) => this.handleClose(event);
+    this.boundClose = onClose;
+    socket.addEventListener("close", onClose);
+  }
+
+  private waitForOpen(socket: WebSocketLike): Promise<void> {
+    if (socket.readyState === SOCKET_OPEN) return Promise.resolve();
+    return new Promise<void>((resolve, reject) => {
+      this.connectReject = reject;
+      const onOpen = () => {
+        socket.removeEventListener("open", onOpen);
+        this.connectReject = null;
+        resolve();
+      };
+      socket.addEventListener("open", onOpen);
+    });
+  }
+
+  private async performJoin(token: string): Promise<JoinedFrame> {
+    const id = this.nextId++;
+    const timeoutMs = this.options.joinTimeoutMs ?? DEFAULT_JOIN_TIMEOUT_MS;
+    const reply = this.track(id, "join", timeoutMs);
+    const joined = new Promise<JoinedFrame>((resolve, reject) => {
+      this.joinedResolve = resolve;
+      // The same rejection path as the reply: a socket that dies mid-handshake
+      // must not leave `connect()` hanging until the join timeout.
+      const previous = this.connectReject;
+      this.connectReject = (error) => {
+        previous?.(error);
+        reject(error);
+      };
+    });
+
+    this.send({
+      method: "join",
+      id,
+      protocolVersion: this.options.protocolVersion ?? MEDIA_PROTOCOL_VERSION,
+      token,
+    });
+
+    const [, joinedFrame] = await Promise.all([reply, this.withDeadline(joined, timeoutMs, "joined")]);
+    return joinedFrame;
+  }
+
+  private withDeadline<T>(promise: Promise<T>, ms: number, what: string): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        // No `timeout` code exists in the frozen error union, so this reports
+        // `internal` and says what timed out in the message.
+        reject(new MediaError("internal", `timed out waiting for ${what} after ${ms}ms`));
+      }, ms);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      );
+    });
+  }
+
+  private track(id: number, method: string, timeoutMs: number): Promise<unknown> {
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new MediaError("internal", `no reply to ${method} (id ${id}) after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer, method });
+    });
+  }
+
+  private settle(id: number, error: unknown): void {
+    const pending = this.pending.get(id);
+    if (!pending) return;
+    this.pending.delete(id);
+    if (pending.timer) clearTimeout(pending.timer);
+    pending.reject(error);
+  }
+
+  private send(frame: RequestFrame): void {
+    const socket = this.socket;
+    if (!socket) throw new MediaError("internal", "no socket");
+    socket.send(JSON.stringify(frame));
+  }
+
+  private handleMessage(data: unknown): void {
+    const text = toText(data);
+    if (text === null) {
+      this.log("warn", "dropping a non-text signal frame");
+      return;
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      this.log("warn", "dropping an unparseable signal frame");
+      return;
+    }
+    const parsed = serverFrameSchema.safeParse(raw);
+    if (!parsed.success) {
+      // Dropped, not thrown: a node that gains a frame in a later protocol
+      // version must not kill an older client's live call. A real mismatch is
+      // caught by the version handshake, loudly, at join.
+      this.log("warn", "dropping a frame that does not match the protocol", raw);
+      return;
+    }
+    this.dispatch(parsed.data);
+  }
+
+  private dispatch(frame: ServerFrame): void {
+    if (isEvent(frame)) {
+      this.handleEvent(frame);
+      return;
+    }
+    const pending = this.pending.get(frame.id);
+    if (!pending) {
+      // Either a second reply to one id or a reply to a request that already
+      // timed out. Both are protocol violations by the node, so they are said
+      // out loud rather than absorbed.
+      this.log("warn", `reply for unknown request id ${frame.id}`, frame);
+      return;
+    }
+    this.pending.delete(frame.id);
+    if (pending.timer) clearTimeout(pending.timer);
+    if (frame.ok) {
+      pending.resolve(frame.data);
+    } else {
+      pending.reject(new MediaError(frame.code, frame.message ?? `${pending.method} refused: ${frame.code}`));
+    }
+  }
+
+  private handleEvent(frame: EventFrame): void {
+    switch (frame.event) {
+      case "joined":
+        this.identityValue = frame.identity;
+        this.joinedResolve?.(frame);
+        this.joinedResolve = null;
+        break;
+      case "draining":
+        // Recorded now because the node closes the socket next, and by then the
+        // reason is gone. Reconnecting to this node is precisely wrong.
+        this.terminalCause = { type: "draining", reconnectAfterMs: frame.reconnectAfterMs };
+        break;
+      case "roomClosed":
+        this.terminalCause = { type: "room_closed", reason: frame.reason };
+        break;
+      default:
+        break;
+    }
+
+    for (const handler of this.handlers.get(frame.event) ?? []) handler(frame);
+    for (const handler of this.anyHandlers) handler(frame);
+  }
+
+  private handleClose(event: { code?: number; reason?: string }): void {
+    if (this.phaseValue === "closed") return;
+    this.phaseValue = "closed";
+    const cause: DisconnectCause = this.terminalCause ?? {
+      type: "socket_closed",
+      ...(event.code === undefined ? {} : { code: event.code }),
+      ...(event.reason === undefined ? {} : { reason: event.reason }),
+    };
+
+    const closedError = new MediaError("internal", `signal connection closed before a reply arrived (${cause.type})`);
+    for (const [, pending] of this.pending) {
+      if (pending.timer) clearTimeout(pending.timer);
+      pending.reject(closedError);
+    }
+    this.pending.clear();
+
+    this.connectReject?.(closedError);
+    this.connectReject = null;
+    this.joinedResolve = null;
+
+    for (const handler of this.closeHandlers) handler(cause);
+  }
+
+  private closeSocket(): void {
+    const socket = this.socket;
+    if (!socket) {
+      // Nothing was ever opened, so no close event will arrive to settle
+      // pending work. Settle it here.
+      if (this.phaseValue !== "closed") this.handleClose({});
+      return;
+    }
+    this.socket = null;
+    try {
+      socket.close(1000, "client");
+    } catch (error) {
+      this.log("debug", "socket.close threw", error);
+    }
+    if (this.boundClose) socket.removeEventListener("close", this.boundClose);
+    this.boundClose = null;
+    this.handleClose({ code: 1000 });
+  }
+
+  private log(level: SignalLogLevel, message: string, detail?: unknown): void {
+    this.options.onLog?.(level, message, detail);
+  }
+}
+
+function toText(data: unknown): string | null {
+  if (typeof data === "string") return data;
+  if (data instanceof Uint8Array) return new TextDecoder().decode(data);
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(new Uint8Array(data));
+  return null;
+}

package/src/core/socket.ts

@@ -0,0 +1,58 @@
+/**
+ * The one WebSocket shape `core/` knows about.
+ *
+ * Four hosts have to drive this client and no two of them have the same socket:
+ * a browser has the DOM one, Node 24 has a global `WebSocket`, older Node
+ * services carry `ws`, and the load harness may want a socket that lies about
+ * latency. Rather than branch on the environment, `core/` takes a factory and
+ * never constructs anything itself.
+ *
+ * The listener style is `addEventListener`, because that is the intersection:
+ * the browser, Node's global and the `ws` package all provide it, while only
+ * `ws` provides `.on()`.
+ */
+
+export const SOCKET_CONNECTING = 0;
+export const SOCKET_OPEN = 1;
+export const SOCKET_CLOSING = 2;
+export const SOCKET_CLOSED = 3;
+
+export type SocketOpenEvent = { type: "open" };
+export type SocketMessageEvent = { type: "message"; data: unknown };
+export type SocketErrorEvent = { type: "error"; error?: unknown };
+export type SocketCloseEvent = { type: "close"; code?: number; reason?: string };
+
+export type SocketEventMap = {
+  open: SocketOpenEvent;
+  message: SocketMessageEvent;
+  error: SocketErrorEvent;
+  close: SocketCloseEvent;
+};
+
+export interface WebSocketLike {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  addEventListener<K extends keyof SocketEventMap>(type: K, listener: (event: SocketEventMap[K]) => void): void;
+  removeEventListener<K extends keyof SocketEventMap>(type: K, listener: (event: SocketEventMap[K]) => void): void;
+}
+
+export type MediaWebSocketFactory = (url: string) => WebSocketLike;
+
+/**
+ * Resolves `globalThis.WebSocket` at CALL time, never at module load.
+ *
+ * Reading it at module scope would make importing this package fail outright in
+ * a host that has no global socket but was going to pass its own factory, and
+ * "importing a type broke my service" is the class of problem the isomorphic
+ * split exists to prevent.
+ */
+export function defaultWebSocketFactory(url: string): WebSocketLike {
+  const ctor = (globalThis as { WebSocket?: new (url: string) => unknown }).WebSocket;
+  if (!ctor) {
+    throw new Error(
+      "no global WebSocket in this runtime. Pass `webSocket: (url) => new WS(url)` to the signal client.",
+    );
+  }
+  return new ctor(url) as unknown as WebSocketLike;
+}