@zap-proto/web 0.1.0

package/src/client.ts

@@ -0,0 +1,165 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+/**
+ * client.ts — connect(url, opts): open a ZAP-over-WebSocket RPC connection from
+ * the browser (or Node, for tests) and return the bootstrap call surface.
+ *
+ * The transport is isomorphic: in the browser this uses the native WebSocket
+ * global; in Node you inject the `ws` package's WebSocket via
+ * {@link ConnectOptions.WebSocketImpl} (Node 22+ also has a built-in global
+ * WebSocket, but it cannot set request headers — see the bearer note below).
+ *
+ * Bearer note: the browser's native WebSocket constructor CANNOT set an
+ * Authorization header — the WS protocol gives JS no header control. So:
+ *   - Node `ws` (tests, SSR): we pass `{ headers: { Authorization } }`, which
+ *     `ws` forwards on the upgrade request, where serve()'s mintCap reads it.
+ *   - browser: rely on a cookie sent automatically on the upgrade, or encode
+ *     the bearer in a subprotocol; the Authorization-header path only applies
+ *     to a header-capable WebSocketImpl. We feature-detect by arity and fall
+ *     back to a query param (`?authorization=Bearer%20...`) the server can read.
+ */
+
+import { Conn } from "./conn.js";
+import { browserWsTransport } from "./transport.js";
+import { WebRpcError } from "./errors.js";
+
+/** Options for {@link connect}. */
+export interface ConnectOptions {
+  /** Bearer token; forwarded as `Authorization: Bearer <bearer>` on upgrade. */
+  bearer?: string;
+  /**
+   * WebSocket constructor to use. Defaults to globalThis.WebSocket (browser /
+   * Node 22+). Inject the `ws` package's WebSocket in Node tests/SSR so the
+   * bearer can ride an Authorization header.
+   */
+  WebSocketImpl?: typeof WebSocket;
+}
+
+/**
+ * The bootstrap call surface returned by {@link connect}. RootCap is the
+ * generated typed wrapper a consumer layers over the raw {@link Conn} call
+ * surface — `connect<MyRootCap>(...)` then exposes typed methods on `bootstrap`.
+ *
+ * On the real @zap-proto/zap foundation the bootstrap is the connection's call
+ * surface (method ordinal + ZAP payload), not a Cap'n Proto capability object.
+ * The default `RootCap = Conn` gives you raw `bootstrap.call(method, { payload })`;
+ * a zapgen-generated client wraps that into named, typed methods.
+ */
+export interface Connection<RootCap = Conn> {
+  bootstrap: RootCap;
+  close(): void;
+}
+
+/**
+ * Open a ZAP RPC WebSocket to `url`, wait for the connection to open, and
+ * return the bootstrap call surface. The default RootCap is the raw {@link Conn}.
+ */
+export async function connect<RootCap = Conn>(
+  url: string,
+  opts: ConnectOptions = {},
+): Promise<Connection<RootCap>> {
+  const Impl = opts.WebSocketImpl ?? (globalThis.WebSocket as typeof WebSocket);
+  if (!Impl) {
+    throw new WebRpcError(
+      "zap-web: no WebSocket implementation (pass opts.WebSocketImpl)",
+    );
+  }
+
+  const ws = openSocket(Impl, url, opts.bearer);
+
+  await new Promise<void>((resolve, reject) => {
+    const onOpen = (): void => {
+      cleanup();
+      resolve();
+    };
+    const onErr = (): void => {
+      cleanup();
+      reject(new WebRpcError(`zap-web: failed to connect to ${url}`));
+    };
+    const onClose = (ev: unknown): void => {
+      cleanup();
+      const code = (ev as CloseEvent | undefined)?.code;
+      reject(
+        new WebRpcError(
+          `zap-web: upgrade rejected by ${url}`,
+          code === 1006 ? 401 : code,
+        ),
+      );
+    };
+    const cleanup = (): void => {
+      remove(ws, "open", onOpen);
+      remove(ws, "error", onErr);
+      remove(ws, "close", onClose);
+    };
+    add(ws, "open", onOpen);
+    add(ws, "error", onErr);
+    add(ws, "close", onClose);
+  });
+
+  const transport = browserWsTransport(ws);
+  const conn = new Conn(transport);
+
+  return {
+    bootstrap: conn as unknown as RootCap,
+    close(): void {
+      conn.close(1000, "client closed");
+    },
+  };
+}
+
+/**
+ * Construct a WebSocket, attaching the bearer the best way the impl allows.
+ * Node `ws` accepts a 3rd `options.headers` arg; the browser native WebSocket
+ * does not, so we fall back to a query param the server can read.
+ */
+function openSocket(
+  Impl: typeof WebSocket,
+  url: string,
+  bearer?: string,
+): WebSocket {
+  if (!bearer) return new Impl(url);
+
+  // Node `ws` WebSocket: third constructor arg is options { headers }.
+  // We detect header support by the constructor's declared arity (>= 3).
+  if ((Impl as unknown as { length: number }).length >= 3) {
+    return new (Impl as unknown as new (
+      u: string,
+      protocols: undefined,
+      options: { headers: Record<string, string> },
+    ) => WebSocket)(url, undefined, {
+      headers: { Authorization: `Bearer ${bearer}` },
+    });
+  }
+
+  // Browser native WebSocket: no header control — encode on the URL instead.
+  const u = new URL(url);
+  u.searchParams.set("authorization", `Bearer ${bearer}`);
+  return new Impl(u.toString());
+}
+
+// --- isomorphic add/remove listener (browser EventTarget vs `ws` emitter) ---
+
+function add(ws: WebSocket, type: string, fn: (ev?: unknown) => void): void {
+  const anyWs = ws as unknown as {
+    addEventListener?: (t: string, f: (ev: unknown) => void) => void;
+    on?: (t: string, f: (...a: unknown[]) => void) => void;
+  };
+  if (typeof anyWs.addEventListener === "function") {
+    anyWs.addEventListener(type, fn);
+  } else if (typeof anyWs.on === "function") {
+    anyWs.on(type, fn);
+  }
+}
+
+function remove(ws: WebSocket, type: string, fn: (ev?: unknown) => void): void {
+  const anyWs = ws as unknown as {
+    removeEventListener?: (t: string, f: (ev: unknown) => void) => void;
+    off?: (t: string, f: (...a: unknown[]) => void) => void;
+  };
+  if (typeof anyWs.removeEventListener === "function") {
+    anyWs.removeEventListener(type, fn);
+  } else if (typeof anyWs.off === "function") {
+    anyWs.off(type, fn);
+  }
+}

