@norskvideo/ctl-test-harness 0.1.56 → 0.1.58

package/daemon-stores.d.ts

@@ -0,0 +1,5 @@
+/** Called by startDaemon. Last writer wins: a port reused by a later daemon in
+ *  the same process belongs to that daemon. */
+export declare function rememberDaemonStore(port: number, storeDir: string): void;
+export declare function forgetDaemonStore(port: number): void;
+export declare function storeDirForDaemonPort(port: number): string | undefined;

package/daemon-stores.js

@@ -0,0 +1,31 @@
+// Which store dir the daemon on a given port was started with.
+//
+// The daemon's ingress secret lives in its store (`<storeDir>/proxy-secret`),
+// and RFC 0003 D10b guards /api/* for loopback callers too — so anything
+// driving a test daemon's API needs that file. Every caller already has the
+// PORT; almost none of them has the store dir, because a test holds a harness
+// that started the daemon for it. That gap is why `startCameraSource` shipped
+// with a `proxySecret` option that nearly nobody passed, and why five product
+// repos' smoke tiers were 307'd for days.
+//
+// `startDaemon` knows both, so it records the pairing here and the pump looks
+// it up. Deliberately a process-global: the two are one-to-one within a test
+// process (one daemon per port), and the alternative — threading a store dir
+// through every helper signature and every call site — is the arrangement that
+// already failed.
+//
+// A daemon this process did not start (the demo driver's `reuse` policy, a
+// developer's own `norsk-ctl serve`) is absent, and callers that know their
+// store read it themselves.
+const storeByPort = new Map();
+/** Called by startDaemon. Last writer wins: a port reused by a later daemon in
+ *  the same process belongs to that daemon. */
+export function rememberDaemonStore(port, storeDir) {
+    storeByPort.set(port, storeDir);
+}
+export function forgetDaemonStore(port) {
+    storeByPort.delete(port);
+}
+export function storeDirForDaemonPort(port) {
+    return storeByPort.get(port);
+}

package/daemon.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { join } from "node:path";
 import { cliCommand } from "./cli-command.js";
+import { rememberDaemonStore } from "./daemon-stores.js";
 import { pollUntil } from "./poll.js";
 import { makeStoreDir, makeTempDir, TEST_TMP_BASE } from "./temp-dir.js";
 export const HEALTH_TIMEOUT_MS = 120_000;
