@query-farm/vgi-rpc 0.8.0 → 0.9.0

package/dist/serve-stream.d.ts

@@ -0,0 +1,23 @@
+import type { Socket } from "node:net";
+import type { Protocol } from "./protocol.js";
+import { VgiRpcServer } from "./server.js";
+import { TransportKind } from "./types.js";
+export interface ServeStreamOptions {
+    /** Incoming request bytes — a web `ReadableStream<Uint8Array>` or a Node
+     *  `Readable` (e.g. a `Duplex` bridging a MessagePort). */
+    readable: ReadableStream<Uint8Array> | NodeJS.ReadableStream;
+    /** Outgoing response sink — a stdout-like fd number, or a `net.Socket` /
+     *  structurally-compatible `Duplex`. Omit for the stdout fd. */
+    writable?: number | Socket;
+    /** Passed through to the `VgiRpcServer` constructor (describe, hooks, …). */
+    serverOptions?: ConstructorParameters<typeof VgiRpcServer>[1];
+    /** Reported to the `on_serve_start` hook. Defaults to `PIPE`. */
+    transportKind?: TransportKind;
+}
+/**
+ * Serve `protocol` over the provided `readable`/`writable` until the readable
+ * ends. Thin wrapper over {@link VgiRpcServer.serveConnection}. Resolves on
+ * clean EOF; rejects on a real protocol/transport error.
+ */
+export declare function serveStream(protocol: Protocol, options: ServeStreamOptions): Promise<void>;
+//# sourceMappingURL=serve-stream.d.ts.map

package/dist/serve-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-stream.d.ts","sourceRoot":"","sources":["../src/serve-stream.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC;+DAC2D;IAC3D,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC;IAC7D;oEACgE;IAChE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,qBAAqB,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,iEAAiE;IACjE,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhG"}

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import type { ExternalLocationConfig } from "./external.js";
 import type { Protocol } from "./protocol.js";
-import { type DispatchHook, type ServeStartHook } from "./types.js";
+import { type DispatchHook, type ServeStartHook, TransportKind } from "./types.js";
 /**
  * RPC server that reads Arrow IPC requests from stdin and writes responses to stdout.
  * Supports unary and streaming (producer/exchange) methods.
@@ -39,8 +39,24 @@ export declare class VgiRpcServer {
      *  `RpcServer._check_protocol_version`: exact major+minor match, patch
      *  ignored; directional error message names which side is older. */
     private checkProtocolVersion;
-    /** Start the server loop. Reads requests until stdin closes. */
+    /** Start the server loop over stdin/stdout. Reads requests until stdin closes. */
     run(): Promise<void>;
