@trevrpc/trevrpc-js 0.1.0

package/examples/greeter/index.html

@@ -0,0 +1,140 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>TrevRPC JavaScript Greeter Client</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        font-family:
+          Inter,
+          ui-sans-serif,
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          "Segoe UI",
+          sans-serif;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background:
+          radial-gradient(circle at top left, rgb(80 80 180 / 30%), transparent 35rem), Canvas;
+        color: CanvasText;
+      }
+
+      main {
+        box-sizing: border-box;
+        width: min(54rem, 100%);
+        margin: 0 auto;
+        padding: 3rem 1rem;
+      }
+
+      form,
+      pre {
+        border: 1px solid color-mix(in srgb, CanvasText 18%, transparent);
+        border-radius: 1rem;
+        background: color-mix(in srgb, Canvas 92%, CanvasText 8%);
+        box-shadow: 0 1rem 3rem rgb(0 0 0 / 12%);
+      }
+
+      form {
+        display: grid;
+        gap: 1rem;
+        padding: 1rem;
+      }
+
+      label {
+        display: grid;
+        gap: 0.35rem;
+        font-weight: 700;
+      }
+
+      input,
+      button {
+        border: 1px solid color-mix(in srgb, CanvasText 22%, transparent);
+        border-radius: 0.7rem;
+        font: inherit;
+        padding: 0.75rem;
+      }
+
+      button {
+        cursor: pointer;
+        font-weight: 800;
+      }
+
+      .actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.75rem;
+      }
+
+      #submit {
+        background: #5b5bd6;
+        color: white;
+      }
+
+      small {
+        opacity: 0.75;
+      }
+
+      pre {
+        min-height: 14rem;
+        overflow: auto;
+        padding: 1rem;
+        white-space: pre-wrap;
+      }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "protobufjs": "./vendor/protobufjs.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <main>
+      <h1>TrevRPC JavaScript Greeter Client</h1>
+      <p>
+        Connect this page to a WebTransport-enabled TrevRPC Go or Rust greeter server and run all
+        four RPC shapes from the browser.
+      </p>
+
+      <form id="client-form">
+        <label>
+          WebTransport URL
+          <input name="url" required value="https://127.0.0.1:50051/trevrpc" />
+        </label>
+        <div class="actions">
+          <button type="button" data-url="https://127.0.0.1:50051/trevrpc">Go default URL</button>
+          <button type="button" data-url="https://127.0.0.1:5000/trevrpc">Rust default URL</button>
+        </div>
+        <label>
+          Name
+          <input name="name" value="TrevRPC" />
+        </label>
+        <label>
+          Bearer token
+          <input name="token" value="trevrpc-example-token" />
+        </label>
+        <label>
+          Server certificate SHA-256 hash
+          <input name="certificate-hash" placeholder="optional hex or base64 hash" />
+          <small>
+            The local static server loads this from
+            <code>~/.config/trevrpc/trevrpc-example-cert.pem</code> when available. Leave empty when
+            the browser already trusts the server certificate.
+          </small>
+        </label>
+        <button id="submit" type="submit">Run RPCs</button>
+      </form>
+
+      <h2>Output</h2>
+      <pre id="output" aria-live="polite"></pre>
+    </main>
+    <script type="module" src="./client.js"></script>
+  </body>
+</html>

