@query-farm/vgi 0.37.1 → 0.38.0

package/dist/protocol/handlers/catalog/contents.d.ts

@@ -0,0 +1,27 @@
+import { type CatalogContentsResponse } from "../../../generated/vgi-protocol-types.js";
+import type { AttachOpaqueData, CatalogInterface } from "../../../catalog/interface.js";
+type Wire = {
+    result: Uint8Array;
+};
+/**
+ * Ask the catalog for its contents and shape the typed wire response.
+ *
+ * Enforces the revalidation rules: `not_modified` needs an etag equal to
+ * `ifNoneMatch` and no schemas; a catalog with no etag never yields
+ * `not_modified` (and so ignores `ifNoneMatch`). Validates the schema paths
+ * (unique, parent present) and orders them parent-first. Every item is
+ * encoded with the SAME encoder its per-schema RPC uses, so items are
+ * byte-identical to catalog_schemas / catalog_schema_contents_* items.
+ */
+export declare function buildCatalogContents(cat: CatalogInterface, owner: CatalogInterface, attach: AttachOpaqueData, version: number, ifNoneMatch: string | null): Promise<CatalogContentsResponse>;
+/**
+ * Serve one catalog_contents call (the attach value is already opened).
+ *
+ * Caching: a catalog whose `catalogContentsCacheable()` is true (by default:
+ * version frozen and contents attach-independent; ReadOnlyCatalogInterface) is
+ * built once per (catalog instance, version); every later call reuses the same
+ * serialized response bytes. A conditional call matching the cached etag is
+ * answered `not_modified` without touching the snapshot.
+ */
+export declare function serveCatalogContents(cat: CatalogInterface, attach: AttachOpaqueData, ifNoneMatch: string | null): Promise<Wire>;
+export {};

package/dist/rpc-server.d.ts