+    /**
+     * Serve requests over an explicit byte-stream pair until the readable ends —
+     * the transport-agnostic core that {@link run} (stdin/stdout) is built on.
+     *
+     * Use this to serve over any duplex channel that the stdio/unix/tcp helpers
+     * don't cover: a Web Worker / `MessagePort` bridge, an in-memory pipe, or a
+     * pre-connected socket. The loop, on_serve_start firing, and EOF/broken-pipe
+     * handling are identical to {@link run}.
+     *
+     * @param readable incoming request bytes — a web `ReadableStream<Uint8Array>`
+     *   or a Node `Readable` (e.g. a `Duplex` bridging a MessagePort).
+     * @param writable outgoing response sink — a stdout-like fd number, or a
+     *   `net.Socket` / structurally-compatible `Duplex`. Omit for the stdout fd.
+     * @param transportKind reported to the `on_serve_start` hook (default `PIPE`).
+     */
+    serveConnection(readable: ReadableStream<Uint8Array> | NodeJS.ReadableStream, writable?: number | import("node:net").Socket, transportKind?: TransportKind): Promise<void>;
     private serveOne;
 }
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAkBpB;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAS;IAIzB,OAAO,CAAC,gBAAgB,CAGP;IACjB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,YAAY,CAA+B;IACnD;;;0EAGsE;IACtE,OAAO,CAAC,eAAe,CAAS;gBAG9B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;QAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,qEAAqE;QACrE,YAAY,CAAC,EAAE,cAAc,CAAC;KAC/B;IAWH;yEACqE;YACvD,eAAe;IAQ7B,iEAAiE;YACnD,YAAY;IAkB1B;;;;wEAIoE;IACpE,OAAO,CAAC,oBAAoB;IAyC5B,gEAAgE;IAC1D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YA6CZ,QAAQ;CA2IvB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,cAAc,EACnB,aAAa,EACd,MAAM,YAAY,CAAC;AAkBpB;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAS;IAIzB,OAAO,CAAC,gBAAgB,CAGP;IACjB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,YAAY,CAA+B;IACnD;;;0EAGsE;IACtE,OAAO,CAAC,eAAe,CAAS;gBAG9B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;QAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,qEAAqE;QACrE,YAAY,CAAC,EAAE,cAAc,CAAC;KAC/B;IAWH;yEACqE;YACvD,eAAe;IAQ7B,iEAAiE;YACnD,YAAY;IAkB1B;;;;wEAIoE;IACpE,OAAO,CAAC,oBAAoB;IAyC5B,kFAAkF;IAC5E,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAe1B;;;;;;;;;;;;;;OAcG;IACG,eAAe,CACnB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,cAAc,EAC5D,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,UAAU,EAAE,MAAM,EAC7C,aAAa,GAAE,aAAkC,GAChD,OAAO,CAAC,IAAI,CAAC;YAgCF,QAAQ;CA2IvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi-rpc",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "Apache-2.0",
   "homepage": "https://vgi-rpc-typescript.query.farm",
   "repository": {

package/src/index.core.ts

@@ -92,6 +92,7 @@ export {
   uint64,
 } from "./schema.js";
 export { VgiRpcServer } from "./server.js";
+export { serveStream, type ServeStreamOptions } from "./serve-stream.js";
 export {
   type CallContext,
   type CallStatistics,

package/src/serve-stream.ts

@@ -0,0 +1,38 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+//! Serve a protocol over a caller-provided byte-stream pair — the stream
+//! sibling of `serveTcp` / `serveUnix`, with no socket/listener of its own.
+//!
+//! Useful for transports the launcher helpers don't cover: a Web Worker /
+//! `MessagePort` bridge (postMessage), an in-memory pipe, or a pre-connected
+//! socket. The host side already has this symmetry via `pipeConnect`.
+
+import type { Socket } from "node:net";
+
+import type { Protocol } from "./protocol.js";
+import { VgiRpcServer } from "./server.js";
+import { TransportKind } from "./types.js";
+
+export interface ServeStreamOptions {
+  /** Incoming request bytes — a web `ReadableStream<Uint8Array>` or a Node
+   *  `Readable` (e.g. a `Duplex` bridging a MessagePort). */
+  readable: ReadableStream<Uint8Array> | NodeJS.ReadableStream;
+  /** Outgoing response sink — a stdout-like fd number, or a `net.Socket` /
+   *  structurally-compatible `Duplex`. Omit for the stdout fd. */
+  writable?: number | Socket;
+  /** Passed through to the `VgiRpcServer` constructor (describe, hooks, …). */
+  serverOptions?: ConstructorParameters<typeof VgiRpcServer>[1];
+  /** Reported to the `on_serve_start` hook. Defaults to `PIPE`. */
+  transportKind?: TransportKind;
+}
+
+/**
+ * Serve `protocol` over the provided `readable`/`writable` until the readable
+ * ends. Thin wrapper over {@link VgiRpcServer.serveConnection}. Resolves on
+ * clean EOF; rejects on a real protocol/transport error.
+ */
+export async function serveStream(protocol: Protocol, options: ServeStreamOptions): Promise<void> {
+  const server = new VgiRpcServer(protocol, options.serverOptions);
+  await server.serveConnection(options.readable, options.writable, options.transportKind);
+}

package/src/server.ts

@@ -161,10 +161,8 @@ export class VgiRpcServer {
     );
   }
 
-  /** Start the server loop. Reads requests until stdin closes. */
+  /** Start the server loop over stdin/stdout. Reads requests until stdin closes. */
   async run(): Promise<void> {
-    const stdin = process.stdin as unknown as ReadableStream<Uint8Array>;
-
     // Warn if running interactively
     if (process.stdin.isTTY || process.stdout.isTTY) {
       process.stderr.write(
@@ -174,21 +172,44 @@ export class VgiRpcServer {
           "(e.g. vgi_rpc.connect()).\n",
       );
     }
+    const stdin = process.stdin as unknown as ReadableStream<Uint8Array>;
+    // writable omitted → IpcStreamWriter defaults to the stdout fd.
+    await this.serveConnection(stdin);
+  }
 
-    const reader = await IpcStreamReader.create(stdin);
-    const writer = new IpcStreamWriter();
+  /**
+   * Serve requests over an explicit byte-stream pair until the readable ends —
+   * the transport-agnostic core that {@link run} (stdin/stdout) is built on.
+   *
+   * Use this to serve over any duplex channel that the stdio/unix/tcp helpers
+   * don't cover: a Web Worker / `MessagePort` bridge, an in-memory pipe, or a
+   * pre-connected socket. The loop, on_serve_start firing, and EOF/broken-pipe
+   * handling are identical to {@link run}.
+   *
+   * @param readable incoming request bytes — a web `ReadableStream<Uint8Array>`
+   *   or a Node `Readable` (e.g. a `Duplex` bridging a MessagePort).
+   * @param writable outgoing response sink — a stdout-like fd number, or a
+   *   `net.Socket` / structurally-compatible `Duplex`. Omit for the stdout fd.
+   * @param transportKind reported to the `on_serve_start` hook (default `PIPE`).
+   */
+  async serveConnection(
+    readable: ReadableStream<Uint8Array> | NodeJS.ReadableStream,
+    writable?: number | import("node:net").Socket,
+    transportKind: TransportKind = TransportKind.PIPE,
+  ): Promise<void> {
+    const reader = await IpcStreamReader.create(readable);
+    const writer = new IpcStreamWriter(writable);
 
     try {
       while (true) {
-        // Fire on_serve_start lazily so the hook can do work that
-        // depends on the transport binding (matches Python which fires
-        // it inside serve()). Inside the loop so a failure on the very
+        // Fire on_serve_start lazily so the hook can do work that depends on
+        // the transport binding. Inside the loop so a failure on the very
         // first request can be retried.
-        await this.notifyTransport(TransportKind.PIPE);
+        await this.notifyTransport(transportKind);
         await this.serveOne(reader, writer);
       }
     } catch (e: any) {
-      // EOF or broken pipe → clean exit
+      // EOF or broken pipe / closed channel → clean exit
       if (
         e.message?.includes("closed") ||
         e.message?.includes("Expected Schema Message") ||