@query-farm/vgi 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.26.0",
+  "version": "0.27.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)",

package/src/http/fetch.ts

@@ -29,10 +29,18 @@ export interface VgiFetchOptions {
   prefix?: string;
   /** Server ID for state-token attribution (default "vgi-cf"). */
   serverId?: string;
-  /** CORS allowed origins. When set, CORS headers are added to all responses,
-   *  and the preflight `OPTIONS` that browser clients (e.g. the hosted Cupola
-   *  UI) send before `__describe__` will succeed. Omit to disable CORS. */
-  corsOrigins?: string;
+  /** CORS allowed origins, added to all responses so the preflight `OPTIONS`
+   *  that browser clients send before `__describe__` succeeds.
+   *
+   *  **Defaults to `"*"`.** A VGI worker exists to be attached and explored, and
+   *  the hosted Cupola UI reaches it from another origin, so cross-origin is the
+   *  normal case rather than the exception — and a worker that omits this gets
+   *  no CORS headers at all, which fails only in a browser and only for someone
+   *  else's page, i.e. nowhere its author is looking. `serveVgiWorker` has
+   *  always defaulted this way; this matches it so both entries agree.
+   *
+   *  Pass `null` to disable CORS. */
+  corsOrigins?: string | null;
   /** Public source-repository URL, surfaced on the landing page. */
   repositoryUrl?: string;
   /** Worker identity for the standardized VGI landing surface: `GET /` serves
@@ -92,7 +100,8 @@ export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise
     tokenKey: opts.signingKey,
     tokenTtl,
     stateSerializer: arrowStateSerializer,
-    corsOrigins: opts.corsOrigins,
+    // `null` is the explicit opt-out; `undefined` (omitted) means "*".
+    corsOrigins: opts.corsOrigins === null ? undefined : (opts.corsOrigins ?? "*"),
     repositoryUrl: opts.repositoryUrl,
     // The landing surface is ours, contributed into vgi-rpc's routing rather
     // than built there. `enableLandingPage: false` drops vgi-rpc's generic

package/src/http/landing.ts

@@ -56,6 +56,62 @@ export interface LandingInfo {
 /** Default Cupola deployment the page's "Explore" links point at. */
 export const DEFAULT_CUPOLA_BASE = "https://cupola.query-farm.services";
 
+// Caching. Both assets are immutable for a given build but live at URLs that
+// never change, which is the combination that goes wrong quietly: the page used
+// to be served with no Cache-Control and no validator at all, so browsers
+// applied heuristic caching with nothing to revalidate against and could hold a
+// stale page indefinitely — every landing-page fix needed a shift-reload to
+// see. The bundle was worse in a different way: `max-age=3600` with no
+// validator meant a full hour where a client could not learn that a release had
+// happened, which is how a bundle that could not decode workerd's compressed
+// responses stayed live in a browser long after it was fixed.
+//
+// `no-cache` does not mean "do not store" — it means "store, but revalidate
+// before reuse". With a strong ETag a repeat visit is a conditional GET that
+// answers 304 with no body, so the bandwidth is the same as a long TTL and the
+// staleness window closes to zero. `public` is kept so shared caches (the
+// Cloudflare edge in front of a Workers deployment) can hold and revalidate it
+// too, rather than each viewer paying the full transfer.
+const REVALIDATE = "public, no-cache";
+
+/**
+ * FNV-1a over the asset bytes, as a strong ETag.
+ *
+ * Computed lazily and memoised rather than at module load: most requests to a
+ * worker are RPC and never touch these routes, and hashing ~700 KB on every
+ * isolate start would tax cold starts for a page nobody may open. Once per
+ * isolate on first use is the right trade.
+ */
+function etagFor(bytes: Uint8Array): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i]!;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  // Length is folded in so two builds that collide on the hash still differ.
+  return `"${hash.toString(16)}-${bytes.length.toString(16)}"`;
+}
+
+let landingEtag: string | null = null;
+let bundleEtag: string | null = null;
+
+/** 304 when the client already holds this exact body, else null. */
+function notModified(request: Request, etag: string, extra?: HeadersInit): Response | null {
+  const ifNoneMatch = request.headers.get("If-None-Match");
+  if (!ifNoneMatch) return null;
+  // A conditional GET may list several validators, and a cache is allowed to
+  // weaken ours to `W/"…"` on the way back.
+  const matches = ifNoneMatch
+    .split(",")
+    .map((c) => c.trim().replace(/^W\//, ""))
+    .includes(etag);
+  if (!matches) return null;
+  const headers = new Headers(extra);
+  headers.set("ETag", etag);
+  headers.set("Cache-Control", REVALIDATE);
+  return new Response(null, { status: 304, headers });
+}
+
 /**
  * Build the VGI landing surface as a route contributed to vgi-rpc's HTTP
  * handler.
@@ -98,7 +154,17 @@ export function createLandingRoutes(info: LandingInfo): ExtraRouteHandler {
         ctx.addCorsHeaders(headers);
         return new Response(body, { status: 200, headers });
       }
-      const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+      landingEtag ??= etagFor(LANDING_HTML_BYTES);
+      const conditional = notModified(request, landingEtag);
+      if (conditional) {
+        ctx.addCorsHeaders(conditional.headers);
+        return conditional;
+      }
+      const headers = new Headers({
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": REVALIDATE,
+        ETag: landingEtag,
+      });
       ctx.addCorsHeaders(headers);
       return new Response(LANDING_HTML_BYTES as unknown as BodyInit, { status: 200, headers });
     }
@@ -109,9 +175,16 @@ export function createLandingRoutes(info: LandingInfo): ExtraRouteHandler {
     // CDN dependency would break air-gapped deployments that today need nothing
     // but the worker.
     if (path === `${prefix}/vgi-client.js`) {
+      bundleEtag ??= etagFor(CLIENT_BUNDLE_BYTES);
+      const conditional = notModified(request, bundleEtag);
+      if (conditional) {
+        ctx.addCorsHeaders(conditional.headers);
+        return conditional;
+      }
       const headers = new Headers({
         "Content-Type": "text/javascript; charset=utf-8",
-        "Cache-Control": "public, max-age=3600",
+        "Cache-Control": REVALIDATE,
+        ETag: bundleEtag,
       });
       ctx.addCorsHeaders(headers);
       return new Response(CLIENT_BUNDLE_BYTES as unknown as BodyInit, { status: 200, headers });

package/src/protocol/serializers/bind.ts

@@ -150,6 +150,8 @@ export function deserializeBindRequest(
     functionType = FunctionType.SCALAR;
   } else if (ftStr === "table" || ftStr === "TABLE") {
     functionType = FunctionType.TABLE;
+  } else if (ftStr === "table_buffering" || ftStr === "TABLE_BUFFERING") {
+    functionType = FunctionType.TABLE_BUFFERING;
   } else if (ftStr === "aggregate" || ftStr === "AGGREGATE") {
     functionType = FunctionType.AGGREGATE;
   } else {

package/src/serve-entry.ts

@@ -179,9 +179,11 @@ export function createVgiWorkerFetch(
   const env = opts.env ?? (process.env as ServeEnv);
   const signingKey = resolveSigningKey(opts.signingKey, env);
   const tokenTtl = resolveTokenTtl(opts.tokenTtl, env);
-  // `null` disables CORS; `undefined` falls through to the env var, then "*".
-  const corsOrigins =
-    opts.corsOrigins === null ? undefined : (opts.corsOrigins ?? env.CORS_ORIGINS ?? "*");
+  // `null` disables CORS and must stay `null` through to createVgiFetch, which
+  // now reads a bare `undefined` as "default to *" — passing `undefined` here to
+  // mean "off" would silently re-enable it. `undefined` falls through to the env
+  // var and then to that same default.
+  const corsOrigins = opts.corsOrigins === null ? null : (opts.corsOrigins ?? env.CORS_ORIGINS);
 
   return createVgiFetch({
     protocol: { registry: opts.registry, catalogInterface: opts.catalogInterface },

package/src/types.ts

@@ -4,6 +4,10 @@
 export enum FunctionType {
   SCALAR = "scalar",
   TABLE = "table",
+  // Sink+source function bound through defineTableBufferingFunction. Mirrors
+  // vgi-python's FunctionType.TABLE_BUFFERING; without it a buffering bind fell
+  // through deserializeBindRequest's normalization to a bare `as` cast.
+  TABLE_BUFFERING = "table_buffering",
   AGGREGATE = "aggregate",
 }
 

package/src/worker-cf-entry.ts

@@ -36,6 +36,11 @@ export {
   // The blended config has no `argConstraints` of its own, so a worker that
   // wants ge/le/choices/pattern on a row-transform's args applies them itself.
   constraintSpecFields,
+  // Result-cache control (`vgi.cache.*`). Advertised as metadata on the FIRST
+  // emitted batch, so it composes with `parentRowsMetadata` via the `extra`
+  // argument. Belongs on this facade for the same reason the blended helpers do:
+  // a workerd worker cannot reach it through the package root.
+  cacheControlMetadata,
   FunctionRegistry,
   ReadOnlyCatalogInterface,
   CompositeCatalogInterface,
@@ -50,6 +55,8 @@ export {
 } from "./index.core.js";
 
 export type {
+  CacheControl,
+  CacheScope,
   AttachOptionSpec,
   ColumnStatistics,
   CatalogAttachResult,