@norskvideo/ctl-test-harness 0.1.40 → 0.1.42

package/demo/run.d.ts

@@ -217,6 +217,28 @@ export interface SessionOptions {
     /** Containers teardown must also wait out — an overridden proxy's pair. */
     extraContainers?: string[];
 }
+/** The host a demo's daemon-port URLs name.
+ *
+ *  NORSK_TEST_HOST is a STUDIO-port setting: on a docker-outside-of-docker
+ *  runner the test process sits in a container while the studio it launched
+ *  published its port on the HOST, reachable only via the host-gateway alias.
+ *  A PRIVATE daemon is the opposite case -- this process starts it, and its
+ *  proxy, so its ports are on this process's own loopback. studio-state.ts
+ *  states the invariant plainly ("daemon-port fetches are deliberately left on
+ *  localhost"); letting the env reach them here aimed playout's visualiser gate
+ *  at the host gateway, where nothing listens on the private proxy port, and
+ *  `demo -- check` missed `video_compose advancing` on every poll for 180s
+ *  while the compositor was advancing perfectly well (2026-09-03). It passed
+ *  only where a runner's network happened to route back, which is what made it
+ *  read as a flake rather than a wrong address.
+ *
+ *  `reuse` keeps the alias: that daemon is a process this one did not start and
+ *  may genuinely be the host sibling. An explicit --public-host always wins. */
+export declare function demoUrlHost(opts: {
+    publicHost: string | undefined;
+    daemon: DemoDaemonPolicy;
+    env?: NodeJS.ProcessEnv;
+}): string;
 /** The pieces of a run that `runDemo`, `runExportCheck` and the dev-loop
  *  share: the daemon (private on its band, or the developer's), the dev
  *  backend on the driver's port, the registration, and the template (built

package/demo/run.js

@@ -37,7 +37,13 @@ import { pollUntil } from "../poll.js";
 import { nukePathAsRoot, reportForeignOwners } from "../root-nuke.js";
 import { startSrtSources } from "../source-pump.js";
 import { makeStoreDir, TEST_TMP_BASE } from "../temp-dir.js";
-const DEMO_PORT_BASE = 35000;
+// Below 32768, for the reason smoke.ts's band carries in full: 35000 sat inside
+// the kernel's ephemeral range (32768-60999), so a banded port could be handed
+// to an outbound connection as its source port and the daemon would then fail
+// to bind with EADDRINUSE while nothing was listening on it. Disjoint from the
+// smoke band and from the products' own (15000-31800); guarded by
+// tests/port-bands.test.ts.
+const DEMO_PORT_BASE = 22000;
 const DEMO_BAND_WIDTH = 20;
 const DEMO_BANDS = 50;
 const DEFAULT_DAEMON_PORT = 8333;
@@ -311,6 +317,31 @@ export function defaultDemoDeps(cwd) {
         log: (line) => console.log(`[demo] ${line}`),
     };
 }
+/** The host a demo's daemon-port URLs name.
+ *
+ *  NORSK_TEST_HOST is a STUDIO-port setting: on a docker-outside-of-docker
+ *  runner the test process sits in a container while the studio it launched
+ *  published its port on the HOST, reachable only via the host-gateway alias.
+ *  A PRIVATE daemon is the opposite case -- this process starts it, and its
+ *  proxy, so its ports are on this process's own loopback. studio-state.ts
+ *  states the invariant plainly ("daemon-port fetches are deliberately left on
+ *  localhost"); letting the env reach them here aimed playout's visualiser gate
+ *  at the host gateway, where nothing listens on the private proxy port, and
+ *  `demo -- check` missed `video_compose advancing` on every poll for 180s
+ *  while the compositor was advancing perfectly well (2026-09-03). It passed
+ *  only where a runner's network happened to route back, which is what made it
+ *  read as a flake rather than a wrong address.
+ *
+ *  `reuse` keeps the alias: that daemon is a process this one did not start and
+ *  may genuinely be the host sibling. An explicit --public-host always wins. */
+export function demoUrlHost(opts) {
+    if (opts.publicHost !== undefined)
+        return opts.publicHost;
+    const envHost = (opts.env ?? process.env).NORSK_TEST_HOST;
+    if (opts.daemon === "reuse" && envHost)
+        return envHost;
+    return "localhost";
+}
 /** The pieces of a run that `runDemo`, `runExportCheck` and the dev-loop
  *  share: the daemon (private on its band, or the developer's), the dev
  *  backend on the driver's port, the registration, and the template (built
@@ -346,7 +377,7 @@ export class DemoSession {
         this.mode = opts.mode;
         this.policy = opts.daemon;
         this.publicHost = opts.publicHost;
-        const host = opts.publicHost ?? process.env.NORSK_TEST_HOST ?? "localhost";
+        const host = demoUrlHost({ publicHost: opts.publicHost, daemon: opts.daemon });
         this.host = host;
         if (opts.daemon === "reuse") {
             const daemonPort = opts.daemonPort ?? (Number(process.env.NORSK_CTL_PORT) || DEFAULT_DAEMON_PORT);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "type": "module",
   "exports": {
     ".": {

package/root-nuke.d.ts

@@ -1,8 +1,22 @@
-/** Minimal shape of `spawnSync` this needs, so tests can inject. */
+/** Minimal shape of `spawnSync` this needs, so tests can inject. `stdout` is
+ *  optional because only the container-scan calls read it. */
 export type NukeSpawn = (cmd: string, argv: string[], opts?: unknown) => {
     error?: unknown;
     status?: number | null;
+    stdout?: string | Buffer | null;
 };