package/examples/greeter/static-server.js

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { extname, join, normalize, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const port = Number.parseInt(process.env.PORT ?? "8080", 10);
+const authToken = "trevrpc-example-token";
+const protobufBundlePath = fileURLToPath(import.meta.resolve("protobufjs/dist/protobuf.min.js"));
+
+const contentTypes = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+  [".json", "application/json; charset=utf-8"],
+  [".md", "text/markdown; charset=utf-8"],
+  [".proto", "text/plain; charset=utf-8"],
+]);
+
+const server = createServer(async (request, response) => {
+  try {
+    const path = requestPath(request.url ?? "/");
+
+    if (path === "/favicon.ico") {
+      response.writeHead(204);
+      response.end();
+      return;
+    }
+
+    if (path === "/examples/greeter/certificate-hash.json") {
+      await writeCertificateHash(response);
+      return;
+    }
+
+    if (path === "/examples/greeter/vendor/protobufjs.js") {
+      writeProtobufModule(response);
+      return;
+    }
+
+    if (path === "/examples/greeter/vendor/protobuf.min.js") {
+      await writeProtobufBundle(response);
+      return;
+    }
+
+    const file = path.endsWith("/") ? join(path, "index.html") : path;
+    await writeStaticFile(response, safePath(file));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      notFound(response);
+      return;
+    }
+
+    response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+    response.end(error?.message ?? String(error));
+  }
+});
+
+server.listen(port, "127.0.0.1", () => {
+  console.log(`serving trevrpc-js from http://127.0.0.1:${port}/examples/greeter/`);
+});
+
+function requestPath(url) {
+  return decodeURIComponent(new URL(url, "http://127.0.0.1").pathname);
+}
+
+async function writeStaticFile(response, absolute) {
+  const info = await stat(absolute);
+
+  if (!info.isFile()) {
+    notFound(response);
+    return;
+  }
+
+  response.writeHead(200, {
+    "content-type": contentTypes.get(extname(absolute)) ?? "application/octet-stream",
+  });
+  createReadStream(absolute).pipe(response);
+}
+
+function safePath(path) {
+  const absolute = normalize(join(root, path));
+  if (absolute !== root && !absolute.startsWith(`${root}${sep}`)) {
+    throw new Error("path escapes example root");
+  }
+
+  return absolute;
+}
+
+async function writeCertificateHash(response) {
+  const path = certificatePath();
+
+  try {
+    const certificate = await readFile(path);
+    const der = certificateDer(certificate);
+    const hash = createHash("sha256").update(der).digest();
+
+    response.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    response.end(
+      JSON.stringify({
+        exists: true,
+        path,
+        bearerToken: authToken,
+        sha256Base64: hash.toString("base64"),
+        sha256Hex: hash.toString("hex"),
+      }),
+    );
+  } catch (error) {
+    response.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    response.end(
+      JSON.stringify({
+        exists: false,
+        path,
+        bearerToken: authToken,
+        error: error?.message ?? String(error),
+      }),
+    );
+  }
+}
+
+function writeProtobufModule(response) {
+  response.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
+  response.end(`await new Promise((resolve, reject) => {
+  if (globalThis.protobuf != null) {
+    resolve();
+    return;
+  }
+
+  const script = document.createElement("script");
+  script.src = new URL("./protobuf.min.js", import.meta.url).href;
+  script.onload = resolve;
+  script.onerror = () => reject(new Error("failed to load protobuf.js browser bundle"));
+  document.head.append(script);
+});
+
+export default globalThis.protobuf;
+export const protobuf = globalThis.protobuf;
+`);
+}
+
+async function writeProtobufBundle(response) {
+  await writeStaticFile(response, protobufBundlePath);
+}
+
+function certificatePath() {
+  return (
+    process.env.TREVRPC_EXAMPLE_CERT ??
+    join(homedir(), ".config", "trevrpc", "trevrpc-example-cert.pem")
+  );
+}
+
+function certificateDer(certificate) {
+  const text = certificate.toString("utf8");
+  const match = /-----BEGIN CERTIFICATE-----([A-Za-z0-9+/=\s]+)-----END CERTIFICATE-----/.exec(
+    text,
+  );
+  if (match == null) {
+    return certificate;
+  }
+
+  return Buffer.from(match[1].replace(/\s/g, ""), "base64");
+}
+
+function notFound(response) {
+  response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+  response.end("not found");
+}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@trevrpc/trevrpc-js",
+  "version": "0.1.0",
+  "description": "JavaScript WebTransport runtime and protobuf.js code generator for TrevRPC",
+  "homepage": "https://trev.zip/llc/TrevRPC",
+  "bugs": {
+    "url": "https://trev.zip/llc/TrevRPC/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://trev.zip/llc/TrevRPC.git"
+  },
+  "bin": {
+    "protoc-gen-trevrpc-js": "bin/protoc-gen-trevrpc-js.js"
+  },
+  "files": [
+    "src/**",
+    "bin/protoc-gen-trevrpc-js.js",
+    "examples/greeter/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "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",
+    "provenance": true
+  },
+  "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",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint --deny-warnings",
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "esbuild": "^0.28.1",
+    "playwright": "^1.62.1",
+    "typescript": "^7.0.2"
+  },
+  "optionalDependencies": {
+    "@trevrpc/trevrpc-js-native-linux-x64-gnu": "0.1.0"
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "packageManager": "npm@11.19.0"
+}

