@zap-proto/web 0.1.1 → 0.2.0

package/dist/http.d.ts

@@ -0,0 +1,75 @@
+/**
+ * http.ts — httpServe(httpServer, opts): mount a JSON-over-HTTP face on the
+ * SAME ZAP service that serve() exposes over WebSocket.
+ *
+ * Motivation: external consumers (and the OpenAPI surface emitted by
+ * `zapgen --emit=openapi`) speak POST /<service>/<method> with a JSON body.
+ * httpServe terminates that HTTP shape and dispatches each request through the
+ * identical {@link CallHandler} the WebSocket transport uses — so there is ONE
+ * service implementation, reached two ways.
+ *
+ * The JSON⇄ZAP codec is schema-specific and therefore supplied by the caller as
+ * a {@link HttpRoute} per method (the generated zapgen bindings know each
+ * struct's shape; the runtime stays schema-agnostic — orthogonal separation).
+ * Each route declares:
+ *   - path:    POST path, matching the OpenAPI doc (`/document-service/...`).
+ *   - method:  the .zap method ordinal (the same ordinal the WS client sends).
+ *   - decode:  JSON request body  → ZAP payload bytes.
+ *   - encode:  ZAP response body bytes → JSON value (omit for void methods).
+ *
+ * Auth runs per-request via the same {@link MintCap} slot serve() uses: a null
+ * mint yields HTTP 401; a non-null mint becomes the `ctx` passed to rootCap,
+ * whose {@link CallHandler} dispatches the decoded Call.
+ *
+ * Node `http` only — no framework. The HTTP server is supplied by the caller
+ * (the same http.Server that serve() attaches its WebSocket upgrade to), so one
+ * port serves WS + HTTP.
+ */
+import type { Server as HttpServer } from "node:http";
+import type { MintCap } from "./auth.js";
+import type { RootCap } from "./server.js";
+/**
+ * HttpRoute binds one POST path to one ZAP method, with the JSON⇄ZAP codec for
+ * that method. `decode` turns the parsed JSON request body into the method's
+ * ZAP payload bytes; `encode` turns the ZAP response body bytes into the JSON
+ * value to serialize. A void method omits `encode` (returns HTTP 204).
+ */
+export interface HttpRoute {
+    /** POST path, e.g. "/document-service/create-document". */
+    path: string;
+    /** The .zap method ordinal this path dispatches. */
+    method: number;
+    /** Parse a JSON request body into ZAP payload bytes. */
+    decode: (json: unknown) => Uint8Array;
+    /** Encode ZAP response body bytes into a JSON value. Omit for void methods. */
+    encode?: (body: Uint8Array) => unknown;
+}
+/** Options for {@link httpServe}. */
+export interface HttpServeOptions<Ctx> {
+    /** The method routes (one per OpenAPI operation). */
+    routes: HttpRoute[];
+    /** Bearer→ctx boundary; return null to reject with HTTP 401. */
+    mintCap: MintCap<Ctx>;
+    /** Produce the dispatch handler for a minted ctx (same shape as serve()). */
+    rootCap: RootCap<Ctx>;
+    /**
+     * Optional path prefix mounted before each route path, e.g. "/v1" makes the
+     * route "/echo/echo" serve at "/v1/echo/echo". Default "" (no prefix).
+     */
+    prefix?: string;
+    /** Optional sink for handler errors. */
+    onError?: (err: unknown) => void;
+}
+/** A live HTTP face attached to an http.Server. */
+export interface HttpServeHandle {
+    /** Detach the request listener. */
+    close(): void;
+}
+/**
+ * Attach a JSON-over-HTTP face to `httpServer`. Returns a handle whose close()
+ * detaches the listener. Non-matching requests are passed through untouched so
+ * httpServe can coexist with the app's own request handler and with serve()'s
+ * WebSocket upgrade on the same server.
+ */
+export declare function httpServe<Ctx>(httpServer: HttpServer, opts: HttpServeOptions<Ctx>): HttpServeHandle;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAGV,MAAM,IAAI,UAAU,EACrB,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAK3C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,UAAU,CAAC;IACtC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC;CACxC;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB,CAAC,GAAG;IACnC,qDAAqD;IACrD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAC3B,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAC1B,eAAe,CA8DjB"}

