@tribe-nest/media-protocol 1.0.0

package/src/claims.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { mediaGrantsSchema, participantKindSchema, transportKindSchema } from "./grants";
+
+/**
+ * The join token's claims: the whole authorization decision, made once by the
+ * backend and carried to a media plane that never asks it anything.
+ *
+ * Names here were contested by the parallel phase plans; each disagreement is
+ * resolved once, in this file, and everything else imports it.
+ */
+
+/**
+ * The longest display name a join token may carry.
+ *
+ * Exported because it is a MINT-TIME refusal, not a preference: `signJoinToken`
+ * hard-parses these claims, so a caller that builds a name out of stored text
+ * and does not clamp it throws instead of minting. Every such caller has to
+ * know the bound, and a caller that hard-codes 200 is a caller that will not
+ * follow this number if it ever moves.
+ */
+export const MEDIA_PARTICIPANT_NAME_MAX_LENGTH = 200;
+
+/**
+ * A display name cut to what a token may carry.
+ *
+ * Lives HERE, beside the bound it enforces, rather than in each surface that
+ * mints. Two reasons, and the second is the one that matters.
+ *
+ * A minting surface builds the name out of stored text (a buyer's name off a
+ * booking, a seat's display name off a roster) and cannot promise a length, so
+ * every one of them needs this. And a surface that instead compared against the
+ * exported NUMBER would go silently unclamped the moment it read a stale build
+ * of this package: `value.length > undefined` is `false`, so the clamp
+ * evaporates and the failure only shows up as a 500 from `signJoinToken` in
+ * production. A missing FUNCTION throws on the first call instead.
+ *
+ * Truncation rather than refusal is deliberate. A name is a label on a tile,
+ * and no call should fail to open over one.
+ */
+export function clampParticipantName(value: string): string {
+  return value.length > MEDIA_PARTICIPANT_NAME_MAX_LENGTH ? value.slice(0, MEDIA_PARTICIPANT_NAME_MAX_LENGTH) : value;
+}
+
+/**
+ * `iss` IS the instance id (`legal-de`, `main`), not a service name.
+ *
+ * One plan proposed `iss: "tribenest-backend"` with the instance in a separate
+ * `inst` claim. That displaces the one value a verifier actually checks, and a
+ * legal-de token would then verify happily on the main instance - which is the
+ * whole reason instances are separate.
+ */
+export const mediaJoinClaimsSchema = z
+  .object({
+    v: z.literal(1),
+    iss: z.string().min(1),
+    aud: z.literal("media"),
+    room: z.string().min(1).max(200),
+    /** `identity`, not `sub`: it is a first-class concept the barrier rules name. */
+    identity: z.string().min(1).max(200),
+    name: z.string().max(MEDIA_PARTICIPANT_NAME_MAX_LENGTH).optional(),
+    /** Top level, NOT inside grants - it decides what may be minted at all. */
+    kind: participantKindSchema,
+    /** Top level. Transport authority is not media authority. */
+    transport: transportKindSchema,
+    grants: mediaGrantsSchema,
+    jti: z.string().min(8),
+    iat: z.number().int().positive(),
+    nbf: z.number().int().positive().optional(),
+    exp: z.number().int().positive(),
+  })
+  .strict();
+
+export type MediaJoinClaims = z.infer<typeof mediaJoinClaimsSchema>;
+
+/**
+ * Server-to-server control calls (create room, end room, attach an agent).
+ *
+ * A separate audience so a join token can never be replayed as a control call.
+ * It carries no room, identity, kind, transport or grants: a control caller is
+ * not a participant, and giving it participant-shaped claims invites code that
+ * treats it as one.
+ */
+export const mediaControlClaimsSchema = z
+  .object({
+    v: z.literal(1),
+    iss: z.string().min(1),
+    aud: z.literal("control"),
+    jti: z.string().min(8),
+    iat: z.number().int().positive(),
+    nbf: z.number().int().positive().optional(),
+    exp: z.number().int().positive(),
+  })
+  .strict();
+
+export type MediaControlClaims = z.infer<typeof mediaControlClaimsSchema>;
+
+/**
+ * Why a token was refused.
+ *
+ * Deliberately granular for the SERVER's logs and deliberately NOT returned to
+ * the client, which gets `unauthorized` and nothing else. Telling a caller
+ * whether the signature or the room was wrong is an oracle.
+ */
+export type JoinTokenRejection =
+  | "malformed"
+  | "unknown_kid"
+  | "bad_signature"
+  | "expired"
+  | "not_yet_valid"
+  | "ttl_too_long"
+  | "wrong_audience"
+  | "wrong_issuer"
+  | "wrong_room"
+  | "bad_claims";
+
+export type VerifyResult<T> = { ok: true; claims: T; kid: string } | { ok: false; reason: JoinTokenRejection };

