@tribe-nest/media-client 0.1.0

package/src/core/reconnect.ts

@@ -0,0 +1,233 @@
+import { type MediaErrorCode } from "@tribe-nest/media-protocol";
+
+import { causeFromError, type DisconnectCause } from "./signal";
+
+/**
+ * When to try again, and when to stop.
+ *
+ * Two decisions, both of which cost an outage if guessed:
+ *
+ * **Jitter is not a refinement.** Every client on a node that just died
+ * reconnects at once. Without jitter they arrive in lockstep, land together on
+ * whichever node the balancer picks, and take that one down too. The retry
+ * storm is the outage; the original failure was one node.
+ *
+ * **`draining` is not a failure.** The node is asking to be left. Retrying the
+ * same node is the one response that cannot work, so a drain always sends the
+ * client back through `MEDIA_URL` for a fresh placement and a fresh token, and
+ * waits at least as long as the node asked.
+ *
+ * Everything here is pure. `Math.random` is injectable, so a spec pins exact
+ * delays rather than asserting a range and hoping.
+ */
+
+export type JitterMode = "full" | "equal" | "none";
+
+export type ReconnectOptions = {
+  baseMs: number;
+  maxMs: number;
+  factor: number;
+  jitter: JitterMode;
+  /** Give up after this many consecutive failed attempts. */
+  maxAttempts: number;
+  /**
+   * A reconnect that races the node's reaping of our old session comes back
+   * `duplicate_identity`. Waiting is the fix, so this is a floor rather than a
+   * refusal.
+   */
+  duplicateIdentityFloorMs: number;
+  random: () => number;
+};
+
+export const DEFAULT_RECONNECT_OPTIONS: ReconnectOptions = {
+  baseMs: 500,
+  maxMs: 30_000,
+  factor: 2,
+  jitter: "full",
+  maxAttempts: 10,
+  duplicateIdentityFloorMs: 2_000,
+  random: Math.random,
+};
+
+/**
+ * Delay before attempt number `attempt` (0 = the first retry).
+ *
+ * Full jitter is the default because it is the variant that actually
+ * decorrelates a fleet: exponential-with-a-small-fudge still has every client
+ * retrying inside the same narrow window.
+ */
+export function backoffDelay(attempt: number, options?: Partial<ReconnectOptions>): number {
+  const o = { ...DEFAULT_RECONNECT_OPTIONS, ...options };
+  const ceiling = Math.min(o.maxMs, o.baseMs * Math.pow(o.factor, Math.max(0, attempt)));
+  switch (o.jitter) {
+    case "none":
+      return Math.round(ceiling);
+    case "equal":
+      return Math.round(ceiling / 2 + o.random() * (ceiling / 2));
+    case "full":
+      return Math.round(o.random() * ceiling);
+  }
+}
+
+export type StopReason =
+  | "client_closed"
+  | "room_closed"
+  | "refused"
+  | "attempts_exhausted";
+
+export type ReconnectDecision =
+  | { action: "stop"; reason: StopReason; code?: MediaErrorCode }
+  | {
+      action: "reconnect";
+      delayMs: number;
+      /** The attempt this decision authorises, 0-based. */
+      attempt: number;
+      /**
+       * Always true, and stated in the type rather than in prose: the client
+       * re-resolves through `MEDIA_URL` and takes a FRESH token every time. It
+       * never holds a node address (the wire deliberately carries no `nodeId`),
+       * and a join ticket lives minutes.
+       */
+      viaMediaUrl: true;
+    };
+
+/**
+ * Codes that a later attempt could plausibly survive.
+ *
+ * Split by hand, and pinned by a spec against `MEDIA_ERROR_CODES`, so that a
+ * code added to the contract fails a test here instead of silently falling into
+ * whichever branch the default happened to be.
+ */
+const RETRYABLE_CODES: ReadonlySet<MediaErrorCode> = new Set<MediaErrorCode>([
+  "node_draining",
+  "capacity",
+  "internal",
+  "duplicate_identity",
+]);
+
+/**
+ * Codes that mean "the credential was wrong", which a fresh mint may fix once.
+ *
+ * Once, not forever: a laptop resumed from sleep presents an expired ticket and
+ * deserves a retry, but a revoked grant answers the same way every time and
+ * retrying it is a loop against the minting endpoint.
+ */
+const CREDENTIAL_CODES: ReadonlySet<MediaErrorCode> = new Set<MediaErrorCode>(["unauthorized", "replayed"]);
+
+const TERMINAL_CODES: ReadonlySet<MediaErrorCode> = new Set<MediaErrorCode>([
+  "protocol_version",
+  "forbidden_transport",
+  "forbidden",
+  "not_subscribable",
+  "subscription_limit",
+  "room_closed",
+  "no_such_room",
+  "no_such_producer",
+  "no_such_transport",
+  "bad_request",
+]);
+
+/** Exposed so the exhaustiveness spec can assert every contract code is classified. */
+export const RECONNECT_CODE_CLASSES = {
+  retryable: RETRYABLE_CODES,
+  credential: CREDENTIAL_CODES,
+  terminal: TERMINAL_CODES,
+} as const;
+
+export function classifyCode(code: MediaErrorCode): "retryable" | "credential" | "terminal" {
+  if (RETRYABLE_CODES.has(code)) return "retryable";
+  if (CREDENTIAL_CODES.has(code)) return "credential";
+  if (TERMINAL_CODES.has(code)) return "terminal";
+  // Unclassified is treated as terminal: a client that retries something nobody
+  // reasoned about hammers the node for as long as the user leaves the tab open.
+  return "terminal";
+}
+
+export function decideReconnect(input: {
+  cause: DisconnectCause;
+  /** Consecutive failed attempts since the last successful join. 0 on the first drop. */
+  attempt: number;
+  options?: Partial<ReconnectOptions>;
+}): ReconnectDecision {
+  const o = { ...DEFAULT_RECONNECT_OPTIONS, ...input.options };
+  const { cause, attempt } = input;
+
+  if (cause.type === "closed_by_client") return { action: "stop", reason: "client_closed" };
+  if (cause.type === "room_closed") return { action: "stop", reason: "room_closed" };
+
+  if (cause.type === "refused") {
+    const kind = classifyCode(cause.code);
+    if (kind === "terminal") return { action: "stop", reason: "refused", code: cause.code };
+    if (kind === "credential" && attempt >= 1) {
+      // The retry already carried a freshly minted token and was refused again.
+      return { action: "stop", reason: "refused", code: cause.code };
+    }
+  }
+
+  if (attempt >= o.maxAttempts) return { action: "stop", reason: "attempts_exhausted" };
+
+  return {
+    action: "reconnect",
+    attempt,
+    delayMs: delayFor(cause, attempt, o),
+    viaMediaUrl: true,
+  };
+}
+
+function delayFor(cause: DisconnectCause, attempt: number, o: ReconnectOptions): number {
+  const backoff = backoffDelay(attempt, o);
+  if (cause.type === "draining") {
+    // The node named a window; honour it and add the jittered backoff on top so
+    // a drained node's whole population does not arrive at the replacement in
+    // one burst the instant the window expires.
+    return cause.reconnectAfterMs + backoff;
+  }
+  if (cause.type === "refused" && cause.code === "node_draining") {
+    return Math.max(backoff, o.baseMs);
+  }
+  if (cause.type === "refused" && cause.code === "duplicate_identity") {
+    return Math.max(backoff, o.duplicateIdentityFloorMs);
+  }
+  return backoff;
+}
+
+/**
+ * Drives connect-then-wait-then-decide until something says stop.
+ *
+ * Deliberately knows nothing about sockets: `attempt` returns whatever a
+ * session is and `waitForClose` resolves with why it ended. That is what makes
+ * the whole loop testable with no server, and it is the same loop the room API
+ * (P3b) should use rather than deriving a second one.
+ */
+export async function superviseConnection<TSession>(input: {
+  attempt: () => Promise<TSession>;
+  waitForClose: (session: TSession) => Promise<DisconnectCause>;
+  onConnected?: (session: TSession) => void;
+  onDecision?: (decision: ReconnectDecision, cause: DisconnectCause) => void;
+  sleep?: (ms: number) => Promise<void>;
+  options?: Partial<ReconnectOptions>;
+}): Promise<Extract<ReconnectDecision, { action: "stop" }>> {
+  const sleep = input.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  let attempt = 0;
+
+  for (;;) {
+    let cause: DisconnectCause;
+    try {
+      const session = await input.attempt();
+      // A successful join resets the ladder: an hour-long call that drops once
+      // should not start at a 30-second delay because of a blip at minute two.
+      attempt = 0;
+      input.onConnected?.(session);
+      cause = await input.waitForClose(session);
+    } catch (error) {
+      cause = causeFromError(error);
+    }
+
+    const decision = decideReconnect({ cause, attempt, options: input.options });
+    input.onDecision?.(decision, cause);
+    if (decision.action === "stop") return decision;
+
+    await sleep(decision.delayMs);
+    attempt += 1;
+  }
+}