@query-farm/vgi 0.15.0 → 0.18.0

package/dist/serve-entry.d.ts

@@ -0,0 +1,84 @@
+import type { CatalogInterface } from "./catalog/interface.js";
+import type { FunctionRegistry } from "./functions/registry.js";
+/** Environment variables `serveVgiWorker` reads. Injectable for testing. */
+export interface ServeEnv {
+    PORT?: string;
+    VGI_SIGNING_KEY?: string;
+    VGI_TOKEN_TTL?: string;
+    CORS_ORIGINS?: string;
+}
+export declare const DEFAULT_PORT = 8787;
+export declare const DEFAULT_TOKEN_TTL = 3600;
+/** Bytes of HMAC key `createHttpHandler` expects; 64 hex characters. */
+export declare const SIGNING_KEY_BYTES = 32;
+export interface ServeVgiWorkerOptions {
+    /** Short worker name shown on the landing page, e.g. "ishares". */
+    name: string;
+    /** One-line description of what the worker serves. */
+    doc: string;
+    /** Worker version string shown on the landing page. */
+    version: string;
+    /** Functions the worker serves, already registered. */
+    registry: FunctionRegistry;
+    /** Catalog DuckDB attaches to. */
+    catalogInterface: CatalogInterface;
+    /** Public source-repository URL, linked from the landing page. */
+    repositoryUrl?: string;
+    /** Overrides `$PORT` (default 8787). Pass 0 to bind an ephemeral port. */
+    port?: number;
+    /** Overrides `$VGI_SIGNING_KEY`. 32 bytes. */
+    signingKey?: Uint8Array;
+    /** Overrides `$VGI_TOKEN_TTL` (default 3600 seconds). */
+    tokenTtl?: number;
+    /** Overrides `$CORS_ORIGINS` (default "*"). Pass `null` to disable CORS. */
+    corsOrigins?: string | null;
+    /** Server ID for state-token attribution (default: `name`). */
+    serverId?: string;
+    /** Mount point for the VGI endpoints (default "", the origin root). */
+    prefix?: string;
+    /** Suppress the startup banner on stdout. */
+    quiet?: boolean;
+    /** Environment source (default `process.env`). */
+    env?: ServeEnv;
+}
+/** The slice of `Bun.serve`'s return value this module uses. */
+export interface VgiHttpServer {
+    readonly port: number;
+    readonly url: URL;
+    stop(closeActiveConnections?: boolean): void;
+}
+/**
+ * Decode a 32-byte signing key from its hex representation.
+ *
+ * Throws on anything that is not exactly 64 hex characters. A silent truncate
+ * or zero-pad here would produce a worker that starts happily with a key far
+ * weaker than the operator believed they supplied.
+ */
+export declare function parseSigningKeyHex(hex: string): Uint8Array;
+/**
+ * Resolve the state-token signing key: explicit option, then `$VGI_SIGNING_KEY`,
+ * then a fresh random key.
+ *
+ * The random fallback is safe but ephemeral, and that tradeoff is why it warns:
+ * state tokens minted under it stop validating after a restart, and never
+ * validate across a second instance behind a load balancer. It exists so
+ * `bun run scripts/serve.ts` works with no setup, not so deployments can skip
+ * the key.
+ */
+export declare function resolveSigningKey(explicit: Uint8Array | undefined, env: ServeEnv, warn?: (msg: string) => void): Uint8Array;
+/**
+ * Build the fetch handler a VGI worker serves over HTTP, with the standardized
+ * landing surface mounted at `prefix`.
+ *
+ * Exposed separately from {@link serveVgiWorker} so a worker can put the VGI
+ * routes inside its own Bun/Hono/Elysia server, or drive them from a test
+ * without binding a port.
+ */
+export declare function createVgiWorkerFetch(opts: ServeVgiWorkerOptions): (req: Request) => Promise<Response>;
+/**
+ * Serve a VGI worker over HTTP on Bun and return the running server.
+ *
+ * Reads `PORT`, `VGI_SIGNING_KEY`, `VGI_TOKEN_TTL`, and `CORS_ORIGINS` from the
+ * environment; every one has an explicit option that takes precedence.
+ */
+export declare function serveVgiWorker(opts: ServeVgiWorkerOptions): VgiHttpServer;