@openmarket/rooms-client 0.1.0

package/src/ws-client.ts

@@ -0,0 +1,611 @@
+import {
+  type RoomAuthSuccessPayload,
+  type RoomClientMessage,
+  RoomClientMessageType,
+  type RoomErrorPayload,
+  type RoomServerMessage,
+  type RoomServerMessageOf,
+  RoomServerMessageType,
+  SUPPORTED_ROOM_PROTOCOL_VERSION,
+} from "./types.js";
+import { VERSION } from "./version.js";
+
+interface WsCloseLike extends Event {
+  code?: number;
+  reason?: string;
+}
+
+interface WsMessageLike {
+  data: unknown;
+}
+
+export class RoomProtocolError extends Error {
+  override readonly name = "RoomProtocolError";
+  readonly code: string;
+  readonly details?: unknown;
+  readonly requestId?: string;
+
+  constructor(payload: RoomErrorPayload) {
+    super(payload.message);
+    this.code = payload.code;
+    if (payload.details !== undefined) this.details = payload.details;
+    if (payload.requestId) this.requestId = payload.requestId;
+  }
+}
+
+export class RoomTransportError extends Error {
+  override readonly name = "RoomTransportError";
+}
+
+export type RoomWebSocketCtor = new (url: string) => WebSocket;
+
+export interface RoomWsClientOptions {
+  url: string;
+  apiKey: string;
+  /** Refreshes a locally managed credential after an authentication refusal. */
+  refreshAuthToken?: () => Promise<string>;
+  webSocketCtor?: RoomWebSocketCtor;
+  timeoutMs?: number;
+  /** Enable bounded exponential-backoff reconnection on an unexpected drop. */
+  reconnect?: boolean;
+  /** Base backoff in ms (default 500). */
+  reconnectBaseMs?: number;
+  /** Max backoff in ms (default 15_000). */
+  reconnectMaxMs?: number;
+  /** Flat 0..N ms herd jitter added to every reconnect delay (default 5_000).
+   *  A relay restart drops every client at once; the exponential backoff's
+   *  first window is only ~250-500ms, so without this the whole fleet
+   *  re-AUTHENTICATEs in the same instant. */
+  reconnectHerdJitterMs?: number;
+  /** Give up after this many consecutive failures (default: never; live sessions reconnect indefinitely). */
+  reconnectMaxAttempts?: number;
+  /** Sidekick identity assertion: this session presents itself as the named
+   *  operator-owned agent (AUTHENTICATE carries isAgent plus the display
+   *  username, additive fields old relays ignore). Ghost and plain user
+   *  sessions omit it entirely, keeping their first frame byte-shaped like
+   *  today's. Display only; safety keys on the daemon credential. */
+  agentIdentity?: { name: string };
+  onProtocolMismatch?: (info: { supported: number; server: number }) => void;
+}
+
+type RoomListener = (msg: RoomServerMessage) => void;
+
+/** Notified when the socket drops and when it comes back after a reconnect. */
+export type RoomConnectionListener = (
+  state: "reconnecting" | "reconnected" | "failed",
+  detail?: { attempt?: number; error?: string },
+) => void;
+
+interface PendingWait {
+  type: RoomServerMessageType;
+  types?: ReadonlySet<RoomServerMessageType>;
+  predicate?: (msg: RoomServerMessage) => boolean;
+  requestId?: string;
+  resolve: (msg: RoomServerMessage) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class RoomWsClient {
+  private readonly url: string;
+  // Mutable: a guest session re-mints its key via refreshAuthToken.
+  private apiKey: string;
+  private readonly agentIdentity: { name: string } | undefined;
+  private readonly webSocketCtor: new (
+    url: string,
+  ) => WebSocket;
+  private readonly timeoutMs: number;
+
+  private ws: WebSocket | null = null;
+  private auth: RoomAuthSuccessPayload | null = null;
+  private serverProtocolVersionValue: number | null = null;
+  private listeners = new Set<RoomListener>();
+  private connectionListeners = new Set<RoomConnectionListener>();
+  private pending: PendingWait[] = [];
+  private connected = false;
+
+  private readonly reconnectEnabled: boolean;
+  private readonly reconnectBaseMs: number;
+  private readonly reconnectMaxMs: number;
+  private readonly reconnectHerdJitterMs: number;
+  private readonly reconnectMaxAttempts: number;
+  private readonly refreshAuthToken: (() => Promise<string>) | undefined;
+  private readonly onProtocolMismatch:
+    | ((info: { supported: number; server: number }) => void)
+    | undefined;
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private closedByClient = false;
+  private authRefreshRequested = false;
+  private authRefreshInFlight = false;
+  /** True after a successful re-mint whose refreshed attempt hasn't authed yet.
+   *  Caps the mint-succeeds-but-server-rejects cycle (config skew) at ONE
+   *  refreshed attempt per episode — without it, openSocket → fail → re-mint →
+   *  openSocket recurses in a hot loop with no backoff. Reset on AUTH_SUCCESS.
+   *  A FAILED re-mint does not set it: that path already backs off through
+   *  maybeReconnect, so transient auth-service outages keep retrying. */
+  private authRefreshAttempted = false;
+
+  constructor(options: RoomWsClientOptions) {
+    this.url = options.url;
+    this.apiKey = options.apiKey;
+    this.agentIdentity = options.agentIdentity;
+    this.webSocketCtor = options.webSocketCtor ?? globalThis.WebSocket;
+    this.timeoutMs = options.timeoutMs ?? 15_000;
+    this.reconnectEnabled = options.reconnect ?? false;
+    this.reconnectBaseMs = options.reconnectBaseMs ?? 500;
+    this.reconnectMaxMs = options.reconnectMaxMs ?? 15_000;
+    this.reconnectHerdJitterMs = options.reconnectHerdJitterMs ?? 5_000;
+    this.reconnectMaxAttempts = options.reconnectMaxAttempts ?? Number.POSITIVE_INFINITY;
+    this.refreshAuthToken = options.refreshAuthToken;
+    this.onProtocolMismatch = options.onProtocolMismatch;
+  }
+
+  /** Subscribe to connection-state transitions (reconnecting/reconnected/failed). */
+  onConnectionChange(listener: RoomConnectionListener): () => void {
+    this.connectionListeners.add(listener);
+    return () => {
+      this.connectionListeners.delete(listener);
+    };
+  }
+
+  private emitConnectionState(
+    state: "reconnecting" | "reconnected" | "failed",
+    detail?: { attempt?: number; error?: string },
+  ): void {
+    for (const listener of this.connectionListeners) {
+      try {
+        listener(state, detail);
+      } catch {
+        // A listener error must not break reconnection.
+      }
+    }
+  }
+
+  connect(): Promise<RoomAuthSuccessPayload> {
+    if (this.ws) {
+      if (this.auth) return Promise.resolve(this.auth);
+      return this.waitFor(RoomServerMessageType.AUTH_SUCCESS).then((msg) => msg.payload);
+    }
+    this.closedByClient = false;
+    return this.openSocket();
+  }
+
+  private openSocket(): Promise<RoomAuthSuccessPayload> {
+    // Fence any prior socket so a slow-to-die predecessor (e.g. one whose auth
+    // timed out while still connecting) can't feed record() or null out the
+    // fresh socket. Handlers below no-op unless they belong to the current ws.
+    const previous = this.ws;
+    if (previous) {
+      this.ws = null;
+      try {
+        previous.close(1000, "superseded");
+      } catch {
+        // best-effort
+      }
+    }
+
+    let ws: WebSocket;
+    try {
+      ws = new this.webSocketCtor(this.url);
+    } catch (err) {
+      throw new RoomTransportError(errorMessage(err));
+    }
+    this.ws = ws;
+
+    ws.addEventListener("open", () => {
+      if (this.ws !== ws) return;
+      this.connected = true;
+      this.send({
+        type: RoomClientMessageType.AUTHENTICATE,
+        payload: {
+          token: this.apiKey,
+          protocolVersion: SUPPORTED_ROOM_PROTOCOL_VERSION,
+          // Sidekick sessions assert their agenthood and display name;
+          // ghost and user sessions send the bare frame unchanged.
+          ...(this.agentIdentity ? { isAgent: true, username: this.agentIdentity.name } : {}),
+        },
+        timestamp: Date.now(),
+      });
+    });
+
+    ws.addEventListener("message", (event) => {
+      if (this.ws !== ws) return;
+      const data = (event as WsMessageLike).data;
+      if (typeof data !== "string" || data.length === 0) return;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        this.rejectAll(new RoomTransportError("rooms ws: dropped non-json frame"));
+        return;
+      }
+      if (!isRoomShapedFrame(parsed)) {
+        this.rejectAll(new RoomTransportError("rooms ws: dropped malformed frame"));
+        return;
+      }
+      if (!isRoomServerMessage(parsed)) {
+        // Additive-only protocol: a newer relay may send frame types this
+        // client does not know yet. Ignore them; never fail the session.
+        return;
+      }
+      this.record(parsed);
+    });
+
+    ws.addEventListener("close", (event) => {
+      // A superseded socket's close must not touch current state or trigger
+      // another reconnect.
+      if (this.ws !== ws) return;
+      const e = event as WsCloseLike;
+      const hadAuth = this.auth !== null;
+      this.connected = false;
+      this.auth = null;
+      this.ws = null;
+      if (!this.closedByClient && !hadAuth && e.code === 1008 && this.refreshAuthToken) {
+        this.authRefreshRequested = true;
+      }
+      this.rejectAll(
+        new RoomTransportError(
+          `rooms ws closed${e.code ? ` (${e.code})` : ""}${e.reason ? `: ${e.reason}` : ""}`,
+        ),
+      );
+      this.maybeReconnect(e.reason || (e.code ? `code ${e.code}` : undefined));
+    });
+
+    ws.addEventListener("error", () => {
+      if (this.ws !== ws) return;
+      this.rejectAll(new RoomTransportError("rooms ws error"));
+    });
+
+    return this.waitFor(RoomServerMessageType.AUTH_SUCCESS)
+      .then((msg) => {
+        this.reconnectAttempts = 0;
+        this.authRefreshAttempted = false;
+        return msg.payload;
+      })
+      .catch(async (error) => this.retryGuestAuthentication(error));
+  }
+
+  private maybeReconnect(reason?: string): void {
+    if (
+      !this.reconnectEnabled ||
+      this.closedByClient ||
+      this.authRefreshRequested ||
+      this.authRefreshInFlight
+    ) {
+      return;
+    }
+    if (this.reconnectTimer) return;
+    if (this.reconnectAttempts >= this.reconnectMaxAttempts) {
+      this.emitConnectionState("failed", {
+        attempt: this.reconnectAttempts,
+        ...(reason ? { error: reason } : {}),
+      });
+      return;
+    }
+    const attempt = this.reconnectAttempts + 1;
+    this.reconnectAttempts = attempt;
+    // Exponential backoff with full jitter, capped.
+    const ceiling = Math.min(this.reconnectMaxMs, this.reconnectBaseMs * 2 ** (attempt - 1));
+    const delay = Math.floor(
+      ceiling * (0.5 + Math.random() * 0.5) + Math.random() * this.reconnectHerdJitterMs,
+    );
+    this.emitConnectionState("reconnecting", {
+      attempt,
+      ...(reason ? { error: reason } : {}),
+    });
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.closedByClient) return;
+      try {
+        this.openSocket()
+          .then(() => {
+            this.emitConnectionState("reconnected", { attempt });
+          })
+          .catch((err) => {
+            // Re-auth failed; drive the next backoff attempt.
+            this.maybeReconnect(errorMessage(err));
+          });
+      } catch (err) {
+        // openSocket can throw synchronously (constructor failure) before it
+        // returns a promise — that must not escape the timer as an uncaught
+        // exception. Fold it back into the backoff loop.
+        this.maybeReconnect(errorMessage(err));
+      }
+    }, delay);
+    if (typeof (this.reconnectTimer as { unref?: () => void }).unref === "function") {
+      (this.reconnectTimer as unknown as { unref: () => void }).unref();
+    }
+  }
+
+  send(msg: RoomClientMessage): void {
+    if (!this.ws || !this.connected) {
+      throw new RoomTransportError("rooms ws: not open");
+    }
+    this.ws.send(JSON.stringify(msg));
+  }
+
+  waitFor<T extends RoomServerMessageType>(
+    type: T,
+    predicate?: (msg: RoomServerMessageOf<T>) => boolean,
+    timeoutMs = this.timeoutMs,
+    requestId?: string,
+  ): Promise<RoomServerMessageOf<T>> {
+    return new Promise((resolve, reject) => {
+      let pending: PendingWait;
+      const timer = setTimeout(() => {
+        this.pending = this.pending.filter((wait) => wait !== pending);
+        reject(new RoomTransportError(`timed out waiting for ${type}`));
+      }, timeoutMs);
+      pending = {
+        type,
+        ...(predicate
+          ? { predicate: (msg: RoomServerMessage) => predicate(msg as RoomServerMessageOf<T>) }
+          : {}),
+        ...(requestId ? { requestId } : {}),
+        resolve: (msg: RoomServerMessage) => resolve(msg as RoomServerMessageOf<T>),
+        reject,
+        timer,
+      };
+      this.pending.push(pending);
+    });
+  }
+
+  waitForAny<T extends RoomServerMessageType>(
+    types: readonly T[],
+    predicate?: (msg: Extract<RoomServerMessage, { type: T }>) => boolean,
+    timeoutMs = this.timeoutMs,
+    requestId?: string,
+  ): Promise<Extract<RoomServerMessage, { type: T }>> {
+    return new Promise((resolve, reject) => {
+      let pending: PendingWait;
+      const timer = setTimeout(() => {
+        this.pending = this.pending.filter((wait) => wait !== pending);
+        reject(new RoomTransportError(`timed out waiting for ${types.join(" or ")}`));
+      }, timeoutMs);
+      const typeSet = new Set<RoomServerMessageType>(types);
+      pending = {
+        type: types[0] as RoomServerMessageType,
+        types: typeSet,
+        predicate: (msg: RoomServerMessage) =>
+          typeSet.has(msg.type) &&
+          (!predicate || predicate(msg as Extract<RoomServerMessage, { type: T }>)),
+        ...(requestId ? { requestId } : {}),
+        resolve: (msg: RoomServerMessage) =>
+          resolve(msg as Extract<RoomServerMessage, { type: T }>),
+        reject,
+        timer,
+      };
+      this.pending.push(pending);
+    });
+  }
+
+  onMessage(listener: RoomListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  close(): void {
+    this.closedByClient = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    const ws = this.ws;
+    this.ws = null;
+    this.auth = null;
+    this.connected = false;
+    this.rejectAll(new RoomTransportError("rooms ws closed by client"));
+    ws?.close(1000, "client closed");
+  }
+
+  private readonly waiterHandledErrors = new WeakSet<object>();
+
+  serverProtocolVersion(): number | null {
+    return this.serverProtocolVersionValue;
+  }
+
+  isGuest(): boolean {
+    return this.auth?.isGuest === true;
+  }
+
+  private record(msg: RoomServerMessage): void {
+    if (msg.type === RoomServerMessageType.AUTH_SUCCESS) {
+      if (!this.handleAuthSuccess(msg.payload)) return;
+    }
+
+    if (msg.type === RoomServerMessageType.ERROR) {
+      if (
+        !this.auth &&
+        this.refreshAuthToken &&
+        isAuthenticationError(msg.payload.code) &&
+        !this.closedByClient
+      ) {
+        this.authRefreshRequested = true;
+      }
+      const err = new RoomProtocolError(msg.payload);
+      if (msg.payload.requestId) {
+        if (this.rejectByRequestId(msg.payload.requestId, err)) {
+          // Precisely correlated: the request's caller owns this failure. Mark
+          // the frame so passive listeners (the tape pump) don't ALSO surface
+          // it — background requests against older relays degrade silently.
+          this.waiterHandledErrors.add(msg);
+        }
+        // A requestId we don't recognize is someone else's request (another
+        // session, a stale retry): never misattribute it to an unrelated
+        // waiter. Passive surfaces still see the frame.
+      } else if (this.rejectOldest(err)) {
+        // Heuristic old-relay fallback: the oldest waiter got the rejection,
+        // but the correlation is a guess. Only hide pure protocol noise;
+        // user-actionable errors (MUTED, READ_ONLY, …) must stay visible.
+        if (msg.payload.code === "BAD_FRAME") this.waiterHandledErrors.add(msg);
+      }
+    } else {
+      this.resolvePending(msg);
+    }
+
+    for (const listener of this.listeners) listener(msg);
+  }
+
+  private handleAuthSuccess(payload: RoomAuthSuccessPayload): boolean {
+    this.auth = payload;
+    this.serverProtocolVersionValue = payload.protocolVersion;
+    if (payload.protocolVersion !== SUPPORTED_ROOM_PROTOCOL_VERSION) {
+      this.onProtocolMismatch?.({
+        supported: SUPPORTED_ROOM_PROTOCOL_VERSION,
+        server: payload.protocolVersion,
+      });
+      const err = new RoomTransportError(
+        `rooms protocol mismatch: server v${payload.protocolVersion}, client supports v${SUPPORTED_ROOM_PROTOCOL_VERSION}`,
+      );
+      this.closedByClient = true;
+      this.rejectAll(err);
+      this.ws?.close(1002, "protocol mismatch");
+      return false;
+    }
+
+    if (
+      !payload.minClientBuild ||
+      !isRoomClientBuildBelowMinimum(VERSION, payload.minClientBuild)
+    ) {
+      return true;
+    }
+
+    const err = new RoomTransportError(
+      `rooms client upgrade required: server requires om v${payload.minClientBuild} or newer (this build is v${VERSION})`,
+    );
+    this.closedByClient = true;
+    this.rejectAll(err);
+    this.ws?.close(1008, "client upgrade required");
+    return false;
+  }
+
+  private async retryGuestAuthentication(error: unknown): Promise<RoomAuthSuccessPayload> {
+    if (!this.authRefreshRequested || !this.refreshAuthToken || this.closedByClient) {
+      throw error;
+    }
+    if (this.authRefreshAttempted) {
+      // The previous re-mint SUCCEEDED and the server still refused the fresh
+      // key — retrying would mint in a hot loop. Fail the episode instead.
+      throw error;
+    }
+
+    this.authRefreshRequested = false;
+    this.authRefreshInFlight = true;
+    try {
+      this.apiKey = await this.refreshAuthToken();
+      this.authRefreshAttempted = true;
+      return await this.openSocket();
+    } catch (refreshError) {
+      this.authRefreshInFlight = false;
+      this.maybeReconnect(errorMessage(refreshError));
+      throw refreshError;
+    } finally {
+      this.authRefreshInFlight = false;
+    }
+  }
+
+  private resolvePending(msg: RoomServerMessage): void {
+    const remaining: PendingWait[] = [];
+    for (const wait of this.pending) {
+      if (wait.types ? !wait.types.has(msg.type) : wait.type !== msg.type) {
+        remaining.push(wait);
+        continue;
+      }
+      if (wait.predicate && !wait.predicate(msg)) {
+        remaining.push(wait);
+        continue;
+      }
+      clearTimeout(wait.timer);
+      wait.resolve(msg);
+    }
+    this.pending = remaining;
+  }
+
+  private rejectAll(err: Error): void {
+    for (const wait of this.pending) {
+      clearTimeout(wait.timer);
+      wait.reject(err);
+    }
+    this.pending = [];
+  }
+
+  private rejectByRequestId(requestId: string | undefined, err: Error): boolean {
+    if (!requestId) return false;
+    const index = this.pending.findIndex((wait) => wait.requestId === requestId);
+    if (index < 0) return false;
+    const [wait] = this.pending.splice(index, 1);
+    if (!wait) return false;
+    clearTimeout(wait.timer);
+    wait.reject(err);
+    return true;
+  }
+
+  // Fallback for old relays that do not include requestId on ERROR frames.
+  private rejectOldest(err: Error): boolean {
+    const wait = this.pending.shift();
+    if (!wait) return false;
+    clearTimeout(wait.timer);
+    wait.reject(err);
+    return true;
+  }
+
+  /** Was this ERROR frame already delivered to a waiting request's caller? */
+  errorHandledByWaiter(msg: RoomServerMessage): boolean {
+    return this.waiterHandledErrors.has(msg);
+  }
+}
+
+/** Returns false for an invalid server value so a typo cannot lock out every client. */
+export function isRoomClientBuildBelowMinimum(clientBuild: string, minimumBuild: string): boolean {
+  const client = parseBuild(clientBuild);
+  const minimum = parseBuild(minimumBuild);
+  if (!client || !minimum) return false;
+  for (const index of [0, 1, 2] as const) {
+    const clientPart = client[index];
+    const minimumPart = minimum[index];
+    if (clientPart !== minimumPart) return clientPart < minimumPart;
+  }
+  return false;
+}
+
+function parseBuild(value: string): readonly [number, number, number] | null {
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(value.trim());
+  if (!match) return null;
+  const parts = [match[1], match[2] ?? "0", match[3] ?? "0"].map(Number);
+  if (parts.some((part) => !Number.isSafeInteger(part))) return null;
+  return parts as [number, number, number];
+}
+
+const KNOWN_SERVER_MESSAGE_TYPES = new Set<string>(Object.values(RoomServerMessageType));
+
+function isRoomShapedFrame(
+  value: unknown,
+): value is { type: string; payload: object; timestamp: number } {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as {
+    type?: unknown;
+    timestamp?: unknown;
+    payload?: unknown;
+  };
+  if (typeof candidate.type !== "string") return false;
+  if (typeof candidate.timestamp !== "number") return false;
+  if (!candidate.payload || typeof candidate.payload !== "object") return false;
+  return true;
+}
+
+function isRoomServerMessage(value: unknown): value is RoomServerMessage {
+  // A hostile or buggy relay cannot smuggle an unexpected shape past the
+  // type switch that consumers rely on: only known frame types pass.
+  return isRoomShapedFrame(value) && KNOWN_SERVER_MESSAGE_TYPES.has(value.type);
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function isAuthenticationError(code: string): boolean {
+  return code === "AUTH_FAILED" || code === "AUTH_TIMEOUT" || code === "TOKEN_REQUIRED";
+}