Client Transports

The vgi-rpc client library provides HTTP, HTTP-over-Iroh, raw Iroh, subprocess, pipe, and raw-TCP connect functions that all return the same RpcClient interface. Pick the transport that fits your deployment and use call(), stream(), describe(), and close() identically across all of them.

Note

This page covers the client-side connect functions. To serve over an AF_UNIX socket via the launcher (serveUnix), see the Unix Socket Launcher guide.

Tip

For setting up an HTTP server, see the HTTP Transport server guide.

RpcClient interface

interface RpcClient {
  call(method: string, params?: Record<string, any>): Promise<Record<string, any> | null>;
  stream(method: string, params?: Record<string, any>): Promise<StreamSession>;
  describe(): Promise<ServiceDescription>;
  close(): void;
}

HTTP Transport

Use httpConnect to talk to a running HTTP server:

import { httpConnect } from "@query-farm/vgi-rpc";

const client = httpConnect("http://localhost:8080", {
  prefix: "/vgi",          // URL path prefix (default: "" — root)
  compressionLevel: 3,     // zstd compression (omit to disable)
  authorization: "Bearer <token>", // sent as the Authorization header
  onLog: (msg) => console.log(`[${msg.level}] ${msg.message}`),
});

const result = await client.call("add", { a: 2, b: 3 });
console.log(result); // { result: 5 }

client.close();

HTTP transport is stateless — stream continuity is managed via XChaCha20-Poly1305 AEAD-sealed state tokens exchanged in batch metadata.

The authorization option (HTTP only) sets the Authorization request header. All three connect functions also accept an externalLocation option for configuring out-of-band data transfer locations.

HTTP over Iroh (Node/Bun)

httpiConnect runs the complete VGI HTTP client over the iroh-http/2 ALPN. Install the optional native binding first:

bun add @momics/iroh-http-node

Then connect with the worker’s canonical 64-lowercase-hex EndpointId:

import { httpiConnect } from "@query-farm/vgi-rpc";

const client = await httpiConnect(
  "httpi://0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/vgi",
  {
    directAddresses: ["192.0.2.10:4433"], // optional discovery hints
    remoteRelayUrl: "https://relay.example",
    requestTimeoutMs: 30_000,
    authorization: "Bearer <token>",
  },
);

const result = await client.call("add", { a: 2, b: 3 });
client.close();

The connector converts the canonical hex EndpointId to iroh-http’s native base-32 hostname internally. OPTIONS capability discovery, VGI continuations, authorization, compression, response-size negotiation, and external-location fetches all remain handled by the ordinary HTTP client. The native adapter limits each HTTP response to 256 MiB, so acceptedMaxResponseBytes cannot be configured above that value.

By default the connector creates, owns, and closes an Iroh node. Pass node to reuse an application-owned node; it remains open unless closeNode: true is set. Use externalFetch when external-location URLs need a custom non-Iroh fetch implementation.

This binding targets Node/Bun. It is not bundled into browser entry points; browser Iroh support uses the Rust/WASM connector.

Raw Iroh (Node/Bun)

Use irohConnect("iroh://<64-hex-endpoint-id>") with the optional @number0/iroh native binding when both peers speak VGI Arrow mux directly. Unlike HTTP-over-Iroh, this is connection-stateful and does not use the HTTP OPTIONS or continuation protocol.

SOCKS5h (Node/Bun)

The Node/Bun entry point provides explicit credential-free SOCKS5h constructors for HTTP and raw TCP:

import { httpConnectSocks5h, tcpConnectSocks5h } from "@query-farm/vgi-rpc";

const http = httpConnectSocks5h(
  "https://worker.example.internal",
  "socks5h://127.0.0.1:1080",
  {
    connectTimeoutMs: 5_000,
    requestTimeoutMs: 300_000,
    maxResponseBytes: 268_435_456,
    maxResponseHeaderBytes: 65_536,
    signal: abortController.signal,
  },
);

const tcp = await tcpConnectSocks5h(
  "worker.example.internal",
  9400,
  "socks5h://127.0.0.1:1080",
  { connectTimeoutMs: 5_000, signal: abortController.signal },
);

Only the SOCKS NO AUTH method is offered. Proxy URIs with credentials, paths, queries, or fragments are rejected before dialing. Target domains are IDNA-normalized and sent as SOCKS domain names for proxy-side resolution; IPv4 and IPv6 literals use their native SOCKS address types. One request deadline covers setup, request writes, and the complete response; the smaller setup deadline additionally caps proxy TCP connection, the complete partial-I/O-safe negotiation, and (for HTTPS) TLS setup. Failure or cancellation destroys the socket and never retries directly. TCP_NODELAY is enabled.

