@trevrpc/trevrpc-js 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
 # trevrpc-js
 
-TrevRPC is an RPC framework like gRPC, but uses QUIC (and HTTP/3 / WebTransport) instead of HTTP/2. Define services in protobuf, generate typed clients, and call Go or Rust servers over WebTransport.
+TrevRPC is an RPC framework like gRPC, but uses QUIC (and HTTP/3 / WebTransport) instead of HTTP/2. Define services in protobuf, generate typed clients, and call Go or Rust servers over WebTransport, falling back to QMux over WebSocket where WebTransport is missing or UDP is blocked.
 
-`trevrpc-js` is the **browser client**: a WebTransport runtime plus `protoc-gen-trevrpc-js`, which generates typed clients (no server code). It has no Node.js runtime; servers are written in Go or Rust, native QUIC clients in Go or Rust, and HTTP/3 clients in Kotlin.
+`trevrpc-js` is the **browser client**: a WebTransport runtime with a QMux over WebSocket fallback, plus `protoc-gen-trevrpc-js`, which generates typed clients (no server code). It has no Node.js runtime; servers are written in Go or Rust, native QUIC clients in Go or Rust, and HTTP/3 clients in Kotlin.
 
 Full documentation: https://trev.zip/llc/TrevRPC/wiki
 
