@trevrpc/trevrpc-js 0.2.3 → 1.1.0

package/src/race.js

@@ -0,0 +1,90 @@
+import { cancelled, statusFromTransportError, unavailable } from "./status.js";
+
+/**
+ * Dials `primary`, adds `fallback` once the primary fails or `delayMs` passes, and resolves with
+ * `{ session, transport }` from the first to connect. The loser is abandoned and closed if it
+ * connects anyway. Each candidate is `{ transport, dial(signal) }`.
+ */
+export function dialRace(primary, fallback, { delayMs, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    const attempts = new Map();
+    const errors = [];
+    let settled = false;
+    let fallbackStarted = false;
+    let timer;
+
+    const settle = (winner) => {
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      for (const [candidate, controller] of attempts) {
+        if (candidate !== winner) {
+          controller.abort();
+        }
+      }
+    };
+    const start = (candidate) => {
+      const controller = new AbortController();
+      attempts.set(candidate, controller);
+      let dialing;
+      try {
+        // Dialing starts synchronously, so a session exists as soon as the race begins.
+        dialing = Promise.resolve(candidate.dial(controller.signal));
+      } catch (error) {
+        dialing = Promise.reject(error);
+      }
+      dialing.then(
+        (session) => {
+          if (settled) {
+            closeQuietly(session);
+            return;
+          }
+          settle(candidate);
+          resolve({ session, transport: candidate.transport });
+        },
+        (error) => {
+          attempts.delete(candidate);
+          if (settled) {
+            return;
+          }
+          errors.push(`${candidate.transport}: ${statusFromTransportError(error).message}`);
+          if (candidate === primary) {
+            startFallback();
+          } else if (attempts.size === 0) {
+            settle(null);
+            reject(unavailable(`transport unavailable: ${errors.join("; ")}`));
+          }
+        },
+      );
+    };
+    const startFallback = () => {
+      if (!fallbackStarted && !settled) {
+        fallbackStarted = true;
+        clearTimeout(timer);
+        start(fallback);
+      }
+    };
+    const onAbort = () => {
+      if (!settled) {
+        settle(null);
+        reject(cancelled("connection cancelled", signal.reason));
+      }
+    };
+
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    start(primary);
+    timer = setTimeout(startFallback, delayMs);
+  });
+}
+
+function closeQuietly(session) {
+  try {
+    session.close();
+  } catch {
+    // The session may already be gone.
+  }
+}

package/src/status.js

@@ -18,82 +18,38 @@ export const Code = Object.freeze({
   Unauthenticated: 16,
 });
 
-const CODE_NAMES = Object.freeze([
-  "Ok",
-  "Cancelled",
-  "Unknown",
-  "InvalidArgument",
-  "DeadlineExceeded",
-  "NotFound",
-  "AlreadyExists",
-  "PermissionDenied",
-  "ResourceExhausted",
-  "FailedPrecondition",
-  "Aborted",
-  "OutOfRange",
-  "Unimplemented",
-  "Internal",
-  "Unavailable",
-  "DataLoss",
-  "Unauthenticated",
-]);
+const CodeNames = Object.freeze(Object.keys(Code));
 
 /** Error carrying a TrevRPC status code, message, and metadata. */
 export class TrevRpcError extends Error {
   /** Creates a TrevRPC status error. */
   constructor(code, message = "", metadata = {}, options = {}) {
     const normalizedCode = codeFromNumber(code);
-    super(message === "" ? codeName(normalizedCode) : `${codeName(normalizedCode)}: ${message}`, {
-      cause: options.cause,
-    });
+    const name = codeName(normalizedCode);
+    super(
+      message === "" ? name : `${name}: ${message}`,
+      options.cause === undefined ? undefined : { cause: options.cause },
+    );
     this.name = "TrevRpcError";
     this.code = normalizedCode;
     this.statusMessage = message;
     this.metadata = metadata;
-    if (Number.isInteger(options.nativeCode)) {
-      this.nativeCode = options.nativeCode;
-    }
-  }
-}
-
-/** Resource-exhausted status reported when a frame exceeds the configured size limit. */
-export class FrameTooLargeError extends TrevRpcError {
-  /** Creates a frame size error. */
-  constructor(length, max) {
-    super(Code.ResourceExhausted, `frame length ${length} exceeds maximum ${max}`);
-    this.name = "FrameTooLargeError";
-    this.length = length;
-    this.max = max;
   }
 }
 
 /** Converts a number into a known status code, defaulting unknown values to Unknown. */
 export function codeFromNumber(code) {
-  return Number.isInteger(code) && code >= 0 && code < CODE_NAMES.length ? code : Code.Unknown;
+  return Number.isInteger(code) && code >= 0 && code < CodeNames.length ? code : Code.Unknown;
 }
 
 /** Returns the canonical status code name. */
 export function codeName(code) {
-  return CODE_NAMES[codeFromNumber(code)];
+  return CodeNames[codeFromNumber(code)];
 }
 
 /** Creates a TrevRPC status error. */
