eraspace 0.1.0 → 0.3.0

package/sdk/src/client/storage.ts

@@ -6,25 +6,113 @@ export interface UploadedObject {
   size: number;
   contentType: string;
   name: string | null;
+  /** Private upload capability. Keep it out of public rows and file references. */
+  deleteToken?: string;
+}
+
+export interface StorageUploadOptions {
+  name?: string;
+  signal?: AbortSignal;
+  /** Called with the uploaded fraction, from 0 to 1, as the bytes leave the browser. */
+  onProgress?: (fraction: number) => void;
 }
 
 export interface StorageClient {
-  /** Store a file in this app's Postgres schema. v1 apps and their files are public. */
-  upload(body: Blob, options?: { name?: string; signal?: AbortSignal }): Promise<UploadedObject>;
+  /** Store a file in this app's bucket. Apps and their files are public. */
+  upload(body: Blob, options?: StorageUploadOptions): Promise<UploadedObject>;
   url(key: string): string;
-  delete(key: string, options?: { signal?: AbortSignal }): Promise<void>;
+  /** A stored file's metadata, or null when there is no such file. */
+  info(key: string, options?: { signal?: AbortSignal }): Promise<UploadedObject | null>;
+  delete(key: string, options?: { signal?: AbortSignal; deleteToken?: string }): Promise<void>;
+  /**
+   * A page-local URL for an image, video or audio file this client uploaded, so previews show it without
+   * downloading it again. Undefined for any other file, or after the file is deleted or evicted. Optional, so other
+   * implementations keep working; previews then use the server URL.
+   */
+  localUrl?(key: string): string | undefined;
+}
+
+/** Uploaded media kept as object URLs. Each keeps its Blob alive, so only the most recent are retained. */
+const LOCAL_FILES = 50;
+
+function isMedia(contentType: string): boolean {
+  return /^(image|video|audio)\//i.test(contentType.trim());
+}
+
+/** Storage keys are UUIDs. */
+export function isStorageKey(key: unknown): key is string {
+  return typeof key === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(key);
+}
+
+/** The filename in a `filename*=UTF-8''...` Content-Disposition. */
+function dispositionName(value: string | null): string | null {
+  const encoded = value?.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+  if (!encoded) return null;
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+}
+
+/** POST `body` with XMLHttpRequest, which reports upload progress where fetch cannot. */
+function sendWithProgress(target: string, headers: Headers, body: Blob, signal: AbortSignal | undefined, onProgress: (fraction: number) => void) {
+  return new Promise<{ status: number; text: string }>((resolve, reject) => {
+    const abortError = () => signal?.reason ?? new DOMException("The upload was aborted", "AbortError");
+    if (signal?.aborted) return reject(abortError());
+    const xhr = new XMLHttpRequest();
+    const abort = () => xhr.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    const done = () => signal?.removeEventListener("abort", abort);
+    xhr.open("POST", target);
+    headers.forEach((value, name) => xhr.setRequestHeader(name, value));
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && e.total > 0) onProgress(e.loaded / e.total);
+    };
+    xhr.onload = () => {
+      done();
+      if (xhr.status >= 200 && xhr.status < 300) onProgress(1);
+      resolve({ status: xhr.status, text: xhr.responseText });
+    };
+    xhr.onerror = () => {
+      done();
+      reject(new EraspaceError("StorageError", "The upload failed. Check your connection and try again."));
+    };
+    xhr.onabort = () => {
+      done();
+      reject(abortError());
+    };
+    xhr.send(body);
+  });
 }
 
 export function createStorageClient(base: () => string): StorageClient {
+  const deleteTokens = new Map<string, string>();
+  const localFiles = new Map<string, string>();
+  function forgetLocal(key: string) {
+    const local = localFiles.get(key);
+    if (local === undefined) return;
+    localFiles.delete(key);
+    URL.revokeObjectURL(local);
+  }
+  function keepLocal(key: string, body: Blob, contentType: string) {
+    if (!isMedia(contentType) || typeof URL.createObjectURL !== "function") return;
+    forgetLocal(key);
+    localFiles.set(key, URL.createObjectURL(body));
+    while (localFiles.size > LOCAL_FILES) forgetLocal(localFiles.keys().next().value!);
+  }
   function url(key?: string): string {
     const path = `${base().replace(/\/+$/, "")}/_sb/storage`;
     return key === undefined ? path : `${path}/${encodeURIComponent(key)}`;
   }
-  async function check(response: Response): Promise<Record<string, unknown>> {
-    const payload = await response.json() as unknown;
-    if (!payload || typeof payload !== "object") throw new EraspaceError("StorageError", `HTTP ${response.status}`);
+  function check(status: number, text: string): Record<string, unknown> {
+    let payload: unknown;
+    try {
+      payload = JSON.parse(text);
+    } catch {}
+    if (!payload || typeof payload !== "object") throw new EraspaceError("StorageError", `HTTP ${status}`);
     const result = payload as Record<string, unknown>;
-    if (!response.ok || result.ok !== true) throw EraspaceError.from(result.error, `Storage request failed: HTTP ${response.status}`);
+    if (status < 200 || status > 299 || result.ok !== true) throw EraspaceError.from(result.error, `Storage request failed: HTTP ${status}`);
     return result;
   }
   return {
@@ -33,14 +121,43 @@ export function createStorageClient(base: () => string): StorageClient {
       const headers = new Headers({ "content-type": body.type || "application/octet-stream" });
       const name = options.name ?? (typeof File !== "undefined" && body instanceof File ? body.name : undefined);
       if (name) headers.set("x-filename", encodeURIComponent(name));
-      const result = await check(await fetch(url(), { method: "POST", headers, body, signal: options.signal }));
+      const { onProgress, signal } = options;
+      const response = onProgress && typeof XMLHttpRequest !== "undefined"
+        ? await sendWithProgress(url(), headers, body, signal, onProgress)
+        : await fetch(url(), { method: "POST", headers, body, signal }).then(async (r) => ({ status: r.status, text: await r.text() }));
+      const result = check(response.status, response.text);
       if (typeof result.key !== "string" || typeof result.url !== "string" || typeof result.size !== "number" || typeof result.contentType !== "string" || (result.name !== null && typeof result.name !== "string")) {
         throw new EraspaceError("StorageError", "Invalid upload response");
       }
-      return { key: result.key, url: result.url, size: result.size, contentType: result.contentType, name: result.name };
+      const deleteToken = typeof result.deleteToken === "string" ? result.deleteToken : undefined;
+      if (deleteToken) deleteTokens.set(result.key, deleteToken);
+      keepLocal(result.key, body, result.contentType);
+      return { key: result.key, url: result.url, size: result.size, contentType: result.contentType, name: result.name, ...(deleteToken ? { deleteToken } : {}) };
+    },
+    async info(key, options = {}) {
+      if (!isStorageKey(key)) return null;
+      const response = await fetch(url(key), { method: "HEAD", signal: options.signal });
+      if (response.status === 404) return null;
+      if (!response.ok) throw new EraspaceError("StorageError", `Storage request failed: HTTP ${response.status}`);
+      return {
+        key,
+        url: url(key),
+        size: Number(response.headers.get("content-length") ?? 0),
+        contentType: response.headers.get("content-type") ?? "application/octet-stream",
+        name: dispositionName(response.headers.get("content-disposition")),
+      };
     },
     async delete(key, options = {}) {
-      await check(await fetch(url(key), { method: "DELETE", signal: options.signal }));
+      const deleteToken = options.deleteToken ?? deleteTokens.get(key);
+      const headers = new Headers();
+      if (deleteToken) headers.set("x-eraspace-file-token", deleteToken);
+      const response = await fetch(url(key), { method: "DELETE", headers, signal: options.signal });
+      check(response.status, await response.text());
+      deleteTokens.delete(key);
+      forgetLocal(key);
+    },
+    localUrl(key) {
+      return localFiles.get(key);
     },
   };
 }

package/sdk/src/client/sub-key.ts

@@ -2,6 +2,22 @@
 export function subKey(fn: string, args: unknown[]): string {
   return fn + ":" + stableStringify(args);
 }
+/**
+ * Arguments as sent to the server: object keys in sorted order, so equal arguments written in any order share
+ * one server cache entry. Serialization is unchanged otherwise.
+ */
+export function canonicalArgs(args: unknown[]): unknown[] {
+  return args.map(canonical);
+}
+function canonical(v: unknown): unknown {
+  if (v === null || typeof v !== "object") return v;
+  const json = (v as { toJSON?: unknown }).toJSON;
+  if (typeof json === "function") return canonical(json.call(v));
+  if (Array.isArray(v)) return v.map(canonical);
+  const o = v as Record<string, unknown>;
+  // Own data properties, so a `__proto__` key stays a key rather than setting the prototype.
+  return Object.fromEntries(Object.keys(o).sort().map((k) => [k, canonical(o[k])]));
+}
 export function stableStringify(v: unknown): string {
   if (v === undefined) return "null";
   if (v === null || typeof v !== "object") return JSON.stringify(v);

package/sdk/src/client/subscription.ts

@@ -1,11 +1,20 @@
 import { signal, type Signal } from "@preact/signals";
 import { EraspaceError } from "./errors.ts";
 import type { Patch } from "./result-diff.ts";
+import { canonicalArgs } from "./sub-key.ts";
 
 export interface FullResult {
   value: unknown;
   commitSeq: number;
   revision: number;
+  /** The server cache entry holding the value, echoed as `known` on a resubscription. */
+  entry?: string;
+}
+/** A resubscription whose `known` entry and revision still hold: the client keeps its value. */
+export interface UnchangedResult {
+  unchanged: true;
+  commitSeq: number;
+  revision: number;
 }
 export type DataMessage = { id: string } & (FullResult | {
   patch: Patch[];
@@ -27,10 +36,16 @@ export class Subscription {
   hasServer = false;
   commitSeq = -1;
   revision: number | undefined;
+  /** The server cache entry of `revision`. */
+  entry: string | undefined;
   request = 0;
+  retries = 0;
+  retryTimer: ReturnType<typeof setTimeout> | undefined;
   refs = 0;
   layers: Layer[] = [];
   timer: ReturnType<typeof setTimeout> | undefined;
+  /** The id last sent to the server, and the app channel join it was sent on. */
+  sent: { id: string; join: number } | undefined;
   // Resubscriptions take a new id so messages for the previous one are ignored.
   id: string;
   readonly fn: string;
@@ -39,7 +54,7 @@ export class Subscription {
   constructor(id: string, fn: string, args: unknown[], key: string) {
     this.id = id;
     this.fn = fn;
-    this.args = args;
+    this.args = canonicalArgs(args);
     this.key = key;
   }
 

package/sdk/src/client/transport.ts

@@ -0,0 +1,423 @@
+import { EraspaceError } from "./errors.ts";
+import { retryDelay } from "./retry.ts";
+
+// Event classes differ across runtimes. Handlers only read message data.
+type TransportHandler<T> = { handle(event: T): void }["handle"];
+
+/** The browser WebSocket API subset also implemented by Node and ws. */
+export interface WebSocketTransport {
+  readonly readyState: number;
+  onopen: TransportHandler<unknown> | null;
+  onclose: TransportHandler<unknown> | null;
+  onerror: TransportHandler<unknown> | null;
+  onmessage: TransportHandler<{ data: unknown }> | null;
+  send(data: string): void;
+  close(): void;
+}
+export type WebSocketConstructor = new (url: string) => WebSocketTransport;
+export interface SocketOptions {
+  timeout?: number;
+  transport?: WebSocketConstructor;
+  reconnectAfterMs?: (attempt: number) => number;
+  rejoinAfterMs?: (attempt: number) => number;
+  /** How long a socket must stay open before reconnect backoff starts again from the first attempt. */
+  stableAfterMs?: number;
+  /** Accept large payloads as deflated binary frames. Defaults to on where `DecompressionStream` inflates raw deflate. */
+  compression?: boolean;
+}
+
+interface Frame {
+  session: string | null;
+  ref: string | null;
+  topic: string;
+  event: string;
+  payload: unknown;
+}
+interface Pending {
+  /** The frame to send: undefined while not ready, null to withdraw a request that was never sent. */
+  frame: () => Frame | undefined | null;
+  sent?: Frame;
+  resolve: (value: unknown) => void;
+  reject: (error: EraspaceError) => void;
+  timer: ReturnType<typeof setTimeout>;
+  topic: string;
+}
+export interface JoinReply { self?: string; now?: number; version?: number }
+
+function asFrame(value: unknown): Frame | undefined {
+  if (!value || typeof value !== "object" || !("topic" in value) || typeof value.topic !== "string"
+    || !("event" in value) || typeof value.event !== "string" || !("session" in value)
+    || !(value.session === null || typeof value.session === "string") || !("ref" in value)
+    || !(value.ref === null || typeof value.ref === "string") || !("payload" in value)) return undefined;
+  return value as Frame;
+}
+
+/**
+ * Reports an exception thrown by app code that consumes frames, as an uncaught event handler exception would be.
+ * It must not look like a transport failure, which would fail every in-flight request with an unknown outcome.
+ */
+function report(error: unknown): void {
+  if (typeof reportError === "function") reportError(error);
+  else setTimeout(() => { throw error; });
+}
+
+function inflates(): boolean {
+  try { return typeof DecompressionStream === "function" && Boolean(new DecompressionStream("deflate-raw")); }
+  catch { return false; }
+}
+
+async function bytesOf(data: unknown): Promise<Uint8Array<ArrayBuffer> | undefined> {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer);
+  if (typeof Blob !== "undefined" && data instanceof Blob) return new Uint8Array(await data.arrayBuffer());
+  return undefined;
+}
+
+/**
+ * A binary frame is a four-byte big-endian header length, the frame's JSON header and a raw-deflated JSON
+ * object. The header's `z` places the object: `"response"` is the reply's response, `"members"` adds its
+ * members to the header payload.
+ */
+async function inflateFrame(data: unknown): Promise<Frame | undefined> {
+  const bytes = await bytesOf(data);
+  if (!bytes || bytes.length < 4) return undefined;
+  const length = new DataView(bytes.buffer, bytes.byteOffset).getUint32(0);
+  if (4 + length > bytes.length) return undefined;
+  const header: unknown = JSON.parse(new TextDecoder().decode(bytes.subarray(4, 4 + length)));
+  const frame = asFrame(header);
+  const z = header && typeof header === "object" && "z" in header ? header.z : undefined;
+  if (!frame || !frame.payload || typeof frame.payload !== "object") return undefined;
+  const inflated = new Blob([bytes.subarray(4 + length)]).stream().pipeThrough(new DecompressionStream("deflate-raw"));
+  const body: unknown = JSON.parse(await new Response(inflated).text());
+  const payload = frame.payload as Record<string, unknown>;
+  if (z === "response") payload.response = body;
+  else if (z === "members" && body && typeof body === "object") frame.payload = { ...body, ...payload };
+  else return undefined;
+  return { session: frame.session, ref: frame.ref, topic: frame.topic, event: frame.event, payload: frame.payload };
+}
+
+/** Multiplexes topics over one native WebSocket. Sent requests are never replayed on reconnect. */
+export class Socket {
+  private ws: WebSocketTransport | undefined;
+  private channels = new Map<string, Channel>();
+  private pending = new Map<string, Pending>();
+  private nextRef = 0;
+  private incoming = Promise.resolve();
+  private stopped = true;
+  private attempts = 0;
+  private reconnect: ReturnType<typeof setTimeout> | undefined;
+  private opening: ReturnType<typeof setTimeout> | undefined;
+  private stable: ReturnType<typeof setTimeout> | undefined;
+  private heartbeat: ReturnType<typeof setInterval> | undefined;
+  private awaitingHeartbeat: { ref: string; timer: ReturnType<typeof setTimeout> } | undefined;
+  private opens = new Set<() => void>();
+  private closes = new Set<() => void>();
+  readonly options: SocketOptions;
+  private url: string;
+
+  constructor(endpoint: string, options: SocketOptions = {}) {
+    const url = new URL(endpoint, typeof location === "undefined" ? undefined : location.href);
+    url.protocol = url.protocol === "https:" || url.protocol === "wss:" ? "wss:" : "ws:";
+    url.searchParams.set("v", "1");
+    if (options.compression ?? inflates()) url.searchParams.set("z", "1");
+    this.url = url.href;
+    this.options = options;
+  }
+
+  onOpen(cb: () => void): void { this.opens.add(cb); }
+  onClose(cb: () => void): void { this.closes.add(cb); }
+  ref(): string { return String(++this.nextRef); }
+  get connected(): boolean { return this.ws?.readyState === 1; }
+
+  connect(): void {
+    if (!this.stopped) return;
+    this.stopped = false;
+    this.attempts = 0;
+    this.open();
+  }
+
+  private open(): void {
+    if (this.stopped) return;
+    const Transport = this.options.transport ?? WebSocket;
+    let ws: WebSocketTransport;
+    try { ws = new Transport(this.url); }
+    catch { this.scheduleReconnect(); return; }
+    this.ws = ws;
+    (ws as { binaryType?: string }).binaryType = "arraybuffer";
+    this.opening = setTimeout(() => this.lost(ws), this.options.timeout ?? 15000);
+    ws.onopen = () => {
+      if (this.ws !== ws) return;
+      clearTimeout(this.opening);
+      // A server that accepts sockets and then drops them must not reset every client's backoff at once, so
+      // backoff restarts only after the connection has proved stable.
+      this.stable = setTimeout(() => {
+        if (this.ws === ws) this.attempts = 0;
+      }, this.options.stableAfterMs ?? 10000);
+      for (const cb of this.opens) cb();
+      for (const channel of this.channels.values()) channel.rejoin();
+      this.flush();
+      this.heartbeat = setInterval(() => this.sendHeartbeat(ws), 25000);
+    };
+    ws.onmessage = (event) => {
+      if (this.ws !== ws) return;
+      if (typeof event.data !== "string") {
+        // Deflated frames inflate asynchronously, in arrival order with every other frame.
+        const data = event.data;
+        // A frame that does not inflate is a transport failure; an exception while delivering one is not.
+        this.incoming = this.incoming.then(() => inflateFrame(data)).then(
+          frame => { if (frame) this.deliver(ws, frame); },
+          () => this.lost(ws),
+        );
+        return;
+      }
+      let frame: Frame | undefined;
+      try { frame = asFrame(JSON.parse(event.data)); } catch { return; }
+      if (!frame) return;
+      const received = frame;
+      // ws can deliver several frames in one task. Let reply consumers settle before the next push.
+      this.incoming = this.incoming.then(() => this.deliver(ws, received));
+    };
+    ws.onclose = () => this.lost(ws);
+    ws.onerror = () => this.lost(ws);
+  }
+
+  private deliver(ws: WebSocketTransport, frame: Frame): void {
+    if (this.ws !== ws) return;
+    try { this.receive(frame); } catch (error) { report(error); }
+  }
+
+  private receive(frame: Frame): void {
+    if (frame.event === "reply" && frame.ref) {
+      const body = frame.payload;
+      if (!body || typeof body !== "object" || !("status" in body) || !("response" in body)) return;
+      if (body.status !== "ok" && body.status !== "error") return;
+      if (frame.ref === this.awaitingHeartbeat?.ref && frame.topic === "" && frame.session === null && body.status === "ok") {
+        clearTimeout(this.awaitingHeartbeat.timer);
+        this.awaitingHeartbeat = undefined;
+        return;
+      }
+      const pending = this.pending.get(frame.ref);
+      if (!pending?.sent || pending.sent.topic !== frame.topic || pending.sent.session !== frame.session) return;
+      this.pending.delete(frame.ref);
+      clearTimeout(pending.timer);
+      if (body.status === "ok") pending.resolve(body.response);
+      else {
+        const error = EraspaceError.from(body.response);
+        pending.reject(new EraspaceError(error.name, error.message, body.response));
+      }
+      this.flush();
+    } else {
+      this.channels.get(frame.topic)?.receive(frame);
+    }
+  }
+
+  private sendHeartbeat(ws: WebSocketTransport): void {
+    if (this.ws !== ws || ws.readyState !== 1 || this.awaitingHeartbeat) return;
+    const ref = this.ref();
+    // Liveness checks bypass the application window and start their deadline only after send succeeds.
+    try {
+      ws.send(JSON.stringify({ session: null, ref, topic: "", event: "ping", payload: {} }));
+      this.awaitingHeartbeat = { ref, timer: setTimeout(() => this.lost(ws), 10000) };
+    } catch { this.lost(ws); }
+  }
+
+  private lost(ws: WebSocketTransport): void {
+    if (this.ws !== ws) return;
+    this.ws = undefined;
+    clearTimeout(this.opening);
+    clearTimeout(this.stable);
+    ws.onopen = ws.onclose = ws.onmessage = null;
+    ws.onerror = () => {};
+    ws.close();
+    clearInterval(this.heartbeat);
+    clearTimeout(this.awaitingHeartbeat?.timer);
+    this.awaitingHeartbeat = undefined;
+    for (const [ref, pending] of this.pending) {
+      if (pending.sent) this.fail(ref, new EraspaceError("OutcomeUnknownError", "Connection lost before the reply arrived"));
+    }
+    for (const channel of this.channels.values()) channel.disconnected();
+    for (const cb of this.closes) cb();
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped) return;
+    clearTimeout(this.reconnect);
+    this.reconnect = setTimeout(() => this.open(), (this.options.reconnectAfterMs ?? retryDelay)(++this.attempts));
+  }
+
+  disconnect(): void {
+    this.stopped = true;
+    clearTimeout(this.reconnect);
+    clearInterval(this.heartbeat);
+    for (const channel of [...this.channels.values()]) channel.leave();
+    if (this.ws) this.lost(this.ws);
+    for (const ref of this.pending.keys()) this.fail(ref, new EraspaceError("UnavailableError", "Socket closed"));
+  }
+
+  channel(topic: string, payload: object | (() => object) = {}): Channel {
+    const previous = this.channels.get(topic);
+    if (previous) return previous;
+    const channel = new Channel(this, topic, payload);
+    this.channels.set(topic, channel);
+    return channel;
+  }
+
+  remove(channel: Channel, session: string | null): void {
+    if (this.channels.get(channel.topic) !== channel) return;
+    const ws = this.ws;
+    if (session !== null && !this.stopped && ws?.readyState === 1) {
+      // Cleanup must also work while the request window is full or a join reply is still pending.
+      try { ws.send(JSON.stringify({ session, ref: this.ref(), topic: channel.topic, event: "leave", payload: {} })); }
+      catch { this.lost(ws); }
+    }
+    this.channels.delete(channel.topic);
+    for (const [ref, pending] of this.pending) {
+      if (pending.topic === channel.topic) this.fail(ref, new EraspaceError("UnavailableError", "Channel closed"));
+    }
+  }
+
+  request<T>(frame: () => Frame | undefined | null, topic: string, timeout = this.options.timeout ?? 15000): Promise<T> {
+    if (this.pending.size >= 256) return Promise.reject(new EraspaceError("ResourceError", "Too many pending socket requests"));
+    const ref = this.ref();
+    return new Promise<T>((resolve, reject) => {
+      // Work that never left this client has no unknown outcome, so it does not time out like a sent request.
+      const timer = setTimeout(() => this.fail(ref, this.pending.get(ref)?.sent
+        ? new EraspaceError("TimeoutError", "Socket request timed out")
+        : new EraspaceError("UnavailableError", "Not connected; the request was not sent")), timeout);
+      this.pending.set(ref, { frame, topic, timer, resolve: value => resolve(value as T), reject });
+      this.flush();
+    });
+  }
+
+  private fail(ref: string, error: EraspaceError): void {
+    const pending = this.pending.get(ref);
+    if (!pending) return;
+    this.pending.delete(ref);
+    clearTimeout(pending.timer);
+    pending.reject(error);
+    this.flush();
+  }
+
+  flush(): void {
+    const ws = this.ws;
+    if (!ws || ws.readyState !== 1) return;
+    // A join can produce a reply plus presence and state pushes. Bound bursts below the desk's mailboxes.
+    let inFlight = [...this.pending.values()].filter(pending => pending.sent).length;
+    for (const [ref, pending] of this.pending) {
+      if (inFlight >= 16) break;
+      if (pending.sent) continue;
+      const frame = pending.frame();
+      if (frame === null) {
+        this.pending.delete(ref);
+        clearTimeout(pending.timer);
+        pending.reject(new EraspaceError("UnavailableError", "Request withdrawn before it was sent"));
+        continue;
+      }
+      if (!frame) continue;
+      frame.ref = ref;
+      try { ws.send(JSON.stringify(frame)); pending.sent = frame; inFlight++; }
+      catch { this.lost(ws); break; }
+    }
+  }
+}
+
+/** A join generation prevents late replies and pushes from a replaced channel being delivered. */
+export class Channel {
+  readonly topic: string;
+  private socket: Socket;
+  private payload: object | (() => object);
+  private session: string | null = null;
+  private joined = false;
+  private started = false;
+  private closed = false;
+  private joining = false;
+  private attempts = 0;
+  private retry: ReturnType<typeof setTimeout> | undefined;
+  private events = new Map<string, Set<(payload: unknown) => void>>();
+  private joins = new Set<(reply: JoinReply) => void>();
+  private errors = new Set<(error: unknown, rejected: boolean) => void>();
+  private closes = new Set<() => void>();
+  onMessage: ((event: string, payload: unknown) => void) | undefined;
+
+  constructor(socket: Socket, topic: string, payload: object | (() => object)) {
+    this.socket = socket;
+    this.topic = topic;
+    this.payload = payload;
+  }
+  on<T = unknown>(event: string, cb: (payload: T) => void): () => void {
+    const handler = (value: unknown) => cb(value as T);
+    let handlers = this.events.get(event);
+    if (!handlers) this.events.set(event, handlers = new Set());
+    handlers.add(handler);
+    return () => handlers.delete(handler);
+  }
+  onJoin(cb: (reply: JoinReply) => void): void { this.joins.add(cb); }
+  onError(cb: (error: unknown, rejected: boolean) => void): void { this.errors.add(cb); }
+  onClose(cb: () => void): void { this.closes.add(cb); }
+
+  join(): void {
+    if (this.started || this.closed) return;
+    this.started = true;
+    this.rejoin();
+  }
+
+  rejoin(): void {
+    if (!this.started || this.closed || this.joined || this.joining || !this.socket.connected) return;
+    clearTimeout(this.retry);
+    const session = this.socket.ref();
+    this.session = session;
+    this.joining = true;
+    void this.socket.request<JoinReply>(() => ({ session, ref: null, topic: this.topic, event: "join", payload: typeof this.payload === "function" ? this.payload() : this.payload }), this.topic)
+      .then(reply => {
+        if (this.closed || this.session !== session) return;
+        this.joining = false;
+        this.joined = true;
+        this.attempts = 0;
+        for (const cb of this.joins) cb(reply);
+        this.socket.flush();
+      }, error => {
+        if (this.closed || this.session !== session) return;
+        this.joining = false;
+        for (const cb of this.errors) cb(error, error instanceof EraspaceError && error.data !== undefined);
+        if (!this.closed) this.retry = setTimeout(() => this.rejoin(), (this.socket.options.rejoinAfterMs ?? retryDelay)(++this.attempts));
+      });
+  }
+
+  /** A function payload is read when the request is sent; returning null withdraws the request unsent. */
+  push<T = unknown>(event: string, payload: object | (() => object | null), timeout?: number): Promise<T> {
+    if (this.closed) return Promise.reject(new EraspaceError("UnavailableError", "Channel closed"));
+    return this.socket.request<T>(() => {
+      if (!this.joined) return undefined;
+      const body = typeof payload === "function" ? payload() : payload;
+      return body === null ? null : { session: this.session, ref: null, topic: this.topic, event, payload: body };
+    }, this.topic, timeout);
+  }
+
+  receive(frame: Frame): void {
+    if (this.closed || frame.session !== this.session) return;
+    if (frame.event === "closed") { this.leave(); return; }
+    // One throwing handler must not keep the frame from the others.
+    try { this.onMessage?.(frame.event, frame.payload); } catch (error) { report(error); }
+    for (const cb of this.events.get(frame.event) ?? []) {
+      try { cb(frame.payload); } catch (error) { report(error); }
+    }
+  }
+
+  disconnected(): void {
+    this.joined = this.joining = false;
+    this.session = null;
+    clearTimeout(this.retry);
+    for (const cb of this.errors) cb(new EraspaceError("UnavailableError", "Connection lost"), false);
+  }
+
+  leave(): void {
+    if (this.closed) return;
+    const session = this.session;
+    this.closed = true;
+    this.joined = false;
+    clearTimeout(this.retry);
+    this.socket.remove(this, session);
+    for (const cb of this.closes) cb();
+  }
+}