@trevrpc/trevrpc-js 0.2.2 → 1.0.0

package/README.md

@@ -1,6 +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 servers, and run them over QUIC.
+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-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.
 
 Full documentation: https://trev.zip/llc/TrevRPC/wiki
 
@@ -22,75 +24,115 @@ message HelloRequest { string name = 1; }
 message HelloReply { string message = 1; }
 ```
 
-Generate with `protoc-gen-trevrpc-js` (`--trevrpc-js_out`).
+Generate a client with the protoc plugin (it needs Node.js to run):
+
+```sh
+npm install @trevrpc/trevrpc-js
+protoc \
+  --plugin=protoc-gen-trevrpc-js=node_modules/.bin/protoc-gen-trevrpc-js \
+  --trevrpc-js_out=src/gen \
+  greeter.proto
+```
+
+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.                                                     |
 
 ## Client
 
 ```js
 import { connect } from "@trevrpc/trevrpc-js";
-import { GreeterClient } from "./greeter.trevrpc.js";
+import { GreeterClient } from "./gen/greeter.trevrpc.js";
 
-const channel = await connect("https://127.0.0.1:50051/trevrpc");
-const client = new GreeterClient(channel);
+const channel = await connect("https://example.com:4433/trevrpc");
+const client = new GreeterClient(channel, { timeoutMs: 5_000 });
 
 // Unary
 const reply = await client.sayHello({ name: "TrevRPC" });
 
 // Server streaming
-const stream = await client.lotsOfReplies({ name: "TrevRPC" });
-for await (const r of stream) console.log(r.message);
+const replies = await client.lotsOfReplies({ name: "TrevRPC" });
+for await (const reply of replies) console.log(reply.message);
 
 // Client streaming
-const cs = await client.lotsOfGreetings();
-await cs.send({ name: "Alice" });
-await cs.send({ name: "Bob" });
-const summary = await cs.closeAndRecv();
+const upload = await client.lotsOfGreetings();
+await upload.send({ name: "Alice" });
+await upload.send({ name: "Bob" });
+const summary = await upload.closeAndRecv();
 
 // Bidirectional streaming
-const bidi = await client.bidiHello();
-await bidi.send({ name: "Alice" });
-console.log(await bidi.recv());
-await bidi.closeSend();
-for await (const r of bidi) console.log(r.message);
+const chat = await client.bidiHello();
+await chat.send({ name: "Alice" });
+console.log(await chat.recv());
+await chat.closeSend();
+for await (const reply of chat) console.log(reply.message);
 
 channel.close();
 ```
 
-Node uses the same API via `@trevrpc/trevrpc-js/node` (native MsQuic).
+### 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.
+
+| 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).                                      |
+
+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
+call.
+
+### Errors, cancellation and streams
+
+- 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.
+
+### Connections
 
-## Server (Node)
+`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.
 
 ```js
-import { NodeServer } from "@trevrpc/trevrpc-js/node";
-import { registerGreeterServer } from "./greeter.node.trevrpc.js";
-import { createUnaryResponse, createStreamingResponse } from "@trevrpc/trevrpc-js";
-
-const server = await NodeServer.listen({
-  host: "127.0.0.1",
-  port: 50051,
-  certFile: "cert.pem",
-  keyFile: "key.pem",
+const channel = await connect(url, {
+  signal: AbortSignal.timeout(10_000), // cancels the initial connection only
+  serverCertificateHashes: [{ algorithm: "sha-256", value: certificateSha256 }],
+  onStateChange: ({ state, attempt, error }) => console.log(state, attempt, error),
 });
+```
 