-export function statusError(code, message = "", metadata = {}) {
-  return new TrevRpcError(code, message, metadata);
-}
-
-/** Builds a status error from an RPC response. */
-export function statusFromResponse(response) {
-  if (response == null) {
-    return statusError(Code.Internal, "missing RPC response");
-  }
-
-  return statusError(response.status ?? Code.Ok, response.message ?? "", response.metadata ?? {});
-}
-
-/** Reports whether a status-like value is OK. */
-export function isOkStatus(status) {
-  return status != null && codeFromNumber(status.code) === Code.Ok;
+export function statusError(code, message = "", metadata = {}, cause) {
+  return new TrevRpcError(code, message, metadata, { cause });
 }
 
 /** Creates an internal error status. */
@@ -102,8 +58,13 @@ export function internal(message) {
 }
 
 /** Creates an invalid-argument status. */
-export function invalidArgument(message) {
-  return statusError(Code.InvalidArgument, message);
+export function invalidArgument(message, cause) {
+  return statusError(Code.InvalidArgument, message, {}, cause);
+}
+
+/** Creates a failed-precondition status. */
+export function failedPrecondition(message) {
+  return statusError(Code.FailedPrecondition, message);
 }
 
 /** Creates a deadline-exceeded status. */
@@ -112,8 +73,8 @@ export function deadlineExceeded(message) {
 }
 
 /** Creates an unavailable status. */
-export function unavailable(message) {
-  return statusError(Code.Unavailable, message);
+export function unavailable(message, cause) {
+  return statusError(Code.Unavailable, message, {}, cause);
 }
 
 /** Creates a resource-exhausted status. */
@@ -122,24 +83,17 @@ export function resourceExhausted(message) {
 }
 
 /** Creates a cancelled status. */
-export function cancelled(message) {
-  return statusError(Code.Cancelled, message);
+export function cancelled(message, cause) {
+  return statusError(Code.Cancelled, message, {}, cause);
 }
 
-/** Converts a transport error into a TrevRPC status error. */
+/** Converts a transport failure into a status error; status errors pass through. */
 export function statusFromTransportError(error) {
   if (error instanceof TrevRpcError) {
     return error;
   }
-
   if (error?.name === "AbortError") {
-    return new TrevRpcError(Code.Cancelled, "transport closed locally", {}, { cause: error });
+    return cancelled("transport closed locally", error);
   }
-
-  return new TrevRpcError(
-    Code.Unavailable,
-    `transport unavailable: ${error?.message ?? String(error)}`,
-    {},
-    { cause: error },
-  );
+  return unavailable(`transport unavailable: ${error?.message ?? String(error)}`, error);
 }

package/src/varint.js

@@ -0,0 +1,73 @@
+// QUIC variable-length integers (RFC 9000 §16), shared by the frame layer and QMux. Values below
+// 2^53 are numbers; larger codepoints are bigints.
+
+const MaxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+
+/** Encoded length of a varint. */
+export function varintLength(value) {
+  if (typeof value === "number" && value >= 0 && value < 0x4000_0000) {
+    return value < 0x40 ? 1 : value < 0x4000 ? 2 : 4;
+  }
+  const v = typeof value === "bigint" ? value : BigInt(value);
+  if (v < 0x40n) {
+    return 1;
+  }
+  if (v < 0x4000n) {
+    return 2;
+  }
+  if (v < 0x4000_0000n) {
+    return 4;
+  }
+  if (v < 0x4000_0000_0000_0000n) {
+    return 8;
+  }
+  throw new RangeError(`varint ${v} exceeds 2^62 - 1`);
+}
+
+/** Writes a varint at offset and returns the offset after it. */
+export function writeVarint(bytes, offset, value) {
+  const length = varintLength(value);
+  if (typeof value === "number" && length < 8 && Number.isInteger(value)) {
+    // Fast path without BigInt for the common small values.
+    let v = value;
+    for (let i = length - 1; i >= 0; i -= 1) {
+      bytes[offset + i] = v % 256;
+      v = Math.floor(v / 256);
+    }
+    bytes[offset] |= [0, 0x40, 0, 0x80][length - 1];
+    return offset + length;
+  }
+  let v = typeof value === "bigint" ? value : BigInt(value);
+  for (let i = length - 1; i >= 0; i -= 1) {
+    bytes[offset + i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  bytes[offset] |= [0, 0x40, 0, 0x80, 0, 0, 0, 0xc0][length - 1];
+  return offset + length;
+}
+
+/**
+ * Reads a varint at offset. Returns `{ value, next }`, or null when the bytes end first. Values
+ * above 2^53 - 1 are bigints.
+ */
+export function readVarint(bytes, offset) {
+  if (offset >= bytes.length) {
+    return null;
+  }
+  const length = 1 << (bytes[offset] >> 6);
+  if (offset + length > bytes.length) {
+    return null;
+  }
+  if (length < 8) {
+    let value = bytes[offset] & 0x3f;
+    for (let i = 1; i < length; i += 1) {
+      value = value * 256 + bytes[offset + i];
+    }
+    return { value, next: offset + length };
+  }
+  let value = BigInt(bytes[offset] & 0x3f);
+  for (let i = 1; i < 8; i += 1) {
+    value = (value << 8n) | BigInt(bytes[offset + i]);
+  }
+  return { value: value <= MaxSafe ? Number(value) : value, next: offset + 8 };
+}

package/src/wire.js

@@ -1,8 +1,8 @@
 import protobuf from "protobufjs";
 
-export { protobuf };
+import { byteView } from "./bytes.js";
 
-export const WireVersion = 1;
+export { protobuf };
 
 export const RpcKind = Object.freeze({
   Unary: 0,
@@ -11,12 +11,7 @@ export const RpcKind = Object.freeze({
   BidirectionalStreaming: 3,
 });
 
-export const RpcStreamFrameKind = Object.freeze({
-  Message: 0,
-  Status: 1,
-});
-
-export const wireRoot = protobuf.Root.fromJSON({
+const wireRoot = protobuf.Root.fromJSON({
   nested: {
     trevrpc: {
       nested: {
@@ -28,38 +23,32 @@ export const wireRoot = protobuf.Root.fromJSON({
             BidirectionalStreaming: 3,
           },
         },
-        RpcStreamFrameKind: {
-          values: {
-            Message: 0,
-            Status: 1,
-          },
-        },
         RpcRequest: {
           fields: {
-            service: { type: "string", id: 1 },
-            method: { type: "string", id: 2 },
-            body: { type: "bytes", id: 3 },
+            method: { type: "string", id: 1 },
             metadata: { keyType: "string", type: "bytes", id: 4 },
             kind: { type: "RpcKind", id: 5 },
-            version: { type: "uint32", id: 6 },
             timeoutNanos: { type: "uint64", id: 7 },
+            extensions: { rule: "repeated", type: "uint64", id: 8 },
+            datagramFlow: { type: "uint64", id: 9 },
           },
+          // Fields 2 (method name), 3 (request body) and 6 (wire version) must never be reused.
+          reserved: [
+            [2, 3],
+            [6, 6],
+          ],
         },
-        RpcResponse: {
+        RpcHeaders: {
           fields: {
-            status: { type: "uint32", id: 1 },
-            message: { type: "string", id: 2 },
-            body: { type: "bytes", id: 3 },
-            metadata: { keyType: "string", type: "bytes", id: 4 },
+            metadata: { keyType: "string", type: "bytes", id: 1 },
+            extensions: { rule: "repeated", type: "uint64", id: 2 },
           },
         },
-        RpcStreamFrame: {
+        RpcStatus: {
           fields: {
-            kind: { type: "RpcStreamFrameKind", id: 1 },
-            status: { type: "uint32", id: 2 },
-            message: { type: "string", id: 3 },
-            body: { type: "bytes", id: 4 },
-            metadata: { keyType: "string", type: "bytes", id: 5 },
+            code: { type: "uint32", id: 1 },
+            message: { type: "string", id: 2 },
+            metadata: { keyType: "string", type: "bytes", id: 3 },
           },
         },
       },
@@ -68,71 +57,24 @@ export const wireRoot = protobuf.Root.fromJSON({
 });
 
 export const RpcRequest = wireRoot.lookupType("trevrpc.RpcRequest");
-export const RpcResponse = wireRoot.lookupType("trevrpc.RpcResponse");
-export const RpcStreamFrame = wireRoot.lookupType("trevrpc.RpcStreamFrame");
+export const RpcHeaders = wireRoot.lookupType("trevrpc.RpcHeaders");
+export const RpcStatus = wireRoot.lookupType("trevrpc.RpcStatus");
 
 const MaxFieldNumber = 0x1fffffff;
 const MaxUint32 = 0xffffffffn;
 const MaxUint64 = 0xffffffffffffffffn;
 const fatalUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
 
-/** Internal wire-validation failure used by production codec paths. */
-export class WireValidationError extends Error {
-  constructor(reason, message) {
-    super(message);
-    this.name = "WireValidationError";
-    this.reason = reason;
-  }
-}
-
 /** Checks protobuf tags and known-field wire types before protobuf.js decoding. */
 export function preflightWireMessage(messageType, body) {
   scanMessage(messageType, byteView(body), 0);
 }
 
-/** Validates TrevRPC protocol enums and versions after protobuf decoding. */
-export function validateWireMessage(messageType, message) {
-  if (messageType === RpcRequest) {
-    if (message.version !== WireVersion) {
-      throw new WireValidationError(
-        "unsupported_wire_version",
-        `unsupported wire version ${message.version}`,
-      );
-    }
-    if (!Object.values(RpcKind).includes(message.kind)) {
-      throw new WireValidationError("unsupported_rpc_kind", `unsupported RPC kind ${message.kind}`);
-    }
-    return;
-  }
-
-  if (
-    messageType === RpcStreamFrame &&
-    message.kind !== RpcStreamFrameKind.Message &&
-    message.kind !== RpcStreamFrameKind.Status
-  ) {
-    throw new WireValidationError(
-      "unsupported_frame_kind",
-      `unsupported stream frame kind ${message.kind}`,
-    );
-  }
-}
-
 /** Creates a protobuf root from a JSON namespace definition. */
 export function createRoot(json) {
   return protobuf.Root.fromJSON(json);
 }
 
-/** Creates a stream message frame carrying a protobuf body. */
-export function messageFrame(body) {
-  return {
-    kind: RpcStreamFrameKind.Message,
-    status: 0,
-    message: "",
-    body,
-    metadata: {},
-  };
-}
-
 function scanMessage(messageType, bytes, depth) {
   if (depth > 64) {
     throw malformedWire("protobuf message nesting exceeded limit");
@@ -389,15 +331,5 @@ function validateUtf8(bytes, name) {
 }
 
 function malformedWire(message) {
-  return new WireValidationError("malformed_protobuf", message);
-}
-
-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);
+  return new Error(message);
 }

package/examples/greeter/README.md

@@ -1,35 +0,0 @@
-# Greeter example
-
-This directory contains the generated Milestone 6 split:
-
-- `greeter.trevrpc.js` and `.d.ts`: protobuf root, descriptors, typed clients, and factories; browser-safe.
-- `greeter.node.trevrpc.js` and `.d.ts`: typed Node handler interfaces and `registerGreeterServer`.
-
-Browser code must import only `greeter.trevrpc.js`. Node servers import registration from `greeter.node.trevrpc.js` and use `createUnaryResponse` or `createStreamingResponse` when returning metadata or a custom terminal status. A direct protobuf object such as `{ message: "hello" }` remains a protobuf response.
-
-## Run the browser page
-
-From `trevrpc-js`:
-
-```sh
-npm run example:greeter
-```
-
-Open `http://127.0.0.1:8080/examples/greeter/` and use a WebTransport greeter endpoint:
-
-```text
-https://127.0.0.1:50051/trevrpc  # Go default
-https://127.0.0.1:5000/trevrpc   # Rust default
-```
-
-The path selects the WebTransport session; TrevRPC routing remains inside the request frame. The example policies allow origin `http://127.0.0.1:8080` and use bearer token `trevrpc-example-token`.
-
-Both example servers write their development certificate to `~/.config/trevrpc/trevrpc-example-cert.pem`. Override it with `TREVRPC_EXAMPLE_CERT`. The static server computes the SHA-256 DER hash and the browser client passes it through `serverCertificateHashes`.
-
-For a temporary self-signed certificate, calculate the hash with:
-
-```sh
-openssl x509 -in server.pem -outform der | openssl dgst -sha256 -binary | openssl base64
-```
-
-The client fully consumes server streams, then reads terminal metadata from `stream.status`. It calls `close()` when abandoning streams. Client `timeoutMs` is absolute across setup, upload, and receive, while `streamIdleTimeoutMs` is a separate inactivity bound.

package/examples/greeter/client.js

@@ -1,172 +0,0 @@
-import { TrevRpcError, connect } from "../../src/index.js";
-import { GreeterClient } from "./greeter.trevrpc.js";
-
-const form = document.querySelector("#client-form");
-const output = document.querySelector("#output");
-const submit = document.querySelector("#submit");
-
-void loadExampleDefaults();
-
-form.addEventListener("submit", (event) => {
-  event.preventDefault();
-  void runFromForm(new FormData(form));
-});
-
-for (const preset of document.querySelectorAll("[data-url]")) {
-  preset.addEventListener("click", () => {
-    form.elements.url.value = preset.dataset.url;
-  });
-}
-
-async function runFromForm(data) {
-  output.textContent = "";
-  submit.disabled = true;
-
-  const url = String(data.get("url") ?? "").trim();
-  const name = String(data.get("name") ?? "TrevRPC").trim() || "TrevRPC";
-  const token = String(data.get("token") ?? "").trim();
-  const certificateHash = String(data.get("certificate-hash") ?? "").trim();
-
-  let channel;
-  try {
-    log(`connecting to ${url}`);
-    channel = await connect(url, {
-      ...browserConnectOptions(certificateHash),
-      timeoutMs: 10_000,
-    });
-    const client = new GreeterClient(channel, {
-      timeoutMs: 5_000,
-      metadata: token === "" ? {} : { authorization: `Bearer ${token}` },
-    });
-
-    const unary = await client.sayHello({ name });
-    log(`SayHello: ${unary.message}`);
-
-    const replies = await client.lotsOfReplies({ name });
-    for await (const reply of replies) {
-      log(`LotsOfReplies: ${reply.message}`);
-    }
-    const replyStatus = await replies.status;
-    log(
-      `LotsOfReplies status: ${replyStatus.code} ${replyStatus.message}; trailers=${Object.keys(replyStatus.metadata).join(",")}`,
-    );
-
-    const greetings = await client.lotsOfGreetings();
-    await greetings.send({ name: `${name} client stream 1` });
-    await greetings.send({ name: `${name} client stream 2` });
-    const summary = await greetings.closeAndRecvWithResponse();
-    log(
-      `LotsOfGreetings: ${summary.message.message}; trailers=${Object.keys(summary.metadata).join(",")}`,
-    );
-
-    const bidi = await client.bidiHello();
-    try {
-      for (const suffix of ["bidi 1", "bidi 2"]) {
-        await bidi.send({ name: `${name} ${suffix}` });
-
-        const reply = await bidi.recv();
-        if (reply == null) {
-          throw new Error("BidiHello response stream ended early");
-        }
-        log(`BidiHello: ${reply.message}`);
-      }
-      await bidi.closeSend();
-
-      for (;;) {
-        const reply = await bidi.recv();
-        if (reply == null) {
-          break;
-        }
-        log(`BidiHello: ${reply.message}`);
-      }
-    } finally {
-      await bidi.close();
-    }
-
-    log("complete");
-  } catch (error) {
-    logError(error);
-  } finally {
-    submit.disabled = false;
-    channel?.close({ closeCode: 0, reason: "example complete" });
-  }
-}
-
-function browserConnectOptions(certificateHash) {
-  if (certificateHash === "") {
-    return {};
-  }
-
-  return {
-    serverCertificateHashes: [
-      {
-        algorithm: "sha-256",
-        value: parseSha256Hash(certificateHash),
-      },
-    ],
-  };
-}
-
-async function loadExampleDefaults() {
-  try {
-    const response = await fetch("./certificate-hash.json", { cache: "no-store" });
-    if (!response.ok) {
-      return;
-    }
-
-    const config = await response.json();
-    if (typeof config.bearerToken === "string" && form.elements.token.value === "") {
-      form.elements.token.value = config.bearerToken;
-    }
-    if (config.exists && typeof config.sha256Base64 === "string") {
-      form.elements["certificate-hash"].value = config.sha256Base64;
-      log(`loaded certificate hash from ${config.path}`);
-    } else if (typeof config.path === "string") {
-      log(`certificate not found at ${config.path}; start a Go or Rust example server first`);
-    }
-  } catch (error) {
-    log(`could not load local certificate hash: ${error?.message ?? String(error)}`);
-  }
-}
-
-function parseSha256Hash(value) {
-  const normalized = value
-    .trim()
-    .replace(/^sha-?256[=:]/i, "")
-    .trim();
-  const hex = normalized.replace(/[:\s]/g, "");
-
-  if (/^[0-9a-fA-F]{64}$/.test(hex)) {
-    const bytes = new Uint8Array(32);
-    for (let index = 0; index < bytes.length; index += 1) {
-      bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
-    }
-    return bytes;
-  }
-
-  const base64 = normalized.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
-  const binary = atob(padded);
-  if (binary.length !== 32) {
-    throw new Error("certificate hash must decode to 32 bytes of SHA-256 data");
-  }
-
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) {
-    bytes[index] = binary.charCodeAt(index);
-  }
-  return bytes;
-}
-
-function log(message) {
-  output.textContent += `${message}\n`;
-}
-
-function logError(error) {
-  if (error instanceof TrevRpcError) {
-    log(`RPC error: ${error.code}: ${error.statusMessage || error.message}`);
-    return;
-  }
-
-  log(`error: ${error?.message ?? String(error)}`);
-}