@trevrpc/trevrpc-js 0.2.2 → 1.0.0

package/src/channel.js

@@ -1,375 +1,210 @@
-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 { cancelled, statusFromTransportError, unavailable } from "./status.js";
+
+/** WebTransport constructor options passed through unchanged. */
+const WebTransportOptionKeys = [
+  "allowPooling",
+  "congestionControl",
+  "requireUnreliable",
+  "serverCertificateHashes",
+];
+
+const Backoff = Object.freeze({ initialDelayMs: 100, maxDelayMs: 30_000, jitter: 0.2 });
+
+/**
+ * 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.
+ */
+export class Channel {
+  #dial;
   #onStateChange;
-  #options;
-  #state = "connecting";
-  #transport = null;
+  #session;
+  #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 = (signal) => dialSession(url, options, signal);
+    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(session, dial, onStateChange) {
+    this.#dial = dial;
+    this.#onStateChange = onStateChange;
+    this.#adopt(session);
   }
 
-  /** 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;
+  /** Opens a bidirectional stream on the current session. */
+  createBidirectionalStream() {
+    if (this.#state !== "ready") {
+      return Promise.reject(unavailable(`channel is ${this.#state}`));
+    }
+    return this.#session.createBidirectionalStream();
   }
 
-  /** Waits for the current or next connection generation to become ready. */
+  /** Resolves once the channel is ready, immediately if it already is. */
   waitUntilReady() {
-    if (this.ready) {
+    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 });
-    });
-  }
-
-  /** 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;
-    }
-  }
-
-  /** 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;
-    }
+    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) {
+    this.#session = session;
+    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 session = await this.#dial(signal);
+        if (signal.aborted) {
+          closeQuietly(session);
           return;
         }
-        error = connectError;
-        continue;
-      }
-
-      if (controller.signal.aborted || this.#state === "closed") {
-        safeClose(transport);
+        this.#adopt(session);
+        this.#transition("ready", { attempt });
+        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);
-      }
-    }
-    this.dispatchEvent(lifecycleEvent("statechange", detail));
-    this.dispatchEvent(lifecycleEvent(state, detail));
-  }
-
-  #resolveWaiters() {
-    for (const waiter of this.#waiters.splice(0)) {
-      waiter.resolve();
-    }
-  }
-
-  #rejectWaiters(error) {
-    for (const waiter of this.#waiters.splice(0)) {
-      waiter.reject(error);
+    try {
+      this.#onStateChange?.({ state, previousState, ...extra });
+    } catch (error) {
+      globalThis.reportError?.(error);
     }
   }
 }
 
-/** Returns transport options with channel lifecycle settings removed. */
-export function stripChannelOptions(options = {}) {
-  return Object.fromEntries(Object.entries(options).filter(([key]) => !ChannelOptionKeys.has(key)));
+/** Opens a channel to a WebTransport server and waits for its session to be ready. */
+export function connect(url, options = {}) {
+  return Channel.connect(url, options);
 }
 
-/** 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. */
+async function dialSession(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);
-  }
-  if (timeoutMs === 0) {
-    channel.close();
-    throw deadlineExceeded("initial connection deadline exceeded");
+    throw abortError(signal);
   }
 
-  const timeoutAbort = timeoutMs == null ? null : new AbortController();
-  let removeAbort = () => {};
+  const session = new WebTransportConstructor(url, transportOptions(options));
+  const abandon = () => closeQuietly(session);
+  signal?.addEventListener("abort", abandon, { once: true });
   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);
+    // 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("WebTransport session closed before becoming ready");
+      }),
+    ]);
   } catch (error) {
-    channel.close();
-    throw error;
+    closeQuietly(session);
+    throw signal?.aborted ? abortError(signal) : statusFromTransportError(error);
   } finally {
-    timeoutAbort?.abort();
-    removeAbort();
+    signal?.removeEventListener("abort", abandon);
   }
+  if (signal?.aborted) {
+    closeQuietly(session);
+    throw abortError(signal);
+  }
+  return session;
 }
 
-function normalizeChannelOptions(options) {
-  void options;
-  return DefaultChannelOptions;
-}
-
-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 = {};
+  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.
   }
 }