@@ -46,6 +46,7 @@ This writes `greeter.trevrpc.js` and `greeter.trevrpc.d.ts`. Plugin parameters (
 
 ```js
 import { connect } from "@trevrpc/trevrpc-js";
+
 import { GreeterClient } from "./gen/greeter.trevrpc.js";
 
 const channel = await connect("https://example.com:4433/trevrpc");
@@ -64,6 +65,11 @@ await upload.send({ name: "Alice" });
 await upload.send({ name: "Bob" });
 const summary = await upload.closeAndRecv();
 
+// Client streaming from an iterable or async iterable
+const batch = await client.lotsOfGreetings();
+await batch.sendAll([{ name: "Alice" }, { name: "Bob" }]);
+const batchSummary = await batch.closeAndRecv();
+
 // Bidirectional streaming
 const chat = await client.bidiHello();
 await chat.send({ name: "Alice" });
@@ -78,12 +84,14 @@ channel.close();
 
 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.
 
-| Option         | Meaning                                                                                       |
-| -------------- | --------------------------------------------------------------------------------------------- |
-| `timeoutMs`    | Deadline for the whole call, from the request to the final status. Also sent to the server.   |
-| `signal`       | `AbortSignal` that cancels the call.                                                          |
-| `metadata`     | Request metadata (`{ key: "value" }` or a `Map`); keys are lowercase, `trevrpc-` is reserved. |
-| `maxFrameSize` | Largest frame accepted or sent in bytes (default 4 MiB).                                      |
+| Option               | Meaning                                                                                       |
+| -------------------- | --------------------------------------------------------------------------------------------- |
+| `timeoutMs`          | Deadline for the whole call, from the request to the final status. Also sent to the server.   |
+| `signal`             | `AbortSignal` that cancels the call.                                                          |
+| `metadata`           | Request metadata (`{ key: "value" }` or a `Map`); keys are lowercase, `trevrpc-` is reserved. |
+| `maxFrameSize`       | Largest frame accepted or sent in bytes (default 4 MiB).                                      |
+| `onResponseHeaders`  | Called with the response headers.                                                             |
+| `onResponseMetadata` | Called with the trailing metadata of a successful call.                                       |
 
 The client enforces no other response limits: there is no cap on the number of streamed
 messages, their total size, or idle time between them. Use `timeoutMs` or `signal` to bound a
@@ -93,12 +101,22 @@ call.
 
 - Failed calls throw `TrevRpcError` with a `code` (`Code.NotFound`, ...), `statusMessage` and `metadata`. A deadline surfaces as `Code.DeadlineExceeded`, a cancelled call as `Code.Cancelled` (with the abort reason as `cause`), and a lost connection as `Code.Unavailable`.
 - Streaming responses end with the server's final status: iteration finishes after `OK` and throws the `TrevRpcError` otherwise. `stream.status` settles with the same outcome and carries trailing metadata. Leaving a `for await` loop early, or calling `close()`, cancels the call.
-- Unary metadata is available through `...WithResponse(request)` and `closeAndRecvWithResponse()`.
-- The server's response decides the outcome of a call: if it ends a call early (for instance with an error), the final status wins over errors from sending the rest of the request.
+- Response headers and trailing metadata are separate. Every call reports them to the `onResponseHeaders(headers)` and `onResponseMetadata(metadata)` callbacks of its options: the headers (empty when the server sent none) as soon as the first response frame arrives, and the trailing metadata of the final status when the call succeeds, before its result is returned or its stream ends. A failed call carries its metadata on the `TrevRpcError`, and a callback that throws fails the call. Server-streaming and bidirectional calls also have a `headers` promise that resolves as soon as the first response frame arrives, so headers are available before the first message, and rejects with the call's error if the call fails first.
+- Frames follow the [wire format](https://trev.zip/llc/TrevRPC/wiki/Protocol-and-Wire-Format): a type, a length and a payload, with messages sent as raw protobuf. The client skips frame types it does not know, and `maxFrameSize` limits every frame, unknown ones included.
+- The server's response decides the outcome of a call, and a call reports it as soon as the final status arrives. If the server ends a call before the upload is done (client-streaming and bidirectional calls), the upload is cancelled and `send()` rejects at once, without waiting for the server to stop reading and whether or not the caller receives:
+  - with the server's `TrevRpcError` if its status is not OK, and the same error is the call's outcome (`closeAndRecv()`, `recv()`, `status`);
+  - with `Code.Cancelled` ("the server completed the call before the request stream ended") if its status is `OK`, for instance a server that answers after the first messages. The call itself succeeded: `closeAndRecv()` returns the response, and `recv()` and `status` end with `OK`;
+  - with the failure of the response stream, for instance `Code.Unavailable` for a lost connection, if the server stopped reading the request and the response then failed. A bare "stream closed" error from the transport is used only when the response gives no other explanation.
+
+  `send()` calls that are blocked on backpressure fail the same way, and so do all sends of a call that is cancelled or whose deadline expires. A deadline or abort that fires after the final status arrived does not change the outcome, even if the server has not finished the response stream yet.
+
+  `sendAll(requests)` sends every message of an iterable or async iterable and then closes the request stream. When the server ends the call first it stops and resolves, so `closeAndRecv()`, `recv()`, or `status` report the server's outcome instead of an upload error. Requests that throw cancel the 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.
 
 ### Connections
 
-`connect()` opens a WebTransport session and resolves when it is ready; it rejects if the session cannot be established. 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.
+`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.
 
 ```js
 const channel = await connect(url, {
@@ -108,21 +126,42 @@ 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. `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. `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 and the Rust server cannot echo one.
+
+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.
+
+### WebSocket fallback
+
+`connect()` races two transports. WebTransport starts first; QMux over WebSocket (subprotocol `qmux-02.trevrpc-1`, served by Go and Rust on the server's TCP port) starts after `fallbackDelayMs` (default 300) or immediately if WebTransport fails or the browser has no `WebTransport` API. The first session to be ready wins and the other is closed. After the WebSocket wins, reconnects use it directly until `reprobeIntervalMs` (default 5 minutes) has passed since WebTransport was lost, then race again.
+
+```js
+const channel = await connect("https://example.com:4433/trevrpc", {
+  transports: ["webtransport", "websocket"], // default; the first is preferred, a single entry disables the race
+  webSocketUrl: "wss://example.com:4433/trevrpc", // default: `url` with the wss: scheme
+  fallbackDelayMs: 300,
+  reprobeIntervalMs: 5 * 60_000,
+  onStateChange: ({ state, transport }) => console.log(state, transport),
+});
+console.log(channel.transport); // "webtransport" or "websocket"
+```
 
-Any object with `createBidirectionalStream()`, including a plain `WebTransport` session, can be used as the transport of a generated client.
+`channel.transport` and `ChannelStateChange.transport` (set when the channel becomes ready) report which one is in use. `WebSocket` replaces the global WebSocket constructor, like `WebTransport` does for WebTransport. The QMux client is in-tree (`src/qmux/`); WebSocket backpressure polls `bufferedAmount` against a 1 MiB limit.
 
 ## Interop client
 
-`trevrpc-interop-browser` runs the cross-runtime interop scenarios from [`interop/README.md`](../interop/README.md) in a real browser over WebTransport. It is built from `interop/proto/interop.proto` with the generator in this package, so it also serves as a complete example of generated client code.
+`trevrpc-interop-browser` runs the cross-runtime interop scenarios from [`interop/README.md`](../interop/README.md) in a real browser over WebTransport, QMux over WebSocket, or the fallback between them. It is built from `interop/proto/interop.proto` with the generator in this package, so it also serves as a complete example of generated client code.
 
 ```sh
-trevrpc-interop-browser --browser chromium|firefox|webkit \
+trevrpc-interop-browser --browser chromium|firefox|safari \
   --url https://127.0.0.1:4433/trevrpc \
-  --cert-hash <hex sha256 of the server certificate DER>
+  --cert-hash <hex sha256 of the server certificate DER> \
+  [--transport webtransport|websocket|auto] [--ws-url wss://127.0.0.1:4433/trevrpc] \
+  [--expect-transport webtransport|websocket]
 ```
 
-It prints `ok <name>` or `fail <name>: <reason>` per scenario and exits 0 only if all scenarios passed. Browsers come from `PLAYWRIGHT_BROWSERS_PATH`, or from `TREVRPC_BROWSER_CHROMIUM`, `TREVRPC_BROWSER_FIREFOX` and `TREVRPC_BROWSER_WEBKIT` when those name an executable. WebKit on macOS passes against the Go server but not yet the Rust server ([h3#347](https://github.com/hyperium/h3/issues/347)); where the browser has no WebTransport at all, such as Playwright's WebKit on Linux, every scenario fails with a clear reason.
+It prints `ok <name>` or `fail <name>: <reason>` per scenario and exits 0 only if all scenarios passed. Chromium and Firefox are launched through Playwright from `PLAYWRIGHT_BROWSERS_PATH`, or from `TREVRPC_BROWSER_CHROMIUM` and `TREVRPC_BROWSER_FIREFOX` when those name an executable, and ignore certificate errors because WSS cannot pin a certificate hash. Safari is driven through `safaridriver` (`TREVRPC_BROWSER_SAFARI` overrides its path), which needs `sudo safaridriver --enable` once; Safari cannot ignore certificate errors, so the server certificate must be trusted by the system, as `interop/run.py` does. The CLI serves the page from a loopback origin; the page fetches its input from there and posts each result back, so where the browser has no WebTransport at all every scenario fails with a clear reason. `--write-page <dir>` writes that page to a directory instead, and `--page-url <url> --cert <pem> --key <pem>` opens it from a TrevRPC server that serves the directory through its HTTP fallback; the page then reports to the CLI over HTTPS, at the origin in its `report` query parameter. `--page-protocol h2|h3` has the browser load that page over HTTP/2 or HTTP/3 and fails every scenario unless it did (`h3` in Chromium only).
 
 ## Development
 
@@ -135,4 +174,4 @@ npm run interop -- --browser chromium --url ... --cert-hash ...
 
 `nix build .#trevrpc-js` runs the same checks and installs the library, the plugin and the wrapped `trevrpc-interop-browser` with matching Playwright browsers. The pinned `playwright` version must equal nixpkgs' `playwright-driver`; `nix run .#sync-playwright` updates it.
 
-Tests (`node --test`) cover the wire format against `testdata/wire-golden-vectors.txt`, framing, the generator, and the client — deadlines, cancellation, stream termination and reconnection — against in-memory fake servers, including a fake Echo server that runs all interop scenarios.
+Tests (`node --test`) cover the wire format against `testdata/wire-golden-vectors.txt` (frame bytes, and the frame reader against the shared byte streams), the QMux frames against `testdata/qmux-golden-vectors.txt`, framing, the generator, and the client — deadlines, cancellation, stream termination and reconnection — against in-memory fake servers, including a fake Echo server that runs all interop scenarios.

package/bin/protoc-gen-trevrpc-js.js

@@ -1,4 +1,4 @@
-#!/nix/store/lfaydgacdyngci7p60s8wwvgdm74fjkx-nodejs-24.19.0/bin/node
+#!/usr/bin/env node
 
 import { runGenerator } from "../src/generator.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Browser WebTransport client and protobuf.js code generator for TrevRPC",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {
@@ -36,24 +36,21 @@
     "format": "oxfmt --write",
     "format:check": "oxfmt --check",
     "lint": "oxlint --deny-warnings",
-    "pretypecheck": "npm run build",
-    "typecheck": "tsc -p tsconfig.json",
-    "pretest": "npm run build",
-    "test": "node --test --test-concurrency=1 test/*.test.js",
+    "typecheck": "npm run build && tsc -p tsconfig.json",
+    "test": "npm run build && node --test --test-concurrency=1 test/*.test.js",
     "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
-    "interop": "node interop-browser/cli.js",
-    "prepack": "node -e 'if (process.env.TREVRPC_NIX_RELEASE !== \"1\") throw new Error(\"Build release tarballs with nix build .#trevrpc-js^npm\")'"
+    "interop": "node interop-browser/cli.js"
   },
   "dependencies": {
     "protobufjs": "^8.8.1"
   },
   "devDependencies": {
-    "esbuild": "^0.28.2",
-    "playwright": "1.61.1",
+    "playwright": "1.64.1",
+    "rolldown": "^1.2.14",
     "typescript": "^7.0.2"
   },
   "engines": {
-    "node": ">=24 <25"
+    "node": ">=24"
   },
   "packageManager": "npm@12.2.0"
 }

package/src/call.js

@@ -1,4 +1,10 @@
-import { DefaultMaxFrameSize, FrameReader, encodeFrame, encodeMessageFrame } from "./framing.js";
+import { datagramEndpoint, messageFrameSize } from "./datagram.js";
+import {
+  DefaultMaxFrameSize,
+  FrameReader,
+  encodeMessageFrame,
+  encodeRequestFrame,
+} from "./framing.js";
 import { normalizeMetadata, validateMetadata } from "./metadata.js";
 import {
   Code,
@@ -10,7 +16,6 @@ import {
   statusError,
   statusFromTransportError,
 } from "./status.js";
-import { RpcRequest, WireVersion } from "./wire.js";
 
 /** Longest delay setTimeout can represent; it fires immediately beyond this. */
 const MaxTimerDelayMs = 2_147_483_647;
@@ -108,28 +113,68 @@ export class Call {
   #frames;
   #maxFrameSize;
   #sendClosed = false;
+  /** Set once the close of the request side completed. */
+  #closeCompleted = false;
+  /**
+   * The error every request-side operation fails with once the upload was ended, or undefined
+   * while it is open.
+   */
+  #uploadEnded;
+  /** Rejectors of the request-side operations waiting for the transport. */
+  #pendingUploads = new Set();
+  /** The transport error that made the request side fail on its own, or undefined. */
+  #uploadFailure;
+  /** The call's datagram flow, or undefined if its messages all travel on the stream. */
+  #flow;
+  /** Whether request messages are sent as datagrams when they fit. */
+  #sendDatagrams = false;
+  /** Request messages of a call that uses datagrams, queued for the flush loop, in order. */
+  #unsent = [];
+  /** Settles when the flush loop has sent everything queued so far. */
+  #sendTail = Promise.resolve();
+  #flushing = false;
 
   /**
-   * Opens a stream on the transport and sends the request header. The request carries service,
-   * method, kind and body; version, metadata and the wire timeout come from the options.
+   * Opens a stream on the transport and sends the REQUEST frame. The request carries the
+   * method path and kind; metadata and the wire timeout come from the options. The request
+   * message of a unary or server-streaming call goes out in the same write.
+   *
+   * `datagrams` is `{ send, receive }` for a method that marks a direction unreliable: the call
+   * gets a datagram flow if the session that carries it has datagrams, which is only known once
+   * its stream is open, so the REQUEST is encoded after that. `send` makes it send request
+   * messages as datagrams, `receive` makes it accept response datagrams.
    */
-  static async open(transport, request, options) {
-    const header = encodeFrame(
-      RpcRequest,
-      { ...request, version: WireVersion, metadata: options.metadata, ...timeoutField(options) },
-      options.maxFrameSize,
-    );
+  static async open(transport, request, message, options, datagrams) {
+    const fields = { ...request, metadata: options.metadata, ...timeoutField(options) };
+    const header =
+      datagrams === undefined ? encodeRequestFrame(fields, message, options.maxFrameSize) : null;
     const scope = new CallScope(options);
+    let call;
     try {
-      const stream = await openStream(transport, scope.signal);
-      const call = new Call(stream, scope, options.maxFrameSize);
-      await call.#write(header);
+      const session = datagrams === undefined ? undefined : {};
+      const stream = await openStream(transport, scope.signal, session);
+      call = new Call(stream, scope, options.maxFrameSize);
+      await call.#write(header ?? call.#requestWithFlow(fields, message, session, datagrams));
       return call;
     } catch (error) {
+      if (call !== undefined) {
+        call.#releaseFlow();
+      }
       throw scope.abort(failureStatus(error));
     }
   }
 
+  /** Opens the call's flow on its session, if it has datagrams, and encodes the REQUEST. */
+  #requestWithFlow(fields, message, session, { send, receive }) {
+    this.#flow = datagramEndpoint(session.datagrams)?.openFlow({ receive });
+    this.#sendDatagrams = this.#flow !== undefined && send;
+    return encodeRequestFrame(
+      this.#flow === undefined ? fields : { ...fields, datagramFlow: this.#flow.id },
+      message,
+      this.#maxFrameSize,
+    );
+  }
+
   constructor(stream, scope, maxFrameSize) {
     const reader = stream.readable.getReader();
     this.#scope = scope;
@@ -137,6 +182,12 @@ export class Call {
     this.#cancelReader = (reason) => reader.cancel(reason);
     this.#frames = new FrameReader(reader);
     this.#maxFrameSize = maxFrameSize;
+    // The transport errors the request side as soon as the server stops reading it.
+    this.#writer.closed.catch((error) => {
+      if (this.#uploadEnded === undefined) {
+        this.#uploadFailure ??= statusFromTransportError(error);
+      }
+    });
     scope.signal.addEventListener("abort", () => this.#teardown(), { once: true });
     if (scope.signal.aborted) {
       this.#teardown();
@@ -148,44 +199,145 @@ export class Call {
     return this.#scope.signal;
   }
 
-  /** Sends one streaming request message; writes are ordered and apply backpressure. */
+  /**
+   * The transport error that made the request side fail on its own, for instance because the
+   * server stopped reading it; undefined while the request side works or was ended by the call.
+   */
+  get uploadFailure() {
+    return this.#uploadFailure;
+  }
+
+  /** Whether the request side can still be written: not ended, not closed. */
+  get uploadOpen() {
+    return this.#uploadEnded === undefined && !this.#closeCompleted;
+  }
+
+  /** The largest frame the call accepts and sends, in bytes. */
+  get maxFrameSize() {
+    return this.#maxFrameSize;
+  }
+
+  /** The call's datagram flow, or undefined if its messages all travel on the stream. */
+  get flow() {
+    return this.#flow;
+  }
+
+  /**
+   * Sends one streaming request message; writes are ordered and apply backpressure. Fails with
+   * the error that ended the upload, if any, even while the transport itself is still blocked.
+   * On a call that sends datagrams the message goes out as one if it fits, and on the stream
+   * otherwise.
+   */
   sendMessage(body) {
+    if (this.#uploadEnded !== undefined) {
+      return Promise.reject(this.#uploadEnded);
+    }
     if (this.#sendClosed) {
       return Promise.reject(failedPrecondition("request stream is closed"));
     }
+    if (this.#sendDatagrams) {
+      return this.#upload(
+        new Promise((resolve, reject) => {
+          this.#unsent.push({ body, resolve, reject });
+          if (!this.#flushing) {
+            this.#flushing = true;
+            // Messages sent in the same turn are packed together; nothing waits for a timer.
+            this.#sendTail = Promise.resolve().then(() => this.#flush());
+          }
+        }),
+      );
+    }
     return this.#write(encodeMessageFrame(body, this.#maxFrameSize));
   }
 
+  /**
+   * Sends the queued request messages in order: as many as fit into one datagram go together, a
+   * message that cannot be a datagram goes on the stream, and so does every message of a datagram
+   * that failed to send. Messages queued while a datagram waits for send-buffer space join the
+   * next one.
+   */
+  async #flush() {
+    let inFlight = [];
+    try {
+      while (this.#unsent.length > 0) {
+        if (this.#uploadEnded !== undefined) {
+          throw this.#uploadEnded;
+        }
+        inFlight = this.#takeBatch();
+        if (inFlight.length === 0 || !(await this.#flow.send(inFlight.map(bodyOf), this.signal))) {
+          // Not a datagram: a head message that never fits, or a datagram that failed to send.
+          inFlight = inFlight.length > 0 ? inFlight : [this.#unsent.shift()];
+          for (const { body } of inFlight) {
+            await this.#writer.write(encodeMessageFrame(body, this.#maxFrameSize));
+          }
+        }
+        for (const item of inFlight) {
+          item.resolve();
+        }
+        inFlight = [];
+      }
+    } catch (error) {
+      for (const item of [...inFlight, ...this.#unsent.splice(0)]) {
+        item.reject(error);
+      }
+    } finally {
+      this.#flushing = false;
+    }
+  }
+
+  /**
+   * Removes the longest run of queued messages from the front that fits one datagram, at least
+   * one if the head fits alone; empty if the head can only go on the stream.
+   */
+  #takeBatch() {
+    let room = this.#flow.frameRoom;
+    let count = 0;
+    while (count < this.#unsent.length) {
+      const { body } = this.#unsent[count];
+      const size = messageFrameSize(body);
+      if (body.byteLength > this.#maxFrameSize || size > room) {
+        break;
+      }
+      room -= size;
+      count += 1;
+    }
+    return this.#unsent.splice(0, count);
+  }
+
   /** Finishes the request stream gracefully. */
   closeSend() {
     if (this.#sendClosed) {
       return Promise.resolve();
     }
     this.#sendClosed = true;
-    return this.#guard(this.#writer.close());
-  }
-
-  /** Reads the unary response frame. */
-  readFrame(messageType) {
-    return this.#guard(this.#frames.readFrame(messageType, this.#maxFrameSize));
+    // Datagram sends in flight go first, so the stream does not end before them.
+    const closing = this.#sendDatagrams
+      ? this.#sendTail.then(() => this.#writer.close())
+      : this.#writer.close();
+    return this.#upload(closing).then(() => {
+      this.#closeCompleted = true;
+    });
   }
 
-  /** Reads the next response stream frame, or null if the stream ended cleanly. */
-  readStreamFrame() {
-    return this.#guard(this.#frames.readStreamFrame(this.#maxFrameSize));
+  /**
+   * Reads the next known response frame as `{ type, payload }`, or null if the stream ended
+   * cleanly. Unknown frames are skipped.
+   */
+  readFrame() {
+    return this.#guard(this.#frames.readFrame(this.#maxFrameSize));
   }
 
   /**
-   * Ends the call after its outcome (a final response or status) was received. An unfinished
-   * request side is reset, and the rest of the response stream is drained in the background.
+   * Ends the call after its final status was received. The request side stops: pending and later
+   * sends fail with `uploadError`, and an unfinished upload is reset. The rest of the response
+   * stream is drained in the background: unknown frames are skipped, and a known frame after
+   * STATUS cancels the stream without changing the outcome.
    */
-  finish() {
+  finish(uploadError) {
     this.#scope.settle();
-    if (!this.#sendClosed) {
-      this.#sendClosed = true;
-      this.#writer.abort(cancelled("RPC completed")).catch(() => {});
-    }
-    this.#frames.expectEnd().catch(() => this.#cancelReader().catch(() => {}));
+    this.#releaseFlow();
+    this.#endUpload(uploadError, cancelled("RPC completed"));
+    this.#frames.expectEnd(this.#maxFrameSize).catch(() => this.#cancelReader().catch(() => {}));
   }
 
   /** Cancels the call on behalf of the caller; any reason becomes a Cancelled status. */
@@ -198,8 +350,59 @@ export class Call {
     return this.#scope.abort(failureStatus(error));
   }
 
-  async #write(bytes) {
-    await this.#guard(this.#writer.write(bytes));
+  #write(bytes) {
+    return this.#upload(this.#writer.write(bytes));
+  }
+
+  /**
+   * Waits for a write or close of the request side. Ending the upload settles it at once: a
+   * transport blocked on flow control does not act on an abort while the write is in flight.
+   */
+  #upload(operation) {
+    return new Promise((resolve, reject) => {
+      this.#pendingUploads.add(reject);
+      operation.then(
+        (value) => {
+          this.#pendingUploads.delete(reject);
+          if (this.signal.aborted) {
+            reject(this.signal.reason);
+          } else {
+            resolve(value);
+          }
+        },
+        (error) => {
+          this.#pendingUploads.delete(reject);
+          reject(this.#uploadError(error));
+        },
+      );
+    });
+  }
+
+  /** Maps a failed request-side operation to the call's error. */
+  #uploadError(error) {
+    if (this.signal.aborted) {
+      return this.signal.reason;
+    }
+    if (error === this.#uploadEnded) {
+      return error;
+    }
+    this.#uploadFailure ??= statusFromTransportError(error);
+    return this.#uploadFailure;
+  }
+
+  /** Stops the request side with `error` for everything waiting on it; only the first call counts. */
+  #endUpload(error, abortReason = error) {
+    if (this.#uploadEnded !== undefined) {
+      return;
+    }
+    this.#uploadEnded = error;
+    this.#sendClosed = true;
+    this.#writer.abort(abortReason).catch(() => {});
+    const pending = [...this.#pendingUploads];
+    this.#pendingUploads.clear();
+    for (const reject of pending) {
+      reject(error);
+    }
   }
 
   async #guard(operation) {
@@ -214,14 +417,25 @@ export class Call {
     return result;
   }
 
+  /** Ends the datagram flow, if any; every way a call ends gets here. */
+  #releaseFlow() {
+    this.#flow?.release();
+  }
+
   #teardown() {
+    this.#releaseFlow();
     const reason = this.signal.reason;
-    this.#writer.abort(reason).catch(() => {});
+    this.#endUpload(reason);
     this.#cancelReader(reason).catch(() => {});
   }
 }
 
-function openStream(transport, signal) {
+/**
+ * Opens a bidirectional stream. A call that may use datagrams passes `session`, which receives the
+ * datagram object of the session that opened the stream, so the flow belongs to the connection
+ * that carries the call and not to one a reconnect swapped in later.
+ */
+function openStream(transport, signal, session) {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
       reject(signal.reason);
@@ -232,7 +446,7 @@ function openStream(transport, signal) {
 
     let opening;
     try {
-      opening = Promise.resolve(transport.createBidirectionalStream());
+      opening = Promise.resolve(startStream(transport, session));
     } catch (error) {
       opening = Promise.reject(error);
     }
@@ -255,6 +469,25 @@ function openStream(transport, signal) {
   });
 }
 
+function bodyOf(item) {
+  return item.body;
+}
+
+function startStream(transport, session) {
+  if (session === undefined) {
+    return transport.createBidirectionalStream();
+  }
+  if (typeof transport.createBidirectionalStreamWithDatagrams === "function") {
+    return transport.createBidirectionalStreamWithDatagrams().then(({ stream, datagrams }) => {
+      session.datagrams = datagrams;
+      return stream;
+    });
+  }
+  // A WebTransport session used directly: its datagrams belong to the stream opened right now.
+  session.datagrams = transport.datagrams;
+  return transport.createBidirectionalStream();
+}
+
 function throwIfAborted(signal) {
   if (signal.aborted) {
     throw signal.reason;