-registerGreeterServer(server, {
-  sayHello(req) {
-    return createUnaryResponse({ message: `hello, ${req.name}` });
-  },
-  lotsOfReplies(req) {
-    return createStreamingResponse([
-      { message: `hello, ${req.name}` },
-      { message: `goodbye, ${req.name}` },
-    ]);
-  },
-  async lotsOfGreetings(reqs) {
-    const names = [];
-    for await (const r of reqs) names.push(r.name);
-    return createUnaryResponse({ message: names.join(", ") });
-  },
-  async *bidiHello(reqs) {
-    for await (const r of reqs) yield { message: `hello, ${r.name}` };
-  },
-});
+`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.
+
+Any object with `createBidirectionalStream()`, including a plain `WebTransport` session, can be used as the transport of a generated client.
 
-await server.serve();
+## 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.
+
+```sh
+trevrpc-interop-browser --browser chromium|firefox|webkit \
+  --url https://127.0.0.1:4433/trevrpc \
+  --cert-hash <hex sha256 of the server certificate DER>
 ```
+
+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.
+
+## Development
+
+```sh
+npm ci
+npm run check      # format check, lint, typecheck, tests
+npm run build      # generate the Echo client and bundle the interop page into build/interop/
+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.

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "0.2.2",
-  "description": "JavaScript WebTransport runtime and protobuf.js code generator for TrevRPC",
+  "version": "1.0.0",
+  "description": "Browser WebTransport client and protobuf.js code generator for TrevRPC",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {
     "url": "https://trev.zip/llc/TrevRPC/issues"
@@ -17,7 +17,6 @@
   "files": [
     "src/**",
     "bin/protoc-gen-trevrpc-js.js",
-    "examples/greeter/**",
     "README.md",
     "LICENSE"
   ],
@@ -25,56 +24,30 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "node": {
-        "types": "./src/index.node.d.ts",
-        "import": "./src/index.node.js"
-      },
-      "browser": {
-        "types": "./src/index.d.ts",
-        "import": "./src/index.js"
-      },
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
-    },
-    "./node": {
-      "types": "./src/node.d.ts",
-      "import": "./src/node-index.js"
-    },
-    "./advanced": {
-      "types": "./src/advanced.d.ts",
-      "import": "./src/advanced.js"
-    },
-    "./node/advanced": {
-      "types": "./src/node-advanced.d.ts",
-      "import": "./src/node-advanced.js"
-    },
-    "./node/generated": {
-      "types": "./src/node-generated.d.ts",
-      "import": "./src/node-generated.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build:native": "TREVRPC_NODE_TEST_HOOKS=OFF npm run build:native:cmake",
-    "build:native:test": "TREVRPC_NODE_TEST_HOOKS=ON npm run build:native:cmake",
-    "build:native:cmake": "cmake -S native -B build/native -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE:-Release} -DTREVRPC_NODE_TEST_HOOKS=${TREVRPC_NODE_TEST_HOOKS:?} ${TREVRPC_C_ROOT:+-DTREVRPC_C_ROOT=$TREVRPC_C_ROOT} ${NODE_INCLUDE_DIR:+-DNODE_INCLUDE_DIR=$NODE_INCLUDE_DIR} && cmake --build build/native --config ${CMAKE_BUILD_TYPE:-Release}",
-    "check": "npm run lint && npm run typecheck && npm run build:native:test && npm test && npm run build:native && npm run verify:native:production",
-    "example:greeter": "node examples/greeter/static-server.js",
+    "build": "node interop-browser/build.js",
     "format": "oxfmt --write",
     "format:check": "oxfmt --check",
     "lint": "oxlint --deny-warnings",
-    "prepack": "node -e 'if (process.env.TREVRPC_NIX_PUBLICATION !== \"1\") throw new Error(\"Build release tarballs with nix build .#trevrpc-js^npm\")'",
+    "pretypecheck": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
     "test": "node --test --test-concurrency=1 test/*.test.js",
-    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.browser.json && tsc -p tsconfig.node.json",
-    "verify:native:production": "node -e 'const { readFileSync } = require(\"node:fs\"); const path = \"./build/native/trevrpc_native.node\"; const expectedExports = [\"connectMsQuic\", \"createCancellation\", \"listenMsQuic\"]; const actualExports = Object.getOwnPropertyNames(require(path)).sort(); const exportsMatch = JSON.stringify(actualExports) === JSON.stringify(expectedExports); const embedsDebugNames = readFileSync(path).includes(Buffer.from(\"_debug\")); if (!exportsMatch || embedsDebugNames) throw new Error(`production addon exports ${JSON.stringify(actualExports)}; expected exactly ${JSON.stringify(expectedExports)}${embedsDebugNames ? \"; binary contains _debug\" : \"\"}`);'"
+    "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\")'"
   },
   "dependencies": {
-    "protobufjs": "^8.8.0"
+    "protobufjs": "^8.8.1"
   },
   "devDependencies": {
-    "@types/node": "^24.13.3",
     "esbuild": "^0.28.2",
     "playwright": "1.61.1",
     "typescript": "^7.0.2"
@@ -82,8 +55,5 @@
   "engines": {
     "node": ">=24 <25"
   },
-  "packageManager": "npm@12.0.2",
-  "optionalDependencies": {
-    "@trevrpc/trevrpc-js-native-linux-x64-gnu": "0.2.2"
-  }
+  "packageManager": "npm@12.2.0"
 }

