@query-farm/vgi-rpc 0.7.0 → 0.7.2

package/src/constants.ts

@@ -1,21 +1,33 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
-/** Well-known metadata keys matching Python's metadata.py */
+// Well-known metadata keys matching Python's metadata.py.
 
+/** Batch-metadata key carrying the invoked RPC method name. */
 export const RPC_METHOD_KEY = "vgi_rpc.method";
+/** Batch-metadata key carrying a log batch's severity level. */
 export const LOG_LEVEL_KEY = "vgi_rpc.log_level";
+/** Batch-metadata key carrying a log batch's message text. */
 export const LOG_MESSAGE_KEY = "vgi_rpc.log_message";
+/** Batch-metadata key carrying a log batch's structured extra fields. */
 export const LOG_EXTRA_KEY = "vgi_rpc.log_extra";
+/** Batch-metadata key carrying the wire request-framing version. */
 export const REQUEST_VERSION_KEY = "vgi_rpc.request_version";
+/** Current wire request-framing version. Distinct from the application-level
+ *  {@link PROTOCOL_VERSION_KEY protocol version}. */
 export const REQUEST_VERSION = "1";
 
+/** Batch-metadata key identifying the server instance that produced a batch. */
 export const SERVER_ID_KEY = "vgi_rpc.server_id";
+/** Batch-metadata key carrying the client-supplied request id. */
 export const REQUEST_ID_KEY = "vgi_rpc.request_id";
 
+/** Batch-metadata key carrying the service / protocol name. */
 export const PROTOCOL_NAME_KEY = "vgi_rpc.protocol_name";
+/** Batch-metadata key carrying the `__describe__` response schema version. */
 export const DESCRIBE_VERSION_KEY = "vgi_rpc.describe_version";
 export const PROTOCOL_HASH_KEY = "vgi_rpc.protocol_hash";
+/** Current `__describe__` response schema version (the slim 8-column schema). */
 export const DESCRIBE_VERSION = "4";
 
 /** Application protocol surface version. Carried on every request batch from
@@ -26,14 +38,17 @@ export const DESCRIBE_VERSION = "4";
  *  (wire framing). Mirrors Python's `PROTOCOL_VERSION_KEY`. */
 export const PROTOCOL_VERSION_KEY = "vgi_rpc.protocol_version";
 
+/** Reserved method name for the introspection (`__describe__`) call. */
 export const DESCRIBE_METHOD_NAME = "__describe__";
 
+/** Batch-metadata key carrying the base64-encoded stream continuation/state token. */
 export const STATE_KEY = "vgi_rpc.stream_state#b64";
 export const CANCEL_KEY = "vgi_rpc.cancel";
 
 export const LOCATION_KEY = "vgi_rpc.location";
 export const LOCATION_SHA256_KEY = "vgi_rpc.location.sha256";
 
