@trevrpc/trevrpc-js 0.2.3 → 1.1.0

package/src/channel.js

@@ -1,375 +1,345 @@
-import { cancelled, deadlineExceeded, unavailable } from "./status.js";
-
-const ChannelOptionKeys = new Set(["onStateChange", "signal", "timeoutMs"]);
-
-const DefaultChannelOptions = Object.freeze({
-  initialDelayMs: 100,
-  maxDelayMs: 30_000,
-  multiplier: 2,
-  jitter: 0.2,
-});
-const MaxTimerDelayMs = 2_147_483_647;
-
-/** Shared state machine for reconnecting channels. */
-export class ChannelStateMachine extends EventTarget {
-  #connect;
-  #connectAbort = null;
-  #generation = 0;
-  #observeClosed;
-  #isConnectionFailure;
+import { QMuxWebSocketSession } from "./qmux/session.js";
+import { dialRace } from "./race.js";
+import { cancelled, failedPrecondition, statusFromTransportError, unavailable } from "./status.js";
+
+/**
+ * The WebTransport protocol that names wire version 1, offered through the `protocols` constructor
+ * option. It is the protocol version, so callers cannot change it.
+ */
+const WebTransportProtocol = "trevrpc-1";
+
+/** WebTransport constructor options passed through unchanged. */
+const WebTransportOptionKeys = [
+  "allowPooling",
+  "congestionControl",
+  "requireUnreliable",
+  "serverCertificateHashes",
+];
+
+const Backoff = Object.freeze({ initialDelayMs: 100, maxDelayMs: 30_000, jitter: 0.2 });
+
+const DefaultTransports = Object.freeze(["webtransport", "websocket"]);
+const DefaultFallbackDelayMs = 300;
+const DefaultReprobeIntervalMs = 5 * 60_000;
+
+/**
+ * A session that reconnects in the background after it is lost: WebTransport, or QMux over
+ * WebSocket when WebTransport is unavailable or blocked. Calls open their streams on the current
+ * session and fail fast with Unavailable while it reconnects; a call that was in flight when the
+ * session was lost is never replayed.
+ */
+export class Channel {
+  #dial;
   #onStateChange;
-  #options;
-  #state = "connecting";
-  #transport = null;
+  #session;
+  #transport;
+  #state = "ready";
   #waiters = [];
+  #stopped = new AbortController();
 
-  constructor(connect, options = {}, observeClosed = null, isConnectionFailure = () => false) {
-    super();
-    this.#connect = connect;
-    this.#observeClosed = observeClosed;
-    this.#isConnectionFailure = isConnectionFailure;
-    this.#onStateChange = options.onStateChange;
-    this.#options = normalizeChannelOptions(options);
-    queueMicrotask(() => this.#runConnectLoop(false));
+  /** Opens a channel and waits for its first session; use connect() instead. */
+  static async connect(url, options = {}) {
+    const dial = sessionDialer(url, options);
+    return new Channel(await dial(options.signal), dial, options.onStateChange);
   }
 
-  /** Reports whether a generation is currently ready to accept new calls. */
-  get ready() {
-    return this.#state === "ready";
+  constructor(dialed, dial, onStateChange) {
+    this.#dial = dial;
+    this.#onStateChange = onStateChange;
+    this.#adopt(dialed);
   }
 
-  /** Reports the channel lifecycle state. */
+  /** "ready", "reconnecting" while the session is being re-established, or "closed". */
   get state() {
     return this.#state;
   }
 
-  /** Identifies the current successful connection generation, starting at one. */
-  get generation() {
-    return this.#generation;
+  /** The transport of the current or last session: "webtransport" or "websocket". */
+  get transport() {
+    return this.#transport;
   }
 
-  /** Waits for the current or next connection generation to become ready. */
-  waitUntilReady() {
-    if (this.ready) {
-      return Promise.resolve();
-    }
-    if (this.#state === "closed") {
-      return Promise.reject(unavailable("channel is closed"));
+  /** Opens a bidirectional stream on the current session. */
+  createBidirectionalStream() {
+    if (this.#state !== "ready") {
+      return Promise.reject(unavailable(`channel is ${this.#state}`));
     }
-
-    return new Promise((resolve, reject) => {
-      this.#waiters.push({ resolve, reject });
-    });
+    return this.#session.createBidirectionalStream();
   }
 
-  /** Sends a unary call on the current generation without replaying it. */
-  async call(request, options = {}) {
-    const transport = this.#readyTransport();
-    try {
-      return await transport.call(request, options);
-    } catch (error) {
-      this.#operationFailed(transport, error);
-      throw error;
+  /**
+   * Opens a bidirectional stream on the current session, together with that session's WebTransport
+   * `datagrams` object, or undefined if the session has none (QMux over WebSocket). Calls that may
+   * use datagrams open their stream here, so their datagram flow belongs to the session that
+   * carries them even if the channel reconnects meanwhile.
+   */
+  createBidirectionalStreamWithDatagrams() {
+    if (this.#state !== "ready") {
+      return Promise.reject(unavailable(`channel is ${this.#state}`));
     }
+    const session = this.#session;
+    return session
+      .createBidirectionalStream()
+      .then((stream) => ({ stream, datagrams: session.datagrams }));
   }
 
-  /** Starts a streaming call on the current generation without resuming it later. */
-  async streamingCall(request, requestBody, options = {}) {
-    const transport = this.#readyTransport();
-    try {
-      const stream = await transport.streamingCall(request, requestBody, options);
-      return observedStream(stream, (error) => this.#operationFailed(transport, error));
-    } catch (error) {
-      this.#operationFailed(transport, error);
-      throw error;
+  /** Resolves once the channel is ready, immediately if it already is. */
+  waitUntilReady() {
+    if (this.#state === "ready") {
+      return Promise.resolve();
     }
+    if (this.#state === "closed") {
+      return Promise.reject(unavailable("channel is closed"));
+    }
+    return new Promise((resolve, reject) => this.#waiters.push({ resolve, reject }));
   }
 
-  /** Stops reconnecting and closes the current generation. */
-  close(closeInfo = {}) {
+  /** Stops reconnecting and closes the current session. */
+  close(closeInfo) {
     if (this.#state === "closed") {
       return;
     }
-
-    const transport = this.#transport;
-    this.#transport = null;
-    this.#connectAbort?.abort();
-    this.#connectAbort = null;
+    const session = this.#session;
+    this.#session = undefined;
+    this.#stopped.abort();
     this.#transition("closed");
-    this.#rejectWaiters(unavailable("channel is closed"));
-    safeClose(transport, closeInfo);
+    for (const waiter of this.#waiters.splice(0)) {
+      waiter.reject(unavailable("channel is closed"));
+    }
+    closeQuietly(session, closeInfo);
   }
 
-  #readyTransport() {
-    if (!this.ready || this.#transport == null) {
-      throw unavailable(`channel is ${this.#state}`);
-    }
-    return this.#transport;
+  #adopt({ session, transport }) {
+    this.#session = session;
+    this.#transport = transport;
+    const lost = (reason) => this.#lost(session, reason);
+    session.closed.then(lost, lost);
   }
 
-  async #runConnectLoop(reconnecting, initialError) {
-    if (this.#state === "closed" || this.#connectAbort != null) {
+  #lost(session, reason) {
+    if (session !== this.#session) {
       return;
     }
+    this.#session = undefined;
+    closeQuietly(session);
+    void this.#reconnect(reason);
+  }
 
-    const controller = new AbortController();
-    this.#connectAbort = controller;
-    let attempt = 0;
-    let error = initialError;
-
-    while (!controller.signal.aborted) {
-      attempt += 1;
-      const delayed = reconnecting || attempt > 1;
-      const delayMs = delayed
-        ? reconnectDelay(this.#options, reconnecting ? attempt - 1 : attempt - 2)
-        : 0;
-      this.#transition(reconnecting ? "reconnecting" : "connecting", {
-        attempt,
-        delayMs,
-        error,
-      });
-
-      if (delayed) {
-        await waitForDelay(delayMs, controller.signal);
-        if (controller.signal.aborted) {
-          return;
-        }
+  async #reconnect(error) {
+    const { signal } = this.#stopped;
+    for (let attempt = 1; !signal.aborted; attempt += 1) {
+      const delayMs = backoffDelay(attempt);
+      this.#transition("reconnecting", { attempt, delayMs, error });
+      await sleep(delayMs, signal);
+      if (signal.aborted) {
+        return;
       }
 
-      let transport;
       try {
-        transport = await this.#connect(controller.signal);
-      } catch (connectError) {
-        if (controller.signal.aborted) {
+        const dialed = await this.#dial(signal);
+        if (signal.aborted) {
+          closeQuietly(dialed.session);
           return;
         }
-        error = connectError;
-        continue;
-      }
-
-      if (controller.signal.aborted || this.#state === "closed") {
-        safeClose(transport);
+        this.#adopt(dialed);
+        this.#transition("ready", { attempt, transport: dialed.transport });
+        for (const waiter of this.#waiters.splice(0)) {
+          waiter.resolve();
+        }
         return;
+      } catch (dialError) {
+        error = dialError;
       }
-
-      this.#connectAbort = null;
-      this.#transport = transport;
-      this.#generation += 1;
-      this.#transition("ready", { attempt });
-      this.#resolveWaiters();
-      this.#watchTransport(transport);
-      return;
-    }
-  }
-
-  #watchTransport(transport) {
-    const closed = this.#observeClosed?.(transport);
-    if (closed == null || typeof closed.then !== "function") {
-      return;
-    }
-
-    Promise.resolve(closed).then(
-      (closeInfo) => this.#transportFailed(transport, closeInfo),
-      (error) => this.#transportFailed(transport, error),
-    );
-  }
-
-  #transportFailed(transport, error) {
-    if (this.#state !== "ready" || transport !== this.#transport) {
-      return;
-    }
-
-    this.#transport = null;
-    safeClose(transport);
-    void this.#runConnectLoop(true, error);
-  }
-
-  #operationFailed(transport, error) {
-    if (this.#isConnectionFailure(error)) {
-      this.#transportFailed(transport, error);
     }
   }
 
   #transition(state, extra = {}) {
     const previousState = this.#state;
     this.#state = state;
-    const detail = Object.freeze({
-      state,
-      previousState,
-      generation: this.#generation,
-      ...extra,
-    });
-
-    if (typeof this.#onStateChange === "function") {
-      try {
-        this.#onStateChange(detail);
-      } catch (error) {
-        globalThis.reportError?.(error);
-      }
+    try {
+      this.#onStateChange?.({ state, previousState, ...extra });
+    } catch (error) {
+      globalThis.reportError?.(error);
     }
-    this.dispatchEvent(lifecycleEvent("statechange", detail));
-    this.dispatchEvent(lifecycleEvent(state, detail));
   }
+}
 
-  #resolveWaiters() {
-    for (const waiter of this.#waiters.splice(0)) {
-      waiter.resolve();
+/** Opens a channel to a TrevRPC server and waits for its session to be ready. */
+export function connect(url, options = {}) {
+  return Channel.connect(url, options);
+}
+
+/**
+ * Returns `dial(signal)`, which establishes the next session as `{ session, transport }`.
+ *
+ * WebTransport is preferred. QMux over WebSocket starts in parallel once WebTransport fails or has
+ * not connected within `fallbackDelayMs`, and the first ready session wins. After WebSocket wins,
+ * reconnects use it directly until `reprobeIntervalMs` has passed.
+ */
+function sessionDialer(url, options) {
+  const webSocketUrl = options.webSocketUrl ?? defaultWebSocketUrl(url);
+  const candidates = {
+    webtransport: {
+      transport: "webtransport",
+      dial: (signal) => dialWebTransport(url, options, signal),
+    },
+    websocket: {
+      transport: "websocket",
+      dial: (signal) => dialWebSocket(webSocketUrl, options, signal),
+    },
+  };
+  const [primary, fallback, ...rest] = (options.transports ?? DefaultTransports).map((name) => {
+    const candidate = candidates[name];
+    if (candidate === undefined) {
+      throw new TypeError(`unknown transport "${name}"`);
     }
+    return candidate;
+  });
+  if (primary === undefined || rest.length > 0 || primary === fallback) {
+    throw new TypeError("transports must list one or two distinct transports");
   }
+  const delayMs = options.fallbackDelayMs ?? DefaultFallbackDelayMs;
+  const reprobeIntervalMs = options.reprobeIntervalMs ?? DefaultReprobeIntervalMs;
+  let fallbackWonAt = null;
 
-  #rejectWaiters(error) {
-    for (const waiter of this.#waiters.splice(0)) {
-      waiter.reject(error);
+  const dialOne = async (candidate, signal) => ({
+    session: await candidate.dial(signal),
+    transport: candidate.transport,
+  });
+  return async (signal) => {
+    if (fallback === undefined) {
+      return dialOne(primary, signal);
     }
-  }
+    if (fallbackWonAt !== null && Date.now() - fallbackWonAt < reprobeIntervalMs) {
+      return dialOne(fallback, signal);
+    }
+    const dialed = await dialRace(primary, fallback, { delayMs, signal });
+    fallbackWonAt = dialed.transport === fallback.transport ? Date.now() : null;
+    return dialed;
+  };
 }
 
-/** Returns transport options with channel lifecycle settings removed. */
-export function stripChannelOptions(options = {}) {
-  return Object.fromEntries(Object.entries(options).filter(([key]) => !ChannelOptionKeys.has(key)));
+/** The `wss://` URL of the same endpoint as an `https://` URL. */
+function defaultWebSocketUrl(url) {
+  const webSocketUrl = new URL(url);
+  webSocketUrl.protocol = webSocketUrl.protocol === "http:" ? "ws:" : "wss:";
+  return webSocketUrl.href;
 }
 
-/** Waits for initial readiness with caller-controlled cancellation and deadline. */
-export async function waitForInitialReady(channel, options = {}) {
-  const timeoutMs = options.timeoutMs;
-  if (timeoutMs != null && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
-    channel.close();
-    throw new TypeError("timeoutMs must be a non-negative finite number");
+/** Establishes a ready WebTransport session; aborting the signal abandons the attempt. */
+function dialWebTransport(url, options, signal) {
+  const WebTransportConstructor = options.WebTransport ?? globalThis.WebTransport;
+  if (typeof WebTransportConstructor !== "function") {
+    throw unavailable("WebTransport is not available in this JavaScript runtime");
   }
-
-  const signal = options.signal;
   if (signal?.aborted) {
-    channel.close();
-    throw initialAbortError(signal);
+    throw abortError(signal);
   }
-  if (timeoutMs === 0) {
-    channel.close();
-    throw deadlineExceeded("initial connection deadline exceeded");
+  return establish(
+    new WebTransportConstructor(url, transportOptions(options)),
+    "WebTransport",
+    signal,
+    requireWireVersion,
+  );
+}
+
+/**
+ * Fails a ready WebTransport session whose server selected another protocol than version 1. An
+ * empty or missing `protocol` means version 1: older browsers do not support the option, and the
+ * Rust server cannot echo a selection. A mismatch is FailedPrecondition rather than Unavailable
+ * because retrying the same server cannot fix it; the channel still treats it like any failed
+ * dial, so the WebSocket fallback and the reconnect loop carry on.
+ */
+function requireWireVersion(session) {
+  const { protocol } = session;
+  if (typeof protocol === "string" && protocol !== "" && protocol !== WebTransportProtocol) {
+    throw failedPrecondition(
+      `server selected WebTransport protocol "${protocol}", but this client speaks "${WebTransportProtocol}"`,
+    );
   }
+}
 
-  const timeoutAbort = timeoutMs == null ? null : new AbortController();
-  let removeAbort = () => {};
+/** Establishes a ready QMux over WebSocket session; aborting the signal abandons the attempt. */
+function dialWebSocket(url, options, signal) {
+  if (signal?.aborted) {
+    throw abortError(signal);
+  }
+  let session;
   try {
-    const waits = [channel.waitUntilReady()];
-    if (signal != null) {
-      waits.push(
-        new Promise((_, reject) => {
-          const rejectCancelled = () => reject(initialAbortError(signal));
-          if (signal.aborted) {
-            rejectCancelled();
-            return;
-          }
-          signal.addEventListener("abort", rejectCancelled, { once: true });
-          removeAbort = () => signal.removeEventListener("abort", rejectCancelled);
-        }),
-      );
-    }
-    if (timeoutMs != null) {
-      waits.push(
-        waitForDelay(timeoutMs, timeoutAbort.signal).then(() => {
-          throw deadlineExceeded("initial connection deadline exceeded");
-        }),
-      );
-    }
-    await Promise.race(waits);
+    session = new QMuxWebSocketSession(url, { WebSocket: options.WebSocket });
   } catch (error) {
-    channel.close();
-    throw error;
-  } finally {
-    timeoutAbort?.abort();
-    removeAbort();
+    throw statusFromTransportError(error);
   }
+  return establish(session, "WebSocket", signal);
 }
 
-function normalizeChannelOptions(options) {
-  void options;
-  return DefaultChannelOptions;
+/**
+ * Waits for a new session to become ready, closing it if it fails or the signal aborts. `verify`
+ * may reject the ready session by throwing.
+ */
+async function establish(session, name, signal, verify) {
+  const abandon = () => closeQuietly(session);
+  signal?.addEventListener("abort", abandon, { once: true });
+  try {
+    // A session that fails to connect settles both promises; one that closes first never becomes
+    // ready, so readiness must not wait for it.
+    await Promise.race([
+      session.ready,
+      session.closed.then(() => {
+        throw unavailable(`${name} session closed before becoming ready`);
+      }),
+    ]);
+    verify?.(session);
+  } catch (error) {
+    closeQuietly(session);
+    throw signal?.aborted ? abortError(signal) : statusFromTransportError(error);
+  } finally {
+    signal?.removeEventListener("abort", abandon);
+  }
+  if (signal?.aborted) {
+    closeQuietly(session);
+    throw abortError(signal);
+  }
+  return session;
 }
 
-function initialAbortError(signal) {
-  if (signal.reason?.name === "TrevRpcError") {
-    return signal.reason;
-  }
-  const error = cancelled("initial connection cancelled");
-  if (signal.reason !== undefined) {
-    Object.defineProperty(error, "cause", { configurable: true, value: signal.reason });
+function transportOptions(options) {
+  const picked = { protocols: [WebTransportProtocol] };
+  for (const key of WebTransportOptionKeys) {
+    if (options[key] !== undefined) {
+      picked[key] = options[key];
+    }
   }
-  return error;
+  return picked;
 }
 
-function reconnectDelay(options, exponent) {
-  const exponential = options.initialDelayMs * options.multiplier ** exponent;
-  const base = Math.min(options.maxDelayMs, exponential);
-  const jitter = 1 + (Math.random() * 2 - 1) * options.jitter;
-  return Math.min(options.maxDelayMs, Math.max(0, base * jitter));
+function abortError(signal) {
+  return cancelled("connection cancelled", signal.reason);
 }
 
-async function waitForDelay(delayMs, signal) {
-  let remaining = delayMs;
-  while (remaining > 0 && !signal.aborted) {
-    const chunk = Math.min(remaining, MaxTimerDelayMs);
-    await waitForTimer(chunk, signal);
-    remaining -= chunk;
-  }
+/** Exponential backoff with jitter, capped at maxDelayMs. */
+function backoffDelay(attempt) {
+  const { initialDelayMs, maxDelayMs, jitter } = Backoff;
+  const base = Math.min(maxDelayMs, initialDelayMs * 2 ** (attempt - 1));
+  return Math.min(maxDelayMs, base * (1 + (Math.random() * 2 - 1) * jitter));
 }
 
-function waitForTimer(delayMs, signal) {
+function sleep(delayMs, signal) {
   return new Promise((resolve) => {
-    const timer = setTimeout(done, delayMs);
-    signal.addEventListener("abort", done, { once: true });
-
-    function done() {
+    const done = () => {
       clearTimeout(timer);
       signal.removeEventListener("abort", done);
       resolve();
-    }
+    };
+    const timer = setTimeout(done, delayMs);
+    signal.addEventListener("abort", done, { once: true });
   });
 }
 
-function lifecycleEvent(type, detail) {
-  const event = new Event(type);
-  Object.defineProperty(event, "detail", { value: detail });
-  return event;
-}
-
-function observedStream(stream, onFailure) {
-  const iterator = stream[Symbol.asyncIterator]();
-  const observed = {
-    [Symbol.asyncIterator]() {
-      return this;
-    },
-    next(...args) {
-      return observeResult(() => iterator.next(...args), onFailure);
-    },
-  };
-
-  for (const method of ["nextBatch", "nextBodyBatch"]) {
-    if (typeof iterator[method] === "function") {
-      observed[method] = (...args) => observeResult(() => iterator[method](...args), onFailure);
-    }
-  }
-  if (typeof iterator.return === "function") {
-    observed.return = (...args) => iterator.return(...args);
-  }
-  if (typeof iterator.throw === "function") {
-    observed.throw = (...args) => iterator.throw(...args);
-  }
-  return observed;
-}
-
-async function observeResult(operation, onFailure) {
-  try {
-    return await operation();
-  } catch (error) {
-    onFailure(error);
-    throw error;
-  }
-}
-
-function safeClose(transport, closeInfo) {
+function closeQuietly(session, closeInfo) {
   try {
-    transport?.close?.(closeInfo);
+    session?.close(closeInfo);
   } catch {
-    // The failed generation may already have released its transport resources.
+    // The session may already be gone.
   }
 }