package/src/bytes.js

@@ -0,0 +1,10 @@
+/** Returns a Uint8Array view over bytes, typed-array views, or ArrayBuffers without copying. */
+export function byteView(value) {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  return new Uint8Array(value ?? 0);
+}

package/src/call.js

@@ -0,0 +1,287 @@
+import { DefaultMaxFrameSize, FrameReader, encodeFrame, encodeMessageFrame } from "./framing.js";
+import { normalizeMetadata, validateMetadata } from "./metadata.js";
+import {
+  Code,
+  TrevRpcError,
+  cancelled,
+  deadlineExceeded,
+  failedPrecondition,
+  invalidArgument,
+  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;
+const MaxUint64 = 0xffffffffffffffffn;
+
+/** Returns the default call options. */
+export function defaultCallOptions() {
+  return {
+    timeoutMs: undefined,
+    maxFrameSize: DefaultMaxFrameSize,
+    metadata: {},
+    signal: undefined,
+  };
+}
+
+/** Merges override options over resolved base options; metadata merges per key. */
+export function mergeCallOptions(base, override = {}) {
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value !== undefined && key !== "metadata") {
+      merged[key] = value;
+    }
+  }
+  if (override.metadata != null) {
+    merged.metadata = Object.assign(
+      Object.create(null),
+      base.metadata,
+      normalizeMetadata(override.metadata),
+    );
+    validateMetadata(merged.metadata);
+  }
+  return merged;
+}
+
+/**
+ * Cancellation and deadline for one call. The signal aborts with a TrevRpcError reason: the
+ * failure that ended the call, the caller's own status error, DeadlineExceeded, or Cancelled
+ * wrapping any other abort reason.
+ */
+class CallScope {
+  #controller = new AbortController();
+  #parent;
+  #timer;
+
+  /** timeoutMs must be validated by the caller. */
+  constructor({ signal, timeoutMs }) {
+    if (signal?.aborted) {
+      this.abort(signal.reason);
+      return;
+    }
+    if (signal != null) {
+      this.#parent = { signal, listener: () => this.abort(signal.reason) };
+      signal.addEventListener("abort", this.#parent.listener, { once: true });
+    }
+    if (timeoutMs != null && timeoutMs <= MaxTimerDelayMs) {
+      this.#timer = setTimeout(
+        () => this.abort(deadlineExceeded("RPC deadline exceeded")),
+        timeoutMs,
+      );
+    }
+  }
+
+  get signal() {
+    return this.#controller.signal;
+  }
+
+  /** Aborts the call; only the first reason counts. Returns the effective reason. */
+  abort(reason) {
+    if (!this.signal.aborted) {
+      this.settle();
+      this.#controller.abort(
+        reason instanceof TrevRpcError ? reason : cancelled("RPC cancelled", reason),
+      );
+    }
+    return this.signal.reason;
+  }
+
+  /** Stops the deadline and detaches from the caller's signal once the outcome is known. */
+  settle() {
+    clearTimeout(this.#timer);
+    this.#parent?.signal.removeEventListener("abort", this.#parent.listener);
+    this.#parent = undefined;
+  }
+}
+
+/**
+ * One RPC over one bidirectional stream: the request writer, the response frame reader, and the
+ * call's cancellation scope. Transport failures surface as TrevRpcError, and once the call is
+ * aborted every operation fails with the abort reason.
+ */
+export class Call {
+  #scope;
+  #writer;
+  #cancelReader;
+  #frames;
+  #maxFrameSize;
+  #sendClosed = 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.
+   */
+  static async open(transport, request, options) {
+    const header = encodeFrame(
+      RpcRequest,
+      { ...request, version: WireVersion, metadata: options.metadata, ...timeoutField(options) },
+      options.maxFrameSize,
+    );
+    const scope = new CallScope(options);
+    try {
+      const stream = await openStream(transport, scope.signal);
+      const call = new Call(stream, scope, options.maxFrameSize);
+      await call.#write(header);
+      return call;
+    } catch (error) {
+      throw scope.abort(failureStatus(error));
+    }
+  }
+
+  constructor(stream, scope, maxFrameSize) {
+    const reader = stream.readable.getReader();
+    this.#scope = scope;
+    this.#writer = stream.writable.getWriter();
+    this.#cancelReader = (reason) => reader.cancel(reason);
+    this.#frames = new FrameReader(reader);
+    this.#maxFrameSize = maxFrameSize;
+    scope.signal.addEventListener("abort", () => this.#teardown(), { once: true });
+    if (scope.signal.aborted) {
+      this.#teardown();
+    }
+  }
+
+  /** The call's abort signal. */
+  get signal() {
+    return this.#scope.signal;
+  }
+
+  /** Sends one streaming request message; writes are ordered and apply backpressure. */
+  sendMessage(body) {
+    if (this.#sendClosed) {
+      return Promise.reject(failedPrecondition("request stream is closed"));
+    }
+    return this.#write(encodeMessageFrame(body, this.#maxFrameSize));
+  }
+
+  /** 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));
+  }
+
+  /** Reads the next response stream frame, or null if the stream ended cleanly. */
+  readStreamFrame() {
+    return this.#guard(this.#frames.readStreamFrame(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.
+   */
+  finish() {
+    this.#scope.settle();
+    if (!this.#sendClosed) {
+      this.#sendClosed = true;
+      this.#writer.abort(cancelled("RPC completed")).catch(() => {});
+    }
+    this.#frames.expectEnd().catch(() => this.#cancelReader().catch(() => {}));
+  }
+
+  /** Cancels the call on behalf of the caller; any reason becomes a Cancelled status. */
+  cancel(reason) {
+    this.#scope.abort(reason);
+  }
+
+  /** Fails the call, tearing down both stream directions. Returns the effective error. */
+  fail(error) {
+    return this.#scope.abort(failureStatus(error));
+  }
+
+  async #write(bytes) {
+    await this.#guard(this.#writer.write(bytes));
+  }
+
+  async #guard(operation) {
+    let result;
+    try {
+      result = await operation;
+    } catch (error) {
+      throw this.signal.aborted ? this.signal.reason : statusFromTransportError(error);
+    }
+    // Cancelling the reader completes pending reads as end-of-stream instead of rejecting them.
+    throwIfAborted(this.signal);
+    return result;
+  }
+
+  #teardown() {
+    const reason = this.signal.reason;
+    this.#writer.abort(reason).catch(() => {});
+    this.#cancelReader(reason).catch(() => {});
+  }
+}
+
+function openStream(transport, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+
+    let opening;
+    try {
+      opening = Promise.resolve(transport.createBidirectionalStream());
+    } catch (error) {
+      opening = Promise.reject(error);
+    }
+    opening.then(
+      (stream) => {
+        signal.removeEventListener("abort", onAbort);
+        if (signal.aborted) {
+          // The caller gave up while the stream was opening; do not leak it.
+          stream.writable.abort(signal.reason).catch(() => {});
+          stream.readable.cancel(signal.reason).catch(() => {});
+        } else {
+          resolve(stream);
+        }
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(statusFromTransportError(error));
+      },
+    );
+  });
+}
+
+function throwIfAborted(signal) {
+  if (signal.aborted) {
+    throw signal.reason;
+  }
+}
+
+/** Status errors describe themselves; anything else reaching the call is an internal bug. */
+function failureStatus(error) {
+  return error instanceof TrevRpcError
+    ? error
+    : statusError(Code.Internal, error?.message ?? String(error), {}, error);
+}
+
+/**
+ * Validates a call timeout and returns the request field for it. Zero means unset on the wire, so
+ * a zero timeout is sent as 1ns.
+ */
+function timeoutField({ timeoutMs }) {
+  if (timeoutMs == null) {
+    return {};
+  }
+  if (!(timeoutMs >= 0 && Number.isFinite(timeoutMs))) {
+    throw invalidArgument("RPC timeout must be a non-negative finite number of milliseconds");
+  }
+  const nanos = BigInt(Math.ceil(timeoutMs)) * 1_000_000n;
+  if (nanos > MaxUint64) {
+    throw invalidArgument("RPC timeout does not fit in 64-bit nanoseconds");
+  }
+  return { timeoutNanos: String(nanos === 0n ? 1n : nanos) };
+}