package/src/advanced.d.ts

@@ -0,0 +1,29 @@
+import type {
+  ResolvedCallOptions,
+  RpcRequestMessage,
+  RpcResponseMessage,
+  RpcStreamFrameMessage,
+  Transport,
+  WebTransportBidirectionalStreamLike,
+  WebTransportCloseInfoLike,
+  WebTransportOptions,
+  WebTransportSessionLike,
+} from "./index.js";
+
+/** Raw single-session TrevRPC transport for browser WebTransport. */
+export class RawWebTransport implements Transport {
+  session: WebTransportSessionLike;
+  maxFrameSize: number;
+
+  constructor(session: WebTransportSessionLike, options?: WebTransportOptions);
+  static connect(url: string | URL, options?: WebTransportOptions): Promise<RawWebTransport>;
+  ready(): Promise<void>;
+  close(closeInfo?: WebTransportCloseInfoLike): void;
+  call(request: RpcRequestMessage, options?: ResolvedCallOptions): Promise<RpcResponseMessage>;
+  streamingCall(
+    request: RpcRequestMessage,
+    requestBody: AsyncIterable<Uint8Array>,
+    options?: ResolvedCallOptions,
+  ): Promise<AsyncIterableIterator<RpcStreamFrameMessage>>;
+  openBidirectionalStream(): Promise<WebTransportBidirectionalStreamLike>;
+}

package/src/advanced.js

@@ -0,0 +1 @@
+export { RawWebTransport } from "./webtransport.js";

package/src/browser-channel.js

@@ -0,0 +1,45 @@
+import { ChannelStateMachine, stripChannelOptions, waitForInitialReady } from "./channel.js";
+import { unavailable } from "./status.js";
+import { RawWebTransport, createWebTransportSession } from "./webtransport.js";
+
+/** Browser channel with background session reconnection. */
+export class Channel extends ChannelStateMachine {
+  constructor(url, options = {}) {
+    const retainedUrl = url instanceof URL ? url.href : url;
+    const retainedOptions = Object.freeze({ ...options });
+    const transportOptions = stripChannelOptions(retainedOptions);
+    super(
+      (signal) => connectWebTransport(retainedUrl, transportOptions, signal),
+      retainedOptions,
+      (transport) => transport.session.closed,
+    );
+    this.url = retainedUrl;
+    this.options = retainedOptions;
+  }
+
+  /** Creates a channel and waits for its first ready generation. */
+  static async connect(url, options = {}) {
+    const channel = new Channel(url, options);
+    await waitForInitialReady(channel, options);
+    return channel;
+  }
+}
+
+async function connectWebTransport(url, options, signal) {
+  const session = createWebTransportSession(url, options);
+  const onAbort = () => session.close?.();
+  signal.addEventListener("abort", onAbort, { once: true });
+
+  try {
+    await session.ready;
+    if (signal.aborted) {
+      throw unavailable("channel is closed");
+    }
+    return new RawWebTransport(session, options);
+  } catch (error) {
+    session.close?.();
+    throw error;
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}