The HTTP adapter buffers one response under maxResponseBytes and independently bounds its headers with maxResponseHeaderBytes. It accepts exactly one Content-Length or one final Transfer-Encoding: chunked, rejects ambiguous/conflicting framing, and does not support streaming request bodies. Tune the limits to the largest VGI batch your worker is expected to return.

httpConnectSocks5h routes every HTTP operation owned by the RPC client through the adapter: description, unary and streaming turns, upload-URL acquisition and PUT, and external-location GETs. It does not consult HTTP_PROXY, HTTPS_PROXY, or NO_PROXY. A custom ExternalStorage.upload() implementation is application code rather than an SDK HTTP boundary and is not intercepted.

There is no SOCKS server/listener mode: SOCKS is an outbound dialer. Browser and Worker entry points omit it because their fetch implementations do not expose a TCP dialer.

Subprocess Transport

Use subprocessConnect to spawn a server process and communicate over its stdin/stdout pipes:

import { subprocessConnect } from "@query-farm/vgi-rpc";

const client = subprocessConnect(["bun", "run", "server.ts"], {
  cwd: "./my-project",                // working directory
  env: { DEBUG: "1" },                // extra environment variables
  stderr: "inherit",                  // "inherit" | "pipe" | "ignore" (default: "ignore")
  onLog: (msg) => console.log(msg),
});

const result = await client.call("greet", { name: "World" });
console.log(result); // { result: "Hello, World!" }

client.close(); // kills the subprocess

Pipe Transport

Use pipeConnect for low-level control when you already have a ReadableStream and writable sink:

import { pipeConnect } from "@query-farm/vgi-rpc";

const client = pipeConnect(readable, writable, {
  onLog: (msg) => console.log(msg),
});

const result = await client.call("echo", { text: "hello" });
client.close();

The pipe transport is single-threaded: only one call() or stream() operation can be in flight at a time. Attempting a concurrent operation throws an error.

Unary Calls

All transports use the same call() method for unary requests:

const result = await client.call("add", { a: 2, b: 3 });
// result: { result: 5 }

• Default parameter values from the method definition are applied automatically.
• Void methods (empty result schema) return null.

Streaming

Producer (async iteration)

For server-streaming methods, use stream() and iterate:

const session = await client.stream("count", { limit: 5 });

// Access the stream header (if the method defines headerSchema)
if (session.header) {
  console.log("Header:", session.header);
}

// Iterate over output batches
for await (const rows of session) {
  console.log(rows); // [{ n: 0, n_squared: 0 }, { n: 1, n_squared: 1 }, ...]
}

Exchange (bidirectional)

For exchange methods, use exchange() to send input batches and receive output:

const session = await client.stream("scale", { factor: 2 });

const output = await session.exchange([{ value: 10 }]);
console.log(output); // [{ value: 20 }]

const output2 = await session.exchange([{ value: 5 }]);
console.log(output2); // [{ value: 10 }]

session.close();

StreamSession interface

interface StreamSession {
  readonly header: Record<string, any> | null;
  exchange(input: Record<string, any>[]): Promise<Record<string, any>[]>;
  [Symbol.asyncIterator](): AsyncIterableIterator<Record<string, any>[]>;
  close(): void;
}

Service Introspection

Every RpcClient has a describe() method:

const desc = await client.describe();
console.log(desc.protocolName);    // "Calculator"
console.log(desc.protocolVersion); // server-declared protocol version

for (const method of desc.methods) {
  console.log(`${method.name} (${method.type})`);
  // method.paramsSchema, method.resultSchema, and (for stream methods)
  // method.inputSchema / method.outputSchema / method.headerSchema
}

For standalone HTTP introspection without creating a full client:

import { httpIntrospect } from "@query-farm/vgi-rpc";

const desc = await httpIntrospect("http://localhost:8080", { prefix: "/vgi" });

For custom transports, parse raw describe batches:

import { parseDescribeResponse } from "@query-farm/vgi-rpc";

const desc = await parseDescribeResponse(batches, onLog);

Caution

ServiceDescription returns protocolName, protocolVersion, and methods: MethodInfo[]. Under the slim DESCRIBE v4 wire schema, the doc, paramTypes, and defaults fields on MethodInfo are no longer carried on the wire, so they come back undefined at runtime even though the type still declares them. Treat the schema fields (paramsSchema, resultSchema, inputSchema, outputSchema, headerSchema) as the reliable source of method shape.

Log Messages

All transports accept an onLog callback that receives log messages sent by the server during method execution:

import { httpConnect } from "@query-farm/vgi-rpc";

const client = httpConnect("http://localhost:8080", {
  onLog: (msg) => {
    console.log(`[${msg.level}] ${msg.message}`);
    if (msg.extra) console.log("  extra:", msg.extra);
  },
});

interface LogMessage {
  level: string;
  message: string;
  extra?: Record<string, any>;
}