@query-farm/vgi-rpc 0.4.0 → 0.6.0

package/dist/index.js

@@ -103,21 +103,247 @@ var SERVER_ID_KEY = "vgi_rpc.server_id";
 var REQUEST_ID_KEY = "vgi_rpc.request_id";
 var PROTOCOL_NAME_KEY = "vgi_rpc.protocol_name";
 var DESCRIBE_VERSION_KEY = "vgi_rpc.describe_version";
-var DESCRIBE_VERSION = "2";
+var DESCRIBE_VERSION = "3";
 var DESCRIBE_METHOD_NAME = "__describe__";
 var STATE_KEY = "vgi_rpc.stream_state#b64";
+var LOCATION_KEY = "vgi_rpc.location";
+var LOCATION_SHA256_KEY = "vgi_rpc.location.sha256";
 
-// src/http/common.ts
+// src/external.ts
 import { RecordBatchReader, RecordBatchStreamWriter } from "@query-farm/apache-arrow";
+init_zstd();
 
-// src/util/conform.ts
+// src/wire/response.ts
 import {
+  Data,
+  DataType,
   makeData,
   RecordBatch,
   Struct,
-  Type,
   vectorFromArray
 } from "@query-farm/apache-arrow";
+function coerceInt64(schema, values) {
+  const result = { ...values };
+  for (const field of schema.fields) {
+    const val = result[field.name];
+    if (val === undefined)
+      continue;
+    if (!DataType.isInt(field.type) || field.type.bitWidth !== 64)
+      continue;
+    if (Array.isArray(val)) {
+      result[field.name] = val.map((v) => typeof v === "number" ? BigInt(v) : v);
+    } else if (typeof val === "number") {
+      result[field.name] = BigInt(val);
+    }
+  }
+  return result;
+}
+function buildResultBatch(schema, values, serverId, requestId) {
+  const metadata = new Map;
+  metadata.set(SERVER_ID_KEY, serverId);
+  if (requestId !== null) {
+    metadata.set(REQUEST_ID_KEY, requestId);
+  }
+  if (schema.fields.length === 0) {
+    return buildEmptyBatch(schema, metadata);
+  }
+  for (const field of schema.fields) {
+    if (values[field.name] === undefined && !field.nullable) {
+      const got = Object.keys(values);
+      throw new TypeError(`Handler result missing required field '${field.name}'. Got keys: [${got.join(", ")}]`);
+    }
+  }
+  const coerced = coerceInt64(schema, values);
+  const children = schema.fields.map((f) => {
+    const val = coerced[f.name];
+    if (val instanceof Data) {
+      return val;
+    }
+    const arr = vectorFromArray([val], f.type);
+    return arr.data[0];
+  });
+  const structType = new Struct(schema.fields);
+  const data = makeData({
+    type: structType,
+    length: 1,
+    children,
+    nullCount: 0
+  });
+  return new RecordBatch(schema, data, metadata);
+}
+function buildErrorBatch(schema, error, serverId, requestId) {
+  const metadata = new Map;
+  metadata.set(LOG_LEVEL_KEY, "EXCEPTION");
+  metadata.set(LOG_MESSAGE_KEY, `${error.constructor.name}: ${error.message}`);
+  const extra = {
+    exception_type: error.constructor.name,
+    exception_message: error.message,
+    traceback: error.stack ?? ""
+  };
+  metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
+  metadata.set(SERVER_ID_KEY, serverId);
+  if (requestId !== null) {
+    metadata.set(REQUEST_ID_KEY, requestId);
+  }
+  return buildEmptyBatch(schema, metadata);
+}
+function buildLogBatch(schema, level, message, extra, serverId, requestId) {
+  const metadata = new Map;
+  metadata.set(LOG_LEVEL_KEY, level);
+  metadata.set(LOG_MESSAGE_KEY, message);
+  if (extra) {
+    metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
+  }
+  if (serverId != null) {
+    metadata.set(SERVER_ID_KEY, serverId);
+  }
+  if (requestId != null) {
+    metadata.set(REQUEST_ID_KEY, requestId);
+  }
+  return buildEmptyBatch(schema, metadata);
+}
+function makeEmptyData(type) {
+  if (DataType.isStruct(type)) {
+    const children = type.children.map((f) => makeEmptyData(f.type));
+    return makeData({ type, length: 0, children, nullCount: 0 });
+  }
+  if (DataType.isList(type)) {
+    const childData = makeEmptyData(type.children[0].type);
+    return makeData({ type, length: 0, children: [childData], nullCount: 0, valueOffsets: new Int32Array([0]) });
+  }
+  if (DataType.isFixedSizeList(type)) {
+    const childData = makeEmptyData(type.children[0].type);
+    return makeData({ type, length: 0, child: childData, nullCount: 0 });
+  }
+  if (DataType.isMap(type)) {
+    const entryType = type.children[0]?.type;
+    const entryData = entryType ? makeEmptyData(entryType) : makeData({ type: new Struct([]), length: 0, children: [], nullCount: 0 });
+    return makeData({ type, length: 0, children: [entryData], nullCount: 0, valueOffsets: new Int32Array([0]) });
+  }
+  return makeData({ type, length: 0, nullCount: 0 });
+}
+function buildEmptyBatch(schema, metadata) {
+  const children = schema.fields.map((f) => makeEmptyData(f.type));
+  const structType = new Struct(schema.fields);
+  const data = makeData({
+    type: structType,
+    length: 0,
+    children,
+    nullCount: 0
+  });
+  return new RecordBatch(schema, data, metadata);
+}
+
+// src/external.ts
+var DEFAULT_THRESHOLD = 1048576;
+function httpsOnlyValidator(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:") {
+    throw new Error(`External location URL must use HTTPS, got "${parsed.protocol}"`);
+  }
+}
+async function sha256Hex(data) {
+  const buf = new ArrayBuffer(data.byteLength);
+  new Uint8Array(buf).set(data);
+  const hash = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function isExternalLocationBatch(batch) {
+  if (batch.numRows !== 0)
+    return false;
+  const meta = batch.metadata;
+  if (!meta)
+    return false;
+  return meta.has(LOCATION_KEY) && !meta.has(LOG_LEVEL_KEY);
+}
+function makeExternalLocationBatch(schema, url, sha256) {
+  const metadata = new Map;
+  metadata.set(LOCATION_KEY, url);
+  if (sha256) {
+    metadata.set(LOCATION_SHA256_KEY, sha256);
+  }
+  return buildEmptyBatch(schema, metadata);
+}
+function serializeBatchToIpc(batch) {
+  const writer = new RecordBatchStreamWriter;
+  writer.reset(undefined, batch.schema);
+  writer.write(batch);
+  writer.close();
+  return writer.toUint8Array(true);
+}
+function batchByteSize(batch) {
+  const writer = new RecordBatchStreamWriter;
+  writer.reset(undefined, batch.schema);
+  writer.write(batch);
+  writer.close();
+  return writer.toUint8Array(true).byteLength;
+}
+async function maybeExternalizeBatch(batch, config) {
+  if (!config?.storage)
+    return batch;
+  if (batch.numRows === 0)
+    return batch;
+  const threshold = config.externalizeThresholdBytes ?? DEFAULT_THRESHOLD;
+  if (batchByteSize(batch) < threshold)
+    return batch;
+  let ipcData = serializeBatchToIpc(batch);
+  const checksum = await sha256Hex(ipcData);
+  let contentEncoding = "";
+  if (config.compression?.algorithm === "zstd") {
+    ipcData = zstdCompress(ipcData, config.compression.level ?? 3);
+    contentEncoding = "zstd";
+  }
+  const url = await config.storage.upload(ipcData, contentEncoding);
+  return makeExternalLocationBatch(batch.schema, url, checksum);
+}
+async function resolveExternalLocation(batch, config) {
+  if (!config)
+    return batch;
+  if (!isExternalLocationBatch(batch))
+    return batch;
+  const url = batch.metadata?.get(LOCATION_KEY);
+  if (!url)
+    return batch;
+  const validator = config.urlValidator === null ? undefined : config.urlValidator ?? httpsOnlyValidator;
+  if (validator) {
+    validator(url);
+  }
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`External location fetch failed: ${response.status} ${response.statusText} [url: ${url}]`);
+  }
+  let data = new Uint8Array(await response.arrayBuffer());
+  const contentEncoding = response.headers.get("Content-Encoding");
+  if (contentEncoding === "zstd") {
+    data = new Uint8Array(zstdDecompress(data));
+  }
+  const expectedSha256 = batch.metadata?.get(LOCATION_SHA256_KEY);
+  if (expectedSha256) {
+    const actualSha256 = await sha256Hex(data);
+    if (actualSha256 !== expectedSha256) {
+      throw new Error(`SHA-256 checksum mismatch for ${url}: expected ${expectedSha256}, got ${actualSha256}`);
+    }
+  }
+  const reader = await RecordBatchReader.from(data);
+  await reader.open();
+  const resolved = reader.next();
+  if (!resolved || resolved.done || !resolved.value) {
+    throw new Error(`No data batch found in external IPC stream from ${url}`);
+  }
+  return resolved.value;
+}
+
+// src/http/common.ts
+import { RecordBatchReader as RecordBatchReader2, RecordBatchStreamWriter as RecordBatchStreamWriter2 } from "@query-farm/apache-arrow";
+
+// src/util/conform.ts
+import {
+  makeData as makeData2,
+  RecordBatch as RecordBatch2,
+  Struct as Struct2,
+  Type,
+  vectorFromArray as vectorFromArray2
+} from "@query-farm/apache-arrow";
 function needsValueCast(src, dst) {
   if (src.typeId === dst.typeId)
     return false;
@@ -153,19 +379,19 @@ function conformBatchToSchema(batch, schema) {
         const v = col.get(r);
         values.push(typeof v === "bigint" ? Number(v) : v);
       }
-      return vectorFromArray(values, dstType).data[0];
+      return vectorFromArray2(values, dstType).data[0];
     }
     return srcChild.clone(dstType);
   });
