@trevrpc/trevrpc-js 1.0.0 → 1.2.0

package/src/channel.js

@@ -1,4 +1,14 @@
-import { cancelled, statusFromTransportError, unavailable } from "./status.js";
+import { ConnectionMetadataKey, ConnectionMetadataSource } from "./connection-metadata.js";
+import { QMuxWebSocketSession } from "./qmux/session.js";
+import { dialRace } from "./race.js";
+import { cancelled, failedPrecondition, statusFromTransportError, unavailable } from "./status.js";
+import { StreamBudget, StreamBudgetKey } from "./stream-compression.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 = [
@@ -10,29 +20,57 @@ const WebTransportOptionKeys = [
 
 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 WebTransport session that reconnects in the background after it is lost. 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.
+ * 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;
+  #compression;
   #onStateChange;
   #session;
+  #transport;
   #state = "ready";
   #waiters = [];
   #stopped = new AbortController();
 
   /** Opens a channel and waits for its first session; use connect() instead. */
   static async connect(url, options = {}) {
-    const dial = (signal) => dialSession(url, options, signal);
-    return new Channel(await dial(options.signal), dial, options.onStateChange);
+    const dial = sessionDialer(url, options);
+    // Checked before dialing, so an invalid option never leaves a session behind.
+    const streamBudget = new StreamBudget(options.streamCompressionMemory);
+    const connectionMetadata = new ConnectionMetadataSource(options.connectionMetadata);
+    return new Channel(await dial(options.signal), dial, {
+      ...options,
+      streamBudget,
+      connectionMetadata,
+    });
   }
 
-  constructor(session, dial, onStateChange) {
+  constructor(
+    dialed,
+    dial,
+    {
+      compression,
+      streamBudget = new StreamBudget(),
+      connectionMetadata = new ConnectionMetadataSource(),
+      onStateChange,
+    } = {},
+  ) {
     this.#dial = dial;
+    this.#compression = compression;
+    // The memory budget of the stream compression contexts of this channel's calls.
+    this[StreamBudgetKey] = streamBudget;
+    // The connection metadata every call of this channel carries.
+    this[ConnectionMetadataKey] = connectionMetadata;
     this.#onStateChange = onStateChange;
-    this.#adopt(session);
+    this.#adopt(dialed);
   }
 
   /** "ready", "reconnecting" while the session is being re-established, or "closed". */
@@ -40,6 +78,25 @@ export class Channel {
     return this.#state;
   }
 
+  /** The transport of the current or last session: "webtransport" or "websocket". */
+  get transport() {
+    return this.#transport;
+  }
+
+  /** The compression settings from the connect options, or undefined. */
+  get compression() {
+    return this.#compression;
+  }
+
+  /**
+   * Replaces the channel's connection metadata, which every call carries; empty or missing
+   * metadata removes it. Calls started after this use the new metadata. Throws InvalidArgument if
+   * it is invalid, and then keeps the old.
+   */
+  setConnectionMetadata(metadata) {
+    this[ConnectionMetadataKey].set(metadata);
+  }
+
   /** Opens a bidirectional stream on the current session. */
   createBidirectionalStream() {
     if (this.#state !== "ready") {
@@ -48,6 +105,21 @@ export class Channel {
     return this.#session.createBidirectionalStream();
   }
 
+  /**
+   * Opens a bidirectional stream on the current session, together with that session: the
+   * WebTransport or QMux over WebSocket session, whose `datagrams` are undefined for QMux. Calls
+   * whose setup depends on their session (dictionary negotiation, datagram flows) open their stream
+   * here, so that setup belongs to the session that carries them even if the channel reconnects
+   * meanwhile.
+   */
+  createBidirectionalStreamWithSession() {
+    if (this.#state !== "ready") {
+      return Promise.reject(unavailable(`channel is ${this.#state}`));
+    }
+    const session = this.#session;
+    return session.createBidirectionalStream().then((stream) => ({ stream, session }));
+  }
+
   /** Resolves once the channel is ready, immediately if it already is. */
   waitUntilReady() {
     if (this.#state === "ready") {
@@ -74,8 +146,9 @@ export class Channel {
     closeQuietly(session, closeInfo);
   }
 
-  #adopt(session) {
+  #adopt({ session, transport }) {
     this.#session = session;
+    this.#transport = transport;
     const lost = (reason) => this.#lost(session, reason);
     session.closed.then(lost, lost);
   }
@@ -100,13 +173,13 @@ export class Channel {
       }
 
       try {
-        const session = await this.#dial(signal);
+        const dialed = await this.#dial(signal);
         if (signal.aborted) {
-          closeQuietly(session);
+          closeQuietly(dialed.session);
           return;
         }
-        this.#adopt(session);
-        this.#transition("ready", { attempt });
+        this.#adopt(dialed);
+        this.#transition("ready", { attempt, transport: dialed.transport });
         for (const waiter of this.#waiters.splice(0)) {
           waiter.resolve();
         }
@@ -128,13 +201,70 @@ export class Channel {
   }
 }
 
-/** Opens a channel to a WebTransport server and waits for its session to be ready. */
+/** 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;
+
+  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;
+  };
+}
+
+/** 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;
+}
+
 /** Establishes a ready WebTransport session; aborting the signal abandons the attempt. */
-async function dialSession(url, options, signal) {
+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");
@@ -142,8 +272,49 @@ async function dialSession(url, options, signal) {
   if (signal?.aborted) {
     throw abortError(signal);
   }
+  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}"`,
+    );
+  }
+}
+
+/** 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 {
+    session = new QMuxWebSocketSession(url, { WebSocket: options.WebSocket });
+  } catch (error) {
+    throw statusFromTransportError(error);
+  }
+  return establish(session, "WebSocket", signal);
+}
 
-  const session = new WebTransportConstructor(url, transportOptions(options));
+/**
+ * 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 {
@@ -152,9 +323,10 @@ async function dialSession(url, options, signal) {
     await Promise.race([
       session.ready,
       session.closed.then(() => {
-        throw unavailable("WebTransport session closed before becoming ready");
+        throw unavailable(`${name} session closed before becoming ready`);
       }),
     ]);
+    verify?.(session);
   } catch (error) {
     closeQuietly(session);
     throw signal?.aborted ? abortError(signal) : statusFromTransportError(error);
@@ -169,7 +341,7 @@ async function dialSession(url, options, signal) {
 }
 
 function transportOptions(options) {
-  const picked = {};
+  const picked = { protocols: [WebTransportProtocol] };
   for (const key of WebTransportOptionKeys) {
     if (options[key] !== undefined) {
       picked[key] = options[key];