@trevrpc/trevrpc-js 0.1.8 → 0.2.2

package/README.md

@@ -1,202 +1,96 @@
 # trevrpc-js
 
-`trevrpc-js` is the ESM-only JavaScript runtime and protobuf.js generator for TrevRPC.
+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.
 
-## Generated files
+Full documentation: https://trev.zip/llc/TrevRPC/wiki
 
-For every protobuf file containing services, `protoc-gen-trevrpc-js` emits an ordinary browser-safe client module and a separate Node server module:
+## Protobuf
 
-```text
-greeter.trevrpc.js
-greeter.trevrpc.d.ts
-greeter.node.trevrpc.js
-greeter.node.trevrpc.d.ts
-```
-
-The ordinary module contains the protobuf root, service descriptors, typed clients, and client factories. The Node companion contains typed handler interfaces and registration helpers backed by `@trevrpc/trevrpc-js/node/generated`.
-
-```sh
-protoc \
-  --plugin=protoc-gen-trevrpc-js=./node_modules/.bin/protoc-gen-trevrpc-js \
-  --trevrpc-js_out=. \
-  greeter.proto
-```
+```proto
+syntax = "proto3";
 
-Generator options are `runtime_import`, `runtime_type_import`, `node_runtime_import`, `node_runtime_type_import`, and `file_suffix`. Runtime type imports default to their matching runtime import for bare and relative specifiers. URL specifiers such as `file:` require an explicit type import because TypeScript NodeNext does not resolve them in declarations. A Node import is never inferred by appending `/node` to another specifier.
+package example.greeter;
 
-## Browser clients
-
-Browser declarations accept only `BrowserChannelOptions`.
-
-```js
-import { connect } from "@trevrpc/trevrpc-js";
-import { GreeterClient } from "./greeter.trevrpc.js";
-
-const channel = await connect("https://localhost:50051/trevrpc", {
-  timeoutMs: 10_000,
-  congestionControl: "low-latency",
-  serverCertificateHashes: [{ algorithm: "sha-256", value: certificateHash }],
-});
-try {
-  const client = new GreeterClient(channel, { timeoutMs: 5_000 });
-  const reply = await client.sayHello({ name: "TrevRPC" });
-  console.log(reply.message);
-} finally {
-  channel.close({ closeCode: 0, reason: "client shutdown" });
+service Greeter {
+  rpc SayHello(HelloRequest) returns (HelloReply);
+  rpc LotsOfReplies(HelloRequest) returns (stream HelloReply);
+  rpc LotsOfGreetings(stream HelloRequest) returns (HelloReply);
+  rpc BidiHello(stream HelloRequest) returns (stream HelloReply);
 }
-```
 
-Native TLS bypass, certificate validation, MsQuic buffering, and native stream options are intentionally unavailable under browser or Bundler resolution.
+message HelloRequest { string name = 1; }
+message HelloReply { string message = 1; }
+```
 
-## Node clients
+Generate with `protoc-gen-trevrpc-js` (`--trevrpc-js_out`).
 
-Under Node conditions, the root package uses the native channel. The explicit `@trevrpc/trevrpc-js/node` subpath also exports `Channel`, `NodeServer`, and `NodeServerCall`.
+## Client
 
 ```js
 import { connect } from "@trevrpc/trevrpc-js";
 import { GreeterClient } from "./greeter.trevrpc.js";
 
-const channel = await connect("https://localhost:50051", {
-  timeoutMs: 10_000,
-  caCertFile: "localhost-cert.pem",
-});
-try {
-  console.log(channel.endpoint); // frozen { host, port }
-  console.log(channel.options); // frozen effective NodeChannelOptions
-  const client = new GreeterClient(channel, { timeoutMs: 5_000 });
-  console.log((await client.sayHello({ name: "TrevRPC" })).message);
-} finally {
-  channel.close();
-}
-```
-
-URL and `{ host, port, ...options }` forms normalize to the same public state. Channels reconnect for future calls after native transport loss, but never replay or resume an operation that already failed.
-
-## Streaming clients
-
-Server-streaming methods resolve to `ResponseAsyncIterable<T>`:
+const channel = await connect("https://127.0.0.1:50051/trevrpc");
+const client = new GreeterClient(channel);
 
-```js
-const replies = await client.lotsOfReplies({ name: "TrevRPC" });
-try {
-  for await (const reply of replies) {
-    console.log(reply.message);
-  }
-  const terminal = await replies.status;
-  console.log(terminal.code, terminal.message, terminal.metadata);
-} finally {
-  await replies.close();
-}
-```
+// Unary
+const reply = await client.sayHello({ name: "TrevRPC" });
 
-Full clean consumption resolves `status`. A non-OK terminal status rejects iteration and `status` with the same `TrevRpcError`. `close()`, iterator `return()`, and breaking a `for await` loop cancel the stream and reject `status` with `Code.Cancelled`. Consuming a valid terminal frame claims terminal precedence and cancels the absolute deadline, but `status` settles only after trailing EOF is validated; merely buffering a status frame is not completion.
+// Server streaming
+const stream = await client.lotsOfReplies({ name: "TrevRPC" });
+for await (const r of stream) console.log(r.message);
 
-The status/error text distinction is deliberate:
+// Client streaming
+const cs = await client.lotsOfGreetings();
+await cs.send({ name: "Alice" });
+await cs.send({ name: "Bob" });
+const summary = await cs.closeAndRecv();
 
-- `StreamStatus.message` is the unmodified peer terminal message.
-- `TrevRpcError.statusMessage` is the unmodified peer error message.
-- `TrevRpcError.message` is formatted JavaScript text such as `"Unavailable: down"`.
+// 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);
 
-Unary and client-streaming terminal metadata is available through `sayHelloWithResponse()` and `closeAndRecvWithResponse()`.
-
-Client streaming:
-
-```js
-const call = await client.lotsOfGreetings();
-await call.send({ name: "Alice" });
-await call.send({ name: "Bob" });
-const { message, metadata } = await call.closeAndRecvWithResponse();
+channel.close();
 ```
 
-Bidirectional streaming:
+Node uses the same API via `@trevrpc/trevrpc-js/node` (native MsQuic).
 
-```js
-const call = await client.bidiHello();
-try {
-  await call.send({ name: "Alice" });
-  console.log(await call.recv());
-  await call.closeSend();
-  while ((await call.recv()) != null) {}
-  console.log(await call.status);
-} finally {
-  await call.close();
-}
-```
-
-`timeoutMs` is one absolute RPC deadline that begins before transport setup and covers upload, send, receive, and cleanup. The same `DeadlineExceeded` object wins signal and rejection settlement. `streamIdleTimeoutMs` remains an independent per-read inactivity bound.
-
-## Typed Node servers
-
-Import the generated registration helper from the Node companion. Direct protobuf responses are never confused with metadata envelopes, even when they have `message` or `messages` properties.
+## Server (Node)
 
 ```js
-import { Code, createStreamingResponse, createUnaryResponse } from "@trevrpc/trevrpc-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: "localhost-cert.pem",
-  keyFile: "localhost-key.pem",
+  certFile: "cert.pem",
+  keyFile: "key.pem",
 });
 
 registerGreeterServer(server, {
-  sayHello(request, call) {
-    console.log(call.deadline, call.signal.aborted);
-    return createUnaryResponse(
-      { message: `Hello, ${request.name || "world"}` },
-      { trailer: "unary" },
-    );
+  sayHello(req) {
+    return createUnaryResponse({ message: `hello, ${req.name}` });
   },
-
-  async lotsOfGreetings(requests) {
-    const names = [];
-    for await (const request of requests) names.push(request.name);
-    return createUnaryResponse({ message: names.join(", ") }, { trailer: "client-stream" });
+  lotsOfReplies(req) {
+    return createStreamingResponse([
+      { message: `hello, ${req.name}` },
+      { message: `goodbye, ${req.name}` },
+    ]);
   },
-
-  lotsOfReplies(request) {
-    return createStreamingResponse([{ message: request.name }], {
-      code: Code.Ok,
-      message: "complete",
-      metadata: { trailer: "server-stream" },
-    });
+  async lotsOfGreetings(reqs) {
+    const names = [];
+    for await (const r of reqs) names.push(r.name);
+    return createUnaryResponse({ message: names.join(", ") });
   },
-
-  async *bidiHello(requests) {
-    for await (const request of requests) yield { message: request.name };
+  async *bidiHello(reqs) {
+    for await (const r of reqs) yield { message: `hello, ${r.name}` };
   },
 });
 
 await server.serve();
 ```
-
-Client-streaming completion uses streaming wire semantics: exactly one response message followed by exactly one terminal status; it never uses unary `respond()`.
-
-`NodeServerCall.signal` covers effective deadlines, server shutdown, local close, and cancellation observed by native I/O. The current native bridge cannot promptly report remote peer cancellation while a handler is idle and performs no call I/O; cancellation becomes observable when the handler next enters native call I/O.
-
-## Native package support
-
-The core tarball is platform-neutral. Native code is supplied by the exact optional package `@trevrpc/trevrpc-js-native-linux-x64-gnu@0.1.8`.
-
-Initial support is Linux x86-64, glibc 2.42 or newer, and Node 24. Browser usage still installs and runs on Darwin, ARM, and musl. Requesting a native Node channel on an unsupported or incomplete installation throws `TrevRpcError(Code.Unavailable)` with the detected target, supported targets, expected optional package, whether loading was missing or failed, and the original loader error as `cause`.
-
-All addon errors crossing public Node transport and server boundaries become `TrevRpcError` unless already normalized. `nativeCode` and `cause` preserve native provenance.
-
-## Package resolution
-
-Conditional ESM exports are authoritative; the package has no legacy top-level `main` or `types`. Use TypeScript NodeNext resolution for Node consumers and Bundler resolution with browser conditions for browser consumers.
-
-## Native development
-
-Installation never builds native code. In a source checkout:
-
-```sh
-npm run build:native:test
-npm test
-npm run build:native
-npm run verify:native:production
-```
-
-The development fallback is only `build/native/trevrpc_native.node` in a source checkout.

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "0.1.8",
+  "version": "0.2.2",
   "description": "JavaScript WebTransport runtime and protobuf.js code generator for TrevRPC",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {
@@ -65,24 +65,25 @@
     "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\")'",
     "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\" : \"\"}`);'"
   },
   "dependencies": {
-    "protobufjs": "^8.7.1"
+    "protobufjs": "^8.8.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "esbuild": "^0.28.1",
-    "playwright": "^1.62.1",
+    "esbuild": "^0.28.2",
+    "playwright": "1.61.1",
     "typescript": "^7.0.2"
   },
-  "optionalDependencies": {
-    "@trevrpc/trevrpc-js-native-linux-x64-gnu": "0.1.8"
-  },
   "engines": {
     "node": ">=24 <25"
   },
-  "packageManager": "npm@11.19.0"
+  "packageManager": "npm@12.0.2",
+  "optionalDependencies": {
+    "@trevrpc/trevrpc-js-native-linux-x64-gnu": "0.2.2"
+  }
 }