package/src/conn.ts

@@ -0,0 +1,172 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+/**
+ * conn.ts — a transport-agnostic ZAP RPC connection over a {@link WsTransport}.
+ *
+ * This is the shared core of both serve() and connect(). It mirrors the
+ * correlation logic of @zap-proto/zap's ZapClient (Node TCP), but rides a duplex
+ * WebSocket transport instead of a TCP socket and works in both directions:
+ *
+ *   - client side: call() ships a request envelope and resolves its Response
+ *     when the matching promiseID comes back.
+ *   - server side: an inbound request envelope is decoded into a Call and
+ *     handed to the registered handler, whose Response is shipped back.
+ *
+ * Each WS binary message is exactly one ZAP envelope (see transport.ts), so the
+ * envelope's own header tag (MSG_TYPE_ROUTER_BASE) distinguishes a request from
+ * a response and there is no extra framing. We disambiguate direction by trying
+ * the request decode first; a frame that parses as a request with a known
+ * method is dispatched as a server call, otherwise it is treated as a response
+ * to one of our outstanding promises.
+ */
+
+import {
+  buildRequest,
+  buildResponse,
+  parseRequest,
+  parseResponse,
+  NO_TARGET,
+  Status,
+  type Call,
+  type Response,
+} from "@zap-proto/zap";
+import type { WsTransport } from "./transport.js";
+import { WebRpcError } from "./errors.js";
+
+/** A server-side request handler: a decoded Call in, a Response out. */
+export type CallHandler = (call: Call) => Promise<Response> | Response;
+
+/** Options for an outbound {@link Conn.call}. */
+export interface CallOptions {
+  /** Pipeline this call off an earlier call's promiseID (0 = root). */
+  target?: number;
+  /** Capability buffer to carry on the call (defaults to the conn's cap). */
+  cap?: Uint8Array;
+  /** Method params, ZAP-encoded. */
+  payload?: Uint8Array;
+}
+
+const EMPTY = new Uint8Array(0);
+
+/**
+ * Conn correlates ZAP request/response envelopes over a single duplex
+ * WebSocket transport. One Conn is FIFO per direction on the wire, matching the
+ * Go node's per-connection dispatch.
+ */
+export class Conn {
+  private readonly pending = new Map<number, (r: Response) => void>();
+  private promiseSeq = 0;
+  private closed = false;
+  private handler: CallHandler | null = null;
+  private readonly cap: Uint8Array;
+
+  constructor(
+    private readonly transport: WsTransport,
+    opts: { handler?: CallHandler; cap?: Uint8Array } = {},
+  ) {
+    this.handler = opts.handler ?? null;
+    this.cap = opts.cap ?? EMPTY;
+    transport.onMessage((bytes) => this.onFrame(bytes));
+    transport.onClose(() => this.fail());
+  }
+
+  /**
+   * Ship one Call and await its correlated Response. The promiseID is assigned
+   * here unless the caller pipelines via {@link CallOptions.target}.
+   */
+  call(method: number, opts: CallOptions = {}): Promise<Response> {
+    if (this.closed) {
+      return Promise.reject(new WebRpcError("zap-web: connection closed"));
+    }
+    this.promiseSeq = (this.promiseSeq + 1) >>> 0 || 1;
+    const promiseID = this.promiseSeq;
+    const c: Call = {
+      method,
+      promiseID,
+      target: opts.target ?? NO_TARGET,
+      cap: opts.cap ?? this.cap,
+      payload: opts.payload ?? EMPTY,
+    };
+    return new Promise<Response>((resolve, reject) => {
+      this.pending.set(promiseID, resolve);
+      try {
+        this.transport.send(buildRequest(c));
+      } catch (err) {
+        this.pending.delete(promiseID);
+        reject(err instanceof Error ? err : new WebRpcError(String(err)));
+      }
+    });
+  }
+
+  /** Close the connection and fail all in-flight calls. */
+  close(code?: number, reason?: string): void {
+    if (this.closed) return;
+    this.transport.close(code, reason);
+    this.fail();
+  }
+
+  private onFrame(bytes: Uint8Array): void {
+    if (this.handler) {
+      // Server side: every inbound frame is a request to dispatch.
+      this.dispatch(bytes);
+      return;
+    }
+    // Client side: every inbound frame is a response to one of our calls.
+    let resp: Response;
+    try {
+      resp = parseResponse(bytes);
+    } catch {
+      return; // malformed frame from peer — drop it.
+    }
+    const resolve = this.pending.get(resp.promiseID);
+    if (!resolve) return;
+    this.pending.delete(resp.promiseID);
+    resolve(resp);
+  }
+
+  private async dispatch(bytes: Uint8Array): Promise<void> {
+    let call: Call;
+    try {
+      call = parseRequest(bytes);
+    } catch {
+      return; // unparseable request — drop it.
+    }
+    const handler = this.handler;
+    if (!handler) return;
+    let resp: Response;
+    try {
+      resp = await handler(call);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "internal handler error";
+      resp = {
+        status: Status.Internal,
+        promiseID: call.promiseID,
+        body: new TextEncoder().encode(JSON.stringify({ error: msg })),
+      };
+    }
+    if (this.closed) return;
+    try {
+      this.transport.send(
+        buildResponse(resp.status, call.promiseID, resp.body),
+      );
+    } catch {
+      // peer went away mid-response — nothing to do.
+    }
+  }
+
+  private fail(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const [, resolve] of this.pending) {
+      resolve({
+        status: 0,
+        promiseID: 0,
+        body: new TextEncoder().encode(
+          JSON.stringify({ error: "connection closed" }),
+        ),
+      });
+    }
+    this.pending.clear();
+  }
+}