package/dist/http.js

@@ -0,0 +1,216 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+import { NO_TARGET, Status } from "@zap-proto/zap";
+const EMPTY = new Uint8Array(0);
+const MAX_BODY_BYTES = 8 * 1024 * 1024; // 8 MiB request-body ceiling.
+/**
+ * Attach a JSON-over-HTTP face to `httpServer`. Returns a handle whose close()
+ * detaches the listener. Non-matching requests are passed through untouched so
+ * httpServe can coexist with the app's own request handler and with serve()'s
+ * WebSocket upgrade on the same server.
+ */
+export function httpServe(httpServer, opts) {
+    const onError = opts.onError ?? (() => { });
+    const prefix = normalizePrefix(opts.prefix ?? "");
+    // path → route, built once. Promise ordinal collisions are the caller's
+    // concern (each method has a distinct path by construction).
+    const table = new Map();
+    for (const r of opts.routes)
+        table.set(prefix + r.path, r);
+    const appListeners = httpServer.listeners("request");
+    httpServer.removeAllListeners("request");
+    const delegate = (req, res) => {
+        if (appListeners.length === 0) {
+            if (!res.writableEnded) {
+                writeJson(res, 404, { error: "not found" });
+            }
+            return;
+        }
+        for (const l of appListeners)
+            l(req, res);
+    };
+    const onRequest = (req, res) => {
+        let url;
+        try {
+            url = new URL(req.url ?? "/", "http://localhost");
+        }
+        catch {
+            delegate(req, res);
+            return;
+        }
+        const route = table.get(url.pathname);
+        if (!route) {
+            delegate(req, res); // not ours — hand to the app's own handler.
+            return;
+        }
+        if (req.method !== "POST") {
+            writeJson(res, 405, { error: "method not allowed; use POST" });
+            return;
+        }
+        void handle(req, res, route, opts, onError).catch((err) => {
+            onError(err);
+            if (!res.headersSent)
+                writeJson(res, 500, { error: "internal error" });
+        });
+    };
+    httpServer.on("request", onRequest);
+    return {
+        close() {
+            httpServer.removeListener("request", onRequest);
+            // Restore the app's original listeners.
+            for (const l of appListeners)
+                httpServer.on("request", l);
+        },
+    };
+}
+/** handle runs one matched POST through mint → decode → dispatch → encode. */
+async function handle(req, res, route, opts, onError) {
+    // Auth boundary — identical slot to serve()'s upgrade mint.
+    let ctx;
+    try {
+        ctx = await opts.mintCap(req);
+    }
+    catch (err) {
+        onError(err);
+        writeJson(res, 500, { error: "auth error" });
+        return;
+    }
+    if (ctx === null) {
+        writeJson(res, 401, { error: "unauthorized" });
+        return;
+    }
+    // Read + parse the JSON request body.
+    let json;
+    try {
+        const raw = await readBody(req);
+        json = raw.length === 0 ? {} : JSON.parse(raw);
+    }
+    catch {
+        writeJson(res, 400, { error: "invalid JSON request body" });
+        return;
+    }
+    // JSON → ZAP payload bytes (schema-specific codec from the route).
+    let payload;
+    try {
+        payload = route.decode(json);
+    }
+    catch (err) {
+        writeJson(res, 400, {
+            error: err instanceof Error ? err.message : "request decode failed",
+        });
+        return;
+    }
+    // Build the Call and dispatch it through the SAME handler the WS path uses.
+    let handler;
+    try {
+        handler = opts.rootCap(ctx);
+    }
+    catch (err) {
+        onError(err);
+        writeJson(res, 500, { error: "rootCap failed" });
+        return;
+    }
+    const call = {
+        method: route.method,
+        promiseID: 1,
+        target: NO_TARGET,
+        cap: EMPTY,
+        payload,
+    };
+    let resp;
+    try {
+        resp = await handler(call);
+    }
+    catch (err) {
+        onError(err);
+        writeJson(res, 500, { error: "handler error" });
+        return;
+    }
+    if (resp.status !== Status.OK) {
+        writeJson(res, httpStatusFor(resp.status), {
+            error: errorBodyText(resp.body) ?? `status ${resp.status}`,
+        });
+        return;
+    }
+    // Void method: 204, no body.
+    if (!route.encode) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    // ZAP response body → JSON value.
+    let out;
+    try {
+        out = route.encode(resp.body);
+    }
+    catch (err) {
+        onError(err);
+        writeJson(res, 500, { error: "response encode failed" });
+        return;
+    }
+    writeJson(res, 200, out);
+}
+/** readBody collects the request body as a UTF-8 string, capped at the ceiling. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+/** writeJson sends a JSON response with the given HTTP status. */
+function writeJson(res, status, value) {
+    const body = Buffer.from(JSON.stringify(value), "utf8");
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "content-length": String(body.byteLength),
+    });
+    res.end(body);
+}
+/** Map a ZAP Status to the closest HTTP status (they share the 4xx/5xx space). */
+function httpStatusFor(zapStatus) {
+    switch (zapStatus) {
+        case Status.BadRequest:
+        case Status.Unauthorized:
+        case Status.Forbidden:
+        case Status.NotFound:
+        case Status.Internal:
+            return zapStatus;
+        default:
+            return zapStatus >= 400 && zapStatus <= 599 ? zapStatus : 500;
+    }
+}
+/** errorBodyText extracts {"error": "..."} text from a ZAP error body, if any. */
+function errorBodyText(body) {
+    if (body.byteLength === 0)
+        return null;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(body));
+        if (parsed && typeof parsed.error === "string")
+            return parsed.error;
+    }
+    catch {
+        // not JSON — fall through.
+    }
+    return null;
+}
+/** normalizePrefix trims a trailing slash and ensures a leading slash (or ""). */
+function normalizePrefix(prefix) {
+    if (prefix === "" || prefix === "/")
+        return "";
+    let p = prefix.startsWith("/") ? prefix : "/" + prefix;
+    if (p.endsWith("/"))
+        p = p.slice(0, -1);
+    return p;
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -3,6 +3,8 @@ import type { CallHandler } from "./conn.js";
 import type { MintCap } from "./auth.js";
 export { nodeWsTransport } from "./transport.js";
 export type { MintCap } from "./auth.js";
+export { httpServe } from "./http.js";
+export type { HttpRoute, HttpServeOptions, HttpServeHandle, } from "./http.js";
 /**
  * rootCap produces the per-connection dispatch root for a minted ctx.
  *

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAmB,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,WAAW,CAAC;AAErD,iCAAiC;AACjC,MAAM,WAAW,YAAY,CAAC,GAAG;IAC/B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,oDAAoD;IACpD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,EACvB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,GACtB,WAAW,CAmEb"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAmB,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,WAAW,CAAC;AAErD,iCAAiC;AACjC,MAAM,WAAW,YAAY,CAAC,GAAG;IAC/B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,oDAAoD;IACpD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,EACvB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,GACtB,WAAW,CAmEb"}

package/dist/server.js

@@ -26,6 +26,11 @@ import { nodeWsTransport } from "./transport.js";
 // server-side transport factory and the auth slot so consumers import the whole
 // server API from one sub-path (the root entry is browser-safe and omits these).
 export { nodeWsTransport } from "./transport.js";
+// httpServe mounts a JSON-over-HTTP face on the SAME ZAP service, dispatching
+// each POST /<service>/<method> through the identical CallHandler serve() uses
+// over WebSocket. The OpenAPI doc emitted by `zapgen --emit=openapi` describes
+// exactly these routes.
+export { httpServe } from "./http.js";
 /**
  * Attach a ZAP RPC endpoint to `httpServer`. Returns a handle whose close()
  * tears down the WebSocket server and all open connections.

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zap-proto/web",
-  "version": "0.1.1",
-  "description": "Browser frontend RPC over ZAP — a drop-in tRPC replacement for Next.js / Remix / SvelteKit. Native ZAP envelopes over WebSocket binary frames; layered on @zap-proto/zap. No Cap'n Proto, no JSON.",
+  "version": "0.2.0",
+  "description": "Browser frontend RPC over ZAP — a drop-in tRPC replacement for Next.js / Remix / SvelteKit. Native ZAP envelopes over WebSocket binary frames, plus an optional JSON-over-HTTP face (httpServe) for the OpenAPI 3.1 surface emitted by zapgen. Layered on @zap-proto/zap. No Cap'n Proto.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -40,7 +40,7 @@
     "src"
   ],
   "dependencies": {
-    "@zap-proto/zap": "^1.2.0"
+    "@zap-proto/zap": "^1.3.0"
   },
   "peerDependencies": {
     "ws": ">=8"
@@ -53,6 +53,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.12",
+    "ajv": "^8.20.0",
     "eslint": "^9.0.0",
     "happy-dom": "^20.10.4",
     "prettier": "^3.3.0",

package/src/http.ts

@@ -0,0 +1,315 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+/**
+ * http.ts — httpServe(httpServer, opts): mount a JSON-over-HTTP face on the
+ * SAME ZAP service that serve() exposes over WebSocket.
+ *
+ * Motivation: external consumers (and the OpenAPI surface emitted by
+ * `zapgen --emit=openapi`) speak POST /<service>/<method> with a JSON body.
+ * httpServe terminates that HTTP shape and dispatches each request through the
+ * identical {@link CallHandler} the WebSocket transport uses — so there is ONE
+ * service implementation, reached two ways.
+ *
+ * The JSON⇄ZAP codec is schema-specific and therefore supplied by the caller as
+ * a {@link HttpRoute} per method (the generated zapgen bindings know each
+ * struct's shape; the runtime stays schema-agnostic — orthogonal separation).
+ * Each route declares:
+ *   - path:    POST path, matching the OpenAPI doc (`/document-service/...`).
+ *   - method:  the .zap method ordinal (the same ordinal the WS client sends).
+ *   - decode:  JSON request body  → ZAP payload bytes.
+ *   - encode:  ZAP response body bytes → JSON value (omit for void methods).
+ *
+ * Auth runs per-request via the same {@link MintCap} slot serve() uses: a null
+ * mint yields HTTP 401; a non-null mint becomes the `ctx` passed to rootCap,
+ * whose {@link CallHandler} dispatches the decoded Call.
+ *
+ * Node `http` only — no framework. The HTTP server is supplied by the caller
+ * (the same http.Server that serve() attaches its WebSocket upgrade to), so one
+ * port serves WS + HTTP.
+ */
+
+import type {
+  IncomingMessage,
+  ServerResponse,
+  Server as HttpServer,
+} from "node:http";
+import { NO_TARGET, Status, type Call, type Response } from "@zap-proto/zap";
+import type { CallHandler } from "./conn.js";
+import type { MintCap } from "./auth.js";
+import type { RootCap } from "./server.js";
+
+const EMPTY = new Uint8Array(0);
+const MAX_BODY_BYTES = 8 * 1024 * 1024; // 8 MiB request-body ceiling.
+
+/**
+ * HttpRoute binds one POST path to one ZAP method, with the JSON⇄ZAP codec for
+ * that method. `decode` turns the parsed JSON request body into the method's
+ * ZAP payload bytes; `encode` turns the ZAP response body bytes into the JSON
+ * value to serialize. A void method omits `encode` (returns HTTP 204).
+ */
+export interface HttpRoute {
+  /** POST path, e.g. "/document-service/create-document". */
+  path: string;
+  /** The .zap method ordinal this path dispatches. */
+  method: number;
+  /** Parse a JSON request body into ZAP payload bytes. */
+  decode: (json: unknown) => Uint8Array;
+  /** Encode ZAP response body bytes into a JSON value. Omit for void methods. */
+  encode?: (body: Uint8Array) => unknown;
+}
+
+/** Options for {@link httpServe}. */
+export interface HttpServeOptions<Ctx> {
+  /** The method routes (one per OpenAPI operation). */
+  routes: HttpRoute[];
+  /** Bearer→ctx boundary; return null to reject with HTTP 401. */
+  mintCap: MintCap<Ctx>;
+  /** Produce the dispatch handler for a minted ctx (same shape as serve()). */
+  rootCap: RootCap<Ctx>;
+  /**
+   * Optional path prefix mounted before each route path, e.g. "/v1" makes the
+   * route "/echo/echo" serve at "/v1/echo/echo". Default "" (no prefix).
+   */
+  prefix?: string;
+  /** Optional sink for handler errors. */
+  onError?: (err: unknown) => void;
+}
+
+/** A live HTTP face attached to an http.Server. */
+export interface HttpServeHandle {
+  /** Detach the request listener. */
+  close(): void;
+}
+
+/**
+ * Attach a JSON-over-HTTP face to `httpServer`. Returns a handle whose close()
+ * detaches the listener. Non-matching requests are passed through untouched so
+ * httpServe can coexist with the app's own request handler and with serve()'s
+ * WebSocket upgrade on the same server.
+ */
+export function httpServe<Ctx>(
+  httpServer: HttpServer,
+  opts: HttpServeOptions<Ctx>,
+): HttpServeHandle {
+  const onError = opts.onError ?? (() => {});
+  const prefix = normalizePrefix(opts.prefix ?? "");
+
+  // path → route, built once. Promise ordinal collisions are the caller's
+  // concern (each method has a distinct path by construction).
+  const table = new Map<string, HttpRoute>();
+  for (const r of opts.routes) table.set(prefix + r.path, r);
+
+  // Take over `request` dispatch: capture the app's existing listeners, detach
+  // them, and install a single dispatcher that either handles a matched route
+  // fully (so the response is written exactly once) or delegates to the
+  // captured listeners. Because route handling is async (mintCap, body read),
+  // a plain extra listener would race the app's synchronous catch-all; owning
+  // dispatch is the only way to guarantee a single writer per request.
+  type RequestListener = (req: IncomingMessage, res: ServerResponse) => void;
+  const appListeners = httpServer.listeners("request") as RequestListener[];
+  httpServer.removeAllListeners("request");
+
+  const delegate = (req: IncomingMessage, res: ServerResponse): void => {
+    if (appListeners.length === 0) {
+      if (!res.writableEnded) {
+        writeJson(res, 404, { error: "not found" });
+      }
+      return;
+    }
+    for (const l of appListeners) l(req, res);
+  };
+
+  const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
+    let url: URL;
+    try {
+      url = new URL(req.url ?? "/", "http://localhost");
+    } catch {
+      delegate(req, res);
+      return;
+    }
+    const route = table.get(url.pathname);
+    if (!route) {
+      delegate(req, res); // not ours — hand to the app's own handler.
+      return;
+    }
+
+    if (req.method !== "POST") {
+      writeJson(res, 405, { error: "method not allowed; use POST" });
+      return;
+    }
+
+    void handle(req, res, route, opts, onError).catch((err) => {
+      onError(err);
+      if (!res.headersSent) writeJson(res, 500, { error: "internal error" });
+    });
+  };
+
+  httpServer.on("request", onRequest);
+  return {
+    close(): void {
+      httpServer.removeListener("request", onRequest);
+      // Restore the app's original listeners.
+      for (const l of appListeners) httpServer.on("request", l);
+    },
+  };
+}
+
+/** handle runs one matched POST through mint → decode → dispatch → encode. */
+async function handle<Ctx>(
+  req: IncomingMessage,
+  res: ServerResponse,
+  route: HttpRoute,
+  opts: HttpServeOptions<Ctx>,
+  onError: (err: unknown) => void,
+): Promise<void> {
+  // Auth boundary — identical slot to serve()'s upgrade mint.
+  let ctx: Ctx | null;
+  try {
+    ctx = await opts.mintCap(req);
+  } catch (err) {
+    onError(err);
+    writeJson(res, 500, { error: "auth error" });
+    return;
+  }
+  if (ctx === null) {
+    writeJson(res, 401, { error: "unauthorized" });
+    return;
+  }
+
+  // Read + parse the JSON request body.
+  let json: unknown;
+  try {
+    const raw = await readBody(req);
+    json = raw.length === 0 ? {} : JSON.parse(raw);
+  } catch {
+    writeJson(res, 400, { error: "invalid JSON request body" });
+    return;
+  }
+
+  // JSON → ZAP payload bytes (schema-specific codec from the route).
+  let payload: Uint8Array;
+  try {
+    payload = route.decode(json);
+  } catch (err) {
+    writeJson(res, 400, {
+      error: err instanceof Error ? err.message : "request decode failed",
+    });
+    return;
+  }
+
+  // Build the Call and dispatch it through the SAME handler the WS path uses.
+  let handler: CallHandler;
+  try {
+    handler = opts.rootCap(ctx);
+  } catch (err) {
+    onError(err);
+    writeJson(res, 500, { error: "rootCap failed" });
+    return;
+  }
+
+  const call: Call = {
+    method: route.method,
+    promiseID: 1,
+    target: NO_TARGET,
+    cap: EMPTY,
+    payload,
+  };
+
+  let resp: Response;
+  try {
+    resp = await handler(call);
+  } catch (err) {
+    onError(err);
+    writeJson(res, 500, { error: "handler error" });
+    return;
+  }
+
+  if (resp.status !== Status.OK) {
+    writeJson(res, httpStatusFor(resp.status), {
+      error: errorBodyText(resp.body) ?? `status ${resp.status}`,
+    });
+    return;
+  }
+
+  // Void method: 204, no body.
+  if (!route.encode) {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  // ZAP response body → JSON value.
+  let out: unknown;
+  try {
+    out = route.encode(resp.body);
+  } catch (err) {
+    onError(err);
+    writeJson(res, 500, { error: "response encode failed" });
+    return;
+  }
+  writeJson(res, 200, out);
+}
+
+/** readBody collects the request body as a UTF-8 string, capped at the ceiling. */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    req.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > MAX_BODY_BYTES) {
+        reject(new Error("request body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+/** writeJson sends a JSON response with the given HTTP status. */
+function writeJson(res: ServerResponse, status: number, value: unknown): void {
+  const body = Buffer.from(JSON.stringify(value), "utf8");
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": String(body.byteLength),
+  });
+  res.end(body);
+}
+
+/** Map a ZAP Status to the closest HTTP status (they share the 4xx/5xx space). */
+function httpStatusFor(zapStatus: number): number {
+  switch (zapStatus) {
+    case Status.BadRequest:
+    case Status.Unauthorized:
+    case Status.Forbidden:
+    case Status.NotFound:
+    case Status.Internal:
+      return zapStatus;
+    default:
+      return zapStatus >= 400 && zapStatus <= 599 ? zapStatus : 500;
+  }
+}
+
+/** errorBodyText extracts {"error": "..."} text from a ZAP error body, if any. */
+function errorBodyText(body: Uint8Array): string | null {
+  if (body.byteLength === 0) return null;
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(body));
+    if (parsed && typeof parsed.error === "string") return parsed.error;
+  } catch {
+    // not JSON — fall through.
+  }
+  return null;
+}
+
+/** normalizePrefix trims a trailing slash and ensures a leading slash (or ""). */
+function normalizePrefix(prefix: string): string {
+  if (prefix === "" || prefix === "/") return "";
+  let p = prefix.startsWith("/") ? prefix : "/" + prefix;
+  if (p.endsWith("/")) p = p.slice(0, -1);
+  return p;
+}

package/src/server.ts

@@ -35,6 +35,17 @@ import type { MintCap } from "./auth.js";
 export { nodeWsTransport } from "./transport.js";
 export type { MintCap } from "./auth.js";
 
+// httpServe mounts a JSON-over-HTTP face on the SAME ZAP service, dispatching
+// each POST /<service>/<method> through the identical CallHandler serve() uses
+// over WebSocket. The OpenAPI doc emitted by `zapgen --emit=openapi` describes
+// exactly these routes.
+export { httpServe } from "./http.js";
+export type {
+  HttpRoute,
+  HttpServeOptions,
+  HttpServeHandle,
+} from "./http.js";
+
 /**
  * rootCap produces the per-connection dispatch root for a minted ctx.
  *