package/src/browser-channel.js

@@ -1,6 +1,10 @@
 import { ChannelStateMachine, stripChannelOptions, waitForInitialReady } from "./channel.js";
 import { unavailable } from "./status.js";
-import { RawWebTransport, createWebTransportSession } from "./webtransport.js";
+import {
+  RawWebTransport,
+  createWebTransportSession,
+  waitForWebTransportReady,
+} from "./webtransport.js";
 
 /** Browser channel with background session reconnection. */
 export class Channel extends ChannelStateMachine {
@@ -31,7 +35,7 @@ async function connectWebTransport(url, options, signal) {
   signal.addEventListener("abort", onAbort, { once: true });
 
   try {
-    await session.ready;
+    await waitForWebTransportReady(session);
     if (signal.aborted) {
       throw unavailable("channel is closed");
     }

package/src/native-loader.js

@@ -13,17 +13,17 @@ const packageVersion = (() => {
     return "unknown";
   }
 })();
-const SupportedTarget = "linux/x64/glibc";
+const SupportedOptionalTarget = "linux/x64/glibc";
 const LinuxX64GnuPackage = "@trevrpc/trevrpc-js-native-linux-x64-gnu";
 
 /** Loads the target-specific native addon without building during installation. */
-export function loadNativeAddon() {
+export function loadNativeAddon({ loadOptionalPackage = true, loadBundledAddon = true } = {}) {
   const target = nativeTarget();
   const packageName = nativePackageName(target);
   let packageError;
   let packageState = "unsupported";
 
-  if (packageName != null) {
+  if (loadOptionalPackage && packageName != null) {
     try {
       return require(packageName);
     } catch (error) {
@@ -32,6 +32,16 @@ export function loadNativeAddon() {
     }
   }
 
+  const bundled = loadBundledAddon ? bundledNativePath() : null;
+  let bundledError;
+  if (bundled != null) {
+    try {
+      return require(bundled);
+    } catch (error) {
+      bundledError = error;
+    }
+  }
+
   const fallback = developmentFallbackPath();
   let fallbackError;
   if (fallback != null) {
@@ -44,6 +54,8 @@ export function loadNativeAddon() {
 
   const detected = targetName(target);
   const expected = packageName ?? "no optional package (unsupported target)";
+  const bundledState =
+    bundled == null ? "no Nix-bundled addon was present" : "the Nix-bundled addon failed to load";
   const fallbackState =
     fallback == null
       ? "no source-checkout fallback was present"
@@ -52,10 +64,10 @@ export function loadNativeAddon() {
         : "the source-checkout fallback failed to load";
   throw new Error(
     `TrevRPC native addon is unavailable for detected target ${detected}. ` +
-      `Supported targets: ${SupportedTarget}. Expected optional package: ${expected}@${packageVersion}; ` +
-      `package state: ${packageState}; ${fallbackState}. ` +
+      `Supported optional-package targets: ${SupportedOptionalTarget}. Expected optional package: ${expected}@${packageVersion}; ` +
+      `package state: ${packageState}; ${bundledState}; ${fallbackState}. ` +
       "Install the matching optional package or build build/native/trevrpc_native.node explicitly in a source checkout; npm installation never starts a source build.",
-    { cause: fallbackError ?? packageError },
+    { cause: fallbackError ?? bundledError ?? packageError },
   );
 }
 
@@ -75,6 +87,11 @@ function nativePackageName(target) {
   return null;
 }
 
+function bundledNativePath() {
+  const path = join(packageRoot, "native", "trevrpc_native.node");
+  return existsSync(path) ? path : null;
+}
+
 function developmentFallbackPath() {
   if (!existsSync(join(packageRoot, "native", "CMakeLists.txt"))) {
     return null;

package/src/webtransport.js

@@ -30,13 +30,13 @@ export class RawWebTransport {
   /** Opens a WebTransport session and wraps it in a TrevRPC client. */
   static async connect(url, options = {}) {
     const session = createWebTransportSession(url, options);
-    await session.ready;
+    await waitForWebTransportReady(session);
     return new RawWebTransport(session, options);
   }
 
   /** Waits for the underlying WebTransport session to become ready. */
   async ready() {
-    await this.session.ready;
+    await waitForWebTransportReady(this.session);
   }
 
   /** Closes the underlying WebTransport session. */
@@ -146,6 +146,21 @@ export class RawWebTransport {
   }
 }
 
+/** Waits for readiness without hanging when a session closes during setup. */
+export async function waitForWebTransportReady(session) {
+  if (session.closed == null) {
+    await session.ready;
+    return;
+  }
+
+  await Promise.race([
+    session.ready,
+    Promise.resolve(session.closed).then(() => {
+      throw unavailable("WebTransport session closed before becoming ready");
+    }),
+  ]);
+}
+
 /** Creates a WebTransport session using only browser constructor options. */
 export function createWebTransportSession(url, options = {}) {
   const WebTransportCtor = options.WebTransport ?? globalThis.WebTransport;