-  const structType = new Struct(schema.fields);
-  const data = makeData({
+  const structType = new Struct2(schema.fields);
+  const data = makeData2({
     type: structType,
     length: batch.numRows,
     children,
     nullCount: batch.data.nullCount,
     nullBitmap: batch.data.nullBitmap
   });
-  return new RecordBatch(schema, data, batch.metadata);
+  return new RecordBatch2(schema, data, batch.metadata);
 }
 
 // src/http/common.ts
@@ -180,7 +406,7 @@ class HttpRpcError extends Error {
   }
 }
 function serializeIpcStream(schema, batches) {
-  const writer = new RecordBatchStreamWriter;
+  const writer = new RecordBatchStreamWriter2;
   writer.reset(undefined, schema);
   for (const batch of batches) {
     writer.write(conformBatchToSchema(batch, schema));
@@ -194,7 +420,7 @@ function arrowResponse(body, status = 200, extraHeaders) {
   return new Response(body, { status, headers });
 }
 async function readRequestFromBody(body) {
-  const reader = await RecordBatchReader.from(body);
+  const reader = await RecordBatchReader2.from(body);
   await reader.open();
   const schema = reader.schema;
   if (!schema) {
@@ -208,25 +434,25 @@ async function readRequestFromBody(body) {
 }
 
 // src/client/introspect.ts
-import { Schema as ArrowSchema, RecordBatchReader as RecordBatchReader4 } from "@query-farm/apache-arrow";
+import { Schema as ArrowSchema, RecordBatchReader as RecordBatchReader5 } from "@query-farm/apache-arrow";
 
 // src/client/ipc.ts
 import {
   Binary,
   Bool,
-  DataType,
+  DataType as DataType2,
   Float64,
   Int64,
-  makeData as makeData2,
-  RecordBatch as RecordBatch2,
-  RecordBatchReader as RecordBatchReader3,
-  Struct as Struct2,
+  makeData as makeData3,
+  RecordBatch as RecordBatch3,
+  RecordBatchReader as RecordBatchReader4,
+  Struct as Struct3,
   Utf8,
-  vectorFromArray as vectorFromArray2
+  vectorFromArray as vectorFromArray3
 } from "@query-farm/apache-arrow";
 
 // src/wire/reader.ts
-import { RecordBatchReader as RecordBatchReader2 } from "@query-farm/apache-arrow";
+import { RecordBatchReader as RecordBatchReader3 } from "@query-farm/apache-arrow";
 
 class IpcStreamReader {
   reader;
@@ -236,7 +462,7 @@ class IpcStreamReader {
     this.reader = reader;
   }
   static async create(input) {
-    const reader = await RecordBatchReader2.from(input);
+    const reader = await RecordBatchReader3.from(input);
     await reader.open({ autoDestroy: false });
     if (reader.closed) {
       throw new Error("Input stream closed before first IPC message");
@@ -313,12 +539,12 @@ function inferArrowType(value) {
 function coerceForArrow(type, value) {
   if (value == null)
     return value;
-  if (DataType.isInt(type) && type.bitWidth === 64) {
+  if (DataType2.isInt(type) && type.bitWidth === 64) {
     if (typeof value === "number")
       return BigInt(value);
     return value;
   }
-  if (DataType.isMap(type)) {
+  if (DataType2.isMap(type)) {
     if (value instanceof Map) {
       const entriesField = type.children[0];
       const valueType = entriesField.type.children[1].type;
@@ -330,7 +556,7 @@ function coerceForArrow(type, value) {
     }
     return value;
   }
-  if (DataType.isList(type)) {
+  if (DataType2.isList(type)) {
     if (Array.isArray(value)) {
       const elemType = type.children[0].type;
       return value.map((v) => coerceForArrow(elemType, v));
@@ -344,32 +570,32 @@ function buildRequestIpc(schema, params, method) {
   metadata.set(RPC_METHOD_KEY, method);
   metadata.set(REQUEST_VERSION_KEY, REQUEST_VERSION);
   if (schema.fields.length === 0) {
-    const structType2 = new Struct2(schema.fields);
-    const data2 = makeData2({
+    const structType2 = new Struct3(schema.fields);
+    const data2 = makeData3({
       type: structType2,
       length: 1,
       children: [],
       nullCount: 0
     });
-    const batch2 = new RecordBatch2(schema, data2, metadata);
+    const batch2 = new RecordBatch3(schema, data2, metadata);
     return serializeIpcStream(schema, [batch2]);
   }
   const children = schema.fields.map((f) => {
     const val = coerceForArrow(f.type, params[f.name]);
-    return vectorFromArray2([val], f.type).data[0];
+    return vectorFromArray3([val], f.type).data[0];
   });
-  const structType = new Struct2(schema.fields);
-  const data = makeData2({
+  const structType = new Struct3(schema.fields);
+  const data = makeData3({
     type: structType,
     length: 1,
     children,
     nullCount: 0
   });
-  const batch = new RecordBatch2(schema, data, metadata);
+  const batch = new RecordBatch3(schema, data, metadata);
   return serializeIpcStream(schema, [batch]);
 }
 async function readResponseBatches(body) {
-  const reader = await RecordBatchReader3.from(body);
+  const reader = await RecordBatchReader4.from(body);
   await reader.open();
   const schema = reader.schema;
   if (!schema) {
@@ -443,7 +669,7 @@ async function readSequentialStreams(body) {
 
 // src/client/introspect.ts
 async function deserializeSchema(bytes) {
-  const reader = await RecordBatchReader4.from(bytes);
+  const reader = await RecordBatchReader5.from(bytes);
   await reader.open();
   return reader.schema;
 }
@@ -507,7 +733,7 @@ async function parseDescribeResponse(batches, onLog) {
   return { protocolName, methods };
 }
 async function httpIntrospect(baseUrl, options) {
-  const prefix = options?.prefix ?? "/vgi";
+  const prefix = options?.prefix ?? "";
   const emptySchema = new ArrowSchema([]);
   const body = buildRequestIpc(emptySchema, {}, DESCRIBE_METHOD_NAME);
   const headers = { "Content-Type": ARROW_CONTENT_TYPE };
@@ -528,7 +754,7 @@ async function httpIntrospect(baseUrl, options) {
 }
 
 // src/client/stream.ts
-import { Field, makeData as makeData3, RecordBatch as RecordBatch3, Schema, Struct as Struct3, vectorFromArray as vectorFromArray3 } from "@query-farm/apache-arrow";
+import { Field, makeData as makeData4, RecordBatch as RecordBatch4, Schema, Struct as Struct4, vectorFromArray as vectorFromArray4 } from "@query-farm/apache-arrow";
 class HttpStreamSession {
   _baseUrl;
   _prefix;
@@ -544,6 +770,7 @@ class HttpStreamSession {
   _compressFn;
   _decompressFn;
   _authorization;
+  _externalConfig;
   constructor(opts) {
     this._baseUrl = opts.baseUrl;
     this._prefix = opts.prefix;
@@ -559,6 +786,7 @@ class HttpStreamSession {
     this._compressFn = opts.compressFn;
     this._decompressFn = opts.decompressFn;
     this._authorization = opts.authorization;
+    this._externalConfig = opts.externalConfig;
   }
   get header() {
     return this._header;
@@ -598,7 +826,7 @@ class HttpStreamSession {
       const emptyBatch = this._buildEmptyBatch(zeroSchema);
       const metadata2 = new Map;
       metadata2.set(STATE_KEY, this._stateToken);
-      const batchWithMeta = new RecordBatch3(zeroSchema, emptyBatch.data, metadata2);
+      const batchWithMeta = new RecordBatch4(zeroSchema, emptyBatch.data, metadata2);
       return this._doExchange(zeroSchema, [batchWithMeta]);
     }
     const keys = Object.keys(input[0]);
@@ -617,10 +845,10 @@ class HttpStreamSession {
     const inputSchema = new Schema(fields);
     const children = inputSchema.fields.map((f) => {
       const values = input.map((row) => row[f.name]);
-      return vectorFromArray3(values, f.type).data[0];
+      return vectorFromArray4(values, f.type).data[0];
     });
-    const structType = new Struct3(inputSchema.fields);
-    const data = makeData3({
+    const structType = new Struct4(inputSchema.fields);
+    const data = makeData4({
       type: structType,
       length: input.length,
       children,
@@ -628,7 +856,7 @@ class HttpStreamSession {
     });
     const metadata = new Map;
     metadata.set(STATE_KEY, this._stateToken);
-    const batch = new RecordBatch3(inputSchema, data, metadata);
+    const batch = new RecordBatch4(inputSchema, data, metadata);
     return this._doExchange(inputSchema, [batch]);
   }
   async _doExchange(schema, batches) {
@@ -663,22 +891,26 @@ class HttpStreamSession {
   }
   _buildEmptyBatch(schema) {
     const children = schema.fields.map((f) => {
-      return makeData3({ type: f.type, length: 0, nullCount: 0 });
+      return makeData4({ type: f.type, length: 0, nullCount: 0 });
     });
-    const structType = new Struct3(schema.fields);
-    const data = makeData3({
+    const structType = new Struct4(schema.fields);
+    const data = makeData4({
       type: structType,
       length: 0,
       children,
       nullCount: 0
     });
-    return new RecordBatch3(schema, data);
+    return new RecordBatch4(schema, data);
   }
   async* [Symbol.asyncIterator]() {
-    for (const batch of this._pendingBatches) {
+    for (let batch of this._pendingBatches) {
       if (batch.numRows === 0) {
-        dispatchLogOrError(batch, this._onLog);
-        continue;
+        if (isExternalLocationBatch(batch)) {
+          batch = await resolveExternalLocation(batch, this._externalConfig);
+        } else {
+          dispatchLogOrError(batch, this._onLog);
+          continue;
+        }
       }
       yield extractBatchRows(batch);
     }
@@ -691,7 +923,7 @@ class HttpStreamSession {
       const responseBody = await this._sendContinuation(this._stateToken);
       const { batches } = await readResponseBatches(responseBody);
       let gotContinuation = false;
-      for (const batch of batches) {
+      for (let batch of batches) {
         if (batch.numRows === 0) {
           const token = batch.metadata?.get(STATE_KEY);
           if (token) {
@@ -699,8 +931,12 @@ class HttpStreamSession {
             gotContinuation = true;
             continue;
           }
-          dispatchLogOrError(batch, this._onLog);
-          continue;
+          if (isExternalLocationBatch(batch)) {
+            batch = await resolveExternalLocation(batch, this._externalConfig);
+          } else {
+            dispatchLogOrError(batch, this._onLog);
+            continue;
+          }
         }
         yield extractBatchRows(batch);
       }
@@ -712,14 +948,14 @@ class HttpStreamSession {
     const emptySchema = new Schema([]);
     const metadata = new Map;
     metadata.set(STATE_KEY, token);
-    const structType = new Struct3(emptySchema.fields);
-    const data = makeData3({
+    const structType = new Struct4(emptySchema.fields);
+    const data = makeData4({
       type: structType,
       length: 1,
       children: [],
       nullCount: 0
     });
-    const batch = new RecordBatch3(emptySchema, data, metadata);
+    const batch = new RecordBatch4(emptySchema, data, metadata);
     const body = serializeIpcStream(emptySchema, [batch]);
     const resp = await fetch(`${this._baseUrl}${this._prefix}/${this._method}/exchange`, {
       method: "POST",
@@ -736,10 +972,11 @@ class HttpStreamSession {
 
 // src/client/connect.ts
 function httpConnect(baseUrl, options) {
-  const prefix = (options?.prefix ?? "/vgi").replace(/\/+$/, "");
+  const prefix = (options?.prefix ?? "").replace(/\/+$/, "");
   const onLog = options?.onLog;
   const compressionLevel = options?.compressionLevel;
   const authorization = options?.authorization;
+  const externalConfig = options?.externalLocation;
   let methodCache = null;
   let compressFn;
   let decompressFn;
@@ -811,10 +1048,14 @@ function httpConnect(baseUrl, options) {
       const responseBody = await readResponse(resp);
       const { batches } = await readResponseBatches(responseBody);
       let resultBatch = null;
-      for (const batch of batches) {
+      for (let batch of batches) {
         if (batch.numRows === 0) {
-          dispatchLogOrError(batch, onLog);
-          continue;
+          if (isExternalLocationBatch(batch)) {
+            batch = await resolveExternalLocation(batch, externalConfig);
+          } else {
+            dispatchLogOrError(batch, onLog);
+            continue;
+          }
         }
         resultBatch = batch;
       }
@@ -950,7 +1191,8 @@ function httpConnect(baseUrl, options) {
         compressionLevel,
         compressFn,
         decompressFn,
-        authorization
+        authorization,
+        externalConfig
       });
     },
     async describe() {
@@ -969,6 +1211,8 @@ function parseMetadataJson(json) {
     result.scopesSupported = json.scopes_supported;
   if (json.bearer_methods_supported)
     result.bearerMethodsSupported = json.bearer_methods_supported;
+  if (json.resource_signing_alg_values_supported)
+    result.resourceSigningAlgValuesSupported = json.resource_signing_alg_values_supported;
   if (json.resource_name)
     result.resourceName = json.resource_name;
   if (json.resource_documentation)
@@ -977,10 +1221,20 @@ function parseMetadataJson(json) {
     result.resourcePolicyUri = json.resource_policy_uri;
   if (json.resource_tos_uri)
     result.resourceTosUri = json.resource_tos_uri;
+  if (json.client_id)
+    result.clientId = json.client_id;
+  if (json.client_secret)
+    result.clientSecret = json.client_secret;
+  if (json.use_id_token_as_bearer)
+    result.useIdTokenAsBearer = json.use_id_token_as_bearer;
+  if (json.device_code_client_id)
+    result.deviceCodeClientId = json.device_code_client_id;
+  if (json.device_code_client_secret)
+    result.deviceCodeClientSecret = json.device_code_client_secret;
   return result;
 }
 async function httpOAuthMetadata(baseUrl, prefix) {
-  const effectivePrefix = (prefix ?? "/vgi").replace(/\/+$/, "");
+  const effectivePrefix = (prefix ?? "").replace(/\/+$/, "");
   const metadataUrl = `${baseUrl.replace(/\/+$/, "")}/.well-known/oauth-protected-resource${effectivePrefix}`;
   try {
     return await fetchOAuthMetadata(metadataUrl);
@@ -1006,15 +1260,65 @@ function parseResourceMetadataUrl(wwwAuthenticate) {
     return null;
   return metadataMatch[1];
 }
+function parseClientId(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const clientIdMatch = params.match(/client_id="([^"]+)"/);
+  if (!clientIdMatch)
+    return null;
+  return clientIdMatch[1];
+}
+function parseClientSecret(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const match = params.match(/client_secret="([^"]+)"/);
+  if (!match)
+    return null;
+  return match[1];
+}
+function parseUseIdTokenAsBearer(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return false;
+  const params = bearerMatch[1];
+  const match = params.match(/use_id_token_as_bearer="([^"]+)"/);
+  if (!match)
+    return false;
+  return match[1] === "true";
+}
+function parseDeviceCodeClientId(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const match = params.match(/device_code_client_id="([^"]+)"/);
+  if (!match)
+    return null;
+  return match[1];
+}
+function parseDeviceCodeClientSecret(wwwAuthenticate) {
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch)
+    return null;
+  const params = bearerMatch[1];
+  const match = params.match(/device_code_client_secret="([^"]+)"/);
+  if (!match)
+    return null;
+  return match[1];
+}
 // src/client/pipe.ts
 import {
   Field as Field2,
-  makeData as makeData4,
-  RecordBatch as RecordBatch4,
-  RecordBatchStreamWriter as RecordBatchStreamWriter2,
+  makeData as makeData5,
+  RecordBatch as RecordBatch5,
+  RecordBatchStreamWriter as RecordBatchStreamWriter3,
   Schema as Schema2,
-  Struct as Struct4,
-  vectorFromArray as vectorFromArray4
+  Struct as Struct5,
+  vectorFromArray as vectorFromArray5
 } from "@query-farm/apache-arrow";
 class PipeIncrementalWriter {
   writer;
@@ -1022,7 +1326,7 @@ class PipeIncrementalWriter {
   closed = false;
   constructor(writeFn, schema) {
     this.writeFn = writeFn;
-    this.writer = new RecordBatchStreamWriter2;
+    this.writer = new RecordBatchStreamWriter3;
     this.writer.reset(undefined, schema);
     this.drain();
   }
@@ -1060,6 +1364,7 @@ class PipeStreamSession {
   _outputSchema;
   _releaseBusy;
   _setDrainPromise;
+  _externalConfig;
   constructor(opts) {
     this._reader = opts.reader;
     this._writeFn = opts.writeFn;
@@ -1068,6 +1373,7 @@ class PipeStreamSession {
     this._outputSchema = opts.outputSchema;
     this._releaseBusy = opts.releaseBusy;
     this._setDrainPromise = opts.setDrainPromise;
+    this._externalConfig = opts.externalConfig;
   }
   get header() {
     return this._header;
@@ -1078,6 +1384,9 @@ class PipeStreamSession {
       if (batch === null)
         return null;
       if (batch.numRows === 0) {
+        if (isExternalLocationBatch(batch)) {
+          return await resolveExternalLocation(batch, this._externalConfig);
+        }
         if (dispatchLogOrError(batch, this._onLog)) {
           continue;
         }
@@ -1103,16 +1412,16 @@ class PipeStreamSession {
     if (input.length === 0) {
       inputSchema = this._inputSchema ?? this._outputSchema;
       const children = inputSchema.fields.map((f) => {
-        return makeData4({ type: f.type, length: 0, nullCount: 0 });
+        return makeData5({ type: f.type, length: 0, nullCount: 0 });
       });
-      const structType = new Struct4(inputSchema.fields);
-      const data = makeData4({
+      const structType = new Struct5(inputSchema.fields);
+      const data = makeData5({
         type: structType,
         length: 0,
         children,
         nullCount: 0
       });
-      batch = new RecordBatch4(inputSchema, data);
+      batch = new RecordBatch5(inputSchema, data);
     } else {
       const keys = Object.keys(input[0]);
       const fields = keys.map((key) => {
@@ -1137,16 +1446,16 @@ class PipeStreamSession {
       }
       const children = inputSchema.fields.map((f) => {
         const values = input.map((row) => row[f.name]);
-        return vectorFromArray4(values, f.type).data[0];
+        return vectorFromArray5(values, f.type).data[0];
       });
-      const structType = new Struct4(inputSchema.fields);
-      const data = makeData4({
+      const structType = new Struct5(inputSchema.fields);
+      const data = makeData5({
         type: structType,
         length: input.length,
         children,
         nullCount: 0
       });
-      batch = new RecordBatch4(inputSchema, data);
+      batch = new RecordBatch5(inputSchema, data);
     }
     if (!this._inputWriter) {
       this._inputWriter = new PipeIncrementalWriter(this._writeFn, inputSchema);
@@ -1185,14 +1494,14 @@ class PipeStreamSession {
     try {
       const tickSchema = new Schema2([]);
       this._inputWriter = new PipeIncrementalWriter(this._writeFn, tickSchema);
-      const structType = new Struct4(tickSchema.fields);
-      const tickData = makeData4({
+      const structType = new Struct5(tickSchema.fields);
+      const tickData = makeData5({
         type: structType,
         length: 0,
         children: [],
         nullCount: 0
       });
-      const tickBatch = new RecordBatch4(tickSchema, tickData);
+      const tickBatch = new RecordBatch5(tickSchema, tickData);
       while (true) {
         this._inputWriter.write(tickBatch);
         await this._ensureOutputStream();
@@ -1247,6 +1556,7 @@ class PipeStreamSession {
 }
 function pipeConnect(readable, writable, options) {
   const onLog = options?.onLog;
+  const externalConfig = options?.externalLocation;
   let reader = null;
   let readerPromise = null;
   let methodCache = null;
@@ -1322,10 +1632,14 @@ function pipeConnect(readable, writable, options) {
           throw new Error("EOF reading response");
         }
         let resultBatch = null;
-        for (const batch of response.batches) {
+        for (let batch of response.batches) {
           if (batch.numRows === 0) {
-            dispatchLogOrError(batch, onLog);
-            continue;
+            if (isExternalLocationBatch(batch)) {
+              batch = await resolveExternalLocation(batch, externalConfig);
+            } else {
+              dispatchLogOrError(batch, onLog);
+              continue;
+            }
           }
           resultBatch = batch;
         }
@@ -1378,7 +1692,8 @@ function pipeConnect(readable, writable, options) {
           header,
           outputSchema,
           releaseBusy,
-          setDrainPromise
+          setDrainPromise,
+          externalConfig
         });
       } catch (e) {
         try {
@@ -1428,7 +1743,8 @@ function subprocessConnect(cmd, options) {
     }
   };
   const client = pipeConnect(stdout, writable, {
-    onLog: options?.onLog
+    onLog: options?.onLog,
+    externalLocation: options?.externalLocation
   });
   const originalClose = client.close;
   client.close = () => {
@@ -1449,6 +1765,8 @@ function oauthResourceMetadataToJson(metadata) {
     json.scopes_supported = metadata.scopesSupported;
   if (metadata.bearerMethodsSupported)
     json.bearer_methods_supported = metadata.bearerMethodsSupported;
+  if (metadata.resourceSigningAlgValuesSupported)
+    json.resource_signing_alg_values_supported = metadata.resourceSigningAlgValuesSupported;
   if (metadata.resourceName)
     json.resource_name = metadata.resourceName;
   if (metadata.resourceDocumentation)
@@ -1457,146 +1775,124 @@ function oauthResourceMetadataToJson(metadata) {
     json.resource_policy_uri = metadata.resourcePolicyUri;
   if (metadata.resourceTosUri)
     json.resource_tos_uri = metadata.resourceTosUri;
+  if (metadata.clientId) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.clientId)) {
+      throw new Error(`Invalid client_id: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.client_id = metadata.clientId;
+  }
+  if (metadata.clientSecret) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.clientSecret)) {
+      throw new Error(`Invalid client_secret: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.client_secret = metadata.clientSecret;
+  }
+  if (metadata.deviceCodeClientId) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.deviceCodeClientId)) {
+      throw new Error(`Invalid device_code_client_id: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.device_code_client_id = metadata.deviceCodeClientId;
+  }
+  if (metadata.deviceCodeClientSecret) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.deviceCodeClientSecret)) {
+      throw new Error(`Invalid device_code_client_secret: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.device_code_client_secret = metadata.deviceCodeClientSecret;
+  }
+  if (metadata.useIdTokenAsBearer) {
+    json.use_id_token_as_bearer = true;
+  }
   return json;
 }
 function wellKnownPath(prefix) {
   return `/.well-known/oauth-protected-resource${prefix}`;
 }
-function buildWwwAuthenticateHeader(metadataUrl) {
+function buildWwwAuthenticateHeader(metadataUrl, clientId, clientSecret, useIdTokenAsBearer, deviceCodeClientId, deviceCodeClientSecret) {
+  let header = "Bearer";
   if (metadataUrl) {
-    return `Bearer resource_metadata="${metadataUrl}"`;
+    header += ` resource_metadata="${metadataUrl}"`;
   }
-  return "Bearer";
-}
-// src/http/handler.ts
-import { randomBytes } from "node:crypto";
-import { Schema as Schema5 } from "@query-farm/apache-arrow";
-
-// src/types.ts
-import { RecordBatch as RecordBatch6, recordBatchFromArrays } from "@query-farm/apache-arrow";
-
-// src/wire/response.ts
-import {
-  Data,
-  DataType as DataType2,
-  makeData as makeData5,
-  RecordBatch as RecordBatch5,
-  Struct as Struct5,
-  vectorFromArray as vectorFromArray5
-} from "@query-farm/apache-arrow";
-function coerceInt64(schema, values) {
-  const result = { ...values };
-  for (const field of schema.fields) {
-    const val = result[field.name];
-    if (val === undefined)
-      continue;
-    if (!DataType2.isInt(field.type) || field.type.bitWidth !== 64)
-      continue;
-    if (Array.isArray(val)) {
-      result[field.name] = val.map((v) => typeof v === "number" ? BigInt(v) : v);
-    } else if (typeof val === "number") {
-      result[field.name] = BigInt(val);
-    }
+  if (clientId) {
+    header += `, client_id="${clientId}"`;
   }
-  return result;
-}
-function buildResultBatch(schema, values, serverId, requestId) {
-  const metadata = new Map;
-  metadata.set(SERVER_ID_KEY, serverId);
-  if (requestId !== null) {
-    metadata.set(REQUEST_ID_KEY, requestId);
+  if (clientSecret) {
+    header += `, client_secret="${clientSecret}"`;
   }
-  if (schema.fields.length === 0) {
-    return buildEmptyBatch(schema, metadata);
+  if (deviceCodeClientId) {
+    header += `, device_code_client_id="${deviceCodeClientId}"`;
   }
-  for (const field of schema.fields) {
-    if (values[field.name] === undefined && !field.nullable) {
-      const got = Object.keys(values);
-      throw new TypeError(`Handler result missing required field '${field.name}'. Got keys: [${got.join(", ")}]`);
-    }
+  if (deviceCodeClientSecret) {
+    header += `, device_code_client_secret="${deviceCodeClientSecret}"`;
   }
-  const coerced = coerceInt64(schema, values);
-  const children = schema.fields.map((f) => {
-    const val = coerced[f.name];
-    if (val instanceof Data) {
-      return val;
-    }
-    const arr = vectorFromArray5([val], f.type);
-    return arr.data[0];
-  });
-  const structType = new Struct5(schema.fields);
-  const data = makeData5({
-    type: structType,
-    length: 1,
-    children,
-    nullCount: 0
-  });
-  return new RecordBatch5(schema, data, metadata);
+  if (useIdTokenAsBearer) {
+    header += `, use_id_token_as_bearer="true"`;
+  }
+  return header;
 }
-function buildErrorBatch(schema, error, serverId, requestId) {
-  const metadata = new Map;
-  metadata.set(LOG_LEVEL_KEY, "EXCEPTION");
-  metadata.set(LOG_MESSAGE_KEY, `${error.constructor.name}: ${error.message}`);
-  const extra = {
-    exception_type: error.constructor.name,
-    exception_message: error.message,
-    traceback: error.stack ?? ""
+// src/http/bearer.ts
+import { timingSafeEqual } from "node:crypto";
+function bearerAuthenticate(options) {
+  const { validate } = options;
+  return async function authenticate(request) {
+    const authHeader = request.headers.get("Authorization") ?? "";
+    if (!authHeader.startsWith("Bearer ")) {
+      throw new Error("Missing or invalid Authorization header");
+    }
+    const token = authHeader.slice(7);
+    return validate(token);
   };
-  metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
-  metadata.set(SERVER_ID_KEY, serverId);
-  if (requestId !== null) {
-    metadata.set(REQUEST_ID_KEY, requestId);
-  }
-  return buildEmptyBatch(schema, metadata);
 }
-function buildLogBatch(schema, level, message, extra, serverId, requestId) {
-  const metadata = new Map;
-  metadata.set(LOG_LEVEL_KEY, level);
-  metadata.set(LOG_MESSAGE_KEY, message);
-  if (extra) {
-    metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
-  }
-  if (serverId != null) {
-    metadata.set(SERVER_ID_KEY, serverId);
-  }
-  if (requestId != null) {
-    metadata.set(REQUEST_ID_KEY, requestId);
-  }
-  return buildEmptyBatch(schema, metadata);
+function safeEqual(a, b) {
+  const enc = new TextEncoder;
+  const bufA = enc.encode(a);
+  const bufB = enc.encode(b);
+  if (bufA.byteLength !== bufB.byteLength)
+    return false;
+  return timingSafeEqual(bufA, bufB);
 }
-function makeEmptyData(type) {
-  if (DataType2.isStruct(type)) {
-    const children = type.children.map((f) => makeEmptyData(f.type));
-    return makeData5({ type, length: 0, children, nullCount: 0 });
-  }
-  if (DataType2.isList(type)) {
-    const childData = makeEmptyData(type.children[0].type);
-    return makeData5({ type, length: 0, children: [childData], nullCount: 0, valueOffsets: new Int32Array([0]) });
-  }
-  if (DataType2.isFixedSizeList(type)) {
-    const childData = makeEmptyData(type.children[0].type);
-    return makeData5({ type, length: 0, child: childData, nullCount: 0 });
-  }
-  if (DataType2.isMap(type)) {
-    const entryType = type.children[0]?.type;
-    const entryData = entryType ? makeEmptyData(entryType) : makeData5({ type: new Struct5([]), length: 0, children: [], nullCount: 0 });
-    return makeData5({ type, length: 0, children: [entryData], nullCount: 0, valueOffsets: new Int32Array([0]) });
+function bearerAuthenticateStatic(options) {
+  const entries = options.tokens instanceof Map ? [...options.tokens.entries()] : Object.entries(options.tokens);
+  function validate(token) {
+    for (const [key, ctx] of entries) {
+      if (safeEqual(token, key))
+        return ctx;
+    }
+    throw new Error("Unknown bearer token");
   }
-  return makeData5({ type, length: 0, nullCount: 0 });
+  return bearerAuthenticate({ validate });
 }
-function buildEmptyBatch(schema, metadata) {
-  const children = schema.fields.map((f) => makeEmptyData(f.type));
-  const structType = new Struct5(schema.fields);
-  const data = makeData5({
-    type: structType,
-    length: 0,
-    children,
-    nullCount: 0
-  });
-  return new RecordBatch5(schema, data, metadata);
+function isCredentialError(err) {
+  return err instanceof Error && err.constructor === Error && err.name !== "PermissionError";
+}
+function chainAuthenticate(...authenticators) {
+  if (authenticators.length === 0) {
+    throw new Error("chainAuthenticate requires at least one authenticator");
+  }
+  return async function authenticate(request) {
+    let lastError = null;
+    for (const authFn of authenticators) {
+      try {
+        return await authFn(request);
+      } catch (err) {
+        if (isCredentialError(err)) {
+          lastError = err;
+          continue;
+        }
+        throw err;
+      }
+    }
+    const error = new Error("No authenticator accepted the request");
+    if (lastError)
+      error.cause = lastError;
+    throw error;
+  };
 }
+// src/http/handler.ts
+import { randomBytes } from "node:crypto";
+import { Schema as Schema5 } from "@query-farm/apache-arrow";
 
 // src/types.ts
+import { RecordBatch as RecordBatch6, recordBatchFromArrays } from "@query-farm/apache-arrow";
 var MethodType;
 ((MethodType2) => {
   MethodType2["UNARY"] = "unary";
@@ -1665,7 +1961,7 @@ class OutputCollector {
 init_zstd();
 
 // src/http/dispatch.ts
-import { RecordBatch as RecordBatch8, RecordBatchReader as RecordBatchReader5, Schema as Schema4 } from "@query-farm/apache-arrow";
+import { RecordBatch as RecordBatch8, RecordBatchReader as RecordBatchReader6, Schema as Schema4 } from "@query-farm/apache-arrow";
 
 // src/dispatch/describe.ts
 import {
@@ -1681,9 +1977,9 @@ import {
 } from "@query-farm/apache-arrow";
 
 // src/util/schema.ts
-import { RecordBatchStreamWriter as RecordBatchStreamWriter3 } from "@query-farm/apache-arrow";
+import { RecordBatchStreamWriter as RecordBatchStreamWriter4 } from "@query-farm/apache-arrow";
 function serializeSchema(schema) {
-  const writer = new RecordBatchStreamWriter3;
+  const writer = new RecordBatchStreamWriter4;
   writer.reset(undefined, schema);
   writer.close();
   return writer.toUint8Array(true);
@@ -1700,7 +1996,9 @@ var DESCRIBE_SCHEMA = new Schema3([
   new Field3("param_types_json", new Utf82, true),
   new Field3("param_defaults_json", new Utf82, true),
   new Field3("has_header", new Bool2, false),
-  new Field3("header_schema_ipc", new Binary2, true)
+  new Field3("header_schema_ipc", new Binary2, true),
+  new Field3("is_exchange", new Bool2, true),
+  new Field3("param_docs_json", new Utf82, true)
 ]);
 function buildDescribeBatch(protocolName, methods, serverId) {
   const sortedEntries = [...methods.entries()].sort(([a], [b]) => a.localeCompare(b));
@@ -1714,6 +2012,8 @@ function buildDescribeBatch(protocolName, methods, serverId) {
   const paramDefaultsJsons = [];
   const hasHeaders = [];
   const headerSchemas = [];
+  const isExchanges = [];
+  const paramDocsJsons = [];
   for (const [name, method] of sortedEntries) {
     names.push(name);
     methodTypes.push(method.type);
@@ -1740,6 +2040,14 @@ function buildDescribeBatch(protocolName, methods, serverId) {
     }
     hasHeaders.push(!!method.headerSchema);
     headerSchemas.push(method.headerSchema ? serializeSchema(method.headerSchema) : null);
+    if (method.exchangeFn) {
+      isExchanges.push(true);
+    } else if (method.producerFn) {
+      isExchanges.push(false);
+    } else {
+      isExchanges.push(null);
+    }
+    paramDocsJsons.push(null);
   }
   const nameArr = vectorFromArray6(names, new Utf82);
   const methodTypeArr = vectorFromArray6(methodTypes, new Utf82);
@@ -1751,6 +2059,8 @@ function buildDescribeBatch(protocolName, methods, serverId) {
   const paramDefaultsArr = vectorFromArray6(paramDefaultsJsons, new Utf82);
   const hasHeaderArr = vectorFromArray6(hasHeaders, new Bool2);
   const headerSchemaArr = vectorFromArray6(headerSchemas, new Binary2);
+  const isExchangeArr = vectorFromArray6(isExchanges, new Bool2);
+  const paramDocsArr = vectorFromArray6(paramDocsJsons, new Utf82);
   const children = [
     nameArr.data[0],
     methodTypeArr.data[0],
@@ -1761,7 +2071,9 @@ function buildDescribeBatch(protocolName, methods, serverId) {
     paramTypesArr.data[0],
     paramDefaultsArr.data[0],
     hasHeaderArr.data[0],
-    headerSchemaArr.data[0]
+    headerSchemaArr.data[0],
+    isExchangeArr.data[0],
+    paramDocsArr.data[0]
   ];
   const structType = new Struct6(DESCRIBE_SCHEMA.fields);
   const data = makeData6({
@@ -1824,7 +2136,7 @@ function parseRequest(schema, batch) {
 }
 
 // src/http/token.ts
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
 var TOKEN_VERSION = 2;
 var HMAC_LEN = 32;
 var MIN_TOKEN_LEN = 1 + 8 + 12 + HMAC_LEN;
@@ -1861,7 +2173,7 @@ function unpackStateToken(tokenBase64, signingKey, tokenTtl) {
   const payload = token.subarray(0, token.length - HMAC_LEN);
   const receivedMac = token.subarray(token.length - HMAC_LEN);
   const expectedMac = createHmac("sha256", signingKey).update(payload).digest();
-  if (!timingSafeEqual(receivedMac, expectedMac)) {
+  if (!timingSafeEqual2(receivedMac, expectedMac)) {
     throw new Error("State token HMAC verification failed");
   }
   let offset = 0;
@@ -1903,7 +2215,7 @@ function unpackStateToken(tokenBase64, signingKey, tokenTtl) {
 
 // src/http/dispatch.ts
 async function deserializeSchema2(bytes) {
-  const reader = await RecordBatchReader5.from(bytes);
+  const reader = await RecordBatchReader6.from(bytes);
   await reader.open();
   return reader.schema;
 }
@@ -1923,12 +2235,17 @@ async function httpDispatchUnary(method, body, ctx) {
   const out = new OutputCollector(schema, true, ctx.serverId, parsed.requestId, ctx.authContext);
   try {
     const result = await method.handler(parsed.params, out);
-    const resultBatch = buildResultBatch(schema, result, ctx.serverId, parsed.requestId);
+    let resultBatch = buildResultBatch(schema, result, ctx.serverId, parsed.requestId);
+    if (ctx.externalLocation) {
+      resultBatch = await maybeExternalizeBatch(resultBatch, ctx.externalLocation);
+    }
     const batches = [...out.batches.map((b) => b.batch), resultBatch];
     return arrowResponse(serializeIpcStream(schema, batches));
   } catch (error) {
     const errBatch = buildErrorBatch(schema, error, ctx.serverId, parsed.requestId);
-    return arrowResponse(serializeIpcStream(schema, [errBatch]), 500);
+    const response = arrowResponse(serializeIpcStream(schema, [errBatch]), 500);
+    response.__dispatchError = error;
+    return response;
   }
 }
 async function httpDispatchStreamInit(method, body, ctx) {
@@ -1950,7 +2267,9 @@ async function httpDispatchStreamInit(method, body, ctx) {
   } catch (error) {
     const errSchema = method.headerSchema ?? EMPTY_SCHEMA;
     const errBatch = buildErrorBatch(errSchema, error, ctx.serverId, parsed.requestId);
-    return arrowResponse(serializeIpcStream(errSchema, [errBatch]), 500);
+    const response = arrowResponse(serializeIpcStream(errSchema, [errBatch]), 500);
+    response.__dispatchError = error;
+    return response;
   }
   const resolvedOutputSchema = state?.__outputSchema ?? outputSchema;
   const effectiveProducer = state?.__isProducer ?? isProducer;
@@ -1964,7 +2283,9 @@ async function httpDispatchStreamInit(method, body, ctx) {
       headerBytes = serializeIpcStream(method.headerSchema, headerBatches);
     } catch (error) {
       const errBatch = buildErrorBatch(method.headerSchema, error, ctx.serverId, parsed.requestId);
-      return arrowResponse(serializeIpcStream(method.headerSchema, [errBatch]), 500);
+      const response = arrowResponse(serializeIpcStream(method.headerSchema, [errBatch]), 500);
+      response.__dispatchError = error;
+      return response;
     }
   }
   if (effectiveProducer) {
@@ -2039,7 +2360,9 @@ async function httpDispatchStreamExchange(method, body, ctx) {
 `).slice(0, 5).join(`
 `));
       const errBatch = buildErrorBatch(outputSchema, error, ctx.serverId, null);
-      return arrowResponse(serializeIpcStream(outputSchema, [errBatch]), 500);
+      const response = arrowResponse(serializeIpcStream(outputSchema, [errBatch]), 500);
+      response.__dispatchError = error;
+      return response;
     }
     const batches = [];
     if (out.finished) {
@@ -2074,6 +2397,7 @@ async function produceStreamResponse(method, state, outputSchema, inputSchema, c
   const allBatches = [];
   const maxBytes = ctx.maxStreamResponseBytes;
   let estimatedBytes = 0;
+  let producerError;
   while (true) {
     const out = new OutputCollector(outputSchema, true, ctx.serverId, requestId, ctx.authContext);
     try {
@@ -2089,6 +2413,7 @@ async function produceStreamResponse(method, state, outputSchema, inputSchema, c
 `).slice(0, 3).join(`
 `));
       allBatches.push(buildErrorBatch(outputSchema, error, ctx.serverId, requestId));
+      producerError = error instanceof Error ? error : new Error(String(error));
       break;
     }
     for (const emitted of out.batches) {
@@ -2118,7 +2443,11 @@ async function produceStreamResponse(method, state, outputSchema, inputSchema, c
   } else {
     responseBody = dataBytes;
   }
-  return arrowResponse(responseBody);
+  const response = arrowResponse(responseBody);
+  if (producerError) {
+    response.__dispatchError = producerError;
+  }
+  return response;
 }
 function concatBytes(...arrays) {
   const totalLen = arrays.reduce((sum, a) => sum + a.length, 0);
@@ -2131,6 +2460,261 @@ function concatBytes(...arrays) {
   return result;
 }
 
+// src/http/pages.ts
+var LOGO_URL = "https://vgi-rpc-python.query.farm/assets/logo-hero.png";
+var FONTS = `<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">`;
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function arrowTypeToString(type) {
+  const id = type.typeId;
+  if (id === 5)
+    return "str";
+  if (id === 4)
+    return "bytes";
+  if (id === 2)
+    return "int";
+  if (id === 3)
+    return "float";
+  if (id === 6)
+    return "bool";
+  if (id === 12)
+    return "list";
+  if (id === 17)
+    return "map";
+  if (id === 24)
+    return "enum";
+  return type.toString();
+}
+function buildLandingPage(protocolName, serverId, describePath, repoUrl) {
+  const links = [];
+  if (describePath) {
+    links.push(`<a class="primary" href="${escapeHtml(describePath)}">View service API</a>`);
+  }
+  if (repoUrl) {
+    links.push(`<a href="${escapeHtml(repoUrl)}">Source repository</a>`);
+  }
+  links.push(`<a href="https://vgi-rpc.query.farm">Learn more about <code>vgi-rpc</code></a>`);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(protocolName)} — vgi-rpc</title>
+${FONTS}
+<style>
+body { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 600px;
+       margin: 0 auto; padding: 60px 20px 0; color: #2c2c1e; text-align: center;
+       background: #faf8f0; }
+.logo { margin-bottom: 24px; }
+.logo img { width: 140px; height: 140px; border-radius: 50%;
+             box-shadow: 0 4px 24px rgba(0,0,0,0.12); }
+h1 { color: #2d5016; margin-bottom: 8px; font-weight: 700; }
+code { font-family: 'JetBrains Mono', monospace; background: #f0ece0;
+        padding: 2px 6px; border-radius: 3px; font-size: 0.9em; color: #2c2c1e; }
+a { color: #2d5016; text-decoration: none; }
+a:hover { color: #4a7c23; }
+p { line-height: 1.7; color: #6b6b5a; }
+.meta { font-size: 0.9em; color: #6b6b5a; }
+.links { margin-top: 28px; display: flex; flex-wrap: wrap; justify-content: center; gap: 8px; }
+.links a { display: inline-block; padding: 8px 18px; border-radius: 6px;
+            border: 1px solid #4a7c23; color: #2d5016; font-weight: 600;
+            font-size: 0.9em; transition: all 0.2s ease; }
+.links a:hover { background: #4a7c23; color: #fff; }
+.links a.primary { background: #2d5016; color: #fff; border-color: #2d5016; }
+.links a.primary:hover { background: #4a7c23; border-color: #4a7c23; }
+footer { margin-top: 48px; padding: 20px 0; border-top: 1px solid #f0ece0;
+          color: #6b6b5a; font-size: 0.85em; }
+footer a { color: #2d5016; font-weight: 600; }
+footer a:hover { color: #4a7c23; }
+</style>
+</head>
+<body>
+<div class="logo">
+  <img src="${LOGO_URL}" alt="vgi-rpc logo">
+</div>
+<h1>${escapeHtml(protocolName)}</h1>
+<p class="meta">Powered by <code>vgi-rpc</code> (TypeScript) &middot; server <code>${escapeHtml(serverId)}</code></p>
+<p>This is a <code>vgi-rpc</code> service endpoint.</p>
+<div class="links">
+${links.join(`
+`)}
+</div>
+<footer>
+  &copy; 2026 &#x1F69C; <a href="https://query.farm">Query.Farm LLC</a>
+</footer>
+</body>
+</html>`;
+}
+function buildNotFoundPage(prefix, protocolName) {
+  const nameFragment = protocolName ? ` (<strong>${escapeHtml(protocolName)}</strong>)` : "";
+  const prefixDisplay = prefix || "/";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>404 — vgi-rpc endpoint</title>
+<style>
+body { font-family: system-ui, -apple-system, sans-serif; max-width: 600px;
+       margin: 60px auto; padding: 0 20px; color: #333; text-align: center; }
+.logo { margin-bottom: 24px; }
+.logo img { width: 120px; height: 120px; }
+h1 { color: #555; }
+code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; font-size: 0.95em; }
+a { color: #0066cc; }
+p { line-height: 1.6; }
+</style>
+</head>
+<body>
+<div class="logo">
+  <img src="${LOGO_URL}" alt="vgi-rpc logo">
+</div>
+<h1>404 — Not Found</h1>
+<p>This is a <code>vgi-rpc</code> service endpoint${nameFragment}.</p>
+<p>RPC methods are available under <code>${escapeHtml(prefixDisplay)}/&lt;method&gt;</code>.</p>
+<p>Learn more at <a href="https://vgi-rpc.query.farm">vgi-rpc.query.farm</a>.</p>
+</body>
+</html>`;
+}
+function buildMethodCard(method) {
+  const name = escapeHtml(method.name);
+  const isUnary = method.type === "unary";
+  const hasHeader = !!method.headerSchema;
+  const badges = [];
+  badges.push(isUnary ? `<span class="badge badge-unary">unary</span>` : `<span class="badge badge-stream">stream</span>`);
+  if (hasHeader)
+    badges.push(`<span class="badge badge-header">header</span>`);
+  let paramsHtml = "";
+  const paramsSchema = method.paramsSchema;
+  if (paramsSchema.fields.length > 0) {
+    const rows = paramsSchema.fields.map((f) => {
+      const paramName = escapeHtml(f.name);
+      const paramType = escapeHtml(arrowTypeToString(f.type));
+      const defaultVal = method.defaults && f.name in method.defaults ? escapeHtml(JSON.stringify(method.defaults[f.name])) : "&mdash;";
+      return `<tr><td><code>${paramName}</code></td><td><code>${paramType}</code></td><td>${defaultVal}</td><td>&mdash;</td></tr>`;
+    });
+    paramsHtml = `<div class="section-label">Parameters</div>
+<table><tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
+${rows.join(`
+`)}
+</table>`;
+  } else {
+    paramsHtml = `<p class="no-params">No parameters</p>`;
+  }
+  let returnsHtml = "";
+  if (isUnary && method.resultSchema.fields.length > 0) {
+    const rows = method.resultSchema.fields.map((f) => {
+      return `<tr><td><code>${escapeHtml(f.name)}</code></td><td><code>${escapeHtml(arrowTypeToString(f.type))}</code></td></tr>`;
+    });
+    returnsHtml = `<div class="section-label">Returns</div>
+<table><tr><th>Name</th><th>Type</th></tr>
+${rows.join(`
+`)}
+</table>`;
+  }
+  let headerHtml = "";
+  if (hasHeader && method.headerSchema && method.headerSchema.fields.length > 0) {
+    const rows = method.headerSchema.fields.map((f) => {
+      return `<tr><td><code>${escapeHtml(f.name)}</code></td><td><code>${escapeHtml(arrowTypeToString(f.type))}</code></td></tr>`;
+    });
+    headerHtml = `<div class="section-label">Stream Header</div>
+<table><tr><th>Name</th><th>Type</th></tr>
+${rows.join(`
+`)}
+</table>`;
+  }
+  const docHtml = method.doc ? `<p class="docstring">${escapeHtml(method.doc)}</p>` : "";
+  return `<div class="card">
+<div class="card-header">
+<span class="method-name">${name}</span>
+${badges.join(`
+`)}
+</div>
+${docHtml}
+${paramsHtml}
+${returnsHtml}
+${headerHtml}
+</div>`;
+}
+function buildDescribePage(protocolName, serverId, methods, repoUrl) {
+  const sortedMethods = [...methods.entries()].filter(([name]) => name !== "__describe__").sort(([a], [b]) => a.localeCompare(b));
+  const cards = sortedMethods.map(([, method]) => buildMethodCard(method)).join(`
+`);
+  const repoLink = repoUrl ? ` &middot; <a href="${escapeHtml(repoUrl)}">Source</a>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(protocolName)} API Reference — vgi-rpc</title>
+${FONTS}
+<style>
+body { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 900px;
+       margin: 0 auto; padding: 40px 20px 0; color: #2c2c1e; background: #faf8f0; }
+.header { text-align: center; margin-bottom: 40px; }
+.header .logo img { width: 80px; height: 80px; border-radius: 50%;
+                     box-shadow: 0 3px 16px rgba(0,0,0,0.10); }
+.header h1 { margin-bottom: 4px; color: #2d5016; font-weight: 700; }
+.header .subtitle { color: #6b6b5a; font-size: 1.1em; margin-top: 0; }
+.header .meta { color: #6b6b5a; font-size: 0.9em; }
+.header .meta a { color: #2d5016; font-weight: 600; }
+.header .meta a:hover { color: #4a7c23; }
+code { font-family: 'JetBrains Mono', monospace; background: #f0ece0;
+        padding: 2px 6px; border-radius: 3px; font-size: 0.85em; color: #2c2c1e; }
+a { color: #2d5016; text-decoration: none; }
+a:hover { color: #4a7c23; }
+.card { border: 1px solid #f0ece0; border-radius: 8px; padding: 20px;
+         margin-bottom: 16px; background: #fff; }
+.card:hover { border-color: #c8a43a; }
+.card-header { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.method-name { font-family: 'JetBrains Mono', monospace; font-size: 1.1em; font-weight: 600;
+                color: #2d5016; }
+.badge { display: inline-block; padding: 2px 8px; border-radius: 4px;
+          font-size: 0.75em; font-weight: 600; text-transform: uppercase;
+          letter-spacing: 0.03em; }
+.badge-unary { background: #e8f5e0; color: #2d5016; }
+.badge-stream { background: #e0ecf5; color: #1a4a6b; }
+.badge-exchange { background: #f5e6f0; color: #6b234a; }
+.badge-producer { background: #e0f0f5; color: #1a5a6b; }
+.badge-header { background: #f5eee0; color: #6b4423; }
+.docstring { color: #6b6b5a; font-size: 0.9em; margin-top: 0; }
+table { width: 100%; border-collapse: collapse; font-size: 0.9em; }
+th { text-align: left; padding: 8px 10px; background: #f0ece0; color: #2c2c1e;
+      font-weight: 600; border-bottom: 2px solid #e0dcd0; }
+td { padding: 8px 10px; border-bottom: 1px solid #f0ece0; }
+td code { font-size: 0.85em; }
+.no-params { color: #6b6b5a; font-style: italic; font-size: 0.9em; }
+.section-label { font-size: 0.8em; font-weight: 600; text-transform: uppercase;
+                  letter-spacing: 0.05em; color: #6b6b5a; margin-top: 14px;
+                  margin-bottom: 6px; }
+footer { text-align: center; margin-top: 48px; padding: 20px 0;
+          border-top: 1px solid #f0ece0; color: #6b6b5a; font-size: 0.85em; }
+footer a { color: #2d5016; font-weight: 600; }
+footer a:hover { color: #4a7c23; }
+</style>
+</head>
+<body>
+<div class="header">
+  <div class="logo">
+    <img src="${LOGO_URL}" alt="vgi-rpc logo">
+  </div>
+  <h1>${escapeHtml(protocolName)}</h1>
+  <p class="subtitle">API Reference</p>
+  <p class="meta">Powered by <code>vgi-rpc</code> (TypeScript) &middot; server <code>${escapeHtml(serverId)}</code>${repoLink}</p>
+</div>
+${cards}
+<footer>
+  <a href="https://vgi-rpc.query.farm">Learn more about <code>vgi-rpc</code></a>
+  &middot;
+  &copy; 2026 &#x1F69C; <a href="https://query.farm">Query.Farm LLC</a>
+</footer>
+</body>
+</html>`;
+}
+
 // src/http/types.ts
 var jsonStateSerializer = {
   serialize(state) {
@@ -2144,7 +2728,7 @@ var jsonStateSerializer = {
 // src/http/handler.ts
 var EMPTY_SCHEMA2 = new Schema5([]);
 function createHttpHandler(protocol, options) {
-  const prefix = (options?.prefix ?? "/vgi").replace(/\/+$/, "");
+  const prefix = (options?.prefix ?? "").replace(/\/+$/, "");
   const signingKey = options?.signingKey ?? randomBytes(32);
   const tokenTtl = options?.tokenTtl ?? 3600;
   const corsOrigins = options?.corsOrigins;
@@ -2156,12 +2740,23 @@ function createHttpHandler(protocol, options) {
   const methods = protocol.getMethods();
   const compressionLevel = options?.compressionLevel;
   const stateSerializer = options?.stateSerializer ?? jsonStateSerializer;
+  const dispatchHook = options?.dispatchHook;
+  const enableLandingPage = options?.enableLandingPage ?? true;
+  const enableDescribePage = options?.enableDescribePage ?? true;
+  const enableNotFoundPage = options?.enableNotFoundPage ?? true;
+  const displayName = options?.protocolName ?? protocol.name;
+  const repoUrl = options?.repositoryUrl ?? null;
+  const landingHtml = enableLandingPage ? buildLandingPage(displayName, serverId, enableDescribePage ? `${prefix}/describe` : null, repoUrl) : null;
+  const describeHtml = enableDescribePage ? buildDescribePage(displayName, serverId, methods, repoUrl) : null;
+  const notFoundHtml = enableNotFoundPage ? buildNotFoundPage(prefix, displayName) : null;
+  const externalLocation = options?.externalLocation;
   const baseCtx = {
     signingKey,
     tokenTtl,
     serverId,
     maxStreamResponseBytes,
-    stateSerializer
+    stateSerializer,
+    externalLocation
   };
   function addCorsHeaders(headers) {
     if (corsOrigins) {
@@ -2199,7 +2794,7 @@ function createHttpHandler(protocol, options) {
       const body2 = JSON.stringify(oauthResourceMetadataToJson(oauthMetadata));
       const headers = new Headers({
         "Content-Type": "application/json",
-        "Cache-Control": "public, max-age=3600"
+        "Cache-Control": "public, max-age=60"
       });
       addCorsHeaders(headers);
       return new Response(body2, { status: 200, headers });
@@ -2220,6 +2815,24 @@ function createHttpHandler(protocol, options) {
       }
       return new Response(null, { status: 405 });
     }
+    if (request.method === "GET") {
+      if (landingHtml && (path === prefix || path === `${prefix}/`)) {
+        const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+        addCorsHeaders(headers);
+        return new Response(landingHtml, { status: 200, headers });
+      }
+      if (describeHtml && path === `${prefix}/describe`) {
+        const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+        addCorsHeaders(headers);
+        return new Response(describeHtml, { status: 200, headers });
+      }
+      if (notFoundHtml) {
+        const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+        addCorsHeaders(headers);
+        return new Response(notFoundHtml, { status: 404, headers });
+      }
+      return new Response("Not Found", { status: 404 });
+    }
     if (request.method !== "POST") {
       return new Response("Method Not Allowed", { status: 405 });
     }
@@ -2250,7 +2863,7 @@ function createHttpHandler(protocol, options) {
           const metadataUrl = new URL(request.url);
           metadataUrl.pathname = wellKnownPath(prefix);
           metadataUrl.search = "";
-          headers.set("WWW-Authenticate", buildWwwAuthenticateHeader(metadataUrl.toString()));
+          headers.set("WWW-Authenticate", buildWwwAuthenticateHeader(metadataUrl.toString(), oauthMetadata.clientId, oauthMetadata.clientSecret, oauthMetadata.useIdTokenAsBearer, oauthMetadata.deviceCodeClientId, oauthMetadata.deviceCodeClientSecret));
         }
         return new Response(error.message || "Unauthorized", { status: 401, headers });
       }
@@ -2286,6 +2899,18 @@ function createHttpHandler(protocol, options) {
       const err = new Error(`Unknown method: '${methodName}'. Available methods: [${available.join(", ")}]`);
       return compressIfAccepted(makeErrorResponse(err, 404), clientAcceptsZstd);
     }
+    const methodType = method.type === "unary" /* UNARY */ ? "unary" : "stream";
+    const info = { method: methodName, methodType, serverId, requestId: null };
+    const stats = {
+      inputBatches: 0,
+      outputBatches: 0,
+      inputRows: 0,
+      outputRows: 0,
+      inputBytes: 0,
+      outputBytes: 0
+    };
+    const hookToken = dispatchHook?.onDispatchStart(info);
+    let dispatchError;
     try {
       let response;
       if (action === "call") {
@@ -2304,13 +2929,20 @@ function createHttpHandler(protocol, options) {
         }
         response = await httpDispatchStreamExchange(method, body, ctx);
       }
+      const internalError = response.__dispatchError;
+      if (internalError) {
+        dispatchError = internalError instanceof Error ? internalError : new Error(String(internalError));
+      }
       addCorsHeaders(response.headers);
       return compressIfAccepted(response, clientAcceptsZstd);
     } catch (error) {
+      dispatchError = error instanceof Error ? error : new Error(String(error));
       if (error instanceof HttpRpcError) {
         return compressIfAccepted(makeErrorResponse(error, error.statusCode), clientAcceptsZstd);
       }
       return compressIfAccepted(makeErrorResponse(error, 500), clientAcceptsZstd);
+    } finally {
+      dispatchHook?.onDispatchEnd(hookToken, info, stats, dispatchError);
     }
   };
 }
@@ -3503,11 +4135,220 @@ function jwtAuthenticate(options) {
       asPromise = null;
       throw error;
     }
-    const claims = await validateJwtAccessToken(as, request, audience);
+    const audiences = Array.isArray(audience) ? audience : [audience];
+    let claims;
+    let lastError;
+    for (const aud of audiences) {
+      try {
+        claims = await validateJwtAccessToken(as, request, aud);
+        break;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if (!claims) {
+      throw lastError;
+    }
     const principal = claims[principalClaim] ?? null;
     return new AuthContext(domain, true, principal, claims);
   };
 }
+// src/http/mtls.ts
+import { createHash, X509Certificate } from "node:crypto";
+function splitRespectingQuotes(text, delimiter) {
+  const parts = [];
+  let current = [];
+  let inQuotes = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      current.push(ch);
+    } else if (ch === "\\" && inQuotes && i + 1 < text.length) {
+      current.push(ch);
+      current.push(text[i + 1]);
+      i++;
+    } else if (ch === delimiter && !inQuotes) {
+      parts.push(current.join(""));
+      current = [];
+    } else {
+      current.push(ch);
+    }
+    i++;
+  }
+  parts.push(current.join(""));
+  return parts;
+}
+function unescapeQuoted(text) {
+  return text.replace(/\\(.)/g, "$1");
+}
+function extractCn(subject) {
+  for (const part of subject.split(/(?<!\\),/)) {
+    const trimmed = part.trim();
+    if (trimmed.toUpperCase().startsWith("CN=")) {
+      return trimmed.slice(3);
+    }
+  }
+  return "";
+}
+function parseXfcc(headerValue) {
+  const elements = [];
+  for (const rawElement of splitRespectingQuotes(headerValue, ",")) {
+    const trimmed = rawElement.trim();
+    if (!trimmed)
+      continue;
+    const pairs = splitRespectingQuotes(trimmed, ";");
+    const fields = {};
+    for (const pair of pairs) {
+      const p = pair.trim();
+      if (!p)
+        continue;
+      const eqIdx = p.indexOf("=");
+      if (eqIdx < 0)
+        continue;
+      const key = p.slice(0, eqIdx).trim().toLowerCase();
+      let value = p.slice(eqIdx + 1).trim();
+      if (value.length >= 2 && value[0] === '"' && value[value.length - 1] === '"') {
+        value = unescapeQuoted(value.slice(1, -1));
+      }
+      if (key === "cert" || key === "uri" || key === "by") {
+        value = decodeURIComponent(value);
+      }
+      if (key === "dns") {
+        const existing = fields.dns;
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          fields.dns = [value];
+        }
+      } else {
+        fields[key] = value;
+      }
+    }
+    const dns = Array.isArray(fields.dns) ? fields.dns : [];
+    elements.push({
+      hash: typeof fields.hash === "string" ? fields.hash : null,
+      cert: typeof fields.cert === "string" ? fields.cert : null,
+      subject: typeof fields.subject === "string" ? fields.subject : null,
+      uri: typeof fields.uri === "string" ? fields.uri : null,
+      dns,
+      by: typeof fields.by === "string" ? fields.by : null
+    });
+  }
+  return elements;
+}
+function mtlsAuthenticateXfcc(options) {
+  const validate = options?.validate;
+  const domain = options?.domain ?? "mtls";
+  const selectElement = options?.selectElement ?? "first";
+  return async function authenticate(request) {
+    const headerValue = request.headers.get("x-forwarded-client-cert");
+    if (!headerValue) {
+      throw new Error("Missing x-forwarded-client-cert header");
+    }
+    const elements = parseXfcc(headerValue);
+    if (elements.length === 0) {
+      throw new Error("Empty x-forwarded-client-cert header");
+    }
+    const element = selectElement === "first" ? elements[0] : elements[elements.length - 1];
+    if (validate) {
+      return validate(element);
+    }
+    const principal = element.subject ? extractCn(element.subject) : "";
+    const claims = {};
+    if (element.hash)
+      claims.hash = element.hash;
+    if (element.subject)
+      claims.subject = element.subject;
+    if (element.uri)
+      claims.uri = element.uri;
+    if (element.dns.length > 0)
+      claims.dns = [...element.dns];
+    if (element.by)
+      claims.by = element.by;
+    return new AuthContext(domain, true, principal, claims);
+  };
+}
+function parseCertFromHeader(request, header) {
+  const raw = request.headers.get(header);
+  if (!raw) {
+    throw new Error(`Missing ${header} header`);
+  }
+  const pemStr = decodeURIComponent(raw);
+  if (!pemStr.startsWith("-----BEGIN CERTIFICATE-----")) {
+    throw new Error("Header value is not a PEM certificate");
+  }
+  try {
+    return new X509Certificate(pemStr);
+  } catch (exc) {
+    throw new Error(`Failed to parse PEM certificate: ${exc}`);
+  }
+}
+function checkCertExpiry(cert) {
+  const now = new Date;
+  const notBefore = new Date(cert.validFrom);
+  const notAfter = new Date(cert.validTo);
+  if (now < notBefore) {
+    throw new Error("Certificate is not yet valid");
+  }
+  if (now > notAfter) {
+    throw new Error("Certificate has expired");
+  }
+}
+function mtlsAuthenticate(options) {
+  const { validate, header = "X-SSL-Client-Cert", checkExpiry = false } = options;
+  return async function authenticate(request) {
+    const cert = parseCertFromHeader(request, header);
+    if (checkExpiry) {
+      checkCertExpiry(cert);
+    }
+    return validate(cert);
+  };
+}
+var SUPPORTED_ALGORITHMS = new Set(["sha256", "sha1", "sha384", "sha512"]);
+function mtlsAuthenticateFingerprint(options) {
+  const { fingerprints, header, algorithm = "sha256", checkExpiry } = options;
+  if (!SUPPORTED_ALGORITHMS.has(algorithm)) {
+    throw new Error(`Unsupported hash algorithm: ${algorithm}`);
+  }
+  const entries = fingerprints instanceof Map ? fingerprints : new Map(Object.entries(fingerprints));
+  function validate(cert) {
+    const fp = createHash(algorithm).update(cert.raw).digest("hex");
+    const ctx = entries.get(fp);
+    if (!ctx) {
+      throw new Error(`Unknown certificate fingerprint: ${fp}`);
+    }
+    return ctx;
+  }
+  return mtlsAuthenticate({ validate, header, checkExpiry });
+}
+function mtlsAuthenticateSubject(options) {
+  const { header, domain = "mtls", allowedSubjects = null, checkExpiry } = options ?? {};
+  function validate(cert) {
+    const subjectParts = cert.subject.split(`
+`).map((s) => s.trim()).filter(Boolean);
+    const subjectDn = subjectParts.join(", ");
+    let cn = "";
+    for (const part of subjectParts) {
+      if (part.toUpperCase().startsWith("CN=")) {
+        cn = part.slice(3);
+        break;
+      }
+    }
+    if (allowedSubjects !== null && !allowedSubjects.has(cn)) {
+      throw new Error(`Subject CN '${cn}' not in allowed subjects`);
+    }
+    const serialHex = BigInt(`0x${cert.serialNumber}`).toString(16);
+    const notValidAfter = new Date(cert.validTo).toISOString();
+    return new AuthContext(domain, true, cn, {
+      subject_dn: subjectDn,
+      serial: serialHex,
+      not_valid_after: notValidAfter
+    });
+  }
+  return mtlsAuthenticate({ validate, header, checkExpiry });
+}
 // src/protocol.ts
 import { Schema as Schema7 } from "@query-farm/apache-arrow";
 
@@ -3648,7 +4489,7 @@ import { Schema as Schema9 } from "@query-farm/apache-arrow";
 // src/dispatch/stream.ts
 import { Schema as Schema8 } from "@query-farm/apache-arrow";
 var EMPTY_SCHEMA4 = new Schema8([]);
-async function dispatchStream(method, params, writer, reader, serverId, requestId) {
+async function dispatchStream(method, params, writer, reader, serverId, requestId, externalConfig) {
   const isProducer = !!method.producerFn;
   let state;
   try {
@@ -3716,7 +4557,11 @@ async function dispatchStream(method, params, writer, reader, serverId, requestI
         await method.exchangeFn(state, inputBatch, out);
       }
       for (const emitted of out.batches) {
-        stream.write(emitted.batch);
+        let batch = emitted.batch;
+        if (externalConfig) {
+          batch = await maybeExternalizeBatch(batch, externalConfig);
+        }
+        stream.write(batch);
       }
       if (out.finished) {
         break;
@@ -3732,12 +4577,15 @@ async function dispatchStream(method, params, writer, reader, serverId, requestI
 }
 
 // src/dispatch/unary.ts
-async function dispatchUnary(method, params, writer, serverId, requestId) {
+async function dispatchUnary(method, params, writer, serverId, requestId, externalConfig) {
   const schema = method.resultSchema;
   const out = new OutputCollector(schema, true, serverId, requestId);
   try {
     const result = await method.handler(params, out);
-    const resultBatch = buildResultBatch(schema, result, serverId, requestId);
+    let resultBatch = buildResultBatch(schema, result, serverId, requestId);
+    if (externalConfig) {
+      resultBatch = await maybeExternalizeBatch(resultBatch, externalConfig);
+    }
     const batches = [...out.batches.map((b) => b.batch), resultBatch];
     writer.writeStream(schema, batches);
   } catch (error) {
@@ -3748,7 +4596,7 @@ async function dispatchUnary(method, params, writer, serverId, requestId) {
 
 // src/wire/writer.ts
 import { writeSync } from "node:fs";
-import { RecordBatchStreamWriter as RecordBatchStreamWriter4 } from "@query-farm/apache-arrow";
+import { RecordBatchStreamWriter as RecordBatchStreamWriter5 } from "@query-farm/apache-arrow";
 var STDOUT_FD = 1;
 function writeAll(fd, data) {
   let offset = 0;
@@ -3774,7 +4622,7 @@ class IpcStreamWriter {
     this.fd = fd;
   }
   writeStream(schema, batches) {
-    const writer = new RecordBatchStreamWriter4;
+    const writer = new RecordBatchStreamWriter5;
     writer.reset(undefined, schema);
     for (const batch of batches) {
       writer._writeRecordBatch(batch);
@@ -3794,7 +4642,7 @@ class IncrementalStream {
   closed = false;
   constructor(fd, schema) {
     this.fd = fd;
-    this.writer = new RecordBatchStreamWriter4;
+    this.writer = new RecordBatchStreamWriter5;
     this.writer.reset(undefined, schema);
     this.drain();
   }
@@ -3828,10 +4676,14 @@ class VgiRpcServer {
   enableDescribe;
   serverId;
   describeBatch = null;
+  dispatchHook = null;
+  externalConfig;
   constructor(protocol, options) {
     this.protocol = protocol;
     this.enableDescribe = options?.enableDescribe ?? true;
     this.serverId = options?.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+    this.dispatchHook = options?.dispatchHook ?? null;
+    this.externalConfig = options?.externalLocation;
     if (this.enableDescribe) {
       const { batch } = buildDescribeBatch(protocol.name, protocol.getMethods(), this.serverId);
       this.describeBatch = batch;
@@ -3901,10 +4753,29 @@ class VgiRpcServer {
       writer.writeStream(EMPTY_SCHEMA5, [errBatch]);
       return;
     }
-    if (method.type === "unary" /* UNARY */) {
-      await dispatchUnary(method, params, writer, this.serverId, requestId);
-    } else {
-      await dispatchStream(method, params, writer, reader, this.serverId, requestId);
+    const methodType = method.type === "unary" /* UNARY */ ? "unary" : "stream";
+    const info = { method: methodName, methodType, serverId: this.serverId, requestId };
+    const stats = {
+      inputBatches: 0,
+      outputBatches: 0,
+      inputRows: 0,
+      outputRows: 0,
+      inputBytes: 0,
+      outputBytes: 0
+    };
+    const token = this.dispatchHook?.onDispatchStart(info);
+    let dispatchError;
+    try {
+      if (method.type === "unary" /* UNARY */) {
+        await dispatchUnary(method, params, writer, this.serverId, requestId, this.externalConfig);
+      } else {
+        await dispatchStream(method, params, writer, reader, this.serverId, requestId, this.externalConfig);
+      }
+    } catch (e) {
+      dispatchError = e instanceof Error ? e : new Error(String(e));
+      throw e;
+    } finally {
+      this.dispatchHook?.onDispatchEnd(token, info, stats, dispatchError);
     }
   }
 }
@@ -3913,15 +4784,30 @@ export {
   toSchema,
   subprocessConnect,
   str,
+  resolveExternalLocation,
   pipeConnect,
+  parseXfcc,
+  parseUseIdTokenAsBearer,
   parseResourceMetadataUrl,
+  parseDeviceCodeClientSecret,
+  parseDeviceCodeClientId,
   parseDescribeResponse,
+  parseClientSecret,
+  parseClientId,
   oauthResourceMetadataToJson,
+  mtlsAuthenticateXfcc,
+  mtlsAuthenticateSubject,
+  mtlsAuthenticateFingerprint,
+  mtlsAuthenticate,
+  maybeExternalizeBatch,
+  makeExternalLocationBatch,
   jwtAuthenticate,
   jsonStateSerializer,
+  isExternalLocationBatch,
   int32,
   int,
   inferParamTypes,
+  httpsOnlyValidator,
   httpOAuthMetadata,
   httpIntrospect,
   httpConnect,
@@ -3929,8 +4815,11 @@ export {
   float,
   fetchOAuthMetadata,
   createHttpHandler,
+  chainAuthenticate,
   bytes,
   bool,
+  bearerAuthenticateStatic,
+  bearerAuthenticate,
   VgiRpcServer,
   VersionError,
   STATE_KEY,
@@ -3956,4 +4845,4 @@ export {
   ARROW_CONTENT_TYPE
 };
 
-//# debugId=FCA96ECA4C5D644864756E2164756E21
+//# debugId=37CD76108224132A64756E2164756E21