@statewalker/webrun-rpc-http 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# @statewalker/webrun-rpc-http
+
+HTTP-based service RPC. Expose plain object methods as a standard
+`(Request) ⇒ Response` handler; call them from anywhere with `fetch`.
+
+## Why it exists
+
+The HTTP primitives in
+[`@statewalker/webrun-http-streams`](../webrun-http-streams) let you write a
+handler that answers `fetch()` — over the wire, in the same tab, inside a
+ServiceWorker, across a MessagePort bridge. What they don't give you is a
+layer above that: a way to take a plain service object and turn its methods
+into addressable endpoints.
+
+`webrun-rpc-http` is that layer. Deliberately small — two factory
+functions plus a handful of types:
+
+- `newRpcServer(services, {path?}) ⇒ (Request) ⇒ Response` — one handler
+  that routes `GET /`, `GET /{service}`, and
+  `GET|POST /{service}/{method}` into object method calls.
+- `newRpcClient({baseUrl, fetch?})` — lazily fetches the service
+  descriptor and returns typed proxies whose method calls round-trip
+  through `fetch`.
+
+Because the server is *just* a `(Request) ⇒ Response` handler and the
+client is *just* `fetch`, the exact same RPC code runs over whatever
+transport you wire it to:
+
+| Transport | How |
+| --- | --- |
+| Real HTTP over the network | Default: `fetch = globalThis.fetch`. |
+| An in-browser ServiceWorker | `@statewalker/webrun-http-browser` — the SW intercepts the standard `fetch` call with no special wiring. |
+| In-process tests | Pass `fetch: (request) => handler(request)` — no network at all. |
+| A MessagePort channel | `@statewalker/webrun-streams-port` for the `Duplex`, then `fetchOverDuplex` / `serveFetchOverDuplex` from `@statewalker/webrun-http-streams`. |
+| A WebSocket | Same, with `@statewalker/webrun-streams-ws` supplying the `Duplex`. |
+| Deno / Cloudflare Workers / Node's built-in HTTP | The handler is `(Request) ⇒ Response` — drop in as-is. |
+
+## How to use
+
+```sh
+npm install @statewalker/webrun-rpc-http
+```
+
+### Exports
+
+| Export | Purpose |
+| --- | --- |
+| `newRpcServer(services, opts?)` | Build a `(Request) ⇒ Response` handler from a map of service objects. Accepts `{ path }` to mount under a URL prefix. |
+| `newRpcClient({baseUrl, fetch?})` | Build a lazy RPC client. Returns `{ loadService<T>(name) }`; the descriptor at `baseUrl/` is fetched once on first call and cached. |
+| `RpcMethod` | `(params: Json, body?: Blob) ⇒ Promise<Blob \| Json>` — the shape every exposed method must satisfy. |
+| `RpcClient` | Shape of the object returned from `newRpcClient`: `{ loadService<T>(name) }`. |
+| `Json` / `JsonObject` | Recursive JSON types — everything that survives a `JSON` round-trip. |
+| `getInstanceMethods(instance)` | Reflect callable properties of `instance` into a `Record<string, Function>`, walking the prototype chain up to (but not including) `Object.prototype`. Used internally by `newRpcServer`; exposed for callers that need it. |
+
+## Examples
+
+### Expose a service
+
+```ts
+import { newRpcServer } from "@statewalker/webrun-rpc-http";
+
+class MathService {
+  async add(params: { a: number; b: number }) {
+    return params.a + params.b;
+  }
+  async bytes(params: { count: number }) {
+    return new Blob([new Uint8Array(params.count).fill(0xff)]);
+  }
+}
+
+const handler = newRpcServer({ math: new MathService() });
+
+// Plug into anything that speaks Request ⇒ Response:
+export default { fetch: handler };        // Deno / Bun / Cloudflare Workers
+// or: Bun.serve({ fetch: handler, port: 8080 });
+// or: http.createServer(/* adapt */)      // Node's built-in http
+```
+
+Out of the box the handler answers:
+
+| Request | Response |
+| --- | --- |
+| `GET /` | `{ "math": ["add", "bytes"] }` — service descriptor. |
+| `GET /math` | `["add", "bytes"]` — method list. |
+| `POST /math/add` — multipart with `params` JSON | `{ "type": "json", "result": 5 }` |
+| `GET /math/add?a=2&b=3` | `{ "type": "json", "result": "23" }` — URL params are parsed into `params`, but as **strings**, so `add` concatenates. POST JSON when the argument type matters. |
+| `POST /math/bytes` — Blob result | `application/octet-stream` body. |
+
+### Call a service
+
+```ts
+import { newRpcClient } from "@statewalker/webrun-rpc-http";
+
+const client = newRpcClient({ baseUrl: "https://api.example.com/rpc" });
+const math = await client.loadService<MathService>("math");
+
+await math.add({ a: 2, b: 3 });             // 5
+const blob = (await math.bytes({ count: 16 })) as Blob;
+```
+
+The descriptor at `baseUrl/` is fetched once, on the first `loadService`
+call, and cached for every subsequent call on the same client instance.
+Method proxies are lazy — they build one `POST` per invocation, no
+persistent connection held open.
+
+### Wire client directly to server (in-process)
+
+Pass any `(Request) ⇒ Promise<Response>` as the `fetch` option. This is
+how you run the client against an in-process server — unit tests,
+webrun-http-browser SWs, a MessagePort bridge, a WebSocket bridge:
+
+```ts
+const handler = newRpcServer({ math: new MathService() });
+const client = newRpcClient({
+  baseUrl: "http://in-process",
+  fetch: (request) => handler(request),
+});
+const math = await client.loadService<MathService>("math");
+await math.add({ a: 1, b: 2 }); // 3 — no network.
+```
+
+### Mount in a browser ServiceWorker
+
+Combine with `@statewalker/webrun-http-browser` to get an in-browser RPC
+server that answers real `fetch()` calls:
+
+```ts
+import { SwHttpAdapter } from "@statewalker/webrun-http-browser/sw";
+import { newRpcServer } from "@statewalker/webrun-rpc-http";
+
+const adapter = new SwHttpAdapter({
+  key: "api",
+  serviceWorkerUrl: new URL("./sw-worker.js", import.meta.url).toString(),
+});
+await adapter.start();
+
+const { baseUrl } = await adapter.register(
+  "api/",
+  newRpcServer({ math: new MathService() }),
+);
+
+// Now any page script can do:
+const client = newRpcClient({ baseUrl });
+const math = await client.loadService<MathService>("math");
+```
+
+### Mount under a path prefix
+
+```ts
+const handler = newRpcServer(services, { path: "/api/v1" });
+
+// GET  /api/v1/                   → descriptor
+// POST /api/v1/math/add           → call
+// GET  /api/v1/math/add/foo/bar   → call with params.$path === "foo/bar"
+```
+
+Requests outside the prefix get a 404 response with the same JSON-error
+shape as any other error.
+
+### Errors
+
+Every error — method throws, unknown routes, descriptor failures —
+returns a JSON object:
+
+```json
+{ "type": "error", "message": "…", "stack": "…", "…any custom fields": "…" }
+```
+
+| Cause | HTTP status | Body |
+| --- | --- | --- |
+| Method body throws | 200 | `{ "type": "error", … }` — the call reached the method. |
+| Method doesn't exist | 500 | Same shape — routing failure. |
+| Unknown path | 404 | Same shape. |
+| `response.ok === false` with non-JSON body | — | Client throws a generic `RPC call failed: status text`. |
+
+On the client, every serialized error is rehydrated into an `Error`
+instance via
+[`@statewalker/webrun-streams`](../webrun-streams)'s `deserializeError`
+— preserving `message`, `stack`, and any custom fields the server
+attached to a thrown `Error` subclass.
+
+## Internals
+
+### Descriptor format
+
+`getInstanceMethods` walks each service's prototype chain and picks up
+every function-valued property except `constructor`, stopping before
+`Object.prototype`. It returns a `Record<string, Function>`; the wire
+descriptor is built from its keys. That means:
+
+- Plain object literals `{ foo() {…} }` expose `foo`.
+- Class instances expose methods defined on any ancestor class up to
+  `Object.prototype` (`toString`, `hasOwnProperty`, … are *not*
+  exposed).
+- Inherited methods work: `class Child extends Parent` instance exposes
+  every method from both.
+
+The descriptor shape is `Record<string, string[]>` — just names, no
+signatures. Clients build proxy objects from the name list alone.
+
+### Wire format — call encoding
+
+| Method | Body |
+| --- | --- |
+| `POST /svc/method` | `multipart/form-data` with fields `params` (JSON-stringified) and optional `body` (`Blob`). |
+| `GET /svc/method?k=v` | Query string parsed into JSON. Dot-separated keys nest: `?a.b=c&a.d=e` → `{ a: { b: "c", d: "e" } }`. |
+
+All query-string values stay as **strings** (URLSearchParams' contract).
+If your method expects numbers, POST JSON instead of GET'ing a querystring.
+
+### Wire format — sub-path injection
+
+The URL tail after `/svc/method/` is injected into `params.$path`:
+
+- `GET /svc/method/foo/bar` → `params.$path === "foo/bar"`.
+- Useful for REST-style handlers (`GET /files/read/some/deep/path`).
+- `$path` is always present (empty string when there is no tail).
+
+### Wire format — response encoding
+
+| Method returns | Status | Body |
+| --- | --- | --- |
+| `Json` | 200 `application/json` | `{ "type": "json", "result": … }` |
+| `Blob` | 200 `application/octet-stream` | Raw bytes. |
+| thrown `Error` | 200 `application/json` | `{ "type": "error", message, stack, …}` |
+| routing failure | 500 or 404 | Same `type: "error"` shape. |
+
+### Design notes
+
+- **Factory, not class.** Matches the rest of the workspace
+  (`newHttpClientStub`, `newHttpCodec`, `newBasicAuth`, …). No public
+  class surface to subclass; behaviour is configured via the options
+  object.
+- **Cached descriptor, lazy load.** The first `loadService` call fires
+  the `GET baseUrl/` request; every subsequent call returns the same
+  proxy object. Restart the client (`newRpcClient(...)`) to refresh.
+- **Errors go through `@statewalker/webrun-streams`.** One
+  (de)serialization format shared across the webrun stack; no duplicate
+  `errors.ts` file.
+- **No client-side type generation.** The client returns
+  `Record<string, RpcMethod>` by default; pass a concrete interface with
+  `loadService<MyService>("name")` to recover typing. TypeScript
+  structural compatibility does the rest.
+- **The `$path` trick is optional.** If your method doesn't read
+  `params.$path`, nothing changes. It's there for REST-style handlers
+  that care about the tail.
+
+### Constraints
+
+- **One prototype chain.** `getInstanceMethods` stops before
+  `Object.prototype`. Methods defined on `Object.prototype` are
+  deliberately excluded — you can't accidentally expose `toString`.
+- **No streaming.** A method returns once, with one `Json` or `Blob`.
+  Use `@statewalker/webrun-http-streams` directly (`fetchOverDuplex` /
+  `serveFetchOverDuplex`) for streaming responses.
+- **Path prefix without trailing slash.** `path: "/api"` is right;
+  `path: "/api/"` is normalized (trailing slash stripped).
+- **URLSearchParams are strings.** `?a=1` → `params.a === "1"`. POST
+  JSON-encoded params whenever the argument type matters.
+- **No content negotiation.** JSON in, JSON or binary out — nothing more.
+- **`baseUrl` without trailing slash.** The client concatenates
+  `${baseUrl}/${service}/${method}`; trailing slash would double.
+
+### Dependencies
+
+Runtime:
+
+- `@statewalker/webrun-streams` — error (de)serialization
+  (`serializeError` / `deserializeError`). Workspace-local.
+
+Otherwise zero runtime deps: platform builtins only (`Request`,
+`Response`, `FormData`, `Blob`, `URL`, `URLSearchParams`).
+
+Dev: TypeScript, vitest, rolldown, rimraf, `@types/node` (catalog
+versions from the monorepo root).
+
+## Scripts
+
+```sh
+pnpm test        # vitest run
+pnpm run build   # rolldown + tsc --emitDeclarationOnly
+pnpm lint        # biome check src tests
+```
+
+## License
+
+MIT © statewalker

package/dist/get-instance-methods.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Collect every callable property of `instance` — including inherited ones —
+ * up to (but not including) `Object.prototype`. Constructors and non-function
+ * properties are skipped.
+ */
+export declare function getInstanceMethods<T>(instance: T): Record<string, (...args: unknown[]) => unknown>;
+//# sourceMappingURL=get-instance-methods.d.ts.map

package/dist/get-instance-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-instance-methods.d.ts","sourceRoot":"","sources":["../src/get-instance-methods.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,QAAQ,EAAE,CAAC,GACV,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAkBjD"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./get-instance-methods.js";
+export * from "./new-rpc-client.js";
+export * from "./new-rpc-server.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,238 @@
+//#region src/get-instance-methods.ts
+/**
+* Collect every callable property of `instance` — including inherited ones —
+* up to (but not including) `Object.prototype`. Constructors and non-function
+* properties are skipped.
+*/
+function getInstanceMethods(instance) {
+	const seen = /* @__PURE__ */ new Set();
+	const methods = {};
+	const target = instance;
+	for (let proto = target; proto && proto !== Object.prototype; proto = Reflect.getPrototypeOf(proto)) for (const key of Object.getOwnPropertyNames(proto)) {
+		if (seen.has(key) || key === "constructor") continue;
+		seen.add(key);
+		const value = Reflect.get(target, key);
+		if (typeof value !== "function") continue;
+		methods[key] = value;
+	}
+	return methods;
+}
+//#endregion
+//#region ../webrun-streams/src/errors.ts
+function serializeError(error) {
+	if (error instanceof Error) {
+		const out = {
+			message: error.message,
+			stack: error.stack
+		};
+		const bag = error;
+		for (const key of Object.keys(bag)) out[key] = bag[key];
+		return out;
+	}
+	if (typeof error === "object" && error !== null) {
+		const bag = error;
+		return {
+			message: String(bag.message ?? error),
+			...bag
+		};
+	}
+	return { message: String(error) };
+}
+function deserializeError(error) {
+	const payload = typeof error === "string" ? { message: error } : error;
+	return Object.assign(new Error(payload.message), payload);
+}
+//#endregion
+//#region src/new-rpc-client.ts
+/**
+* Build an RPC client that calls services exposed by {@link newRpcServer}.
+*
+* The descriptor at `GET {baseUrl}/` is fetched lazily on the first
+* `loadService` call and cached for subsequent calls.
+*/
+function newRpcClient({ baseUrl, fetch = globalThis.fetch.bind(globalThis) }) {
+	let apiPromise = null;
+	const loadApi = async () => {
+		const response = await fetch(new Request(baseUrl));
+		if (!response.ok) throw new Error(`Failed to load services descriptor: ${response.status} ${response.statusText}`);
+		const descriptor = await response.json();
+		const services = {};
+		for (const [serviceName, methodNames] of Object.entries(descriptor)) {
+			const serviceApi = {};
+			for (const methodName of methodNames) serviceApi[methodName] = newRpcMethod(fetch, baseUrl, serviceName, methodName);
+			services[serviceName] = serviceApi;
+		}
+		return services;
+	};
+	return { async loadService(serviceName) {
+		if (!apiPromise) apiPromise = loadApi();
+		const service = (await apiPromise)[serviceName];
+		if (!service) throw new Error(`Service ${serviceName} not found`);
+		return service;
+	} };
+}
+function newRpcMethod(fetch, baseUrl, serviceName, methodName) {
+	return async (params = {}, body) => {
+		const url = `${baseUrl}/${serviceName}/${methodName}`;
+		const formData = new FormData();
+		formData.append("params", JSON.stringify(params));
+		if (body) formData.append("body", body);
+		const response = await fetch(new Request(url, {
+			method: "POST",
+			body: formData
+		}));
+		if ((response.headers.get("Content-Type") || "").includes("application/json")) {
+			const json = await response.json();
+			if (!json || typeof json !== "object" || Array.isArray(json)) throw new Error("RPC response is not a JSON object");
+			if (json.type === "error") throw deserializeError(json);
+			if (!response.ok) throw new Error(`RPC call failed: ${response.status} ${response.statusText}`);
+			return json.result;
+		}
+		if (!response.ok) throw new Error(`RPC call failed: ${response.status} ${response.statusText}`);
+		return response.blob();
+	};
+}
+//#endregion
+//#region src/new-rpc-server.ts
+/**
+* Build a webrun-http `(Request) ⇒ Response` handler that exposes every method
+* of every service as an HTTP endpoint.
+*
+* Wire format:
+* - `GET  {path}/`                               → `{ [service]: [methodName, ...] }`
+* - `GET  {path}/{service}`                      → `[methodName, ...]`
+* - `GET  {path}/{service}/{method}?a.b=c`       → calls the method with `{ a: { b: "c" } }`
+* - `POST {path}/{service}/{method}` with multipart/form-data (`params` JSON
+*   + optional `body` Blob) → calls the method with the decoded args
+*
+* Results are returned as `{ type: "json", result }` JSON, or as an
+* `application/octet-stream` blob when the method returns a `Blob`. Errors
+* are serialized to `{ type: "error", message, stack, ... }` JSON.
+*/
+function newRpcServer(services, { path = "" } = {}) {
+	const prefix = path.endsWith("/") ? path.slice(0, -1) : path;
+	const index = buildServiceIndex(services);
+	return async (request) => {
+		try {
+			const route = splitRequestPath(request, prefix);
+			if (!route) return errorResponse(/* @__PURE__ */ new Error("Not found"), 404);
+			const { serviceName, methodName, subPath } = route;
+			if (request.method === "GET" && !serviceName) return jsonResponse(describeServices(index));
+			if (request.method === "GET" && serviceName && !methodName) return jsonResponse(listMethods(index, serviceName));
+			if ((request.method === "GET" || request.method === "POST") && serviceName && methodName) {
+				const { params, body } = await parseCallArgs(request);
+				const result = await invoke(index, serviceName, methodName, subPath, params, body);
+				return result instanceof Blob ? blobResponse(result) : jsonResponse(result);
+			}
+			return errorResponse(/* @__PURE__ */ new Error("Not found"), 404);
+		} catch (error) {
+			return errorResponse(error, 500);
+		}
+	};
+}
+function buildServiceIndex(services) {
+	const index = {};
+	for (const [serviceName, service] of Object.entries(services)) {
+		const methods = getInstanceMethods(service);
+		const methodsIndex = {};
+		for (const [methodName, method] of Object.entries(methods)) methodsIndex[methodName] = async (params, body) => await method.call(service, params, body);
+		index[serviceName] = methodsIndex;
+	}
+	return index;
+}
+function splitRequestPath(request, prefix) {
+	const pathname = new URL(request.url).pathname;
+	if (prefix && !pathname.startsWith(prefix)) return null;
+	const [serviceName = "", methodName = "", ...tail] = pathname.substring(prefix.length + 1).split("/");
+	return {
+		serviceName: serviceName || void 0,
+		methodName: methodName || void 0,
+		subPath: tail.join("/")
+	};
+}
+async function parseCallArgs(request) {
+	if (request.method === "GET") return { params: parseQueryParams(new URL(request.url).searchParams) };
+	if ((request.headers.get("Content-Type") || "").startsWith("multipart/form-data")) {
+		const formData = await request.formData();
+		let params = {};
+		if (formData.has("params")) params = JSON.parse(formData.get("params"));
+		const body = formData.has("body") ? formData.get("body") : void 0;
+		return {
+			params,
+			body
+		};
+	}
+	return {
+		params: {},
+		body: request.body ? await request.blob() : void 0
+	};
+}
+/**
+* Expand dot-separated query keys (`a.b=c`) into nested JSON objects.
+* Repeated keys overwrite rather than merging — same as the original.
+*/
+function parseQueryParams(search) {
+	const root = {};
+	for (const [key, value] of search.entries()) {
+		const segments = key.split(".");
+		let cursor = root;
+		for (let i = 0; i < segments.length - 1; i++) {
+			const seg = segments[i];
+			const existing = cursor[seg];
+			if (typeof existing !== "object" || existing === null || Array.isArray(existing)) cursor[seg] = {};
+			cursor = cursor[seg];
+		}
+		cursor[segments[segments.length - 1]] = value;
+	}
+	return root;
+}
+async function invoke(index, serviceName, methodName, subPath, params, body) {
+	if (params && typeof params === "object" && !Array.isArray(params)) params.$path = subPath;
+	const method = index[serviceName]?.[methodName];
+	if (!method) throw new Error(`Method ${methodName} not found in service ${serviceName}`);
+	try {
+		const result = await method(params, body);
+		return result instanceof Blob ? result : {
+			type: "json",
+			result
+		};
+	} catch (error) {
+		return {
+			type: "error",
+			...serializeError(error)
+		};
+	}
+}
+function describeServices(index) {
+	const out = {};
+	for (const [name, methods] of Object.entries(index)) out[name] = Object.keys(methods);
+	return out;
+}
+function listMethods(index, serviceName) {
+	const svc = index[serviceName];
+	return svc ? Object.keys(svc) : [];
+}
+function jsonResponse(body, status = 200) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+function blobResponse(body) {
+	return new Response(body, {
+		status: 200,
+		headers: { "Content-Type": "application/octet-stream" }
+	});
+}
+function errorResponse(error, status) {
+	const body = {
+		type: "error",
+		...serializeError(error)
+	};
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+//#endregion
+export { getInstanceMethods, newRpcClient, newRpcServer };

package/dist/new-rpc-client.d.ts

@@ -0,0 +1,25 @@
+import type { RpcMethod } from "./types.js";
+export interface NewRpcClientOptions {
+    /** Base URL of the RPC endpoint (no trailing slash). */
+    baseUrl: string;
+    /**
+     * Optional fetch override. Defaults to `globalThis.fetch`. Pass a webrun-http
+     * handler here to run the client against an in-process server.
+     */
+    fetch?: (request: Request) => Promise<Response>;
+}
+export interface RpcClient {
+    /**
+     * Load (and cache) the service descriptor and return a proxy object whose
+     * methods round-trip through the transport.
+     */
+    loadService<T = Record<string, RpcMethod>>(serviceName: string): Promise<T>;
+}
+/**
+ * Build an RPC client that calls services exposed by {@link newRpcServer}.
+ *
+ * The descriptor at `GET {baseUrl}/` is fetched lazily on the first
+ * `loadService` call and cached for subsequent calls.
+ */
+export declare function newRpcClient({ baseUrl, fetch, }: NewRpcClientOptions): RpcClient;
+//# sourceMappingURL=new-rpc-client.d.ts.map

package/dist/new-rpc-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-rpc-client.d.ts","sourceRoot":"","sources":["../src/new-rpc-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,SAAS,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,KAAyC,GAC1C,EAAE,mBAAmB,GAAG,SAAS,CA+BjC"}

package/dist/new-rpc-server.d.ts

@@ -0,0 +1,24 @@
+export interface NewRpcServerOptions {
+    /**
+     * URL prefix under which the RPC endpoints are mounted. A trailing slash is
+     * stripped. Empty (the default) mounts at the origin root.
+     */
+    path?: string;
+}
+/**
+ * Build a webrun-http `(Request) ⇒ Response` handler that exposes every method
+ * of every service as an HTTP endpoint.
+ *
+ * Wire format:
+ * - `GET  {path}/`                               → `{ [service]: [methodName, ...] }`
+ * - `GET  {path}/{service}`                      → `[methodName, ...]`
+ * - `GET  {path}/{service}/{method}?a.b=c`       → calls the method with `{ a: { b: "c" } }`
+ * - `POST {path}/{service}/{method}` with multipart/form-data (`params` JSON
+ *   + optional `body` Blob) → calls the method with the decoded args
+ *
+ * Results are returned as `{ type: "json", result }` JSON, or as an
+ * `application/octet-stream` blob when the method returns a `Blob`. Errors
+ * are serialized to `{ type: "error", message, stack, ... }` JSON.
+ */
+export declare function newRpcServer(services: Record<string, object>, { path }?: NewRpcServerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=new-rpc-server.d.ts.map

package/dist/new-rpc-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-rpc-server.d.ts","sourceRoot":"","sources":["../src/new-rpc-server.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,EAAE,IAAS,EAAE,GAAE,mBAAwB,GACtC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAyBzC"}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+/** Any value that can survive a JSON round-trip. */
+export type Json = string | number | boolean | null | Json[] | JsonObject;
+/** A JSON object — the only valid shape for RPC call params. */
+export interface JsonObject {
+    [key: string]: Json;
+}
+/**
+ * An RPC method. Takes a JSON-shaped `params` argument and an optional binary
+ * `body`, returns a JSON value or a `Blob`.
+ */
+export type RpcMethod = (params: Json, body?: Blob) => Promise<Blob | Json>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,GAAG,UAAU,CAAC;AAE1E,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@statewalker/webrun-rpc-http",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "HTTP-based service RPC: expose object methods as a (Request) => Response handler and call them with fetch",
+  "homepage": "https://github.com/statewalker/webrun-wire",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-wire.git"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-streams": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome check src tests"
+  }
+}

package/src/get-instance-methods.ts

@@ -0,0 +1,26 @@
+/**
+ * Collect every callable property of `instance` — including inherited ones —
+ * up to (but not including) `Object.prototype`. Constructors and non-function
+ * properties are skipped.
+ */
+export function getInstanceMethods<T>(
+  instance: T,
+): Record<string, (...args: unknown[]) => unknown> {
+  const seen = new Set<string>();
+  const methods: Record<string, (...args: unknown[]) => unknown> = {};
+  const target = instance as unknown as object;
+  for (
+    let proto: object | null = target;
+    proto && proto !== Object.prototype;
+    proto = Reflect.getPrototypeOf(proto)
+  ) {
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      if (seen.has(key) || key === "constructor") continue;
+      seen.add(key);
+      const value = Reflect.get(target, key);
+      if (typeof value !== "function") continue;
+      methods[key] = value as (...args: unknown[]) => unknown;
+    }
+  }
+  return methods;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./get-instance-methods.js";
+export * from "./new-rpc-client.js";
+export * from "./new-rpc-server.js";
+export * from "./types.js";

package/src/new-rpc-client.ts

@@ -0,0 +1,93 @@
+import { deserializeError, type SerializedError } from "@statewalker/webrun-streams";
+import type { Json, JsonObject, RpcMethod } from "./types.js";
+
+export interface NewRpcClientOptions {
+  /** Base URL of the RPC endpoint (no trailing slash). */
+  baseUrl: string;
+  /**
+   * Optional fetch override. Defaults to `globalThis.fetch`. Pass a webrun-http
+   * handler here to run the client against an in-process server.
+   */
+  fetch?: (request: Request) => Promise<Response>;
+}
+
+export interface RpcClient {
+  /**
+   * Load (and cache) the service descriptor and return a proxy object whose
+   * methods round-trip through the transport.
+   */
+  loadService<T = Record<string, RpcMethod>>(serviceName: string): Promise<T>;
+}
+
+/**
+ * Build an RPC client that calls services exposed by {@link newRpcServer}.
+ *
+ * The descriptor at `GET {baseUrl}/` is fetched lazily on the first
+ * `loadService` call and cached for subsequent calls.
+ */
+export function newRpcClient({
+  baseUrl,
+  fetch = globalThis.fetch.bind(globalThis),
+}: NewRpcClientOptions): RpcClient {
+  let apiPromise: Promise<Record<string, Record<string, RpcMethod>>> | null = null;
+
+  const loadApi = async () => {
+    const response = await fetch(new Request(baseUrl));
+    if (!response.ok) {
+      throw new Error(
+        `Failed to load services descriptor: ${response.status} ${response.statusText}`,
+      );
+    }
+    const descriptor = (await response.json()) as Record<string, string[]>;
+    const services: Record<string, Record<string, RpcMethod>> = {};
+    for (const [serviceName, methodNames] of Object.entries(descriptor)) {
+      const serviceApi: Record<string, RpcMethod> = {};
+      for (const methodName of methodNames) {
+        serviceApi[methodName] = newRpcMethod(fetch, baseUrl, serviceName, methodName);
+      }
+      services[serviceName] = serviceApi;
+    }
+    return services;
+  };
+
+  return {
+    async loadService<T = Record<string, RpcMethod>>(serviceName: string): Promise<T> {
+      if (!apiPromise) apiPromise = loadApi();
+      const apis = await apiPromise;
+      const service = apis[serviceName];
+      if (!service) throw new Error(`Service ${serviceName} not found`);
+      return service as T;
+    },
+  };
+}
+
+function newRpcMethod(
+  fetch: (request: Request) => Promise<Response>,
+  baseUrl: string,
+  serviceName: string,
+  methodName: string,
+): RpcMethod {
+  return async (params: Json = {}, body?: Blob): Promise<Blob | Json> => {
+    const url = `${baseUrl}/${serviceName}/${methodName}`;
+    const formData = new FormData();
+    formData.append("params", JSON.stringify(params));
+    if (body) formData.append("body", body);
+    const response = await fetch(new Request(url, { method: "POST", body: formData }));
+    const contentType = response.headers.get("Content-Type") || "";
+    if (contentType.includes("application/json")) {
+      const json = (await response.json()) as JsonObject | null;
+      if (!json || typeof json !== "object" || Array.isArray(json)) {
+        throw new Error("RPC response is not a JSON object");
+      }
+      if (json.type === "error") throw deserializeError(json as SerializedError);
+      if (!response.ok) {
+        throw new Error(`RPC call failed: ${response.status} ${response.statusText}`);
+      }
+      return json.result as Json;
+    }
+    if (!response.ok) {
+      throw new Error(`RPC call failed: ${response.status} ${response.statusText}`);
+    }
+    return response.blob();
+  };
+}

package/src/new-rpc-server.ts

@@ -0,0 +1,188 @@
+import { serializeError } from "@statewalker/webrun-streams";
+import { getInstanceMethods } from "./get-instance-methods.js";
+import type { Json, JsonObject, RpcMethod } from "./types.js";
+
+export interface NewRpcServerOptions {
+  /**
+   * URL prefix under which the RPC endpoints are mounted. A trailing slash is
+   * stripped. Empty (the default) mounts at the origin root.
+   */
+  path?: string;
+}
+
+type ServiceIndex = Record<string, Record<string, RpcMethod>>;
+
+/**
+ * Build a webrun-http `(Request) ⇒ Response` handler that exposes every method
+ * of every service as an HTTP endpoint.
+ *
+ * Wire format:
+ * - `GET  {path}/`                               → `{ [service]: [methodName, ...] }`
+ * - `GET  {path}/{service}`                      → `[methodName, ...]`
+ * - `GET  {path}/{service}/{method}?a.b=c`       → calls the method with `{ a: { b: "c" } }`
+ * - `POST {path}/{service}/{method}` with multipart/form-data (`params` JSON
+ *   + optional `body` Blob) → calls the method with the decoded args
+ *
+ * Results are returned as `{ type: "json", result }` JSON, or as an
+ * `application/octet-stream` blob when the method returns a `Blob`. Errors
+ * are serialized to `{ type: "error", message, stack, ... }` JSON.
+ */
+export function newRpcServer(
+  services: Record<string, object>,
+  { path = "" }: NewRpcServerOptions = {},
+): (request: Request) => Promise<Response> {
+  const prefix = path.endsWith("/") ? path.slice(0, -1) : path;
+  const index = buildServiceIndex(services);
+
+  return async (request: Request): Promise<Response> => {
+    try {
+      const route = splitRequestPath(request, prefix);
+      if (!route) return errorResponse(new Error("Not found"), 404);
+      const { serviceName, methodName, subPath } = route;
+      if (request.method === "GET" && !serviceName) {
+        return jsonResponse(describeServices(index));
+      }
+      if (request.method === "GET" && serviceName && !methodName) {
+        return jsonResponse(listMethods(index, serviceName));
+      }
+      if ((request.method === "GET" || request.method === "POST") && serviceName && methodName) {
+        const { params, body } = await parseCallArgs(request);
+        const result = await invoke(index, serviceName, methodName, subPath, params, body);
+        return result instanceof Blob ? blobResponse(result) : jsonResponse(result);
+      }
+      return errorResponse(new Error("Not found"), 404);
+    } catch (error) {
+      return errorResponse(error as Error, 500);
+    }
+  };
+}
+
+function buildServiceIndex(services: Record<string, object>): ServiceIndex {
+  const index: ServiceIndex = {};
+  for (const [serviceName, service] of Object.entries(services)) {
+    const methods = getInstanceMethods(service);
+    const methodsIndex: Record<string, RpcMethod> = {};
+    for (const [methodName, method] of Object.entries(methods)) {
+      methodsIndex[methodName] = async (params, body) =>
+        (await method.call(service, params, body)) as Blob | Json;
+    }
+    index[serviceName] = methodsIndex;
+  }
+  return index;
+}
+
+interface ParsedPath {
+  serviceName?: string;
+  methodName?: string;
+  subPath: string;
+}
+
+function splitRequestPath(request: Request, prefix: string): ParsedPath | null {
+  const pathname = new URL(request.url).pathname;
+  if (prefix && !pathname.startsWith(prefix)) return null;
+  const rest = pathname.substring(prefix.length + 1);
+  const [serviceName = "", methodName = "", ...tail] = rest.split("/");
+  return {
+    serviceName: serviceName || undefined,
+    methodName: methodName || undefined,
+    subPath: tail.join("/"),
+  };
+}
+
+async function parseCallArgs(request: Request): Promise<{ params: Json; body?: Blob }> {
+  if (request.method === "GET") {
+    return { params: parseQueryParams(new URL(request.url).searchParams) };
+  }
+  const contentType = request.headers.get("Content-Type") || "";
+  if (contentType.startsWith("multipart/form-data")) {
+    const formData = await request.formData();
+    let params: Json = {};
+    if (formData.has("params")) {
+      params = JSON.parse(formData.get("params") as string) as Json;
+    }
+    const body = formData.has("body") ? (formData.get("body") as Blob) : undefined;
+    return { params, body };
+  }
+  const body = request.body ? await request.blob() : undefined;
+  return { params: {}, body };
+}
+
+/**
+ * Expand dot-separated query keys (`a.b=c`) into nested JSON objects.
+ * Repeated keys overwrite rather than merging — same as the original.
+ */
+function parseQueryParams(search: URLSearchParams): JsonObject {
+  const root: JsonObject = {};
+  for (const [key, value] of search.entries()) {
+    const segments = key.split(".");
+    let cursor: JsonObject = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const seg = segments[i];
+      const existing = cursor[seg];
+      if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
+        cursor[seg] = {};
+      }
+      cursor = cursor[seg] as JsonObject;
+    }
+    cursor[segments[segments.length - 1]] = value;
+  }
+  return root;
+}
+
+async function invoke(
+  index: ServiceIndex,
+  serviceName: string,
+  methodName: string,
+  subPath: string,
+  params: Json,
+  body?: Blob,
+): Promise<Json | Blob> {
+  if (params && typeof params === "object" && !Array.isArray(params)) {
+    (params as JsonObject).$path = subPath;
+  }
+  const method = index[serviceName]?.[methodName];
+  if (!method) {
+    throw new Error(`Method ${methodName} not found in service ${serviceName}`);
+  }
+  try {
+    const result = await method(params, body);
+    return result instanceof Blob ? result : ({ type: "json", result } as JsonObject);
+  } catch (error) {
+    return { type: "error", ...serializeError(error as Error) } as JsonObject;
+  }
+}
+
+function describeServices(index: ServiceIndex): JsonObject {
+  const out: JsonObject = {};
+  for (const [name, methods] of Object.entries(index)) {
+    out[name] = Object.keys(methods);
+  }
+  return out;
+}
+
+function listMethods(index: ServiceIndex, serviceName: string): Json[] {
+  const svc = index[serviceName];
+  return svc ? Object.keys(svc) : [];
+}
+
+function jsonResponse(body: Json, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function blobResponse(body: Blob): Response {
+  return new Response(body, {
+    status: 200,
+    headers: { "Content-Type": "application/octet-stream" },
+  });
+}
+
+function errorResponse(error: Error, status: number): Response {
+  const body: JsonObject = { type: "error", ...serializeError(error) };
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+/** Any value that can survive a JSON round-trip. */
+export type Json = string | number | boolean | null | Json[] | JsonObject;
+
+/** A JSON object — the only valid shape for RPC call params. */
+export interface JsonObject {
+  [key: string]: Json;
+}
+
+/**
+ * An RPC method. Takes a JSON-shaped `params` argument and an optional binary
+ * `body`, returns a JSON value or a `Blob`.
+ */
+export type RpcMethod = (params: Json, body?: Blob) => Promise<Blob | Json>;