@query-farm/vgi 0.25.4 → 0.26.1

package/src/http/fetch.ts

@@ -13,7 +13,7 @@
 import { createHttpHandler, unpackStateToken, type Protocol } from "@query-farm/vgi-rpc";
 import { arrowStateSerializer } from "../protocol/state-serializer.js";
 import { buildVgiProtocol, type ProtocolConfig } from "../protocol/dispatch.js";
-import type { LandingInfo } from "@query-farm/vgi-rpc";
+import { createLandingRoutes, type LandingInfo } from "./landing.js";
 
 export interface VgiFetchOptions {
   /** Wire-protocol config (registry + catalogInterface). */
@@ -35,11 +35,20 @@ export interface VgiFetchOptions {
   corsOrigins?: string;
   /** Public source-repository URL, surfaced on the landing page. */
   repositoryUrl?: string;
-  /** Enables the standardized VGI landing surface: `GET /` serves the shared
-   *  landing.html plus a JSON status document carrying this identity, and
-   *  `GET /vgi-client.js` serves the browser client build the page reads the
-   *  catalog with. */
-  landingInfo?: LandingInfo;
+  /** Worker identity for the standardized VGI landing surface: `GET /` serves
+   *  the shared landing.html plus a JSON status document carrying this
+   *  identity, and `GET /vgi-client.js` serves the browser client build the
+   *  page reads the catalog with.
+   *
+   *  Required, and deliberately so. It used to be optional, and omitting it
+   *  silently downgraded `GET /` to vgi-rpc's generic "this is an RPC
+   *  endpoint" placeholder while `GET /vgi-client.js` 404'd — a worker that
+   *  looked deployed but had no catalog tree, no Cupola link, and no ATTACH
+   *  snippet. Nothing failed loudly, so the only way to notice was to open the
+   *  page. `serveVgiWorker` never had the problem because it builds this from
+   *  its required name/doc/version; the CF entry had to remember, and
+   *  vgi-open-meteo shipped for weeks without it. */
+  landingInfo: LandingInfo;
 }
 
 /**
@@ -49,6 +58,17 @@ export interface VgiFetchOptions {
  * round-trips through the signed state token created here.
  */
 export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise<Response> {
+  // The type makes this required, but a plain-JS caller (or one that predates
+  // the change) reaches here with it undefined, and the failure mode this
+  // guards is silent: a worker that serves a placeholder page forever. Fail
+  // at construction, where the stack points at the caller.
+  if (!opts.landingInfo) {
+    throw new Error(
+      "createVgiFetch requires `landingInfo` ({ name, doc, version }). Without it " +
+        "GET / serves vgi-rpc's generic placeholder instead of the VGI landing page " +
+        "and GET /vgi-client.js 404s.",
+    );
+  }
   const tokenTtl = opts.tokenTtl ?? 3600;
   // `?? "/vgi"` and not `|| "/vgi"`: an explicit "" means "mount at root".
   const prefix = opts.prefix ?? "/vgi";
@@ -74,7 +94,12 @@ export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise
     stateSerializer: arrowStateSerializer,
     corsOrigins: opts.corsOrigins,
     repositoryUrl: opts.repositoryUrl,
-    landingInfo: opts.landingInfo,
+    // The landing surface is ours, contributed into vgi-rpc's routing rather
+    // than built there. `enableLandingPage: false` drops vgi-rpc's generic
+    // "this is an RPC endpoint" page, which would otherwise sit behind ours for
+    // no reason — a VGI worker always has the real thing.
+    extraRoutes: createLandingRoutes(opts.landingInfo),
+    enableLandingPage: false,
   });
   return async (req: Request) => handler(req);
 }