@@ -146,6 +147,9 @@ export function seedDaemonConfig(storeDir) {
 }
 export function startDaemon(storeDir, options) {
     const port = options?.port ?? 8333;
+    // Before the spawn, so anything reaching for this daemon's ingress secret can
+    // find its store by the port it will answer on (daemon-stores.ts).
+    rememberDaemonStore(port, storeDir);
     killProcessOnPort(port);
     if (options?.seedConfig !== false)
         seedDaemonConfig(storeDir);

package/demo/run.d.ts

@@ -272,7 +272,11 @@ export declare class DemoSession {
     constructor(spec: DemoSpec, slug: string, cwd: string, deps: DemoDeps, opts: SessionOptions);
     get devUrl(): string;
     templateDir(name: string): string;
-    /** What the real daemon's proxy demands on `/api/*`; absent on a private daemon. */
+    /** What this daemon's guard demands on `/api/*`. Read from the store, for
+     *  EVERY policy: a private daemon arms the same guard and writes the same
+     *  file, so the `reuse`-only read this replaced sent nothing on the policy
+     *  that CI runs and had the pump 307'd (RFC 0003 D10b). Absent only until the
+     *  daemon has issued one, or on a `test-unguarded` daemon. */
     proxySecret(): string | undefined;
     cli: (argv: string[], opts?: {
         output?: "json" | "yaml";

package/demo/run.js

@@ -409,10 +409,12 @@ export class DemoSession {
     templateDir(name) {
         return join(this.storeDir, TEMPLATES_DIR, name);
     }
-    /** What the real daemon's proxy demands on `/api/*`; absent on a private daemon. */
+    /** What this daemon's guard demands on `/api/*`. Read from the store, for
+     *  EVERY policy: a private daemon arms the same guard and writes the same
+     *  file, so the `reuse`-only read this replaced sent nothing on the policy
+     *  that CI runs and had the pump 307'd (RFC 0003 D10b). Absent only until the
+     *  daemon has issued one, or on a `test-unguarded` daemon. */
     proxySecret() {
-        if (this.policy !== "reuse")
-            return undefined;
         return this.deps.readFile(join(this.storeDir, PROXY_SECRET_FILE))?.trim() || undefined;
     }
     cli = async (argv, opts = {}) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "type": "module",
   "exports": {
     ".": {
@@ -15,6 +15,10 @@
       "types": "./daemon.d.ts",
       "default": "./daemon.js"
     },
+    "./daemon-stores": {
+      "types": "./daemon-stores.d.ts",
+      "default": "./daemon-stores.js"
+    },
     "./image-surface": {
       "types": "./image-surface.d.ts",
       "default": "./image-surface.js"

package/smoke.d.ts

@@ -124,6 +124,9 @@ export interface SmokeDeps {
         instanceId: string;
         targets: readonly SrtPumpTarget[];
         timeoutMs?: number;
+        /** The daemon's ingress secret. Not optional in practice — see the
+         *  `proxySecret` read in runProductSmoke. */
+        proxySecret?: string;
     }): Promise<SourceHandle[]>;
     stopSources(handles: SourceHandle[]): Promise<void>;
     readers: SmokeReaders;
@@ -150,6 +153,10 @@ export interface SmokeDeps {
      *  is still up. Optional so an existing custom-deps consumer keeps working;
      *  the default reads every container carrying the instance's label. */
     diagnose?(instanceId: string): string;
+    /** The ingress secret the daemon rooted at `storeDir` demands on `/api/*`.
+     *  Optional so an existing custom-deps consumer keeps working; absent = read
+     *  the store's `proxy-secret` file. */
+    proxySecret?(storeDir: string): string | undefined;
     /** GET a manifest-declared route through the daemon's product proxy — the
      *  same URL ctl's product page links to. */
     fetchProductRoute(opts: {

package/smoke.js

@@ -17,7 +17,7 @@
 // studio-state, container-net). Argv, not Command: @norskvideo/ctl-commands is
 // not a dependency of this package (daemon.ts's cleanupDaemon has the same
 // rule); a product wanting typed commands bridges with toArgv in its own spec.
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { dumpInstanceContainerLogs, preserveEngineLogs } from "./container-logs.js";
 import { ensureRunnerOnNetwork, netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom, } from "./container-net.js";
@@ -26,7 +26,7 @@ import { hashSlot } from "./harness-config.js";
 import { ctlSupportsNoPublish, ctlSupportsPublishDebugPorts, runnerContainerUser } from "./launch.js";
 import { pollUntil } from "./poll.js";
 import { nukePathAsRoot, reportForeignOwners } from "./root-nuke.js";
-import { startSrtSources } from "./source-pump.js";
+import { readProxySecret, startSrtSources } from "./source-pump.js";
 import { applyTestHost, fetchComponentState, fetchComponents, fetchStreamMappings, isSrtListenerState, } from "./studio-state.js";
 import { makeStoreDir, TEST_TMP_BASE } from "./temp-dir.js";
 // Below 32768: the band is a reservation, and Linux hands 32768-60999 out to
@@ -70,6 +70,7 @@ export const defaultSmokeDeps = {
     cleanup: (opts) => cleanupDaemon({ ...opts, stopProxy: async () => { }, proxy: false }),
     nukeStoreAsRoot: (storeDir) => nukePathAsRoot(storeDir, TEST_TMP_BASE),
     storeExists: (storeDir) => existsSync(storeDir),
+    proxySecret: (storeDir) => readProxySecret(storeDir),
     ensureNetwork: () => ensureRunnerOnNetwork(),
     supportsNoPublish: ctlSupportsNoPublish,
     supportsPublishDebugPorts: ctlSupportsPublishDebugPorts,
@@ -78,8 +79,7 @@ export const defaultSmokeDeps = {
     fetchProductRoute: async ({ daemonPort, product, route, storeDir }) => {
         // The daemon fronts the product proxy with the same auth guard as /api/*,
         // so the secret travels when the store has one (source-pump's rule).
-        const secretFile = join(storeDir, "proxy-secret");
-        const secret = existsSync(secretFile) ? readFileSync(secretFile, "utf8").trim() : "";
+        const secret = readProxySecret(storeDir);
         const url = `http://localhost:${daemonPort}/products/${encodeURIComponent(product)}${route.startsWith("/") ? route : `/${route}`}`;
         const res = await fetch(url, {
             headers: secret ? { "x-norsk-proxy": secret } : {},
@@ -360,11 +360,22 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         }
         deps.log(`${slug}: not-yet phase passed for ${phased.length} observation(s)`);
         if (!vacuous) {
+            // The secret is read HERE, not at journey start: the daemon issues it in
+            // guard.configure() as the proxy comes up, so a read taken before `ready`
+            // finds no file and sends nothing. Sending nothing is not a soft failure
+            // — RFC 0003 D10b guards /api/* for loopback callers too, so the pump is
+            // 307'd. Said once, because a store with no secret is worth seeing in the
+            // log before the 307 it causes.
+            const secret = (deps.proxySecret ?? readProxySecret)(storeDir);
+            if (secret === undefined) {
+                deps.log(`${slug}: no proxy-secret in the store — the source pump will go unsecreted, and the guard 307s it`);
+            }
             handles = await deps.startSources({
                 daemonPort: ports.daemonPort,
                 instanceId,
                 targets: spec.sources,
                 timeoutMs: timeouts.observeMs,
+                ...(secret !== undefined ? { proxySecret: secret } : {}),
             });
         }
         for (const o of spec.observe) {

package/source-pump.d.ts

@@ -1,3 +1,9 @@
+/** The secret a daemon rooted at `storeDir` demands on `/api/*`, or undefined
+ *  when the file is not there (a `test-unguarded` daemon, or a store that no
+ *  daemon has armed yet). Absent is NOT the same as "no guard": every
+ *  self-hosted daemon writes this file, so an unexpected undefined here is why
+ *  a call 307s. */
+export declare function readProxySecret(storeDir: string): string | undefined;
 export interface SourceHandle {
     name: string;
     stop(): Promise<void>;
@@ -36,15 +42,17 @@ export interface StartCameraSourceOptions {
      *  (kept even when the fallback is used, so the handle is stable). Required
      *  when the same asset must run multiple times within an instance. */
     name?: string;
-    /** Sent as `x-norsk-proxy`. **Effectively required.** The daemon writes it
-     *  to `<stateDir>/proxy-secret` (`<storeDir>/proxy-secret` under
-     *  NORSK_CTL_STORE_DIR); read it from there and pass it.
+    /** Sent as `x-norsk-proxy`. **Usually leave this out**: when the daemon on
+     *  `daemonPort` was started by this process's harness, the secret is resolved
+     *  from its store automatically. Pass it only for a daemon the harness did
+     *  not start — the demo driver's `reuse` policy, or a developer's own
+     *  `norsk-ctl serve`.
      *
-     *  BREAKING for callers that omitted it (RFC 0003 D10b, ctl >= this
-     *  release): the daemon used to admit any loopback caller without a secret
-     *  while TLS was off, and that bypass is gone — a loopback caller is a host
-     *  admin, and a host admin can read the secret file. A harness or guide that
-     *  relied on it now fails with `POST /api/sources failed (307)`. */
+     *  RFC 0003 D10b: the daemon used to admit any loopback caller without a
+     *  secret while TLS was off, and that bypass is gone — a loopback caller is a
+     *  host admin, and a host admin can read the secret file. When neither this
+     *  option nor the registry supplies one, the call meets the guard's 307,
+     *  which `guardRedirectError` names rather than following. */
     proxySecret?: string;
     timeoutMs?: number;
     /** Test seams. */

package/source-pump.js

@@ -13,10 +13,29 @@
 //
 // PASS `proxySecret`. RFC 0003 D10b removed the daemon's loopback bypass, so
 // a call without it now 307s where it used to be admitted. See the field's
-// docblock for where to read the secret from.
-import { existsSync } from "node:fs";
-import { basename, extname } from "node:path";
+// docblock for where to read the secret from. `readProxySecret` is that read;
+// the smoke and demo drivers both go through it, so neither can drift from the
+// file the daemon writes.
+import { existsSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { storeDirForDaemonPort } from "./daemon-stores.js";
 import { pollUntil } from "./poll.js";
+/** Where every daemon the harness starts writes its ingress secret: the store
+ *  root (the guard's stateDir is `<storeDir>` under NORSK_CTL_STORE_DIR). One
+ *  reader for the whole harness — the three callers that spelled the filename
+ *  themselves are what let the smoke driver quietly stop sending it. */
+const PROXY_SECRET_FILE = "proxy-secret";
+/** The secret a daemon rooted at `storeDir` demands on `/api/*`, or undefined
+ *  when the file is not there (a `test-unguarded` daemon, or a store that no
+ *  daemon has armed yet). Absent is NOT the same as "no guard": every
+ *  self-hosted daemon writes this file, so an unexpected undefined here is why
+ *  a call 307s. */
+export function readProxySecret(storeDir) {
+    const path = join(storeDir, PROXY_SECRET_FILE);
+    if (!existsSync(path))
+        return undefined;
+    return readFileSync(path, "utf8").trim() || undefined;
+}
 /** Mirrors the daemon's default source name (shared/src/source-name.ts) so a
  *  caller can predict the identity it will poll and stop by. The harness
  *  always SENDS the name it derived, so the two cannot drift. */
@@ -40,6 +59,30 @@ function assetFields(asset, fileExists) {
     }
     return { ...asset };
 }
+/** The secret of whichever daemon this process started on `port`, or undefined
+ *  for a daemon it did not start. */
+function secretForDaemonPort(port) {
+    const storeDir = storeDirForDaemonPort(port);
+    return storeDir === undefined ? undefined : readProxySecret(storeDir);
+}
+/** A 307/308 off `/api/*` is the daemon's guard, not a route that moved: the
+ *  API itself never redirects. */
+function isGuardRedirect(res) {
+    return res.status === 307 || res.status === 308;
+}
+function guardRedirectError(method, res, sentSecret) {
+    const where = res.headers.get("location");
+    return new Error(`${method} /api/sources was refused by the daemon's ingress guard (${res.status} -> ${where ?? "the ingress port"}). ` +
+        (sentSecret
+            ? "The x-norsk-proxy secret that was sent is not the one this daemon holds — it is re-issued on start, so a " +
+                "secret read before the daemon booted is stale (read it after `ready`)."
+            : "No x-norsk-proxy secret was sent, and RFC 0003 D10b removed the loopback bypass, so a local caller needs " +
+                "one too. This process started no daemon on that port, so there was no store to read one from: either start " +
+                "it through the harness's startDaemon, or read the secret yourself with `readProxySecret(storeDir)` and pass " +
+                "it as `proxySecret`.") +
+        " Following this redirect instead is what turns a missing secret into an unrelated-looking ConnectionRefused or " +
+        "a `Failed to parse JSON` on nginx's HTML.");
+}
 export async function startCameraSource(opts) {
     if (opts.preset !== undefined && opts.asset !== undefined) {
         throw new Error("startCameraSource: pass either `preset` or `asset`, not both");
@@ -47,7 +90,12 @@ export async function startCameraSource(opts) {
     const asset = opts.asset ?? { preset: opts.preset ?? "camera1" };
     const name = opts.name ?? defaultSourceName(asset);
     const fetchImpl = opts.fetch ?? ((url, init) => fetch(url, init));
-    const headers = opts.proxySecret ? { "x-norsk-proxy": opts.proxySecret } : {};
+    // Resolved here, not at the call site: every caller has the port and almost
+    // none has the store dir, which is exactly why the explicit option went
+    // unpassed. Read now rather than when the daemon was registered — the guard
+    // issues the secret as the proxy comes up, after startDaemon returns.
+    const secret = opts.proxySecret ?? secretForDaemonPort(opts.daemonPort);
+    const headers = secret ? { "x-norsk-proxy": secret } : {};
     const base = `http://localhost:${opts.daemonPort}`;
     const body = {
         instanceId: opts.instanceId,
@@ -61,16 +109,32 @@ export async function startCameraSource(opts) {
         method: "POST",
         headers: { ...headers, "Content-Type": "application/json" },
         body: JSON.stringify(body),
+        // MANUAL. The guard answers an unsecreted /api/* with a 307 to the ingress
+        // port, and a followed redirect hides which call was refused: on a runner
+        // that cannot reach that port it surfaced as `ConnectionRefused` naming
+        // THIS url (bun reports the original), and on one that can, as nginx's
+        // HTML failing `r.json()` 120s later. Neither says "guard" or "secret",
+        // which is how a missing proxySecret stayed unread for days.
+        redirect: "manual",
         signal: AbortSignal.timeout(10_000),
     });
+    if (isGuardRedirect(startRes))
+        throw guardRedirectError("POST", startRes, opts.proxySecret);
     if (!startRes.ok) {
         throw new Error(`POST /api/sources failed (${startRes.status}): ${await startRes.text()}`);
     }
     await pollUntil(async () => {
         const r = await fetchImpl(`${base}/api/sources?instanceId=${encodeURIComponent(opts.instanceId)}`, {
             headers,
+            redirect: "manual",
             signal: AbortSignal.timeout(5000),
         });
+        // Thrown, not `return false`: a guarded-out poll is a permanent
+        // condition, and pollUntil carries the last error into its timeout
+        // message. Returning false spends the whole window and then says only
+        // that the source never ran.
+        if (isGuardRedirect(r))
+            throw guardRedirectError("GET", r, opts.proxySecret);
         if (!r.ok)
             return false;
         // GET /api/sources returns a bare array of SampleSource — not { sources: [...] }.
@@ -88,6 +152,10 @@ export async function startCameraSource(opts) {
             await fetchImpl(`${base}/api/sources/${encodeURIComponent(opts.instanceId)}/${encodeURIComponent(name)}`, {
                 method: "DELETE",
                 headers,
+                // Swallowed either way (stopAll sweeps the instance), but not chased:
+                // following the guard's redirect to a port this process may not reach
+                // spends the full 10s timeout on every source at teardown.
+                redirect: "manual",
                 signal: AbortSignal.timeout(10_000),
             }).catch(() => { });
         },