@query-farm/vgi-rpc 0.6.4 → 0.7.1

package/src/otel.ts

@@ -119,42 +119,48 @@ export function createOtelHook(config?: OtelConfig): DispatchHook {
       const durationS = (performance.now() - t.startTime) / 1000;
       const status = error ? "error" : "ok";
 
-      // Finalize span
-      if (t.span) {
-        if (stats) {
-          t.span.setAttributes({
-            "rpc.vgi_rpc.input_batches": stats.inputBatches,
-            "rpc.vgi_rpc.output_batches": stats.outputBatches,
-            "rpc.vgi_rpc.input_rows": stats.inputRows,
-            "rpc.vgi_rpc.output_rows": stats.outputRows,
-            "rpc.vgi_rpc.input_bytes": stats.inputBytes,
-            "rpc.vgi_rpc.output_bytes": stats.outputBytes,
-          });
-        }
+      // Finalize span — wrap in try/finally so metric recording still
+      // runs if an exporter inside span.end() raises. Mirrors the Python
+      // fix that detaches the otel context unconditionally; TS doesn't
+      // attach context, but the same shape protects metric counters from
+      // a single misbehaving exporter taking out request observability.
+      try {
+        if (t.span) {
+          if (stats) {
+            t.span.setAttributes({
+              "rpc.vgi_rpc.input_batches": stats.inputBatches,
+              "rpc.vgi_rpc.output_batches": stats.outputBatches,
+              "rpc.vgi_rpc.input_rows": stats.inputRows,
+              "rpc.vgi_rpc.output_rows": stats.outputRows,
+              "rpc.vgi_rpc.input_bytes": stats.inputBytes,
+              "rpc.vgi_rpc.output_bytes": stats.outputBytes,
+            });
+          }
 
-        if (error) {
-          t.span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
-          t.span.setAttribute("rpc.vgi_rpc.error_type", error.constructor.name);
-          if (recordExceptions) {
-            t.span.recordException(error);
+          if (error) {
+            t.span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+            t.span.setAttribute("rpc.vgi_rpc.error_type", error.constructor.name);
+            if (recordExceptions) {
+              t.span.recordException(error);
+            }
+          } else {
+            t.span.setStatus({ code: SpanStatusCode.OK });
           }
-        } else {
-          t.span.setStatus({ code: SpanStatusCode.OK });
+          t.span.end();
+        }
+      } finally {
+        // Record metrics — runs even if span finalisation above raises.
+        if (enableMetrics) {
+          const metricAttrs: Attributes = {
+            "rpc.system": "vgi_rpc",
+            "rpc.service": serviceName,
+            "rpc.method": info.method,
+            "rpc.vgi_rpc.method_type": info.methodType,
+            status,
+          };
+          requestCounter?.add(1, metricAttrs);
+          durationHistogram?.record(durationS, metricAttrs);
         }
-        t.span.end();
-      }
-
-      // Record metrics
-      if (enableMetrics) {
-        const metricAttrs: Attributes = {
-          "rpc.system": "vgi_rpc",
-          "rpc.service": serviceName,
-          "rpc.method": info.method,
-          "rpc.vgi_rpc.method_type": info.methodType,
-          status,
-        };
-        requestCounter?.add(1, metricAttrs);
-        durationHistogram?.record(durationS, metricAttrs);
       }
     },
   };

package/src/protocol.ts

@@ -1,7 +1,8 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
-import { Schema } from "@query-farm/apache-arrow";
+import { schema as makeSchema } from "./arrow/index.js";
+import { parseProtocolVersion } from "./errors.js";
 import { inferParamTypes, type SchemaLike, toSchema } from "./schema.js";
 import {
   type ExchangeFn,
@@ -9,23 +10,43 @@ import {
   type HeaderInit,
   type MethodDefinition,
   MethodType,
+  type OnCancelFn,
   type ProducerFn,
   type ProducerInit,
   type UnaryHandler,
 } from "./types.js";
 
-const EMPTY_SCHEMA = new Schema([]);
+const EMPTY_SCHEMA = makeSchema([]);
 
 /**
  * Fluent builder for defining RPC methods.
  * 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
+   * exact major+minor match (patch ignored) against every request's
+   * `vgi_rpc.protocol_version` metadata; clients bound to this Protocol emit
+   * the value on every request. Format: canonical semver MAJOR.MINOR.PATCH.
+   * Mirrors Python's `Protocol.protocol_version` ClassVar.
+   */
+  readonly protocolVersion: string;
+  /** Parsed semver tuple; null when `protocolVersion` is unset. */
+  readonly protocolVersionParts: readonly [number, number, number] | null;
   private _methods: Map<string, MethodDefinition> = new Map();
 
-  constructor(name: string) {
+  constructor(name: string, options?: { protocolVersion?: string }) {
     this.name = name;
+    const raw = options?.protocolVersion;
+    if (raw === undefined || raw === "") {
+      this.protocolVersion = "";
+      this.protocolVersionParts = null;
+    } else {
+      this.protocolVersion = raw;
+      this.protocolVersionParts = parseProtocolVersion(raw);
+    }
   }
 
   /**
@@ -74,6 +95,7 @@ export class Protocol {
       outputSchema: SchemaLike;
       init: ProducerInit<S>;
       produce: ProducerFn<S>;
+      onCancel?: OnCancelFn<S>;
       headerSchema?: SchemaLike;
       headerInit?: HeaderInit;
       doc?: string;
@@ -91,6 +113,7 @@ export class Protocol {
       inputSchema: EMPTY_SCHEMA,
       producerInit: config.init as ProducerInit,
       producerFn: config.produce as ProducerFn,
+      onCancel: config.onCancel as OnCancelFn | undefined,
       headerSchema: config.headerSchema ? toSchema(config.headerSchema) : undefined,
       headerInit: config.headerInit,
       doc: config.doc,
@@ -112,6 +135,7 @@ export class Protocol {
       outputSchema: SchemaLike;
       init: ExchangeInit<S>;
       exchange: ExchangeFn<S>;
+      onCancel?: OnCancelFn<S>;
       headerSchema?: SchemaLike;
       headerInit?: HeaderInit;
       doc?: string;
@@ -129,6 +153,7 @@ export class Protocol {
       outputSchema: toSchema(config.outputSchema),
       exchangeInit: config.init as ExchangeInit,
       exchangeFn: config.exchange as ExchangeFn,
+      onCancel: config.onCancel as OnCancelFn | undefined,
       headerSchema: config.headerSchema ? toSchema(config.headerSchema) : undefined,
       headerInit: config.headerInit,
       doc: config.doc,
@@ -138,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/schema.ts

@@ -2,109 +2,160 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import {
-  Binary,
-  Bool,
-  DataType,
-  Field,
-  Float32,
-  Float64,
-  Int16,
-  Int32,
-  Int64,
-  Schema,
-  Utf8,
-} from "@query-farm/apache-arrow";
+  binary,
+  bool as boolType,
+  float32 as float32Type,
+  float64 as float64Type,
+  int8 as int8Type,
+  int16 as int16Type,
+  int32 as int32Type,
+  int64 as int64Type,
+  isBinary,
+  isBool,
+  isFloat,
+  isInt,
+  isUtf8,
+  field as makeField,
+  schema as makeSchema,
+  uint8 as uint8Type,
+  uint16 as uint16Type,
+  uint32 as uint32Type,
+  uint64 as uint64Type,
+  utf8,
+  type VgiDataType,
+  type VgiField,
+  type VgiSchema,
+} from "./arrow/index.js";
 
 // ---------------------------------------------------------------------------
 // Convenient DataType singletons — re-export so users avoid arrow imports
 // ---------------------------------------------------------------------------
 
 /** Apache Arrow Utf8 type. Use as schema shorthand: `{ name: str }` */
-export const str = new Utf8();
+export const str = utf8();
 /** Apache Arrow Binary type. Use as schema shorthand: `{ data: bytes }` */
-export const bytes = new Binary();
+export const bytes = binary();
 /** Apache Arrow Int64 type. Use as schema shorthand: `{ count: int }` */
-export const int = new Int64();
+export const int = int64Type();
 /** Apache Arrow Int32 type. Use as schema shorthand: `{ count: int32 }` */
-export const int32 = new Int32();
+export const int32 = int32Type();
+/** Apache Arrow Int16 type. Use as schema shorthand: `{ count: int16 }` */
+export const int16 = int16Type();
+/** Apache Arrow Int8 type. Use as schema shorthand: `{ count: int8 }` */
+export const int8 = int8Type();
+/** Apache Arrow Uint8 type. Use as schema shorthand: `{ count: uint8 }` */
+export const uint8 = uint8Type();
+/** Apache Arrow Uint16 type. Use as schema shorthand: `{ count: uint16 }` */
+export const uint16 = uint16Type();
+/** Apache Arrow Uint32 type. Use as schema shorthand: `{ count: uint32 }` */
+export const uint32 = uint32Type();
+/** Apache Arrow Uint64 type. Use as schema shorthand: `{ count: uint64 }` */
+export const uint64 = uint64Type();
 /** Apache Arrow Float64 type. Use as schema shorthand: `{ value: float }` */
-export const float = new Float64();
+export const float = float64Type();
 /** Apache Arrow Float32 type. Use as schema shorthand: `{ value: float32 }` */
-export const float32 = new Float32();
+export const float32 = float32Type();
 /** Apache Arrow Bool type. Use as schema shorthand: `{ flag: bool }` */
-export const bool = new Bool();
+export const bool = boolType();
 
 // ---------------------------------------------------------------------------
 // SchemaLike — shorthand for declaring schemas
 // ---------------------------------------------------------------------------
 
+/**
+ * Structural minimum that any backend's Schema must satisfy. arrow-js's
+ * `Schema`, vgi-typescript's `VgiSchema`, and flechette's `Schema` all match
+ * this shape. Used so vgi-rpc consumers don't have to know which Arrow
+ * library is on the other side of the wire.
+ *
+ * Kept exported for backwards compatibility — equivalent to `VgiSchema`.
+ */
+export interface SchemaShape {
+  readonly fields: ReadonlyArray<{
+    readonly name: string;
+    readonly type: { readonly typeId: number };
+    readonly nullable?: boolean;
+    readonly metadata?: Map<string, string>;
+  }>;
+  readonly metadata?: Map<string, string> | null;
+}
+
 /**
  * A schema specification that accepts:
- * - A real `Schema` (passed through)
- * - A record mapping field names to `DataType` instances or `Field` instances
+ * - A real `VgiSchema` (passed through)
+ * - Anything structurally `SchemaShape`
+ * - A record mapping field names to `VgiDataType` instances or `VgiField` instances
  * - An empty `{}` for an empty schema
  */
-export type SchemaLike = Schema | Record<string, DataType | Field>;
+export type SchemaLike = VgiSchema | SchemaShape | Record<string, VgiDataType | VgiField>;
+
+function isField(x: unknown): x is VgiField {
+  return (
+    x != null &&
+    typeof (x as any).name === "string" &&
+    (x as any).type != null &&
+    typeof (x as any).nullable === "boolean"
+  );
+}
+
+function isDataType(x: unknown): x is VgiDataType {
+  return x != null && typeof (x as any).typeId === "number";
+}
 
 /**
- * Convert a SchemaLike spec into a real `Schema`.
- *
- * - `Schema` → returned as-is
- * - `Record<string, DataType>` → each entry becomes `new Field(name, type, false)`
- * - `Record<string, Field>` → each entry is passed through
- * - `{}` → `new Schema([])`
+ * Convert a SchemaLike spec into a real `VgiSchema`.
  */
-export function toSchema(spec: SchemaLike): Schema {
-  if (spec instanceof Schema) return spec;
+export function toSchema(spec: SchemaLike): VgiSchema {
+  // VgiSchema / SchemaShape branch: anything with a `fields` array.
+  const maybeFields = (spec as { fields?: unknown }).fields;
+  if (Array.isArray(maybeFields)) {
+    const out: VgiField[] = [];
+    for (const f of maybeFields as ReadonlyArray<any>) {
+      if (isField(f)) {
+        out.push(f);
+      } else {
+        out.push(makeField(f.name, f.type, f.nullable ?? true, f.metadata));
+      }
+    }
+    return makeSchema(out);
+  }
 
-  const fields: Field[] = [];
+  const fields: VgiField[] = [];
   for (const [name, value] of Object.entries(spec)) {
-    if (value instanceof Field) {
+    if (isField(value)) {
       fields.push(value);
-    } else if (value instanceof DataType) {
-      fields.push(new Field(name, value, false));
+    } else if (isDataType(value)) {
+      fields.push(makeField(name, value, false));
     } else {
       throw new TypeError(`Invalid schema value for "${name}": expected DataType or Field, got ${typeof value}`);
     }
   }
-  return new Schema(fields);
+  return makeSchema(fields);
 }
 
 // ---------------------------------------------------------------------------
 // inferParamTypes — derive paramTypes from a schema spec
 // ---------------------------------------------------------------------------
 
-const TYPE_MAP: [new (...args: any[]) => DataType, string][] = [
-  [Utf8, "str"],
-  [Binary, "bytes"],
-  [Bool, "bool"],
-  [Float64, "float"],
-  [Float32, "float"],
-  [Int64, "int"],
-  [Int32, "int"],
-  [Int16, "int"],
-];
-
 /**
  * Derive a `paramTypes` record from a SchemaLike spec.
  * Maps common Arrow scalar types to Python-style type strings.
  * Returns `undefined` if any field has a complex type (List, Map_, Dictionary, etc.).
  */
 export function inferParamTypes(spec: SchemaLike): Record<string, string> | undefined {
-  const schema = toSchema(spec);
-  if (schema.fields.length === 0) return undefined;
+  const sch = toSchema(spec);
+  if (sch.fields.length === 0) return undefined;
 
   const result: Record<string, string> = {};
-  for (const field of schema.fields) {
+  for (const f of sch.fields) {
     let mapped: string | undefined;
-    for (const [ctor, name] of TYPE_MAP) {
-      if (field.type instanceof ctor) {
-        mapped = name;
-        break;
-      }
-    }
+    if (isUtf8(f.type)) mapped = "str";
+    else if (isBinary(f.type)) mapped = "bytes";
+    else if (isBool(f.type)) mapped = "bool";
+    else if (isFloat(f.type)) mapped = "float";
+    else if (isInt(f.type)) mapped = "int";
     if (!mapped) return undefined;
-    result[field.name] = mapped;
+    result[f.name] = mapped;
   }
   return result;
 }