+/** HTTP response header set when an RPC error is returned over the HTTP transport. */
 export const RPC_ERROR_HEADER = "X-VGI-RPC-Error";
 
 /** Top-level metadata key on an EXCEPTION batch identifying the error category.

package/src/errors.ts

@@ -4,8 +4,11 @@
 /** Error thrown when the server encounters an RPC protocol error. */
 export class RpcError extends Error {
   constructor(
+    /** Remote error class name (e.g. `"ValueError"`). */
     public readonly errorType: string,
+    /** Human-readable message from the remote error. */
     public readonly errorMessage: string,
+    /** Remote stack-trace text, or an empty string when unavailable. */
     public readonly remoteTraceback: string,
   ) {
     super(`${errorType}: ${errorMessage}`);
@@ -21,10 +24,12 @@ export class VersionError extends Error {
   }
 }
 
-/** Well-known values for the `vgi_rpc.error_kind` batch metadata key. Mirrors
- *  Python's `vgi_rpc.metadata.ERROR_KIND_*` constants. */
+/** `vgi_rpc.error_kind` batch-metadata value for {@link MethodNotImplementedError}.
+ *  Mirrors Python's `vgi_rpc.metadata.ERROR_KIND_*` constants. */
 export const ERROR_KIND_METHOD_NOT_IMPLEMENTED = "method_not_implemented";
+/** `vgi_rpc.error_kind` batch-metadata value for {@link SessionLostError}. */
 export const ERROR_KIND_SESSION_LOST = "session_lost";
+/** `vgi_rpc.error_kind` batch-metadata value for {@link ServerDrainingError}. */
 export const ERROR_KIND_SERVER_DRAINING = "server_draining";
 export const ERROR_KIND_PROTOCOL_VERSION_MISMATCH = "protocol_version_mismatch";
 
@@ -68,7 +73,9 @@ export function parseProtocolVersion(value: string): [number, number, number] {
  *  string-matching the message.
  */
 export class MethodNotImplementedError extends Error {
+  /** Typed `vgi_rpc.error_kind` marker for this error class. */
   static readonly errorKind = ERROR_KIND_METHOD_NOT_IMPLEMENTED;
+  /** Typed `vgi_rpc.error_kind` marker hoisted onto the error batch metadata. */
   readonly errorKind = ERROR_KIND_METHOD_NOT_IMPLEMENTED;
   constructor(message: string) {
     super(message);
@@ -79,7 +86,9 @@ export class MethodNotImplementedError extends Error {
 /** Raised when a sticky session token is malformed, expired, evicted, or
  *  bound to a different worker / principal. HTTP-only. */
 export class SessionLostError extends Error {
+  /** Typed `vgi_rpc.error_kind` marker for this error class. */
   static readonly errorKind = ERROR_KIND_SESSION_LOST;
+  /** Typed `vgi_rpc.error_kind` marker hoisted onto the error batch metadata. */
   readonly errorKind = ERROR_KIND_SESSION_LOST;
   constructor(message: string) {
     super(message);
@@ -89,7 +98,9 @@ export class SessionLostError extends Error {
 
 /** Raised when `ctx.openSession` is called while the server is draining. */
 export class ServerDrainingError extends Error {
+  /** Typed `vgi_rpc.error_kind` marker for this error class. */
   static readonly errorKind = ERROR_KIND_SERVER_DRAINING;
+  /** Typed `vgi_rpc.error_kind` marker hoisted onto the error batch metadata. */
   readonly errorKind = ERROR_KIND_SERVER_DRAINING;
   constructor(message: string) {
     super(message);

package/src/external.ts

@@ -54,7 +54,12 @@ export interface ExternalLocationConfig {
   /** Minimum batch byte size to trigger externalization. Default: 1MB. */
   externalizeThresholdBytes?: number;
   /** Optional zstd compression for uploaded data. */
-  compression?: { algorithm: "zstd"; level?: number };
+  compression?: {
+    /** Compression algorithm; only `"zstd"` is currently supported. */
+    algorithm: "zstd";
+    /** zstd compression level. Default: 3. */
+    level?: number;
+  };
   /** URL validator called before fetching. Throw to reject. Default: HTTPS-only. */
   urlValidator?: ((url: string) => void) | null;
 }

package/src/http/auth.ts

@@ -8,14 +8,27 @@ export type AuthenticateFn = (request: Request) => AuthContext | Promise<AuthCon
 
 /** RFC 9728 OAuth Protected Resource Metadata. */
 export interface OAuthResourceMetadata {
+  /** The protected resource's canonical URL. Doubles as the base for the
+   *  `/_oauth/callback` redirect URI. */
   resource: string;
+  /** Authorization-server issuer URLs. The PKCE flow uses
+   *  `authorizationServers[0]` for OIDC discovery. */
   authorizationServers: string[];
+  /** Scopes the resource advertises. When non-empty these become the PKCE
+   *  authorization request's space-joined `scope`, taking precedence over
+   *  {@link HttpHandlerOptions.oauthPkceScope}. */
   scopesSupported?: string[];
+  /** Advertised bearer methods (e.g. `["header"]`). */
   bearerMethodsSupported?: string[];
+  /** JWS algorithms the resource accepts. */
   resourceSigningAlgValuesSupported?: string[];
+  /** Human-readable resource name. */
   resourceName?: string;
+  /** Documentation URL for the resource. */
   resourceDocumentation?: string;
+  /** Policy URL for the resource. */
   resourcePolicyUri?: string;
+  /** Terms-of-service URL for the resource. */
   resourceTosUri?: string;
   /** OAuth client_id that clients should use with the authorization server. */
   clientId?: string;

package/src/http/common.ts

@@ -11,6 +11,7 @@ import {
 import { RPC_ERROR_HEADER } from "../constants.js";
 import type { CookieSpec } from "../types.js";
 
+/** MIME type for Arrow IPC stream request and response bodies. */
 export const ARROW_CONTENT_TYPE = "application/vnd.apache.arrow.stream";
 
 // Sticky session header conventions (HTTP-only). Mirrors Python's

package/src/http/jwt.ts

@@ -5,6 +5,7 @@ import * as oauth from "oauth4webapi";
 import { AuthContext } from "../auth.js";
 import type { AuthenticateFn } from "./auth.js";
 
+/** Options for {@link jwtAuthenticate}, configuring JWT Bearer-token validation. */
 export interface JwtAuthenticateOptions {
   /** The expected `iss` claim (also used to discover AS metadata). */
   issuer: string;

package/src/http/mtls.ts

@@ -24,11 +24,18 @@ function _loadNodeCrypto(): { X509Certificate: any; createHash: any } {
 
 /** A single element from an `x-forwarded-client-cert` header. */
 export interface XfccElement {
+  /** Hex SHA-256 digest of the client certificate (`Hash` key). */
   hash: string | null;
+  /** URL-decoded PEM of the client certificate (`Cert` key), if the proxy
+   *  forwarded it. */
   cert: string | null;
+  /** Certificate Subject DN (`Subject` key). */
   subject: string | null;
+  /** URL-decoded URI-type Subject Alternative Name (`URI` key). */
   uri: string | null;
+  /** DNS-type Subject Alternative Names (`DNS` keys); may repeat in the header. */
   dns: readonly string[];
+  /** URL-decoded URI of the proxy that presented the cert (`By` key). */
   by: string | null;
 }
 

package/src/http/token.ts

@@ -139,10 +139,15 @@ export function packStateToken(
   return bytesToBase64(wire);
 }
 
+/** Decrypted payload of a state token, as returned by {@link unpackStateToken}. */
 export interface UnpackedToken {
+  /** Serialized stream-state bytes carried by the token. */
   stateBytes: Uint8Array;
+  /** Serialized output-schema IPC bytes. */
   schemaBytes: Uint8Array;
+  /** Serialized input-schema IPC bytes (exchange streams). */
   inputSchemaBytes: Uint8Array;
+  /** Unix epoch seconds at which the token was minted (used for TTL checks). */
   createdAt: number;
 }
 

package/src/http/types.ts

@@ -112,7 +112,9 @@ export interface HttpHandlerOptions {
 
 /** Serializer for stream state objects stored in state tokens. */
 export interface StateSerializer {
+  /** Encode a stream-state object into the bytes sealed inside a state token. */
   serialize(state: any): Uint8Array;
+  /** Decode the bytes recovered from a state token back into a state object. */
   deserialize(bytes: Uint8Array): any;
 }
 

package/src/launcher/serve-unix.ts

@@ -79,6 +79,7 @@ export interface ServeUnixOptions {
 
 /** Handle returned by {@link serveUnix} for callers that want to stop the server. */
 export interface ServeUnixHandle {
+  /** Absolute path of the bound AF_UNIX socket the server is listening on. */
   readonly socketPath: string;
   /** Shut down the listener and unlink the socket file. */
   stop(): Promise<void>;

package/src/launcher/state.ts

@@ -15,11 +15,15 @@ import { computeHash } from "./hash.js";
 
 /** Filesystem layout for one worker tuple: `<state_dir>/<hash>.{lock,sock,meta}`. */
 export interface SocketPaths {
+  /** Advisory lockfile path (`<hash>.lock`) guarding launch + liveness. */
   lockPath: string;
+  /** AF_UNIX socket path (`<hash>.sock`) the worker binds. */
   sockPath: string;
+  /** Launch-metadata JSON path (`<hash>.meta`) read by `--status`. */
   metaPath: string;
 }
 
+/** Derive the lock/sock/meta path triple for a worker `hashId` under `stateDir`. */
 export function socketPaths(stateDir: string, hashId: string): SocketPaths {
   return {
     lockPath: path.join(stateDir, `${hashId}.lock`),
@@ -97,15 +101,23 @@ export function writeMeta(metaPath: string, workerArgv: readonly string[], cwd:
 // Status / GC
 // ---------------------------------------------------------------------------
 
+/** One row of `--status` output describing a launched worker tuple. */
 export interface StatusRow {
+  /** Canonical hash identifying the worker tuple (the `<hash>` filename stem). */
   hashId: string;
+  /** Worker argv recorded at launch, or `[]` when the meta file is missing. */
   cmd: string[];
+  /** Working directory recorded at launch, or `""` when unknown. */
   cwd: string;
+  /** AF_UNIX socket path the worker binds. */
   socket: string;
+  /** Unix epoch seconds the worker was launched, or `null` when unknown. */
   startedAt: number | null;
+  /** Whether a probe connection to {@link StatusRow.socket} currently succeeds. */
   alive: boolean;
 }
 
+/** Outcome of a {@link gcStateDir} sweep. */
 export interface GcResult {
   /** Hash IDs of stale entries that were removed. */
   cleaned: string[];

package/src/protocol.ts

@@ -23,6 +23,7 @@ const EMPTY_SCHEMA = makeSchema([]);
  * Register unary, producer, and exchange methods, then pass to `VgiRpcServer`.
  */
 export class Protocol {
+  /** Service / protocol name, exposed to clients via introspection. */
   readonly name: string;
   /**
    * Application protocol surface version. When non-empty, the server enforces
@@ -162,6 +163,8 @@ export class Protocol {
     return this;
   }
 
+  /** Snapshot of the registered methods, keyed by method name. Returns a copy,
+   *  so mutating it does not affect the protocol. */
   getMethods(): Map<string, MethodDefinition> {
     return new Map(this._methods);
   }

package/src/types.ts

@@ -5,8 +5,14 @@ import { batchFromColumns, isBatch, type VgiBatch, type VgiSchema } from "./arro
 import { AuthContext } from "./auth.js";
 import { buildLogBatch, coerceInt64 } from "./wire/response.js";
 
+/**
+ * Whether an RPC method is request/response or streaming. Mirrors Python's
+ * `MethodType` and is carried in the `__describe__` payload.
+ */
 export enum MethodType {
+  /** Single request batch in, single result batch out. */
   UNARY = "unary",
+  /** Streamed batches — either a producer or an exchange stream. */
   STREAM = "stream",
 }
 
@@ -25,8 +31,11 @@ export enum MethodType {
  * - `UNIX` — AF_UNIX socket handler (the launcher path).
  */
 export enum TransportKind {
+  /** Stdio worker — the standalone {@link VgiRpcServer} loop. */
   PIPE = "pipe",
+  /** Fetch-style HTTP handler (`createHttpHandler`). */
   HTTP = "http",
+  /** AF_UNIX socket handler (the launcher path). */
   UNIX = "unix",
 }
 
@@ -46,6 +55,9 @@ export type ServeStartHook = (kind: TransportKind) => void | Promise<void>;
 
 /** Logging interface available to handlers. */
 export interface LogContext {
+  /** Emit a client-directed log message (sent as a zero-row log batch on the
+   *  wire). `level` is a severity label such as `"info"`, `"warning"`, or
+   *  `"error"`; `extra` carries optional structured string key/value pairs. */
   clientLog(level: string, message: string, extra?: Record<string, string>): void;
 }
 
@@ -90,6 +102,8 @@ export interface StickyContext {
 
 /** Extended context with authentication info, available to handlers. */
 export interface CallContext extends LogContext {
+  /** Authenticated principal for this call; {@link AuthContext.anonymous} when
+   *  the request was not authenticated. */
   readonly auth: AuthContext;
   /** Coarse identifier of the bound transport, or `undefined` until the
    *  server begins serving (the value is committed by the lifecycle hook
@@ -200,23 +214,47 @@ export type HeaderInit = (params: Record<string, any>, state: any, ctx: LogConte
  */
 export type OnCancelFn<S = any> = (state: S) => Promise<void> | void;
 
+/**
+ * In-memory definition of one registered RPC method, produced by the
+ * {@link Protocol} builder and consumed by the dispatch layer. Which optional
+ * fields are populated depends on the method {@link type}: `handler` for unary
+ * methods, `producerInit`/`producerFn` for producer streams, and
+ * `exchangeInit`/`exchangeFn` for exchange streams.
+ */
 export interface MethodDefinition {
+  /** Method name as registered on the protocol. */
   name: string;
+  /** Whether the method is unary or streaming. */
   type: MethodType;
+  /** Schema of the request parameters batch. */
   paramsSchema: VgiSchema;
+  /** Schema of the unary result batch (unused for streams). */
   resultSchema: VgiSchema;
+  /** Schema of streamed output batches (producer and exchange streams). */
   outputSchema?: VgiSchema;
+  /** Schema of streamed input batches (exchange streams only). */
   inputSchema?: VgiSchema;
+  /** Implementation for unary methods. */
   handler?: UnaryHandler;
+  /** Builds the initial state object for a producer stream. */
   producerInit?: ProducerInit;
+  /** Produces output batches for a producer stream. */
   producerFn?: ProducerFn;
+  /** Builds the initial state object for an exchange stream. */
   exchangeInit?: ExchangeInit;
+  /** Handles each input batch of an exchange stream. */
   exchangeFn?: ExchangeFn;
+  /** Schema of the optional per-stream header batch. */
   headerSchema?: VgiSchema;
+  /** Builds the optional header batch emitted before the first output batch. */
   headerInit?: HeaderInit;
+  /** Optional hook run when the client cancels a stream. */
   onCancel?: OnCancelFn;
+  /** Human-readable method documentation, surfaced via introspection. */
   doc?: string;
+  /** Default values applied to omitted request parameters. */
   defaults?: Record<string, any>;
+  /** Human-readable parameter type names, surfaced via introspection. */
   paramTypes?: Record<string, string>;
 }
 
@@ -264,11 +302,17 @@ export interface DispatchInfo {
 
 /** Per-call I/O counters, matching Python's CallStatistics. */
 export interface CallStatistics {
+  /** Number of input batches read from the client. */
   inputBatches: number;
+  /** Number of output batches written to the client. */
   outputBatches: number;
+  /** Total rows across all input batches. */
   inputRows: number;
+  /** Total rows across all output batches. */
   outputRows: number;
+  /** Total serialized bytes of all input batches. */
   inputBytes: number;
+  /** Total serialized bytes of all output batches. */
   outputBytes: number;
 }
 
@@ -280,7 +324,11 @@ export type HookToken = unknown;
  * Implementations must be safe for concurrent use (HTTP transport is concurrent).
  */
 export interface DispatchHook {
+  /** Invoked before the method runs. The returned {@link HookToken} is opaque
+   *  to the framework and passed back to {@link onDispatchEnd}. */
   onDispatchStart(info: DispatchInfo): HookToken;
+  /** Invoked after the method completes or throws. `stats` carries the per-call
+   *  I/O counters; `error` is set only when the dispatch failed. */
   onDispatchEnd(token: HookToken, info: DispatchInfo, stats: CallStatistics, error?: Error): void;
 }
 
@@ -304,6 +352,8 @@ export class OutputCollector implements CallContext {
   private _cookieSinkEnabled = false;
   private _responseCookies: CookieSpec[] = [];
   private _stickyContext: StickyContext | null = null;
+  /** Authenticated principal for this call; {@link AuthContext.anonymous} when
+   *  the request was not authenticated. */
   readonly auth: AuthContext;
   readonly cookies: ReadonlyMap<string, string>;
   readonly kind?: TransportKind;
@@ -423,14 +473,18 @@ export class OutputCollector implements CallContext {
     sink.action = "close";
   }
 
+  /** Schema of the data batches this collector emits. */
   get outputSchema(): VgiSchema {
     return this._outputSchema;
   }
 
+  /** True once {@link finish} has been called (producer streams only). */
   get finished(): boolean {
     return this._finished;
   }
 
+  /** Batches emitted so far this call — the single data batch plus any log
+   *  batches, in emission order. Consumed by the dispatch layer. */
   get batches(): EmittedBatch[] {
     return this._batches;
   }