@query-farm/vgi-rpc 0.3.4 → 0.4.0

package/src/http/types.ts

@@ -1,6 +1,8 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+import type { AuthenticateFn, OAuthResourceMetadata } from "./auth.js";
+
 /** Configuration options for createHttpHandler(). */
 export interface HttpHandlerOptions {
   /** URL path prefix for all endpoints. Default: "/vgi" */
@@ -22,6 +24,10 @@ export interface HttpHandlerOptions {
   /** zstd compression level for responses (1-22). If set, responses are
    *  compressed when the client sends Accept-Encoding: zstd. */
   compressionLevel?: number;
+  /** Optional authentication callback. Called for each request before dispatch. */
+  authenticate?: AuthenticateFn;
+  /** Optional RFC 9728 OAuth Protected Resource Metadata. Served at well-known endpoint. */
+  oauthResourceMetadata?: OAuthResourceMetadata;
 }
 
 /** Serializer for stream state objects stored in state tokens. */

package/src/index.ts

@@ -1,6 +1,7 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+export { AuthContext } from "./auth.js";
 export * from "./client/index.js";
 export {
   DESCRIBE_METHOD_NAME,
@@ -20,9 +21,14 @@ export {
 export { RpcError, VersionError } from "./errors.js";
 export {
   ARROW_CONTENT_TYPE,
+  type AuthenticateFn,
   createHttpHandler,
   type HttpHandlerOptions,
+  type JwtAuthenticateOptions,
   jsonStateSerializer,
+  jwtAuthenticate,
+  type OAuthResourceMetadata,
+  oauthResourceMetadataToJson,
   type StateSerializer,
   type UnpackedToken,
   unpackStateToken,
@@ -42,6 +48,7 @@ export {
 } from "./schema.js";
 export { VgiRpcServer } from "./server.js";
 export {
+  type CallContext,
   type ExchangeFn,
   type ExchangeInit,
   type HeaderInit,

package/src/types.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { RecordBatch, recordBatchFromArrays, type Schema } from "@query-farm/apache-arrow";
+import { AuthContext } from "./auth.js";
 import { buildLogBatch, coerceInt64 } from "./wire/response.js";
 
 export enum MethodType {
@@ -14,6 +15,11 @@ export interface LogContext {
   clientLog(level: string, message: string, extra?: Record<string, string>): void;
 }
 
+/** Extended context with authentication info, available to handlers. */
+export interface CallContext extends LogContext {
+  readonly auth: AuthContext;
+}
+
 /** Handler for unary (request-response) RPC methods. */
 export type UnaryHandler = (
   params: Record<string, any>,
@@ -61,7 +67,7 @@ export interface EmittedBatch {
  * Accumulates output batches during a produce/exchange call.
  * Enforces that exactly one data batch is emitted per call (plus any number of log batches).
  */
-export class OutputCollector implements LogContext {
+export class OutputCollector implements CallContext {
   private _batches: EmittedBatch[] = [];
   private _dataBatchIdx: number | null = null;
   private _finished = false;
@@ -69,12 +75,20 @@ export class OutputCollector implements LogContext {
   private _outputSchema: Schema;
   private _serverId: string;
   private _requestId: string | null;
-
-  constructor(outputSchema: Schema, producerMode = true, serverId = "", requestId: string | null = null) {
+  readonly auth: AuthContext;
+
+  constructor(
+    outputSchema: Schema,
+    producerMode = true,
+    serverId = "",
+    requestId: string | null = null,
+    authContext?: AuthContext,
+  ) {
     this._outputSchema = outputSchema;
     this._producerMode = producerMode;
     this._serverId = serverId;
     this._requestId = requestId;
+    this.auth = authContext ?? AuthContext.anonymous();
   }
 
   get outputSchema(): Schema {

package/src/wire/response.ts

@@ -133,25 +133,39 @@ export function buildLogBatch(
   return buildEmptyBatch(schema, metadata);
 }
 
+/**
+ * Recursively create empty (0-row) Data for any Arrow type,
+ * including complex types (Struct, List, FixedSizeList, Map).
+ */
+function makeEmptyData(type: DataType): Data {
+  if (DataType.isStruct(type)) {
+    const children = type.children.map((f: Field) => 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]) } as any);
+  }
+  if (DataType.isFixedSizeList(type)) {
+    const childData = makeEmptyData(type.children[0].type);
+    return makeData({ type, length: 0, child: childData, nullCount: 0 } as any);
+  }
+  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]) } as any);
+  }
+  return makeData({ type, length: 0, nullCount: 0 });
+}
+
 /**
  * Build a 0-row batch from a schema with metadata.
  * Used for error/log batches.
  */
 export function buildEmptyBatch(schema: Schema, metadata?: Map<string, string>): RecordBatch {
-  const children = schema.fields.map((f: Field) => {
-    return makeData({ type: f.type, length: 0, nullCount: 0 });
-  });
-
-  if (schema.fields.length === 0) {
-    const structType = new Struct(schema.fields);
-    const data = makeData({
-      type: structType,
-      length: 0,
-      children: [],
-      nullCount: 0,
-    });
-    return new RecordBatch(schema, data, metadata);
-  }
+  const children = schema.fields.map((f: Field) => makeEmptyData(f.type));
 
   const structType = new Struct(schema.fields);
   const data = makeData({