@trevrpc/trevrpc-js 0.2.2 → 1.0.0

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 = undefined) {
+  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/wire.js

@@ -1,5 +1,7 @@
 import protobuf from "protobufjs";
 
+import { byteView } from "./bytes.js";
+
 export { protobuf };
 
 export const WireVersion = 1;
@@ -16,7 +18,7 @@ export const RpcStreamFrameKind = Object.freeze({
   Status: 1,
 });
 
-export const wireRoot = protobuf.Root.fromJSON({
+const wireRoot = protobuf.Root.fromJSON({
   nested: {
     trevrpc: {
       nested: {
@@ -76,63 +78,16 @@ 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 +344,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)}`);
-}

package/examples/greeter/greeter.node.trevrpc.d.ts

@@ -1,53 +0,0 @@
-// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.
-
-import type {
-  NodeServer,
-  NodeServerCall,
-  StreamingServerResponse,
-  UnaryServerResponse,
-} from "../../src/node-generated.js";
-import type { HelloRequest, HelloReply } from "./greeter.trevrpc.js";
-
-/** Typed Node handlers for the Greeter service. */
-export interface GreeterHandlers {
-  sayHello?(
-    request: HelloRequest,
-    call: NodeServerCall,
-  ):
-    | HelloReply
-    | UnaryServerResponse<HelloReply>
-    | Promise<HelloReply | UnaryServerResponse<HelloReply>>;
-  lotsOfReplies?(
-    request: HelloRequest,
-    call: NodeServerCall,
-  ):
-    | Iterable<HelloReply>
-    | AsyncIterable<HelloReply>
-    | StreamingServerResponse<HelloReply>
-    | Promise<
-        Iterable<HelloReply> | AsyncIterable<HelloReply> | StreamingServerResponse<HelloReply>
-      >;
-  lotsOfGreetings?(
-    requests: AsyncIterable<HelloRequest>,
-    call: NodeServerCall,
-  ):
-    | HelloReply
-    | UnaryServerResponse<HelloReply>
-    | Promise<HelloReply | UnaryServerResponse<HelloReply>>;
-  bidiHello?(
-    requests: AsyncIterable<HelloRequest>,
-    call: NodeServerCall,
-  ):
-    | Iterable<HelloReply>
-    | AsyncIterable<HelloReply>
-    | StreamingServerResponse<HelloReply>
-    | Promise<
-        Iterable<HelloReply> | AsyncIterable<HelloReply> | StreamingServerResponse<HelloReply>
-      >;
-}
-
-/** Registers typed Node handlers for the Greeter service. */
-export declare function registerGreeterServer(
-  server: NodeServer,
-  handlers: GreeterHandlers,
-): NodeServer;

package/examples/greeter/greeter.node.trevrpc.js

@@ -1,9 +0,0 @@
-// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.
-
-import { registerTypedService } from "../../src/node-generated.js";
-import { GreeterService, root } from "./greeter.trevrpc.js";
-
-/** Registers typed Node handlers for the Greeter service. */
-export function registerGreeterServer(server, handlers) {
-  return registerTypedService(server, root, GreeterService, handlers);
-}

package/examples/greeter/greeter.proto

@@ -1,18 +0,0 @@
-syntax = "proto3";
-
-package example.greeter;
-
-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);
-}
-
-message HelloRequest {
-  string name = 1;
-}
-
-message HelloReply {
-  string message = 1;
-}

package/examples/greeter/greeter.trevrpc.d.ts

@@ -1,55 +0,0 @@
-// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.
-
-import type { Long, Root } from "protobufjs";
-
-import type {
-  BidirectionalStreamingCall,
-  CallOptions,
-  ClientStreamingCall,
-  ResponseAsyncIterable,
-  RpcServiceDescriptor,
-  Transport,
-  UnaryResponse,
-} from "../../src/index.js";
-
-export declare const root: Root;
-
-export interface HelloRequest {
-  name?: string;
-}
-
-export interface HelloReply {
-  message?: string;
-}
-
-/** Service descriptor for the Greeter service. */
-export declare const GreeterService: RpcServiceDescriptor;
-
-/** Client for the Greeter service. */
-export declare class GreeterClient {
-  /** Creates a client for the Greeter service. */
-  constructor(transport: Transport, options?: CallOptions);
-
-  /** Calls the SayHello RPC. */
-  sayHello(request: HelloRequest, options?: CallOptions): Promise<HelloReply>;
-  /** Calls the SayHello RPC and returns response metadata. */
-  sayHelloWithResponse(
-    request: HelloRequest,
-    options?: CallOptions,
-  ): Promise<UnaryResponse<HelloReply>>;
-  /** Calls the LotsOfReplies RPC. */
-  lotsOfReplies(
-    request: HelloRequest,
-    options?: CallOptions,
-  ): Promise<ResponseAsyncIterable<HelloReply>>;
-  /** Calls the LotsOfGreetings RPC. */
-  lotsOfGreetings(options?: CallOptions): Promise<ClientStreamingCall<HelloRequest, HelloReply>>;
-  /** Calls the BidiHello RPC. */
-  bidiHello(options?: CallOptions): Promise<BidirectionalStreamingCall<HelloRequest, HelloReply>>;
-}
-
-/** Creates a client for the Greeter service. */
-export declare function createGreeterClient(
-  transport: Transport,
-  options?: CallOptions,
-): GreeterClient;

package/examples/greeter/greeter.trevrpc.js

@@ -1,103 +0,0 @@
-// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.
-
-import { createRoot, createServiceClient } from "../../src/index.js";
-
-export const root = createRoot({
-  nested: {
-    example: {
-      nested: {
-        greeter: {
-          nested: {
-            HelloRequest: {
-              fields: {
-                name: {
-                  type: "string",
-                  id: 1,
-                },
-              },
-            },
-            HelloReply: {
-              fields: {
-                message: {
-                  type: "string",
-                  id: 1,
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-});
-
-/** Service descriptor for the Greeter service. */
-export const GreeterService = Object.freeze({
-  name: "Greeter",
-  fullName: "example.greeter.Greeter",
-  exportName: "GreeterService",
-  methods: {
-    sayHello: {
-      name: "SayHello",
-      kind: "unary",
-      inputType: "example.greeter.HelloRequest",
-      outputType: "example.greeter.HelloReply",
-    },
-    lotsOfReplies: {
-      name: "LotsOfReplies",
-      kind: "serverStreaming",
-      inputType: "example.greeter.HelloRequest",
-      outputType: "example.greeter.HelloReply",
-    },
-    lotsOfGreetings: {
-      name: "LotsOfGreetings",
-      kind: "clientStreaming",
-      inputType: "example.greeter.HelloRequest",
-      outputType: "example.greeter.HelloReply",
-    },
-    bidiHello: {
-      name: "BidiHello",
-      kind: "bidirectionalStreaming",
-      inputType: "example.greeter.HelloRequest",
-      outputType: "example.greeter.HelloReply",
-    },
-  },
-});
-
-/** Client for the Greeter service. */
-export class GreeterClient {
-  /** Creates a client for the Greeter service. */
-  constructor(transport, options = {}) {
-    this._client = createServiceClient(transport, GreeterService, root, options);
-  }
-
-  /** Calls the SayHello RPC. */
-  sayHello(request, options = {}) {
-    return this._client.sayHello(request, options);
-  }
-
-  /** Calls the SayHello RPC and returns response metadata. */
-  sayHelloWithResponse(request, options = {}) {
-    return this._client.sayHelloWithResponse(request, options);
-  }
-
-  /** Calls the LotsOfReplies RPC. */
-  lotsOfReplies(request, options = {}) {
-    return this._client.lotsOfReplies(request, options);
-  }
-
-  /** Calls the LotsOfGreetings RPC. */
-  lotsOfGreetings(options = {}) {
-    return this._client.lotsOfGreetings(options);
-  }
-
-  /** Calls the BidiHello RPC. */
-  bidiHello(options = {}) {
-    return this._client.bidiHello(options);
-  }
-}
-
-/** Creates a client for the Greeter service. */
-export function createGreeterClient(transport, options = {}) {
-  return new GreeterClient(transport, options);
-}