@query-farm/vgi 0.28.0 → 0.29.1

package/src/worker.ts

@@ -1,15 +1,42 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
 // VGI Worker: main entry point for running a VGI function server.
 
-import { VgiRpcServer, serveUnix, serveTcp, serveStream as serveStreamRpc } from "@query-farm/vgi-rpc";
+import {
+  VgiRpcServer,
+  observePeerIdentity,
+  peerIdentityPrimary,
+  serveUnix,
+  serveTcp,
+  serveStream as serveStreamRpc,
+} from "@query-farm/vgi-rpc";
 import { FunctionRegistry } from "./functions/registry.js";
 import type { VgiFunction } from "./functions/types.js";
 import { buildVgiProtocol } from "./protocol/dispatch.js";
 import type { Protocol } from "@query-farm/vgi-rpc";
-import type { CatalogDescriptor } from "./catalog/descriptors.js";
+import { schemaDescriptorPath, type CatalogDescriptor } from "./catalog/descriptors.js";
 import type { CatalogInterface } from "./catalog/interface.js";
 import { ReadOnlyCatalogInterface } from "./catalog/read-only.js";
 
+/**
+ * Startup/lifecycle tracing, off unless `VGI_DEBUG` is set to something other
+ * than "" or "0".
+ *
+ * These lines used to be unconditional, which put three of them in the log of
+ * every worker anyone ever deployed. They are genuinely useful when an ATTACH
+ * hangs and you need to know how far startup got, so they are kept rather than
+ * deleted — just behind a flag. Errors are NOT gated: `Worker error:` and
+ * `Worker init error:` always print.
+ *
+ * The message is a thunk so an unset flag costs no interpolation.
+ *
+ * stderr, never stdout: on the stdio transport stdout is the protocol.
+ */
+function debug(message: () => string): void {
+  const flag = process.env.VGI_DEBUG;
+  if (flag === undefined || flag === "" || flag === "0") return;
+  process.stderr.write(message() + "\n");
+}
+
 // argv parser for the launcher's `--unix PATH` / `--tcp [HOST:]PORT` /
 // `--idle-timeout SEC` contract. The C++ launcher (vgi extension) appends
 // these to the worker's argv whenever LOCATION uses the `launch:` scheme.
@@ -21,6 +48,10 @@ interface LauncherArgs {
   /** TCP bind port; present iff `--tcp` was passed. */
   tcpPort?: number;
   idleTimeout?: number;
+  irohRawUpstream?: boolean;
+  irohIssuer?: string;
+  irohTrustedProxyAddresses: string[];
+  irohAuthenticate: boolean;
 }
 
 // Parse a `[HOST:]PORT` --tcp bind spec into a LauncherArgs. A bare PORT (no
@@ -38,7 +69,7 @@ function parseTcpSpec(spec: string, out: LauncherArgs): void {
 }
 
 function parseLauncherArgs(argv: readonly string[]): LauncherArgs {
-  const out: LauncherArgs = {};
+  const out: LauncherArgs = { irohTrustedProxyAddresses: [], irohAuthenticate: true };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--unix" && i + 1 < argv.length) {
@@ -53,6 +84,22 @@ function parseLauncherArgs(argv: readonly string[]): LauncherArgs {
       out.idleTimeout = Number(argv[++i]);
     } else if (a.startsWith("--idle-timeout=")) {
       out.idleTimeout = Number(a.slice("--idle-timeout=".length));
+    } else if (a === "--iroh-raw-upstream" && i + 1 < argv.length) {
+      parseTcpSpec(argv[++i], out);
+      out.irohRawUpstream = true;
+    } else if (a.startsWith("--iroh-raw-upstream=")) {
+      parseTcpSpec(a.slice("--iroh-raw-upstream=".length), out);
+      out.irohRawUpstream = true;
+    } else if (a === "--iroh-issuer" && i + 1 < argv.length) {
+      out.irohIssuer = argv[++i];
+    } else if (a.startsWith("--iroh-issuer=")) {
+      out.irohIssuer = a.slice("--iroh-issuer=".length);
+    } else if (a === "--iroh-trusted-proxy" && i + 1 < argv.length) {
+      out.irohTrustedProxyAddresses.push(...argv[++i].split(",").filter(Boolean));
+    } else if (a.startsWith("--iroh-trusted-proxy=")) {
+      out.irohTrustedProxyAddresses.push(...a.slice("--iroh-trusted-proxy=".length).split(",").filter(Boolean));
+    } else if (a === "--iroh-observe") {
+      out.irohAuthenticate = false;
     }
   }
   return out;
