@query-farm/vgi 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",
@@ -34,7 +34,8 @@
     "./src/index.ts",
     "./src/client-entry.ts",
     "./src/worker-cf-entry.ts",
-    "./src/serve-entry.ts"
+    "./src/serve-entry.ts",
+    "./src/arrow/impl-flechette/compat.ts"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -90,12 +91,12 @@
   },
   "peerDependencies": {
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": ">=0.23.0 <0.24.0"
+    "@query-farm/vgi-rpc": ">=0.24.0 <0.25.0"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.5-r.4",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.23.0",
+    "@query-farm/vgi-rpc": "^0.24.0",
     "@types/bun": "latest",
     "typescript": "^7.0.2"
   },

package/src/client/errors.ts

@@ -63,6 +63,25 @@ export function wrapRpcWithErrorEnrichment(rpc: RpcClient): RpcClient {
         throw e;
       }
     },
+    // The batch-level twins (vgi-rpc 0.24.0) get the same treatment: a caller
+    // holding encoded Arrow should still see the worker's traceback rather
+    // than a bare RpcError.
+    async callRaw(method, input) {
+      try {
+        return await rpc.callRaw(method, input);
+      } catch (e) {
+        if (e instanceof RpcError) throw VgiClientError.fromRpcError(e);
+        throw e;
+      }
+    },
+    async streamRaw(method, input, options) {
+      try {
+        return await rpc.streamRaw(method, input, options);
+      } catch (e) {
+        if (e instanceof RpcError) throw VgiClientError.fromRpcError(e);
+        throw e;
+      }
+    },
     describe: () => rpc.describe(),
     close: () => rpc.close(),
   };

package/src/http/fetch.ts

@@ -24,7 +24,7 @@ import {
   type Protocol,
 } from "@query-farm/vgi-rpc";
 import { arrowStateSerializer } from "../protocol/state-serializer.js";
-import { buildVgiProtocol, type ProtocolConfig } from "../protocol/dispatch.js";
+import { buildVgiProtocol, VGI_PROTOCOL_NAME, type ProtocolConfig } from "../protocol/dispatch.js";
 import { createLandingRoutes, type LandingInfo } from "./landing.js";
 import { setRequestAuthScope, type RequestAuthHolder } from "../request-auth.js";
 
@@ -199,8 +199,15 @@ export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise
     recoverExchangeState: async (opaqueData: Uint8Array) => {
       const tokenString = new TextDecoder().decode(opaqueData);
       // principal binding is enforced by the HTTP handler on the request that
-      // carried this token; the recovery path itself is not principal-scoped.
-      const unpacked = await unpackStateToken(tokenString, opts.signingKey, tokenTtl, undefined);
+      // carried this token; the recovery path itself is not principal-scoped,
+      // so the scope names the protocol and leaves the identity anonymous.
+      // `protocol` is required since vgi-rpc 0.24.0: it is bound into the
+      // token's AEAD associated data, so a cursor minted under one hosted
+      // protocol cannot be opened under another.
+      const unpacked = await unpackStateToken(tokenString, opts.signingKey, tokenTtl, {
+        protocol: VGI_PROTOCOL_NAME,
+        principal: undefined,
+      });
       return arrowStateSerializer.deserialize(unpacked.stateBytes);
     },
   });

package/src/protocol/dispatch.ts

@@ -36,8 +36,35 @@ export interface ProtocolConfig {
   signingKey?: Uint8Array;
 }
 
+/**
+ * Wire name of the VGI protocol: the `vgi_rpc.protocol` routing key and the
+ * `{protocol}` HTTP path segment.
+ *
+ * The name carries the major version, so an incompatible major is a
+ * *different* protocol and therefore a 404 — an answer every proxy, WAF and
+ * load balancer understands without an Arrow parser, and one that lets
+ * `vgi.v2` and a future `vgi.v3` be served side by side while clients migrate.
+ * That matters for this consumer specifically: the DuckDB extension ships to
+ * users and cannot be flag-dayed.
+ *
+ * Declared rather than derived. Until the transports made the routing key
+ * required, each implementation's wire name defaulted to whatever its local
+ * type was called, which left the six ports disagreeing four ways — Python
+ * `VgiProtocol`, Java and C# `VgiService`, Go the framework default `Service`,
+ * this port `vgi` — so no client could address them all. The canonical name is
+ * decided in vgi-python and emitted by the DuckDB extension; this is that same
+ * string, not an independent choice.
+ *
+ * Since `@query-farm/vgi-rpc` 0.24.0 the name is also bound into the AEAD
+ * associated data of every state and call token (`TokenScope.protocol`), so a
+ * caller that opens a token minted by this protocol has to name it. Exported
+ * so the HTTP entry points build that scope from the same constant the
+ * protocol is registered under rather than a second copy of the literal.
+ */
+export const VGI_PROTOCOL_NAME = "vgi.v2";
+
 export function buildVgiProtocol(config: ProtocolConfig): Protocol {
-  const protocol = new Protocol("vgi", { protocolVersion: "2.0.0" });
+  const protocol = new Protocol(VGI_PROTOCOL_NAME, { protocolVersion: "2.0.0" });
 
   registerFunctionMethods(protocol, {
     registry: config.registry,