@trevrpc/trevrpc-js 1.3.2 → 1.5.0

package/README.md

@@ -36,11 +36,39 @@ protoc \
 
 This writes `greeter.trevrpc.js` and `greeter.trevrpc.d.ts`. Plugin parameters (`--trevrpc-js_out=key=value,key=value:dir`):
 
-| Parameter             | Default                  | Meaning                                                                            |
-| --------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
-| `runtime_import`      | `@trevrpc/trevrpc-js`    | Module specifier the generated JavaScript imports.                                 |
-| `runtime_type_import` | same as `runtime_import` | Module specifier the declarations import; required when `runtime_import` is a URL. |
-| `file_suffix`         | `.trevrpc.js`            | Suffix of the generated files.                                                     |
+| Parameter             | Default                  | Meaning                                                                              |
+| --------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
+| `runtime_import`      | `@trevrpc/trevrpc-js`    | Module specifier the generated JavaScript imports.                                   |
+| `runtime_type_import` | same as `runtime_import` | Module specifier the declarations import; required when `runtime_import` is a URL.   |
+| `file_suffix`         | `.trevrpc.js`            | Suffix of the generated files.                                                       |
+| `int64`               | `bigint`                 | How decoded 64-bit integers are represented: `bigint`, `number`, `string` or `long`. |
+
+### Generated types
+
+The declarations cover the file's own messages and enums and every type they and its services use, including those of imported files. Each message has two shapes:
+
+- `Foo`, a decoded message, which calls return and streams yield. Every field reads a value: scalars and enums their default when unset, repeated fields and maps an empty array and object, and message and `optional` fields `null` when unset.
+- `FooInit`, a message to send, in which every field may be left out. Requests take it, and a decoded `Foo` can be sent as one.
+
+Each enum is exported as a frozen object of its values and as the type of those values. When every value starts with the enum's name in upper snake case, the prefix is dropped, as protobuf-es does: `TIME_INTERVAL_HOUR` of `TimeInterval` is `TimeInterval.HOUR`.
+
+```ts
+import { TimeInterval, type Sample } from "./gen/metrics.trevrpc.js";
+
+const sample: Sample = await client.get({ interval: TimeInterval.HOUR });
+sample.count; // bigint, never undefined
+```
+
+64-bit integers decode as `bigint` by default; requests take a `bigint`, a `number` or a decimal `string`. The `int64` plugin option picks `number` (exact up to 2^53), `string`, or `long` (protobuf.js `Long` objects, without the conversion) instead, and a field's `jstype` option (`[jstype = JS_STRING]` or `JS_NUMBER`) overrides it for that field. 64-bit map keys are decimal strings. `JSON.stringify` throws on a `bigint`, so a decoded message with a 64-bit field needs a replacer to serialize, such as `(key, value) => (typeof value === "bigint" ? value.toString() : value)`, or generate with `int64=string`.
+
+`google.protobuf.Timestamp`, `Duration`, `Empty`, `Struct`, `Value`, `ListValue` and `NullValue` are declared once by the runtime, which generated files import (Timestamp and Duration only with `bigint`, since the runtime declares their seconds as one). The runtime has helpers for them: `timestampFromDate`, `timestampFromMs`, `timestampDate`, `timestampMs`, `durationFromMs`, `durationMs`, `structFromJson`, `structToJson`, `valueFromJson` and `valueToJson`. The Timestamp and Duration readers take seconds in any representation.
+
+```ts
+import { timestampDate, timestampFromDate } from "@trevrpc/trevrpc-js";
+
+await client.put({ at: timestampFromDate(new Date()) });
+const at = sample.at === null ? undefined : timestampDate(sample.at);
+```
 
 ## Client
 
@@ -82,7 +110,7 @@ channel.close();
 
 ### Call options
 