package/src/errors.ts

@@ -0,0 +1,30 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+/**
+ * errors.ts — error surface for the web RPC layer.
+ *
+ * Method/wire-level decode failures keep using @zap-proto/zap's ZapParseError (the
+ * runtime throws it on a bad magic/version/size); we re-export it so consumers
+ * have one import site. WebRpcError is new: it covers transport-level failures
+ * that only exist at the WebSocket boundary — a rejected upgrade, a socket that
+ * closes mid-call, or a non-OK RPC status surfaced to the caller.
+ */
+
+export { ZapParseError } from "@zap-proto/zap";
+
+/**
+ * WebRpcError is raised for WebSocket-transport-level failures: the upgrade was
+ * rejected (401/other), the socket closed while a call was in flight, or a
+ * call returned a non-OK ZAP status. `status` carries the ZAP/HTTP status when
+ * one is known (e.g. 401 for a rejected mint, or the response envelope status).
+ */
+export class WebRpcError extends Error {
+  readonly status?: number;
+
+  constructor(message: string, status?: number) {
+    super(message);
+    this.name = "WebRpcError";
+    this.status = status;
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+/**
+ * @zap-proto/web — browser-frontend RPC over ZAP.
+ *
+ * A drop-in tRPC replacement that speaks native ZAP envelopes over WebSocket
+ * binary frames instead of JSON-over-HTTP. Layered on @zap-proto/zap (the wire
+ * runtime). Service shape comes from .zap schemas via `zapgen --target=ts`, not
+ * a Zod/procedure DSL. Binary only — no JSON fallback, no Cap'n Proto.
+ *
+ *   - serve(httpServer, opts)   — Node: attach a ZAP RPC endpoint to http.Server.
+ *   - connect(url, opts)        — browser/Node: open a typed RPC connection.
+ *   - {node,browser}WsTransport — isomorphic WS transport factories.
+ *   - MintCap                   — the bearer→ctx auth slot at the upgrade.
+ */
+
+export { serve } from "./server.js";
+export type { ServeOptions, ServeHandle, RootCap } from "./server.js";
+
+export { connect } from "./client.js";
+export type { ConnectOptions, Connection } from "./client.js";
+
+export {
+  nodeWsTransport,
+  browserWsTransport,
+  WS_CLOSE_UNSUPPORTED,
+} from "./transport.js";
+export type { WsTransport } from "./transport.js";
+
+export { Conn } from "./conn.js";
+export type { CallHandler, CallOptions } from "./conn.js";
+
+export type { MintCap } from "./auth.js";
+
+export { WebRpcError, ZapParseError } from "./errors.js";

package/src/server.ts

@@ -0,0 +1,146 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+/**
+ * server.ts — serve(httpServer, opts): attach a ZAP-over-WebSocket RPC endpoint
+ * to an existing Node http.Server.
+ *
+ * Sharing one http.Server is the integration seam: Next.js's
+ * `app.getRequestHandler()` and a Remix Node server both run on a plain
+ * http.Server, so a single `serve(server, ...)` line adds ZAP RPC alongside the
+ * app without a second port. (Same shape as the WebSocket attachments in
+ * hanzo/platform's app/platform/server/server.ts.)
+ *
+ * Auth runs at the upgrade boundary: mintCap(req) is awaited BEFORE the
+ * handshake completes. A null mint writes HTTP 401 and destroys the socket — no
+ * WebSocket is ever opened for an unauthorized request. A non-null mint becomes
+ * the per-connection `ctx`, and rootCap(ctx) yields the CallHandler that
+ * dispatches every decoded ZAP Call on that connection.
+ *
+ * `ws` is a peer dependency (server side only); we import it lazily so the
+ * browser bundle never pulls it in.
+ */
+
+import { createRequire } from "node:module";
+import type { IncomingMessage, Server as HttpServer } from "node:http";
+import type { Socket } from "node:net";
+import type { CallHandler } from "./conn.js";
+import { Conn } from "./conn.js";
+import { nodeWsTransport } from "./transport.js";
+import type { MintCap } from "./auth.js";
+
+/**
+ * rootCap produces the per-connection dispatch root for a minted ctx.
+ *
+ * On the real @zap-proto/zap foundation a "service" is a dispatcher over decoded
+ * Calls (method ordinal + payload), not a Cap'n Proto Server object — so the
+ * bootstrap capability is modelled here as a {@link CallHandler}. Generated
+ * zapgen bindings give you the typed param/result views to decode the payload
+ * and encode the response body inside that handler.
+ */
+export type RootCap<Ctx> = (ctx: Ctx) => CallHandler;
+
+/** Options for {@link serve}. */
+export interface ServeOptions<Ctx> {
+  /** Upgrade path this endpoint binds to (default "/zap"). */
+  path?: string;
+  /** Bearer→ctx boundary; return null to reject the upgrade with HTTP 401. */
+  mintCap: MintCap<Ctx>;
+  /** Produce the bootstrap dispatch handler for the minted ctx. */
+  rootCap: RootCap<Ctx>;
+  /** Optional sink for connection/dispatch errors. */
+  onError?: (err: unknown) => void;
+}
+
+/** A live ZAP-over-WebSocket endpoint attached to an http.Server. */
+export interface ServeHandle {
+  /** Close the endpoint and every live connection. */
+  close(): Promise<void>;
+}
+
+/**
+ * Attach a ZAP RPC endpoint to `httpServer`. Returns a handle whose close()
+ * tears down the WebSocket server and all open connections.
+ */
+export function serve<Ctx>(
+  httpServer: HttpServer,
+  opts: ServeOptions<Ctx>,
+): ServeHandle {
+  const path = opts.path ?? "/zap";
+  const onError = opts.onError ?? (() => {});
+
+  // Lazy require so browser bundles never resolve `ws`. createRequire keeps
+  // this ESM-safe (no top-level `require`) and server-only (node:module never
+  // ends up in a browser bundle, since serve() is the Node entry).
+  const req = createRequire(import.meta.url);
+  const { WebSocketServer } = req("ws") as typeof import("ws");
+  const wss = new WebSocketServer({ noServer: true });
+  const conns = new Set<Conn>();
+
+  const onUpgrade = (
+    req: IncomingMessage,
+    socket: Socket,
+    head: Buffer,
+  ): void => {
+    let url: URL;
+    try {
+      url = new URL(req.url ?? "/", "http://localhost");
+    } catch {
+      return; // not ours; let other upgrade listeners handle it.
+    }
+    if (url.pathname !== path) return; // path mismatch — not our endpoint.
+
+    void (async () => {
+      let ctx: Ctx | null;
+      try {
+        ctx = await opts.mintCap(req);
+      } catch (err) {
+        onError(err);
+        reject(socket, 500, "Internal Server Error");
+        return;
+      }
+      if (ctx === null) {
+        reject(socket, 401, "Unauthorized");
+        return;
+      }
+      const minted = ctx;
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        const transport = nodeWsTransport(ws);
+        let handler: CallHandler;
+        try {
+          handler = opts.rootCap(minted);
+        } catch (err) {
+          onError(err);
+          transport.close(1011, "rootCap failed");
+          return;
+        }
+        const conn = new Conn(transport, { handler });
+        conns.add(conn);
+        transport.onClose(() => conns.delete(conn));
+        ws.on("error", onError);
+      });
+    })();
+  };
+
+  httpServer.on("upgrade", onUpgrade);
+
+  return {
+    async close(): Promise<void> {
+      httpServer.removeListener("upgrade", onUpgrade);
+      for (const conn of conns) conn.close(1001, "server shutting down");
+      conns.clear();
+      await new Promise<void>((resolve) => wss.close(() => resolve()));
+    },
+  };
+}
+
+/** Write a bare HTTP error response on the raw upgrade socket and destroy it. */
+function reject(socket: Socket, code: number, text: string): void {
+  socket.write(
+    `HTTP/1.1 ${code} ${text}\r\n` +
+      "Connection: close\r\n" +
+      "Content-Length: 0\r\n" +
+      "\r\n",
+  );
+  socket.destroy();
+}