package/src/codecs.ts

@@ -0,0 +1,165 @@
+/**
+ * THE codec list. Every Router in the fleet is created from this array and no
+ * other, and every server-side participant derives what it can receive FROM it.
+ *
+ * ## Why it is pinned rather than left to mediasoup's defaults
+ *
+ * Two Routers that disagree about codecs cannot be piped. `pipeToRouter` and
+ * the hand-rolled equivalent in the node's `pipe.ts` both require the receiving
+ * Router to be able to consume the producer, and "able" is decided by this
+ * list. A node booted from a different build with one extra codec still pipes
+ * fine until the day a client happens to negotiate that codec, and then exactly
+ * one leg of one room goes silent, which reads as a network fault.
+ *
+ * So the list lives in one place and every Router in the fleet is created from
+ * it. A change here is a fleet-wide change and a deploy that mixes versions is
+ * a deploy that mixes codec sets, which is why `DEPLOYMENT.md` says drain
+ * before upgrade rather than rolling.
+ *
+ * ## Why it lives in the PROTOCOL package
+ *
+ * The node is not the only party that has to agree. A room agent, the SIP
+ * gateway and the RTMP ingress are participants, not nodes: each one has to
+ * declare RTP capabilities on `consume`, each one runs in its own app, and none
+ * of them may import `apps/media-server`. Every phase that needed this list
+ * from outside the node had exactly one alternative, which is to write a second
+ * copy - and a second copy is the failure the pinning exists to prevent. The
+ * earlier agent plan proved it: its contract test compared two hand-written
+ * lists to EACH OTHER and never to this one, so both could drift together and
+ * stay green.
+ *
+ * Codec agreement is a wire contract between parties that cannot import each
+ * other, which is the same reason the frames and the claims are here.
+ *
+ * ## Zero mediasoup, deliberately
+ *
+ * The types below are declared structurally rather than imported from
+ * mediasoup, because this package is isomorphic and a browser must be able to
+ * import a frame type without pulling in a C++ addon. `apps/media-server`
+ * re-exports these values through explicitly mediasoup-typed bindings, so if
+ * the two shapes ever diverge the node fails to COMPILE rather than failing to
+ * pipe at three in the morning.
+ *
+ * ## What is in it, and what is deliberately not
+ *
+ * Opus for audio, because it is the only audio codec every browser publishes
+ * and the only one worth transcoding to for SIP and for agents.
+ *
+ * VP8 and H.264 for video. VP8 is universal and simple; H.264 is what Safari
+ * and every hardware encoder produce, and its absence is not a quality loss but
+ * a "video does not work on iPhone" bug. Both are listed with the RTCP feedback
+ * mediasoup needs for keyframes and bandwidth estimation: `nack`, `pli` and
+ * `transport-cc`. Drop `pli` and a keyframe request has no wire representation,
+ * so every active-speaker switch shows macroblocks until the encoder happens to
+ * send an IDR on its own schedule.
+ *
+ * VP9 and AV1 are deliberately absent. Both are real wins and both are a
+ * separate decision with a measurement behind it: SVC changes what
+ * `setPreferredLayers` means, and adding a codec that only some clients
+ * negotiate widens the "one leg is silent" surface above.
+ */
+
+export type MediaKind = "audio" | "video";
+
+export type MediaRtcpFeedback = { type: string; parameter?: string };
+
+/** Structurally identical to mediasoup's `RouterRtpCodecCapability`. */
+export type MediaCodecCapability = {
+  kind: MediaKind;
+  mimeType: string;
+  clockRate: number;
+  channels?: number;
+  parameters?: Record<string, unknown>;
+  rtcpFeedback?: MediaRtcpFeedback[];
+  preferredPayloadType?: number;
+};
+
+/** Structurally identical to mediasoup's `RtpCapabilities`. */
+export type MediaRtpCapabilities = {
+  codecs: Array<MediaCodecCapability & { preferredPayloadType: number }>;
+  /**
+   * Always empty, and typed as the empty tuple rather than an array of some
+   * element type.
+   *
+   * A server-side participant declares no header extensions: it reads the RTP
+   * header itself and wants nothing negotiated on top of it. Typing it this way
+   * also means this package never has to describe mediasoup's header-extension
+   * union in order for the node's mediasoup-typed re-export to stay assignable.
+   */
+  headerExtensions: [];
+};
+
+export const MEDIA_CODECS: MediaCodecCapability[] = [
+  {
+    kind: "audio",
+    mimeType: "audio/opus",
+    clockRate: 48000,
+    channels: 2,
+    parameters: {
+      // In-band FEC costs a little bandwidth and buys intelligibility across
+      // exactly the packet loss a consultation is likely to hit.
+      useinbandfec: 1,
+    },
+  },
+  {
+    kind: "video",
+    mimeType: "video/VP8",
+    clockRate: 90000,
+    parameters: {},
+    rtcpFeedback: [
+      { type: "nack" },
+      { type: "nack", parameter: "pli" },
+      { type: "ccm", parameter: "fir" },
+      { type: "goog-remb" },
+      { type: "transport-cc" },
+    ],
+  },
+  {
+    kind: "video",
+    mimeType: "video/H264",
+    clockRate: 90000,
+    parameters: {
+      // Constrained baseline, level 3.1. `packetization-mode: 1` is what every
+      // browser actually offers; mode 0 exists and nothing sends it.
+      "packetization-mode": 1,
+      "profile-level-id": "42e01f",
+      // Without this Chrome offers H.264 and then never sends a parameter set
+      // out of band, so a late joiner sees nothing until the next IDR.
+      "level-asymmetry-allowed": 1,
+    },
+    rtcpFeedback: [
+      { type: "nack" },
+      { type: "nack", parameter: "pli" },
+      { type: "ccm", parameter: "fir" },
+      { type: "goog-remb" },
+      { type: "transport-cc" },
+    ],
+  },
+];
+
+/**
+ * The audio half, for a participant that has no video at all.
+ *
+ * DERIVED, never written beside the list above. A hand-written copy for agents
+ * and SIP was compared against another hand-written copy in an earlier plan and
+ * never against this list, which is precisely the drift the pinning exists to
+ * prevent: both copies agree with each other and neither agrees with the fleet.
+ */
+export function audioOnlyCapabilities(codecs: MediaCodecCapability[] = MEDIA_CODECS): MediaRtpCapabilities {
+  return {
+    codecs: codecs
+      .filter((c) => c.kind === "audio")
+      .map((c, index) => ({
+        kind: "audio" as const,
+        mimeType: c.mimeType,
+        clockRate: c.clockRate,
+        ...(c.channels ? { channels: c.channels } : {}),
+        ...(c.parameters ? { parameters: c.parameters } : {}),
+        ...(c.rtcpFeedback ? { rtcpFeedback: c.rtcpFeedback } : {}),
+        // Dynamic range. mediasoup assigns the real value per Router; this is
+        // only what a server-side participant claims it can receive.
+        preferredPayloadType: c.preferredPayloadType ?? 100 + index,
+      })),
+    headerExtensions: [],
+  };
+}