-Every method takes `CallOptions` as its last argument; the same options can be given to the client constructor as defaults, and per-call `metadata` is merged over the defaults per key.
+Every method takes `CallOptions` as its last argument; the same options can be given to the client constructor as defaults, and per-call `metadata` is merged over the defaults per key. The constructor also takes `interceptors` ([below](#interceptors)).
 
 | Option               | Meaning                                                                                       |
 | -------------------- | --------------------------------------------------------------------------------------------- |
@@ -114,10 +142,54 @@ call.
 
 - To find the final status while the caller only sends, a client-streaming or bidirectional call reads the response ahead of `recv()` while its request side is open: at most 32 frames or 1 MiB (plus one frame of at most `maxFrameSize`) are held; beyond that reading pauses and flow control applies until `recv()` takes messages. Responses read ahead are delivered in order, including before an error that ended the stream.
 
+### Rendering long streams
+
+Once response messages are buffered, `for await` hands them over without returning to the event loop: each `next()` resolves as a microtask, as with any async iterator over a `fetch` body. When the network delivers faster than the page consumes, which is always the case on localhost, a loop over a long stream runs to its end before the browser renders anything, timers fire, or input is handled. The client does not yield on its own, because a timer-based yield would slow streams in hidden tabs and add latency for consumers that do not render.
+
+A page that renders a stream should batch messages per animation frame and, after a time budget, yield with a timer so that frame can render:
+
+```js
+let batch = [];
+let frame;
+const flush = () => {
+  frame = undefined;
+  store.append(batch);
+  batch = [];
+};
+
+let sliceStart = performance.now();
+try {
+  for await (const row of stream) {
+    batch.push(row);
+    frame ??= requestAnimationFrame(flush);
+    if (performance.now() - sliceStart > 8) {
+      if (document.hidden) {
+        cancelAnimationFrame(frame);
+        flush();
+      } else {
+        await new Promise((resolve) => setTimeout(resolve));
+      }
+      sliceStart = performance.now();
+    }
+  }
+} finally {
+  if (frame !== undefined) {
+    cancelAnimationFrame(frame);
+    flush();
+  }
+}
+```
+
+- `scheduler.yield()` does not help: Chromium resumes its continuation before rendering, so every message still lands in one frame.
+- Hidden tabs run no animation frames and throttle timers to about one per second, so while `document.hidden` the loop applies the batch itself after each time budget instead of yielding. It holds at most one budget's worth of messages, and a stream in a background tab keeps its speed.
+- If the stream fails or the loop is left early, which cancels the call, the `finally` still applies the messages received before.
+
 ### Connections
 
 `connect()` opens a session and resolves when it is ready; it rejects if no transport can establish one. After that the `Channel` re-establishes the session in the background with exponential backoff whenever it is lost. Calls fail fast with `Unavailable` while `channel.state` is `"reconnecting"` and are never replayed; use `await channel.waitUntilReady()` or the `onStateChange` option to follow the state. `channel.close()` stops reconnecting.
 
+`createChannel(url, options)` takes the same options but returns the channel right away, in the `"connecting"` state, so generated clients can be created before it is connected. Calls started while it connects wait for that first attempt, within their own deadline and signal; if it fails they fail with its error, and the channel goes on reconnecting with backoff like after a lost session. The `signal` option does not apply to it; close the channel to give up.
+
 ```js
 const channel = await connect(url, {
   signal: AbortSignal.timeout(10_000), // cancels the initial connection only
@@ -126,11 +198,11 @@ const channel = await connect(url, {
 });
 ```
 
-`serverCertificateHashes` trusts a self-signed ECDSA certificate that is valid for at most 14 days by its SHA-256 hash, which is how development servers and the interop tests are reached. It applies to WebTransport only: the WebSocket fallback needs a certificate the browser trusts. `allowPooling`, `congestionControl` and `requireUnreliable` are passed to the `WebTransport` constructor.
+`serverCertificateHashes` trusts a self-signed ECDSA certificate that is valid for at most 14 days by its SHA-256 hash, which is how development servers and the interop tests are reached. It applies to WebTransport only: the WebSocket fallback needs a certificate the browser trusts. `serverCertificateHashesUrl` names a URL that publishes a development server's hashes, such as a path the development web server proxies to the Go or Rust `DevelopmentCertificate`. Every WebTransport attempt fetches it, so reconnects follow a rotated certificate, and adds its hashes; a 404 adds none, so the same build works against a server with a trusted certificate. `fetchServerCertificateHashes(url)` returns the same hashes for code that builds its own options. See [Development certificates](https://trev.zip/llc/TrevRPC/wiki/WebTransport#development-certificates). `allowPooling`, `congestionControl` and `requireUnreliable` are passed to the `WebTransport` constructor.
 
 `connect()` always offers the WebTransport protocol `trevrpc-1` (wire version 1) through the `protocols` constructor option; it cannot be changed. If the server selects any other protocol, that connection attempt fails with `Code.FailedPrecondition` and the channel carries on as after any failed dial: the WebSocket fallback starts, or a reconnect is retried with backoff. An empty or missing selection means version 1, because older browsers cannot negotiate protocols.
 
-Any object with `createBidirectionalStream()`, including a plain `WebTransport` session, can be used as the transport of a generated client. Create such a session with `new WebTransport(url, { protocols: ["trevrpc-1"] })` so the server knows the wire version. Requests name the method by its full path, `/<package.Service>/<Method>` (for example `/example.greeter.Greeter/SayHello`), which the generated clients build from the service and method names.
+Any object with `createBidirectionalStream()`, including a plain `WebTransport` session, can be used as the transport of a generated client. A transport that wraps a `Channel` should forward its `createBidirectionalStreamWithSession()`, `compression`, `connectionMetadata`, `streamCompressionBudget` and `interceptors`; without them its calls carry no connection metadata, get a stream compression budget of their own, and skip the channel's interceptors. Create such a session with `new WebTransport(url, { protocols: ["trevrpc-1"] })` so the server knows the wire version. Requests name the method by its full path, `/<package.Service>/<Method>` (for example `/example.greeter.Greeter/SayHello`), which the generated clients build from the service and method names.
 
 ### Connection metadata
 
@@ -142,7 +214,39 @@ channel.setConnectionMetadata({ authorization: `Bearer ${refreshed}` }); // call
 channel.setConnectionMetadata(); // removes it
 ```
 
-A changed set is sent in full again on every session, and so is the set on a session after a reconnect. Keys follow the rules of call metadata. The `Channel` is the only transport that supports it.
+A changed set is sent in full again on every session, and so is the set on a session after a reconnect. Keys follow the rules of call metadata. Other transports carry it when they forward a channel's `connectionMetadata`.
+
+### Interceptors
+
+Interceptors run around every call of a client, for what each call needs, such as reacting to an expired session. Set them on the channel, for every client created on it, or on a client, after the channel's:
+
+```js
+const channel = createChannel(url, {
+  interceptors: [
+    async (call) => {
+      // call.method, .service, .name, .kind, .timeoutMs and .signal describe the call.
+      call.metadata.authorization = `Bearer ${await session.token()}`;
+      const started = session.id;
+      return ({ code }) => {
+        if (code === Code.Unauthenticated && session.id === started) {
+          session.clear();
+          location.assign("/sign-in");
+        }
+      };
+    },
+  ],
+});
+const client = new GreeterClient(channel, { interceptors: [logCalls] });
+```
+
+- An interceptor runs before the call starts, in order with the others, and may wait. It may add, replace and delete entries of `call.metadata`, which is validated after the last interceptor. The call's deadline starts after the interceptors; an interceptor that waits can watch `call.signal`.
+- It may return a finish function, which is called once with `{ code, error }` when the call ends: when a unary call settles, and when a streaming call receives its final status or fails, including when it is cancelled, so nothing has to wrap a stream's iterator. `code` is `Code.Ok` on success. Finish functions run innermost first; one that throws is reported and does not affect the call. A streaming call that is neither read to its end nor closed does not end.
+- An interceptor that throws fails the call with what it threw before it starts; the finish functions of earlier interceptors still run.
+- A client-streaming call has a `status` promise too, like the other streaming calls.
+
+### Effect
+
+The separate package [`@trevrpc/effect`](effect) wraps a generated client for [Effect](https://effect.website): `createEffectClient(GreeterService, new GreeterClient(channel))` returns a client whose unary calls are effects, whose server-streaming calls are streams, and whose client-streaming and bidirectional calls take their requests as a stream. Interrupting an effect or stream cancels its call. `TrevRpcError` has a `_tag` of `"TrevRpcError"`, so `Effect.catchTag` matches it.
 
 ### Compression
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Browser WebTransport client and protobuf.js code generator for TrevRPC",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {
@@ -37,7 +37,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node zstd-wasm/embed.js && node interop-browser/build.js",
+    "build": "node zstd-wasm/embed.js && node interop-browser/build.js && node test/generate.js",
     "format": "oxfmt --write",
     "format:check": "oxfmt --check",
     "lint": "oxlint --deny-warnings",

package/src/certificate-hashes.js

@@ -0,0 +1,57 @@
+import { unavailable } from "./status.js";
+
+/**
+ * Fetches the certificate hashes a TrevRPC development server publishes, as WebTransport
+ * `serverCertificateHashes`. The server answers JSON such as
+ * `[{"algorithm":"sha-256","value":"<hex>"}]`; a 404 means it has a certificate the browser trusts
+ * already, and yields no hashes. Any other failure rejects with Unavailable.
+ */
+export async function fetchServerCertificateHashes(url, { signal, fetch = globalThis.fetch } = {}) {
+  if (typeof fetch !== "function") {
+    throw unavailable("fetch is not available in this JavaScript runtime");
+  }
+  let response;
+  try {
+    response = await fetch(url, { signal, cache: "no-store" });
+  } catch (error) {
+    if (signal?.aborted) {
+      throw error;
+    }
+    throw unavailable(`cannot fetch server certificate hashes: ${error?.message ?? error}`, error);
+  }
+  if (response.status === 404) {
+    return [];
+  }
+  if (!response.ok) {
+    throw unavailable(`cannot fetch server certificate hashes: HTTP ${response.status}`);
+  }
+  let entries;
+  try {
+    entries = await response.json();
+  } catch (error) {
+    if (signal?.aborted) {
+      throw error;
+    }
+    throw unavailable("server certificate hashes are not JSON", error);
+  }
+  if (!Array.isArray(entries)) {
+    throw unavailable("server certificate hashes are not a JSON array");
+  }
+  return entries.map(parseHash);
+}
+
+function parseHash(entry) {
+  const { algorithm, value } = entry ?? {};
+  if (
+    typeof algorithm !== "string" ||
+    typeof value !== "string" ||
+    !/^(?:[0-9a-f]{2})+$/iu.test(value)
+  ) {
+    throw unavailable(`invalid server certificate hash ${JSON.stringify(entry)}`);
+  }
+  const bytes = new Uint8Array(value.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+  }
+  return { algorithm, value: bytes };
+}

package/src/channel.js

@@ -1,8 +1,10 @@
-import { ConnectionMetadataKey, ConnectionMetadataSource } from "./connection-metadata.js";
+import { fetchServerCertificateHashes } from "./certificate-hashes.js";
+import { ConnectionMetadataSource } from "./connection-metadata.js";
+import { interceptorList } from "./interceptor.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";
+import { StreamBudget } from "./stream-compression.js";
 
 /**
  * The WebTransport protocol that names wire version 1, offered through the `protocols` constructor
@@ -28,57 +30,77 @@ 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.
+ * session was lost is never replayed. Calls started while the channel first connects wait for
+ * that attempt, and fail with its error if it fails.
  */
 export class Channel {
   #dial;
   #compression;
+  #streamCompressionBudget;
+  #connectionMetadata;
+  #interceptors;
   #onStateChange;
   #session;
   #transport;
-  #state = "ready";
+  #state = "connecting";
+  /**
+   * Settles once the first attempt to connect did: with undefined if it established a session,
+   * and with its error otherwise.
+   */
+  #connecting;
   #waiters = [];
   #stopped = new AbortController();
 
   /** Opens a channel and waits for its first session; use connect() instead. */
   static async connect(url, options = {}) {
-    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,
-    });
+    const { signal } = options;
+    if (signal?.aborted) {
+      throw abortError(signal);
+    }
+    const channel = new Channel(url, options, { retry: false });
+    const abandon = () => channel.close();
+    signal?.addEventListener("abort", abandon, { once: true });
+    try {
+      const failure = await channel.#connecting;
+      if (signal?.aborted) {
+        throw abortError(signal);
+      }
+      if (failure !== undefined) {
+        throw failure;
+      }
+      return channel;
+    } finally {
+      signal?.removeEventListener("abort", abandon);
+    }
   }
 
-  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(dialed);
+  /**
+   * Starts connecting; use createChannel() or connect() instead. Unless `retry` is false, a first
+   * attempt that fails is retried like a reconnect; otherwise it closes the channel.
+   */
+  constructor(url, options = {}, { retry = true } = {}) {
+    // Checked before dialing, so an invalid option never leaves a session behind.
+    this.#dial = sessionDialer(url, options);
+    this.#interceptors = interceptorList(options.interceptors, "interceptors");
+    this.#streamCompressionBudget = new StreamBudget(options.streamCompressionMemory);
+    this.#connectionMetadata = new ConnectionMetadataSource(options.connectionMetadata);
+    this.#compression = options.compression;
+    this.#onStateChange = options.onStateChange;
+    this.#connecting = this.#connect(retry);
   }
 
-  /** "ready", "reconnecting" while the session is being re-established, or "closed". */
+  /**
+   * "connecting" until the first session is ready, "ready", "reconnecting" while the session is
+   * being re-established, or "closed".
+   */
   get state() {
     return this.#state;
   }
 
-  /** The transport of the current or last session: "webtransport" or "websocket". */
+  /**
+   * The transport of the current or last session: "webtransport" or "websocket"; undefined before
+   * the first.
+   */
   get transport() {
     return this.#transport;
   }
@@ -88,21 +110,33 @@ export class Channel {
     return this.#compression;
   }
 
+  /** The memory budget of the stream compression contexts of this channel's calls. */
+  get streamCompressionBudget() {
+    return this.#streamCompressionBudget;
+  }
+
+  /** The connection metadata every call of this channel carries. */
+  get connectionMetadata() {
+    return this.#connectionMetadata;
+  }
+
+  /** The interceptors that every client created on this channel runs around its calls. */
+  get interceptors() {
+    return this.#interceptors;
+  }
+
   /**
    * 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);
+    this.#connectionMetadata.set(metadata);
   }
 
   /** 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();
+    return this.#withSession((session) => session.createBidirectionalStream());
   }
 
   /**
@@ -113,11 +147,29 @@ export class Channel {
    * meanwhile.
    */
   createBidirectionalStreamWithSession() {
-    if (this.#state !== "ready") {
-      return Promise.reject(unavailable(`channel is ${this.#state}`));
+    return this.#withSession((session) =>
+      session.createBidirectionalStream().then((stream) => ({ stream, session })),
+    );
+  }
+
+  /**
+   * Calls `open` with the current session. While the channel first connects, that waits for the
+   * attempt, and a failed attempt fails the call with its error; otherwise a channel without a
+   * session fails it with Unavailable.
+   */
+  #withSession(open) {
+    if (this.#state === "ready") {
+      return open(this.#session);
     }
-    const session = this.#session;
-    return session.createBidirectionalStream().then((stream) => ({ stream, session }));
+    if (this.#state === "connecting") {
+      // The state has moved on once the attempt settled, so this does not wait again.
+      return this.#connecting.then((failure) =>
+        failure === undefined || this.#state === "closed"
+          ? this.#withSession(open)
+          : Promise.reject(failure),
+      );
+    }
+    return Promise.reject(unavailable(`channel is ${this.#state}`));
   }
 
   /** Resolves once the channel is ready, immediately if it already is. */
