@query-farm/vgi-rpc 0.6.4 → 0.7.1

package/src/client/ipc.ts

@@ -7,18 +7,17 @@ import {
   DataType,
   Float64,
   Int64,
-  makeData,
-  RecordBatch,
+  type RecordBatch,
   RecordBatchReader,
   type Schema,
-  Struct,
   Utf8,
-  vectorFromArray,
 } from "@query-farm/apache-arrow";
+import { emptyBatchWithMetadata, singleRowBatchWithMetadata } from "#vgi-rpc-arrow";
 import {
   LOG_EXTRA_KEY,
   LOG_LEVEL_KEY,
   LOG_MESSAGE_KEY,
+  PROTOCOL_VERSION_KEY,
   REQUEST_VERSION,
   REQUEST_VERSION_KEY,
   RPC_METHOD_KEY,
@@ -79,38 +78,49 @@ function coerceForArrow(type: DataType, value: any): any {
 
 /**
  * Build a 1-row Arrow IPC request batch with method metadata.
+ *
+ * When `options.protocolVersion` is non-empty, the value is emitted as
+ * `vgi_rpc.protocol_version` so servers that declare a Protocol-level
+ * version validate the request at the dispatch boundary.
  */
-export function buildRequestIpc(schema: Schema, params: Record<string, any>, method: string): Uint8Array {
+export function buildRequestIpc(
+  schema: Schema,
+  params: Record<string, any>,
+  method: string,
+  options?: { protocolVersion?: string },
+): Uint8Array {
   const metadata = new Map<string, string>();
   metadata.set(RPC_METHOD_KEY, method);
   metadata.set(REQUEST_VERSION_KEY, REQUEST_VERSION);
+  if (options?.protocolVersion) {
+    metadata.set(PROTOCOL_VERSION_KEY, options.protocolVersion);
+  }
 
+  // Build the batch through the impl-agnostic #vgi-rpc-arrow layer so this
+  // works under both backends. `buildRequestIpc` previously constructed an
+  // apache-arrow RecordBatch directly and handed it to `serializeIpcStream`,
+  // which then dispatched to the backend's `serializeBatches`. Under the
+  // browser/worker condition that backend is flechette, and flechette's
+  // `tablesToIPC` cannot read apache-arrow's RecordBatch shape — the cross-
+  // impl mixing was silently broken (no browser tests cover this path; see
+  // test/client/ipc-cross-impl.test.ts). The abstract helpers produce a
+  // 0-row metadata-bearing batch for the empty-schema case (which servers
+  // accept identically to a 1-row × 0-col batch) and a 1-row batch with
+  // coerced field values otherwise.
   if (schema.fields.length === 0) {
-    const structType = new Struct(schema.fields);
-    const data = makeData({
-      type: structType,
-      length: 1,
-      children: [],
-      nullCount: 0,
-    });
-    const batch = new RecordBatch(schema, data, metadata);
+    const batch = emptyBatchWithMetadata(schema, metadata);
     return serializeIpcStream(schema, [batch]);
   }
 
-  const children = schema.fields.map((f) => {
-    const val = coerceForArrow(f.type, params[f.name]);
-    return vectorFromArray([val], f.type).data[0];
-  });
-
-  const structType = new Struct(schema.fields);
-  const data = makeData({
-    type: structType,
-    length: 1,
-    children,
-    nullCount: 0,
-  });
-
-  const batch = new RecordBatch(schema, data, metadata);
+  const coerced: Record<string, any> = {};
+  for (const f of schema.fields) {
+    const raw = params[f.name];
+    // Missing values must be sent as null. arrow-js's typed-array builders
+    // throw "Invalid argument type in ToBigInt" when handed `undefined` for
+    // an Int64 column; null builds a proper validity bitmap entry instead.
+    coerced[f.name] = raw === undefined ? null : coerceForArrow(f.type, raw);
+  }
+  const batch = singleRowBatchWithMetadata(schema, coerced, metadata);
   return serializeIpcStream(schema, [batch]);
 }
 

package/src/client/oauth.ts

@@ -3,14 +3,23 @@
 
 /** RFC 9728 OAuth Protected Resource Metadata (client-side response). */
 export interface OAuthResourceMetadataResponse {
+  /** The protected resource's canonical URL (`resource`). */
   resource: string;
+  /** Authorization-server issuer URLs; the first is used for OIDC discovery (`authorization_servers`). */
   authorizationServers: string[];
+  /** Scopes the resource advertises (`scopes_supported`). */
   scopesSupported?: string[];
+  /** Advertised bearer methods, e.g. `["header"]` (`bearer_methods_supported`). */
   bearerMethodsSupported?: string[];
+  /** JWS algorithms the resource accepts (`resource_signing_alg_values_supported`). */
   resourceSigningAlgValuesSupported?: string[];
+  /** Human-readable resource name (`resource_name`). */
   resourceName?: string;
+  /** Documentation URL for the resource (`resource_documentation`). */
   resourceDocumentation?: string;
+  /** Policy URL for the resource (`resource_policy_uri`). */
   resourcePolicyUri?: string;
+  /** Terms-of-service URL for the resource (`resource_tos_uri`). */
   resourceTosUri?: string;
   /** OAuth client_id advertised by the server. */
   clientId?: string;

package/src/client/pipe.ts

@@ -75,6 +75,13 @@ class PipeIncrementalWriter {
 // PipeStreamSession — lockstep streaming over pipes
 // ---------------------------------------------------------------------------
 
+/**
+ * {@link StreamSession} implementation for the pipe/subprocess transport.
+ * Drives lockstep streaming over a single bidirectional pipe: each
+ * {@link PipeStreamSession.exchange} or iteration step writes one input batch
+ * and reads one output batch. Holds the connection's single-threaded busy lock
+ * until closed.
+ */
 export class PipeStreamSession implements StreamSession {
   private _reader: IpcStreamReader;
   private _writeFn: WriteFn;
@@ -109,6 +116,7 @@ export class PipeStreamSession implements StreamSession {
     this._externalConfig = opts.externalConfig;
   }
 
+  /** The stream's one-time header row, or `null` if the method declares no header. */
   get header(): Record<string, any> | null {
     return this._header;
   }
@@ -125,17 +133,17 @@ export class PipeStreamSession implements StreamSession {
 
       if (batch.numRows === 0) {
         // Check for external location pointer batch
-        if (isExternalLocationBatch(batch)) {
-          return await resolveExternalLocation(batch, this._externalConfig);
+        if (isExternalLocationBatch(batch as any)) {
+          return (await resolveExternalLocation(batch as any, this._externalConfig)) as any;
         }
         // Check if it's a log/error batch. If so, dispatch and continue.
         // Otherwise it's a zero-row data batch — return it.
-        if (dispatchLogOrError(batch, this._onLog)) {
+        if (dispatchLogOrError(batch as any, this._onLog)) {
           continue;
         }
       }
 
-      return batch;
+      return batch as any;
     }
   }
 
@@ -335,6 +343,11 @@ export class PipeStreamSession implements StreamSession {
     }
   }
 
+  /**
+   * End the stream: close the input side (or send an empty stream if nothing
+   * was sent yet) and drain the server's remaining output in the background,
+   * releasing the connection's busy lock once the drain completes.
+   */
   close(): void {
     if (this._closed) return;
     this._closed = true;
@@ -377,6 +390,12 @@ export class PipeStreamSession implements StreamSession {
 // pipeConnect — create an RpcClient over raw readable/writable streams
 // ---------------------------------------------------------------------------
 
+/**
+ * Connect to a vgi-rpc server over a raw bidirectional pipe (a readable stream
+ * of server output plus a writable for client input). The connection is
+ * single-threaded: only one call or stream may be in flight at a time. The
+ * `__describe__` handshake is sent before the reader is opened to avoid deadlock.
+ */
 export function pipeConnect(
   readable: ReadableStream<Uint8Array>,
   writable: PipeWritable,
@@ -389,6 +408,7 @@ export function pipeConnect(
   let readerPromise: Promise<IpcStreamReader> | null = null;
   let methodCache: Map<string, MethodInfo> | null = null;
   let protocolName = "";
+  let serverProtocolVersion = "";
   let _busy = false;
   let _drainPromise: Promise<void> | null = null;
   let closed = false;
@@ -458,8 +478,9 @@ export function pipeConnect(
         throw new Error("EOF reading __describe__ response");
       }
 
-      const desc = await parseDescribeResponse(response.batches, onLog);
+      const desc = await parseDescribeResponse(response.batches as any, onLog);
       protocolName = desc.protocolName;
+      serverProtocolVersion = desc.protocolVersion;
       methodCache = new Map(desc.methods.map((m) => [m.name, m]));
       return methodCache;
     } finally {
@@ -483,7 +504,7 @@ export function pipeConnect(
         const fullParams = { ...(info.defaults ?? {}), ...(params ?? {}) };
 
         // Send request
-        const body = buildRequestIpc(info.paramsSchema, fullParams, method);
+        const body = buildRequestIpc(info.paramsSchema, fullParams, method, { protocolVersion: serverProtocolVersion });
         writeFn(body);
 
         // Read response
@@ -494,7 +515,7 @@ export function pipeConnect(
 
         // Process batches: dispatch logs, resolve external pointers, find result
         let resultBatch: RecordBatch | null = null;
-        for (let batch of response.batches) {
+        for (let batch of response.batches as any[]) {
           if (batch.numRows === 0) {
             if (isExternalLocationBatch(batch)) {
               batch = await resolveExternalLocation(batch, externalConfig);
@@ -537,7 +558,7 @@ export function pipeConnect(
         const fullParams = { ...(info.defaults ?? {}), ...(params ?? {}) };
 
         // Send init request (params as a complete IPC stream)
-        const body = buildRequestIpc(info.paramsSchema, fullParams, method);
+        const body = buildRequestIpc(info.paramsSchema, fullParams, method, { protocolVersion: serverProtocolVersion });
         writeFn(body);
 
         // Read header if method has headerSchema
@@ -545,7 +566,7 @@ export function pipeConnect(
         if (info.headerSchema) {
           const headerStream = await r.readStream();
           if (headerStream) {
-            for (const batch of headerStream.batches) {
+            for (const batch of headerStream.batches as any[]) {
               if (batch.numRows === 0) {
                 dispatchLogOrError(batch, onLog);
                 continue;
@@ -597,6 +618,7 @@ export function pipeConnect(
       const methods = await ensureMethodCache();
       return {
         protocolName,
+        protocolVersion: serverProtocolVersion,
         methods: [...methods.values()],
       };
     },
@@ -613,6 +635,11 @@ export function pipeConnect(
 // subprocessConnect — spawn a process and wrap with pipeConnect
 // ---------------------------------------------------------------------------
 
+/**
+ * Spawn a server process (via `Bun.spawn`) and connect to it over its
+ * stdin/stdout using {@link pipeConnect}. The returned client's
+ * {@link RpcClient.close} also kills the subprocess.
+ */
 export function subprocessConnect(cmd: string[], options?: SubprocessConnectOptions): RpcClient {
   const proc = Bun.spawn(cmd, {
     stdin: "pipe",

package/src/client/stream.ts

@@ -9,9 +9,22 @@ import { ARROW_CONTENT_TYPE, serializeIpcStream } from "../http/common.js";
 import { dispatchLogOrError, extractBatchRows, inferArrowType, readResponseBatches } from "./ipc.js";
 import type { LogMessage, StreamSession } from "./types.js";
 
-type CompressFn = (data: Uint8Array, level: number) => Uint8Array;
-type DecompressFn = (data: Uint8Array) => Uint8Array;
-
+type CompressFn = (data: Uint8Array, level: number) => Promise<Uint8Array>;
+type DecompressFn = (data: Uint8Array) => Promise<Uint8Array>;
+
+/**
+ * Posts an Arrow IPC request body to *url*, transparently handling
+ * client-vended request externalization. Provided by the parent connection
+ * so a single capability cache can drive both unary and stream call paths.
+ */
+export type PostFn = (url: string, body: Uint8Array) => Promise<Response>;
+
+/**
+ * {@link StreamSession} implementation for the HTTP transport. Stream state is
+ * carried statelessly across requests via an HMAC state token: each
+ * {@link HttpStreamSession.exchange} or producer-continuation POST sends the
+ * current token and receives the next one in the response metadata.
+ */
 export class HttpStreamSession implements StreamSession {
   private _baseUrl: string;
   private _prefix: string;
@@ -28,6 +41,7 @@ export class HttpStreamSession implements StreamSession {
   private _decompressFn?: DecompressFn;
   private _authorization?: string;
   private _externalConfig?: ExternalLocationConfig;
+  private _postFn?: PostFn;
 
   constructor(opts: {
     baseUrl: string;
@@ -45,6 +59,7 @@ export class HttpStreamSession implements StreamSession {
     decompressFn?: DecompressFn;
     authorization?: string;
     externalConfig?: ExternalLocationConfig;
+    postFn?: PostFn;
   }) {
     this._baseUrl = opts.baseUrl;
     this._prefix = opts.prefix;
@@ -61,8 +76,19 @@ export class HttpStreamSession implements StreamSession {
     this._decompressFn = opts.decompressFn;
     this._authorization = opts.authorization;
     this._externalConfig = opts.externalConfig;
+    this._postFn = opts.postFn;
   }
 
+  private async _post(url: string, body: Uint8Array): Promise<Response> {
+    if (this._postFn) return this._postFn(url, body);
+    return fetch(url, {
+      method: "POST",
+      headers: this._buildHeaders(),
+      body: (await this._prepareBody(body)) as unknown as BodyInit,
+    });
+  }
+
+  /** The stream's one-time header row, or `null` if the method declares no header. */
   get header(): Record<string, any> | null {
     return this._header;
   }
@@ -71,8 +97,10 @@ export class HttpStreamSession implements StreamSession {
     const headers: Record<string, string> = {
       "Content-Type": ARROW_CONTENT_TYPE,
     };
-    if (this._compressionLevel != null) {
+    if (this._compressionLevel != null && this._compressFn) {
       headers["Content-Encoding"] = "zstd";
+    }
+    if (this._compressionLevel != null && this._decompressFn) {
       headers["Accept-Encoding"] = "zstd";
     }
     if (this._authorization) {
@@ -81,9 +109,9 @@ export class HttpStreamSession implements StreamSession {
     return headers;
   }
 
-  private _prepareBody(content: Uint8Array): Uint8Array {
+  private async _prepareBody(content: Uint8Array): Promise<Uint8Array> {
     if (this._compressionLevel != null && this._compressFn) {
-      return this._compressFn(content, this._compressionLevel);
+      return await this._compressFn(content, this._compressionLevel);
     }
     return content;
   }
@@ -91,7 +119,7 @@ export class HttpStreamSession implements StreamSession {
   private async _readResponse(resp: Response): Promise<Uint8Array<ArrayBuffer>> {
     let body = new Uint8Array(await resp.arrayBuffer());
     if (resp.headers.get("Content-Encoding") === "zstd" && this._decompressFn) {
-      body = new Uint8Array(this._decompressFn(body));
+      body = new Uint8Array(await this._decompressFn(body));
     }
     return body;
   }
@@ -159,11 +187,7 @@ export class HttpStreamSession implements StreamSession {
 
   private async _doExchange(schema: Schema, batches: RecordBatch[]): Promise<Record<string, any>[]> {
     const body = serializeIpcStream(schema, batches);
-    const resp = await fetch(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, {
-      method: "POST",
-      headers: this._buildHeaders(),
-      body: this._prepareBody(body) as unknown as BodyInit,
-    });
+    const resp = await this._post(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, body);
     if (resp.status === 401) {
       throw new RpcError("AuthenticationError", "Authentication required", "");
     }
@@ -218,7 +242,7 @@ export class HttpStreamSession implements StreamSession {
     for (let batch of this._pendingBatches) {
       if (batch.numRows === 0) {
         if (isExternalLocationBatch(batch)) {
-          batch = await resolveExternalLocation(batch, this._externalConfig);
+          batch = (await resolveExternalLocation(batch as any, this._externalConfig)) as any;
         } else {
           dispatchLogOrError(batch, this._onLog);
           continue;
@@ -233,7 +257,9 @@ export class HttpStreamSession implements StreamSession {
 
     // Follow continuation tokens
     while (true) {
-      const responseBody = await this._sendContinuation(this._stateToken);
+      const stateToken = this._stateToken;
+      if (stateToken === null) return;
+      const responseBody = await this._sendContinuation(stateToken);
       const { batches } = await readResponseBatches(responseBody);
 
       let gotContinuation = false;
@@ -248,7 +274,7 @@ export class HttpStreamSession implements StreamSession {
           }
           // Check for external location pointer
           if (isExternalLocationBatch(batch)) {
-            batch = await resolveExternalLocation(batch, this._externalConfig);
+            batch = (await resolveExternalLocation(batch as any, this._externalConfig)) as any;
           } else {
             // Log/error batch
             dispatchLogOrError(batch, this._onLog);
@@ -278,11 +304,7 @@ export class HttpStreamSession implements StreamSession {
     const batch = new RecordBatch(emptySchema, data, metadata);
     const body = serializeIpcStream(emptySchema, [batch]);
 
-    const resp = await fetch(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, {
-      method: "POST",
-      headers: this._buildHeaders(),
-      body: this._prepareBody(body) as unknown as BodyInit,
-    });
+    const resp = await this._post(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, body);
     if (resp.status === 401) {
       throw new RpcError("AuthenticationError", "Authentication required", "");
     }
@@ -290,6 +312,7 @@ export class HttpStreamSession implements StreamSession {
     return this._readResponse(resp);
   }
 
+  /** No-op: the HTTP transport is stateless, so there is nothing to tear down. */
   close(): void {
     // No-op for HTTP (stateless)
   }

package/src/client/types.ts

@@ -1,9 +1,13 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+/** Options for {@link httpConnect}, the HTTP-transport RPC client. */
 export interface HttpConnectOptions {
+  /** Route prefix the server mounts its methods under (e.g. `/api`). Trailing slashes are stripped. Defaults to no prefix. */
   prefix?: string;
+  /** Callback invoked for each log/error message the server emits during a request. */
   onLog?: (msg: LogMessage) => void;
+  /** When set, request bodies are zstd-compressed at this level and `Accept-Encoding: zstd` is sent. Omit to disable compression. */
   compressionLevel?: number;
   /** Authorization header value (e.g. "Bearer <token>"). Sent with every request. */
   authorization?: string;
@@ -11,27 +15,46 @@ export interface HttpConnectOptions {
   externalLocation?: import("../external.js").ExternalLocationConfig;
 }
 
+/** A log or error message delivered to an {@link HttpConnectOptions.onLog} callback. */
 export interface LogMessage {
+  /** Severity, mirroring the server's log level (e.g. `INFO`, `WARNING`, `EXCEPTION`). */
   level: string;
+  /** The human-readable log text. */
   message: string;
+  /** Optional structured fields attached to the log record. */
   extra?: Record<string, any>;
 }
 
+/**
+ * A live streaming method call. Exchange methods drive the server with
+ * {@link StreamSession.exchange}; producer methods are consumed by async
+ * iteration. Always {@link StreamSession.close} when done.
+ */
 export interface StreamSession {
+  /** The method's header row (returned once at stream start), or `null` if the method declares no header. */
   readonly header: Record<string, any> | null;
+  /** Send one batch of input rows and receive the server's corresponding output rows (exchange streams). */
   exchange(input: Record<string, any>[]): Promise<Record<string, any>[]>;
+  /** Iterate the server-produced output batches one row-array at a time (producer streams). */
   [Symbol.asyncIterator](): AsyncIterableIterator<Record<string, any>[]>;
+  /** Tear down the stream, flushing/draining the underlying transport. */
   close(): void;
 }
 
+/** Options for {@link pipeConnect}, the client over raw readable/writable streams. */
 export interface PipeConnectOptions {
+  /** Callback invoked for each log/error message the server emits during a request. */
   onLog?: (msg: LogMessage) => void;
   /** External storage config for resolving externalized batches. */
   externalLocation?: import("../external.js").ExternalLocationConfig;
 }
 
+/** Options for {@link subprocessConnect}, which spawns a server process and pipes to it. */
 export interface SubprocessConnectOptions extends PipeConnectOptions {
+  /** Working directory for the spawned process. Defaults to the current directory. */
   cwd?: string;
+  /** Extra environment variables, merged over the current `process.env`. */
   env?: Record<string, string>;
+  /** How to handle the child's stderr. Defaults to `"ignore"`. */
   stderr?: "inherit" | "pipe" | "ignore";
 }

package/src/client/uploadUrl.ts

@@ -0,0 +1,169 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Client-side request-body externalization.
+ *
+ * When a request body would exceed the server-advertised `maxRequestBytes`,
+ * we (1) call `{prefix}/__upload_url__/init` to get a pre-signed upload URL,
+ * (2) PUT the body to that URL, and (3) replace the inline body with a
+ * zero-row "pointer" IPC stream that carries the original RPC dispatch
+ * metadata plus `vgi_rpc.location: <download-url>`. The server then resolves
+ * the pointer and dispatches normally.
+ *
+ * Mirrors Python's `_externalize_via_upload_url()` and `request_upload_urls()`.
+ */
+
+import { Field, Int64, RecordBatchReader, Schema } from "@query-farm/apache-arrow";
+import { REQUEST_VERSION, REQUEST_VERSION_KEY, RPC_METHOD_KEY } from "../constants.js";
+import { RpcError } from "../errors.js";
+import { makeExternalLocationBatch } from "../external.js";
+import { ARROW_CONTENT_TYPE, serializeIpcStream } from "../http/common.js";
+import { buildRequestIpc } from "./ipc.js";
+
+const UPLOAD_URL_METHOD = "__upload_url__";
+const UPLOAD_URL_PARAMS_SCHEMA = new Schema([new Field("count", new Int64(), false)]);
+
+export interface UploadUrlPair {
+  uploadUrl: string;
+  downloadUrl: string;
+  expiresAt: Date;
+}
+
+/**
+ * POST `__upload_url__/init` and return the requested number of pre-signed
+ * URL pairs. Server must have an `uploadUrlProvider` configured; otherwise
+ * the route returns 404 and we surface that as `RpcError("NotSupported")`.
+ */
+export async function requestUploadUrls(
+  baseUrl: string,
+  prefix: string,
+  count: number,
+  authorization?: string,
+): Promise<UploadUrlPair[]> {
+  const body = buildRequestIpc(UPLOAD_URL_PARAMS_SCHEMA, { count: BigInt(count) }, UPLOAD_URL_METHOD);
+  const headers: Record<string, string> = { "Content-Type": ARROW_CONTENT_TYPE };
+  if (authorization) headers.Authorization = authorization;
+
+  const resp = await fetch(`${baseUrl}${prefix}/${UPLOAD_URL_METHOD}/init`, {
+    method: "POST",
+    headers,
+    body: body as unknown as BodyInit,
+  });
+  if (resp.status === 404) {
+    throw new RpcError("NotSupported", "Server does not support upload URLs", "");
+  }
+  if (resp.status === 401) {
+    throw new RpcError("AuthenticationError", "Authentication required", "");
+  }
+  if (!resp.ok) {
+    throw new RpcError("HttpError", `__upload_url__/init failed: HTTP ${resp.status}`, "");
+  }
+
+  const respBody = new Uint8Array(await resp.arrayBuffer());
+  const reader = await RecordBatchReader.from(respBody);
+  await reader.open();
+
+  const pairs: UploadUrlPair[] = [];
+  for (const batch of reader.readAll()) {
+    if (batch.numRows === 0) continue;
+    for (let r = 0; r < batch.numRows; r++) {
+      const uploadUrl = batch.getChildAt(0)?.get(r) as string;
+      const downloadUrl = batch.getChildAt(1)?.get(r) as string;
+      const expiresRaw = batch.getChildAt(2)?.get(r);
+      // Timestamp(us) → either a Date, a number (ms), or a bigint (us)
+      let expiresAt: Date;
+      if (expiresRaw instanceof Date) {
+        expiresAt = expiresRaw;
+      } else if (typeof expiresRaw === "bigint") {
+        expiresAt = new Date(Number(expiresRaw / 1000n));
+      } else if (typeof expiresRaw === "number") {
+        expiresAt = new Date(expiresRaw);
+      } else {
+        expiresAt = new Date();
+      }
+      pairs.push({ uploadUrl, downloadUrl, expiresAt });
+    }
+  }
+
+  if (pairs.length === 0) {
+    throw new RpcError("ProtocolError", "Server returned no upload URLs", "");
+  }
+  return pairs;
+}
+
+/**
+ * Build the externalized pointer body to send in place of *originalBody*.
+ *
+ * The pointer is a zero-row IPC stream whose first batch carries:
+ *   - same schema as the original request batch
+ *   - merged custom_metadata: original RPC dispatch keys + `vgi_rpc.location`
+ *
+ * The server's request reader honours the dispatch keys for routing, then
+ * resolves the pointer to fetch the inline batch for parameter extraction.
+ */
+async function buildPointerRequestBody(originalBody: Uint8Array, downloadUrl: string): Promise<Uint8Array> {
+  const reader = await RecordBatchReader.from(originalBody);
+  await reader.open();
+  const schema = reader.schema;
+  if (!schema) {
+    throw new RpcError("ProtocolError", "Original request body has no schema", "");
+  }
+  const batches = reader.readAll();
+  if (batches.length === 0) {
+    throw new RpcError("ProtocolError", "Original request body has no batches", "");
+  }
+  const original = batches[0];
+  const originalMeta = original.metadata ?? new Map<string, string>();
+
+  const pointer = makeExternalLocationBatch(schema, downloadUrl);
+  const merged = new Map<string, string>(pointer.metadata ?? new Map());
+  // Preserve the original RPC dispatch metadata so the server can route.
+  const method = originalMeta.get(RPC_METHOD_KEY);
+  const version = originalMeta.get(REQUEST_VERSION_KEY) ?? REQUEST_VERSION;
+  if (method) merged.set(RPC_METHOD_KEY, method);
+  merged.set(REQUEST_VERSION_KEY, version);
+  // Carry over any other keys (request id, state token for exchange, etc).
+  for (const [k, v] of originalMeta) {
+    if (!merged.has(k)) merged.set(k, v);
+  }
+
+  // Re-emit the pointer batch with merged metadata.
+  const { RecordBatch } = await import("@query-farm/apache-arrow");
+  const pointerWithMeta = new RecordBatch(schema as any, (pointer as any).data, merged);
+  return serializeIpcStream(schema, [pointerWithMeta]);
+}
+
+export interface ExternalizeOptions {
+  baseUrl: string;
+  prefix: string;
+  authorization?: string;
+  /** Optional per-URL validator; throw to reject. */
+  urlValidator?: ((url: string) => void) | null;
+}
+
+/**
+ * Upload *body* via a server-vended URL and return the pointer-batch body
+ * that should be sent in place of the original. Throws if the server does
+ * not advertise upload-URL support or the upload fails.
+ */
+export async function externalizeRequestBody(body: Uint8Array, opts: ExternalizeOptions): Promise<Uint8Array> {
+  const pairs = await requestUploadUrls(opts.baseUrl, opts.prefix, 1, opts.authorization);
+  const pair = pairs[0];
+
+  if (opts.urlValidator) {
+    opts.urlValidator(pair.uploadUrl);
+    opts.urlValidator(pair.downloadUrl);
+  }
+
+  const putResp = await fetch(pair.uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": ARROW_CONTENT_TYPE },
+    body: body as unknown as BodyInit,
+  });
+  if (!putResp.ok) {
+    throw new RpcError("ExternalUploadFailed", `PUT to upload URL failed: HTTP ${putResp.status}`, "");
+  }
+
+  return buildPointerRequestBody(body, pair.downloadUrl);
+}