@@ -0,0 +1,97 @@
+import { type GrantMinter, type Protocol, type TokenResolver, VgiRpcServer } from "@query-farm/vgi-rpc";
+/** The transport a server is being built for. Only `"http"` changes what is
+ *  hosted (identity); the rest are recorded so the decision lives here rather
+ *  than at each call site. `"iroh"` is the raw TCP upstream of a
+ *  `vgi-iroh-bridge`; `"stream"` a caller-provided byte-stream pair. */
+export type ServerTransport = "pipe" | "unix" | "tcp" | "iroh" | "stream" | "http";
+/** Environment variable naming the principals allowed to call `introspect_token`. */
+export declare const INTROSPECT_PRINCIPALS_ENV = "VGI_INTROSPECT_PRINCIPALS";
+/**
+ * What a worker hosts beyond `vgi.v2`, and whether it opts into identity.
+ *
+ * Accepted by `new Worker({...})`, `serveVgiWorker`, `createVgiWorkerFetch`
+ * and `createVgiFetch` (Cloudflare Workers) alike, so one worker definition
+ * hosts the same set on every transport.
+ */
+export interface HostingOptions {
+    /**
+     * Additional vgi-rpc protocols to host beside `vgi.v2`, on the **same**
+     * listener, whatever the transport.
+     *
+     * A vgi-rpc `Protocol` carries its handlers, so each entry is a whole
+     * `(protocol, implementation)` pair. Called **once**, when the server is
+     * built; it may consult configuration or the environment, but the answer is
+     * fixed for the life of the process, so reflection output and protocol
+     * hashes stay stable. Hosted after `vgi.v2`, in the order returned.
+     *
+     * The protocol is the unit of optionality: there is no way to host a subset
+     * of a protocol's methods. A capability that is optional is its own
+     * protocol, returned here or not.
+     *
+     * Each needs a distinct wire name, which may not be `vgi.v2` and may not
+     * use the reserved `vgi_rpc.` prefix: reflection is hosted automatically and
+     * `vgi_rpc.Identity.v1` is enabled through {@link resolveToken} /
+     * {@link mintGrant}. Violations are a startup error naming this hook.
+     */
+    hostedProtocols?: () => Iterable<Protocol>;
+    /**
+     * Resolve an opaque bearer credential to the identity it authenticates as.
+     * Supplying it hosts `vgi_rpc.Identity.v1`'s `introspect_token` -- on HTTP,
+     * the transport that authenticates callers. Absent, the method is absent
+     * (not hosted-and-refusing), which keeps a dependency upgrade from growing a
+     * credential-to-identity oracle on every existing worker.
+     *
+     * Return `null` for "the store answered and this credential is unknown".
+     * For "I could not find out" (a store or sidecar outage, a timeout, a 5xx)
+     * throw `AuthUnavailableError` from `@query-farm/vgi-rpc` -- the same error
+     * an `authenticate` callback throws for an outage. The framework translates
+     * it to `identity_unavailable` with that error's retry hint
+     * (`vgi_rpc.RetryInfo`), so callers know to retry rather than cache a
+     * refusal. `IdentityUnavailableError` works too. Never throw a plain
+     * `Error` for an outage: a caller cannot tell it from a definitive answer.
+     *
+     * Requires {@link introspectPrincipals} (or `VGI_INTROSPECT_PRINCIPALS`);
+     * there is no permissive default, and a worker without one refuses to start.
+     */
+    resolveToken?: TokenResolver;
+    /**
+     * Mint a standing delegation credential for the *calling* user. Supplying
+     * it hosts `issue_grant` (HTTP only). Throw `GrantRefusedError` to decline,
+     * and `AuthUnavailableError` for a transient failure (translated as for
+     * {@link resolveToken}). Needs no allowlist: it is not an oracle about
+     * anybody else.
+     */
+    mintGrant?: GrantMinter;
+    /**
+     * Principals permitted to call `introspect_token`. When omitted,
+     * `VGI_INTROSPECT_PRINCIPALS` (comma-separated) is read. Only consulted when
+     * {@link resolveToken} is supplied.
+     */
+    introspectPrincipals?: Iterable<string>;
+    /** Maximum age of the caller's authentication for `issue_grant`, in
+     *  seconds. vgi-rpc's default when omitted. */
+    maxAuthAge?: number;
+}
+/** Server-level options passed through to `VgiRpcServer`. */
+export interface BuildRpcServerOptions {
+    /** Which transport this server will serve. */
+    transport: ServerTransport;
+    /** Server identifier, surfaced through reflection. */
+    serverId?: string;
+    /** Environment to read `VGI_INTROSPECT_PRINCIPALS` from. Default
+     *  `process.env` where it exists (not on Cloudflare Workers). */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Build the vgi-rpc server for a worker's `vgi.v2` protocol on `transport`.
+ *
+ * Calls `hosting.hostedProtocols()` exactly once and hosts the result beside
+ * `primary`; see the module comment for the full hosted set.
+ *
+ * @throws TypeError `hostedProtocols()` returned something other than an
+ *   iterable of vgi-rpc `Protocol`s.
+ * @throws Error A hosted protocol's name is invalid, reserved, `vgi.v2`'s, or
+ *   repeated; the transport is unknown; or the worker supplies `resolveToken`
+ *   on HTTP with no introspector allowlist.
+ */
+export declare function buildRpcServer(primary: Protocol, hosting: HostingOptions, options: BuildRpcServerOptions): VgiRpcServer;

package/dist/serve-entry.d.ts

@@ -1,6 +1,7 @@
 import type { CatalogInterface } from "./catalog/interface.js";
 import type { FunctionRegistry } from "./functions/registry.js";
 import { type AuthenticateFn, type PeerResolutionOptions } from "@query-farm/vgi-rpc";
+import type { HostingOptions } from "./rpc-server.js";
 /** Environment variables `serveVgiWorker` reads. Injectable for testing. */
 export interface ServeEnv {
     PORT?: string;
@@ -26,7 +27,7 @@ export interface IrohHttpBridgeOptions {
      */
     peerResolutionContext?: (request: Request) => PeerResolutionOptions | Promise<PeerResolutionOptions>;
 }
-export interface ServeVgiWorkerOptions {
+export interface ServeVgiWorkerOptions extends HostingOptions {
     /** Short worker name shown on the landing page, e.g. "ishares". */
     name: string;
     /** One-line description of what the worker serves. */