package/src/errorSchema.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import { MEDIA_ERROR_CODES } from "./errors";
+
+/**
+ * Separate from `errors.ts` so that file stays a plain union with no zod
+ * import, and so `frames.ts` can validate a code without a circular import
+ * through the error class.
+ */
+export const mediaErrorCodeSchema = z.enum(MEDIA_ERROR_CODES);

package/src/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Every way the media plane refuses, named once.
+ *
+ * A closed union rather than free-text messages, because three surfaces (the
+ * SDK, the harness, the egress client) branch on these, and a string compare
+ * against prose drifts the moment someone improves the wording.
+ */
+export const MEDIA_ERROR_CODES = [
+  // token / session
+  "unauthorized",          // token missing, malformed, or rejected
+  "replayed",              // jti already consumed (a session concern, not a verifier one)
+  "protocol_version",      // client and node disagree on MEDIA_PROTOCOL_VERSION
+  "forbidden_transport",   // token's `transport` claim does not permit this transport kind
+  // authorization
+  "forbidden",             // grants do not permit this operation
+  "not_subscribable",      // maySubscribe said no - an information barrier, not an error
+  "subscription_limit",    // maxSubscriptions or the active-set ceiling
+  // state
+  "room_closed",
+  "no_such_room",
+  "no_such_producer",
+  "no_such_transport",
+  "duplicate_identity",    // that identity is already connected to this room
+  // capacity / lifecycle
+  "node_draining",         // reconnect via the URL; the LB or a redirect will place you
+  "capacity",
+  // catch-alls
+  "bad_request",
+  "internal",
+] as const;
+
+export type MediaErrorCode = (typeof MEDIA_ERROR_CODES)[number];
+
+export class MediaError extends Error {
+  constructor(
+    public readonly code: MediaErrorCode,
+    message?: string,
+    /** Safe to show a user? Most of these are not. */
+    public readonly retryable = false,
+  ) {
+    super(message ?? code);
+    this.name = "MediaError";
+  }
+}