@@ -102,7 +149,7 @@ export class Worker {
             this._registry.register(func);
             // Also index by owning schema + catalog so a schema-qualified bind
             // resolves when one name is declared in more than one schema.
-            this._registry.registerInSchema(func, schema.name, config.catalog.name);
+            this._registry.registerInSchema(func, schemaDescriptorPath(schema), config.catalog.name);
           }
         }
       }
@@ -123,12 +170,18 @@ export class Worker {
   }
 
   run(argv: readonly string[] = process.argv.slice(2)): void {
-    process.stderr.write(`[worker] starting, pid=${process.pid}\n`);
+    debug(() => `[worker] starting, pid=${process.pid}`);
     try {
       const protocol = this.buildProtocol();
-      process.stderr.write(`[worker] protocol built\n`);
+      debug(() => `[worker] protocol built`);
 
       const launcher = parseLauncherArgs(argv);
+      if (launcher.irohRawUpstream) {
+        if (!launcher.irohIssuer) throw new TypeError("--iroh-raw-upstream requires --iroh-issuer");
+        if (!["127.0.0.1", "::1", "localhost"].includes(launcher.tcpHost ?? "")) {
+          throw new TypeError("--iroh-raw-upstream must bind loopback");
+        }
+      }
       if (launcher.unixPath !== undefined) {
         // VGI_WORKER_IDLE_TIMEOUT overrides whatever the C++ launcher
         // appended via --idle-timeout. Useful in test setups where the
@@ -139,14 +192,14 @@ export class Worker {
         const idleTimeout = envOverride !== undefined && envOverride !== ""
           ? Number(envOverride)
           : launcher.idleTimeout;
-        process.stderr.write(
-          `[worker] AF_UNIX mode: ${launcher.unixPath} idle=${idleTimeout ?? 300}s${envOverride !== undefined && envOverride !== "" ? " (env override)" : ""}\n`,
+        debug(() =>
+          `[worker] AF_UNIX mode: ${launcher.unixPath} idle=${idleTimeout ?? 300}s${envOverride !== undefined && envOverride !== "" ? " (env override)" : ""}`,
         );
         serveUnix(protocol, {
           unixPath: launcher.unixPath,
           idleTimeout,
         }).then((handle) => handle.done).then(() => {
-          process.stderr.write(`[worker] serveUnix done (idle shutdown)\n`);
+          debug(() => `[worker] serveUnix done (idle shutdown)`);
         }).catch((err: any) => {
           process.stderr.write(`Worker error: ${err.message}\n${err.stack}\n`);
           process.exit(1);
@@ -164,15 +217,27 @@ export class Worker {
         const idleTimeout = envOverride !== undefined && envOverride !== ""
           ? Number(envOverride)
           : launcher.idleTimeout;
-        process.stderr.write(
-          `[worker] TCP mode: ${launcher.tcpHost}:${launcher.tcpPort} idle=${idleTimeout ?? 300}s${envOverride !== undefined && envOverride !== "" ? " (env override)" : ""}\n`,
+        debug(() =>
+          `[worker] TCP mode: ${launcher.tcpHost}:${launcher.tcpPort} idle=${idleTimeout ?? 300}s${envOverride !== undefined && envOverride !== "" ? " (env override)" : ""}`,
         );
         serveTcp(protocol, {
           host: launcher.tcpHost,
           port: launcher.tcpPort,
           idleTimeout,
+          ...(launcher.irohRawUpstream
+            ? {
+                proxyProtocolV2Required: true,
+                trustedProxyAddresses: launcher.irohTrustedProxyAddresses.length > 0
+                  ? launcher.irohTrustedProxyAddresses
+                  : ["127.0.0.1"],
+                irohProxyIssuer: launcher.irohIssuer,
+                peerAuthenticationPolicy: launcher.irohAuthenticate
+                  ? peerIdentityPrimary("iroh")
+                  : observePeerIdentity,
+              }
+            : {}),
         }).then((handle) => handle.done).then(() => {
-          process.stderr.write(`[worker] serveTcp done (idle shutdown)\n`);
+          debug(() => `[worker] serveTcp done (idle shutdown)`);
         }).catch((err: any) => {
           process.stderr.write(`Worker error: ${err.message}\n${err.stack}\n`);
           process.exit(1);
@@ -181,9 +246,9 @@ export class Worker {
       }
 
       const server = new VgiRpcServer(protocol);
-      process.stderr.write(`[worker] server created, calling run()\n`);
+      debug(() => `[worker] server created, calling run()`);
       server.run().then(() => {
-        process.stderr.write(`[worker] server.run() resolved cleanly\n`);
+        debug(() => `[worker] server.run() resolved cleanly`);
       }).catch((err) => {
         process.stderr.write(`Worker error: ${err.message}\n${err.stack}\n`);
         process.exit(1);