@@ -146,6 +198,42 @@ export class Channel {
     closeQuietly(session, closeInfo);
   }
 
+  /**
+   * Makes the first attempt to connect, and returns its error, or undefined once it established a
+   * session. A failure starts reconnecting if `retry` is true and closes the channel otherwise.
+   */
+  async #connect(retry) {
+    const { signal } = this.#stopped;
+    let dialed;
+    try {
+      dialed = await this.#dial(signal);
+    } catch (error) {
+      if (!signal.aborted) {
+        if (retry) {
+          void this.#reconnect(error);
+        } else {
+          this.close();
+        }
+      }
+      return error;
+    }
+    if (signal.aborted) {
+      closeQuietly(dialed.session);
+      return abortError(signal);
+    }
+    this.#ready(dialed);
+    return undefined;
+  }
+
+  /** Adopts a new session and wakes up whoever waits for the channel to be ready. */
+  #ready(dialed, extra) {
+    this.#adopt(dialed);
+    this.#transition("ready", { ...extra, transport: dialed.transport });
+    for (const waiter of this.#waiters.splice(0)) {
+      waiter.resolve();
+    }
+  }
+
   #adopt({ session, transport }) {
     this.#session = session;
     this.#transport = transport;
@@ -178,11 +266,7 @@ export class Channel {
           closeQuietly(dialed.session);
           return;
         }