+/** Container ids whose bind-mount sources sit at or under `dir`.
+ *
+ *  Matching on the mount SOURCE rather than a label is the point. The
+ *  containers that strand a temp dir are exactly the ones no teardown ever
+ *  tracked -- a run killed mid-flight (CI cancel, timeout, SIGKILL) never
+ *  labels or records them -- so a label filter finds nothing. The mount is the
+ *  one thing that is always true of a container holding the path open. */
+export declare function containersHoldingMountsUnder(dir: string, spawn?: NukeSpawn): string[];
+/** Remove the containers pinning `dir` so a nuke can actually unlink it.
+ *  Returns the ids it tried to reap. Best-effort: a docker that cannot list is
+ *  a docker that cannot nuke either, and the caller reports that separately. */
+export declare function reapContainersUnder(dir: string, spawn?: NukeSpawn, log?: (line: string) => void): string[];
 /** Refuse a target that would turn the nuke into something catastrophic.
  *
  *  `allowedBase` is the containment: the target must sit strictly INSIDE it.

package/root-nuke.js

@@ -10,6 +10,52 @@ import { lstatSync, readdirSync } from "node:fs";
 import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
 const NUKE_IMAGE = "alpine:3";
 const NUKE_TIMEOUT_MS = 60_000;
+const REAP_TIMEOUT_MS = 30_000;
+function spawnOut(spawn, argv) {
+    const r = spawn("docker", argv, { timeout: REAP_TIMEOUT_MS, encoding: "utf8" });
+    if (r?.error || (r?.status ?? 0) !== 0)
+        return undefined;
+    return String(r.stdout ?? "");
+}
+function lines(out) {
+    return out
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+/** Container ids whose bind-mount sources sit at or under `dir`.
+ *
+ *  Matching on the mount SOURCE rather than a label is the point. The
+ *  containers that strand a temp dir are exactly the ones no teardown ever
+ *  tracked -- a run killed mid-flight (CI cancel, timeout, SIGKILL) never
+ *  labels or records them -- so a label filter finds nothing. The mount is the
+ *  one thing that is always true of a container holding the path open. */
+export function containersHoldingMountsUnder(dir, spawn = spawnSync) {
+    const prefix = dir.endsWith(sep) ? dir : dir + sep;
+    const listed = spawnOut(spawn, ["ps", "-aq"]);
+    if (listed === undefined)
+        return [];
+    const held = [];
+    for (const id of lines(listed)) {
+        const mounts = spawnOut(spawn, ["inspect", "-f", "{{range .Mounts}}{{println .Source}}{{end}}", id]);
+        if (mounts === undefined)
+            continue;
+        if (lines(mounts).some((src) => src === dir || src.startsWith(prefix)))
+            held.push(id);
+    }
+    return held;
+}
+/** Remove the containers pinning `dir` so a nuke can actually unlink it.
+ *  Returns the ids it tried to reap. Best-effort: a docker that cannot list is
+ *  a docker that cannot nuke either, and the caller reports that separately. */
+export function reapContainersUnder(dir, spawn = spawnSync, log) {
+    const held = containersHoldingMountsUnder(dir, spawn);
+    if (held.length === 0)
+        return held;
+    log?.(`reaping ${held.length} container(s) pinning ${dir}: ${held.join(" ")}`);
+    spawn("docker", ["rm", "-f", ...held], { timeout: REAP_TIMEOUT_MS });
+    return held;
+}
 /** Refuse a target that would turn the nuke into something catastrophic.
  *
  *  `allowedBase` is the containment: the target must sit strictly INSIDE it.
@@ -83,6 +129,13 @@ export function nukeArgv(target) {
  *  Throws only for an unsafe target -- see {@link assertNukeTarget}. */
 export function nukePathAsRoot(target, allowedBase, spawn = spawnSync) {
     assertNukeTarget(target, allowedBase);
+    // A container still bind-mounting something under `target` makes that path
+    // unlinkable even for root -- the kernel returns EBUSY, `rm -rf` reports it
+    // as a plain non-zero exit, and the nuke silently no-ops. The litter then
+    // outlives every later run and eventually wedges an innocent job's checkout
+    // (2026-09-03: a leaked guide-composition studio, five days up, took
+    // commentary's checks AND integration red). Clear the holders first.
+    reapContainersUnder(target, spawn);
     const r = spawn("docker", nukeArgv(target), { timeout: NUKE_TIMEOUT_MS });
     if (r?.error)
         return false;

package/smoke.js

@@ -29,7 +29,13 @@ import { nukePathAsRoot, reportForeignOwners } from "./root-nuke.js";
 import { startSrtSources } from "./source-pump.js";
 import { applyTestHost, fetchComponentState, fetchComponents, fetchStreamMappings, isSrtListenerState, } from "./studio-state.js";
 import { makeStoreDir, TEST_TMP_BASE } from "./temp-dir.js";
-const SMOKE_PORT_BASE = 33000;
+// Below 32768: the band is a reservation, and Linux hands 32768-60999 out to
+// OUTBOUND connections. At 33000 this band sat inside that range, so any of the
+// many connections a run makes could be assigned a banded port as its source
+// port and the daemon would fail to bind with EADDRINUSE while nothing was
+// listening. Kept clear of the products' own bands (15000-31800) and guarded by
+// tests/port-bands.test.ts.
+const SMOKE_PORT_BASE = 21000;
 const SMOKE_BAND_WIDTH = 20;
 const SMOKE_BANDS = 50;
 const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";