package/src/frames.ts

@@ -0,0 +1,234 @@
+import { z } from "zod";
+import { mediaErrorCodeSchema } from "./errorSchema";
+import { mediaGrantsSchema, participantKindSchema, subscribeRuleSchema } from "./grants";
+
+/**
+ * The client <-> node signalling wire.
+ *
+ * One envelope, stated once. Six phase plans independently invented four
+ * different ones (`m` / `type` / `method` / `action`, numeric versus string
+ * ids, `result` versus `data`), and every mismatch is a hard parse failure
+ * discovered at integration by a different pair of people.
+ *
+ * ## Shape
+ *
+ * Requests carry an `id` and get exactly one reply with the same `id`. Events
+ * carry no `id` and are never replied to. That is the whole protocol; anything
+ * needing more structure is a request that returns a handle.
+ *
+ * ## What is deliberately NOT here
+ *
+ * No pipe verb, no node id, no mesh address. A client cannot express "pipe this
+ * producer to that node", because piping is a side effect of `consume` and the
+ * only way to keep it lazy is for eager piping to be unsayable.
+ */
+
+export const requestFrameSchema = z.discriminatedUnion("method", [
+  z.object({
+    method: z.literal("join"),
+    id: z.number().int().nonnegative(),
+    protocolVersion: z.number().int(),
+    /** The token travels in the first frame, NEVER in the URL: a query string
+     * lands in load-balancer access logs, and a join ticket in a log is a join
+     * ticket for anyone who can read logs. */
+    token: z.string().min(1),
+  }),
+  z.object({
+    method: z.literal("createTransport"),
+    id: z.number().int().nonnegative(),
+    direction: z.enum(["send", "recv"]),
+    /**
+     * Deliberately absent: which KIND of transport this is.
+     *
+     * The kind comes from the token's `transport` claim and from nowhere else.
+     * Letting a client ask would mean a browser holding a valid join token
+     * could request a PlainTransport pointed at an address of its choosing -
+     * an RTP reflector, plus an unauthenticated publish path into whatever room
+     * the token names. Three phases independently needed to refuse that and
+     * none could, because nothing carried the fact.
+     *
+     * So there is no field here to refuse. The claim decides.
+     */
+    sctp: z.boolean().optional(),
+  }),
+  z.object({
+    method: z.literal("connectTransport"),
+    id: z.number().int().nonnegative(),
+    transportId: z.string(),
+    /** WebRTC. */
+    dtlsParameters: z.unknown().optional(),
+    /**
+     * Plain and pipe transports have no DTLS handshake to carry the address, so
+     * a server-side participant names where its RTP comes from. This is the
+     * half the token claim cannot cover: the claim says WHO may create a plain
+     * transport, and `MEDIA_SERVER_PEER_CIDRS` says WHERE its media may be
+     * pointed. Both are required; either alone leaves a reflector.
+     */
+    ip: z.string().optional(),
+    port: z.number().int().positive().max(65535).optional(),
+    rtcpPort: z.number().int().positive().max(65535).optional(),
+    srtpParameters: z.unknown().optional(),
+  }),
+  z.object({
+    method: z.literal("produce"),
+    id: z.number().int().nonnegative(),
+    transportId: z.string(),
+    kind: z.enum(["audio", "video"]),
+    /** Opaque to this package: only mediasoup interprets it. */
+    rtpParameters: z.unknown(),
+    appData: z.record(z.unknown()).optional(),
+  }),
+  z.object({
+    method: z.literal("consume"),
+    id: z.number().int().nonnegative(),
+    transportId: z.string(),
+    producerId: z.string(),
+    rtpCapabilities: z.unknown(),
+  }),
+  z.object({
+    method: z.literal("pauseProducer"),
+    id: z.number().int().nonnegative(),
+    producerId: z.string(),
+  }),
+  z.object({
+    method: z.literal("resumeProducer"),
+    id: z.number().int().nonnegative(),
+    producerId: z.string(),
+  }),
+  z.object({
+    method: z.literal("resumeConsumer"),
+    id: z.number().int().nonnegative(),
+    consumerId: z.string(),
+  }),
+  /**
+   * Drop a subscription.
+   *
+   * Needed because the active set CHURNS: as the conversation moves, a client
+   * following it stops wanting producers it wanted a moment ago. Closing only
+   * the client's own consumer leaves the node holding a Consumer object per
+   * dropped subscription, and in a large room that accumulates for the life of
+   * the call - on the node, which is the side with the ceiling.
+   */
+  z.object({
+    method: z.literal("closeConsumer"),
+    id: z.number().int().nonnegative(),
+    consumerId: z.string(),
+  }),
+  z.object({
+    method: z.literal("closeProducer"),
+    id: z.number().int().nonnegative(),
+    producerId: z.string(),
+  }),
+  /** A keyframe request. Without it every active-speaker switch shows garbage
+   * until the encoder happens to send one. */
+  z.object({
+    method: z.literal("requestKeyFrame"),
+    id: z.number().int().nonnegative(),
+    consumerId: z.string(),
+  }),
+  z.object({ method: z.literal("leave"), id: z.number().int().nonnegative() }),
+]);
+
+export type RequestFrame = z.infer<typeof requestFrameSchema>;
+export type RequestMethod = RequestFrame["method"];
+
+export const responseFrameSchema = z.union([
+  z.object({ id: z.number().int().nonnegative(), ok: z.literal(true), data: z.unknown() }),
+  z.object({
+    id: z.number().int().nonnegative(),
+    ok: z.literal(false),
+    /** The client sees a CODE, never why a token was refused. Telling a caller
+     * whether the signature or the room was wrong turns this into an oracle. */
+    code: mediaErrorCodeSchema,
+    message: z.string().optional(),
+  }),
+]);
+
+export type ResponseFrame = z.infer<typeof responseFrameSchema>;
+
+/** A participant as everyone else sees them. Grants are NOT included: what
+ * someone else is permitted to do is not the room's business. */
+export const peerSchema = z.object({
+  identity: z.string(),
+  name: z.string().optional(),
+  kind: participantKindSchema,
+});
+export type Peer = z.infer<typeof peerSchema>;
+
+export const eventFrameSchema = z.discriminatedUnion("event", [
+  z.object({
+    event: z.literal("joined"),
+    identity: z.string(),
+    room: z.string(),
+    /** Everything the client needs to build its device before any transport. */
+    routerRtpCapabilities: z.unknown(),
+    peers: z.array(peerSchema),
+    /** Producers this participant is ALLOWED to see. The barrier is applied to
+     * the snapshot, not only at consume: an identity it may not receive must
+     * not be discoverable either. */
+    producers: z.array(z.object({ producerId: z.string(), identity: z.string(), kind: z.enum(["audio", "video"]) })),
+    iceServers: z.array(z.object({ urls: z.union([z.string(), z.array(z.string())]), username: z.string().optional(), credential: z.string().optional() })),
+    /** True while any `kind: "egress"` participant is present. A consent
+     * requirement, not a nicety. */
+    recording: z.boolean(),
+    /**
+     * What this token was minted with, echoed back.
+     *
+     * The client already holds the token but must not parse it: a signed blob
+     * a client reads is a signed blob a client eventually trusts its own
+     * reading of. This is the node's understanding of the grants, which is the
+     * one that will actually be enforced, so a UI built from it cannot offer a
+     * control the node is about to refuse.
+     */
+    grants: mediaGrantsSchema.optional(),
+  }),
+  z.object({ event: z.literal("peerJoined"), peer: peerSchema }),
+  z.object({ event: z.literal("peerLeft"), identity: z.string() }),
+  z.object({
+    event: z.literal("producerAppeared"),
+    producerId: z.string(),
+    identity: z.string(),
+    kind: z.enum(["audio", "video"]),
+  }),
+  z.object({ event: z.literal("producerClosed"), producerId: z.string() }),
+  z.object({ event: z.literal("producerPaused"), producerId: z.string(), paused: z.boolean() }),
+  /**
+   * The active set the node wants this client to consume. How a 1,000-person
+   * room stays survivable: the server decides, the client follows.
+   *
+   * `producerIds` is the whole set and is what a simple client renders.
+   * `audio` and `video` are the same set split, because the two limits differ
+   * (you can follow more voices than you can fit faces). `enforced` says
+   * whether a consume outside the set will actually be REFUSED - below the
+   * threshold the set is advisory and a client that ignores it is not wrong.
+   *
+   * `speakers` carries the ordering and the levels, which is what drives a
+   * layout switch and a level meter. Ordered loudest first.
+   */
+  z.object({
+    event: z.literal("activeSpeakers"),
+    producerIds: z.array(z.string()),
+    audio: z.array(z.string()).optional(),
+    video: z.array(z.string()).optional(),
+    enforced: z.boolean().optional(),
+    speakers: z
+      .array(z.object({ identity: z.string(), producerId: z.string(), volumeDb: z.number() }))
+      .optional(),
+  }),
+  z.object({ event: z.literal("recordingChanged"), recording: z.boolean() }),
+  /** This node is going away. Reconnect through MEDIA_URL; do not retry here. */
+  z.object({ event: z.literal("draining"), reconnectAfterMs: z.number().int().nonnegative() }),
+  z.object({ event: z.literal("roomClosed"), reason: z.string() }),
+  /** Barrier changes are pushed, because a rule that only applies at join is a
+   * rule that does not apply to anyone already in the room. */
+  z.object({ event: z.literal("subscribeRuleChanged"), subscribe: subscribeRuleSchema }),
+]);
+
+export type EventFrame = z.infer<typeof eventFrameSchema>;
+export type EventName = EventFrame["event"];
+
+/** Anything arriving from a node. */
+export const serverFrameSchema = z.union([responseFrameSchema, eventFrameSchema]);
+export type ServerFrame = z.infer<typeof serverFrameSchema>;
+
+export const isEvent = (frame: ServerFrame): frame is EventFrame => "event" in frame;