-        this.#adopt(dialed);
-        this.#transition("ready", { attempt, transport: dialed.transport });
-        for (const waiter of this.#waiters.splice(0)) {
-          waiter.resolve();
-        }
+        this.#ready(dialed, { attempt });
         return;
       } catch (dialError) {
         error = dialError;
@@ -201,11 +285,24 @@ export class Channel {
   }
 }
 
-/** Opens a channel to a TrevRPC server and waits for its session to be ready. */
+/**
+ * Opens a channel to a TrevRPC server and waits for its session to be ready. It rejects, leaving
+ * nothing behind, if the first attempt fails.
+ */
 export function connect(url, options = {}) {
   return Channel.connect(url, options);
 }
 
+/**
+ * Returns a channel to a TrevRPC server that connects in the background, so that clients can be
+ * created on it right away. Calls started before its first session is ready wait for that attempt;
+ * a failed attempt fails them and the channel goes on reconnecting with backoff. The `signal`
+ * option does not apply: close the channel instead.
+ */
+export function createChannel(url, options = {}) {
+  return new Channel(url, options);
+}
+
 /**
  * Returns `dial(signal)`, which establishes the next session as `{ session, transport }`.
  *
@@ -263,7 +360,11 @@ function defaultWebSocketUrl(url) {
   return webSocketUrl.href;
 }
 
-/** Establishes a ready WebTransport session; aborting the signal abandons the attempt. */
+/**
+ * Establishes a ready WebTransport session; aborting the signal abandons the attempt. With
+ * `serverCertificateHashesUrl`, each attempt first fetches the hashes, so that reconnects trust a
+ * development certificate that rotated meanwhile.
+ */
 function dialWebTransport(url, options, signal) {
   const WebTransportConstructor = options.WebTransport ?? globalThis.WebTransport;
   if (typeof WebTransportConstructor !== "function") {
@@ -272,11 +373,28 @@ function dialWebTransport(url, options, signal) {
   if (signal?.aborted) {
     throw abortError(signal);
   }
-  return establish(
-    new WebTransportConstructor(url, transportOptions(options)),
-    "WebTransport",
-    signal,
-    requireWireVersion,
+  const open = (transport) =>
+    establish(
+      new WebTransportConstructor(url, transport),
+      "WebTransport",
+      signal,
+      requireWireVersion,
+    );
+  if (options.serverCertificateHashesUrl === undefined) {
+    return open(transportOptions(options));
+  }
+  return fetchServerCertificateHashes(options.serverCertificateHashesUrl, { signal }).then(
+    (fetched) => {
+      if (signal?.aborted) {
+        throw abortError(signal);
+      }
+      const transport = transportOptions(options);
+      const hashes = [...(transport.serverCertificateHashes ?? []), ...fetched];
+      if (hashes.length > 0) {
+        transport.serverCertificateHashes = hashes;
+      }
+      return open(transport);
+    },
   );
 }