@norskvideo/ctl-test-harness 0.1.83 → 0.1.85

package/daemon.d.ts

@@ -102,7 +102,8 @@ export declare function seedDaemonConfig(storeDir: string): void;
  *  (and each daemon start `rm -f`s the cpu-monitor sidecar by name). The port
  *  alone is not unique there -- two repos' slugs can hash into the same band --
  *  so the names carry the store dir too, which is per run and per job. A ctl
- *  that predates an override ignores it. */
+ *  that predates an override ignores it. The node MoQ relay has no per-daemon
+ *  name, so a test daemon runs without it. */
 export declare function daemonSpawnEnv(o: {
     storeDir: string;
     port: number;

package/daemon.js

@@ -231,7 +231,8 @@ export function seedDaemonConfig(storeDir) {
  *  (and each daemon start `rm -f`s the cpu-monitor sidecar by name). The port
  *  alone is not unique there -- two repos' slugs can hash into the same band --
  *  so the names carry the store dir too, which is per run and per job. A ctl
- *  that predates an override ignores it. */
+ *  that predates an override ignores it. The node MoQ relay has no per-daemon
+ *  name, so a test daemon runs without it. */
 export function daemonSpawnEnv(o) {
     // A spawned daemon must boot GUARDED: exercising the real ingress secret is
     // the point of the tiers that spawn one. The unit tier's marker would
@@ -242,6 +243,11 @@ export function daemonSpawnEnv(o) {
     return {
         NORSK_CTL_PROXY_CONTAINER: `norsk-proxy-${id}`,
         NORSK_CTL_CPU_MONITOR_CONTAINER: `norsk-ctl-cpu-monitor-${id}`,
+        // No node MoQ relay: it is a box-global singleton the daemon never removes,
+        // so a test daemon would leave one behind or adopt another job's (probe's
+        // smoke ran in relay mode on 2026-10-10). Instances keep their own MoQ
+        // listener. A caller that wants the relay sets it explicitly.
+        NORSK_CTL_MOQ_RELAY_ENABLE: "0",
         ...inherited,
         NORSK_CTL_STORE_DIR: o.storeDir,
         NORSK_CTL_PORT: String(o.port),

package/free-port.d.ts

@@ -0,0 +1,21 @@
+export declare const FREE_PORT_RANGE: {
+    readonly min: 32000;
+    readonly max: 32767;
+};
+/** Is `port` bindable on 0.0.0.0 right now, for both TCP and UDP? Advisory, as
+ *  ctl's own probe is: docker's bind at container start is the real test. Both
+ *  protocols because the caller does not know which one the template publishes. */
+export declare function hostPortFree(port: number): Promise<boolean>;
+export interface FreeHostPortOptions {
+    range?: {
+        min: number;
+        max: number;
+    };
+    /** Ports this run already holds, which a probe cannot see until docker binds them. */
+    taken?: ReadonlySet<number>;
+    /** Where the scan starts; random by default. */
+    start?: () => number;
+    probe?: (port: number) => Promise<boolean>;
+}
+/** A port in FREE_PORT_RANGE that is free on this host and not in `taken`. */
+export declare function freeHostPort(opts?: FreeHostPortOptions): Promise<number>;

package/free-port.js

@@ -0,0 +1,60 @@
+// A host port no concurrent run on the same host is also using.
+//
+// Every product's smoke shares one runner host, so a port a template fixes, or
+// one ctl allocates from a shared preferred value ("auto", preferred 4443), is
+// the same port in every repo's run. And the node MoQ relay every daemon brings
+// up holds 4443 itself, so a product that fixes MOQ_PORT=4443 fails outright
+// while the relay is up (relay's smoke, 2026-10-10).
+//
+// The range sits below the kernel's ephemeral range: outbound connections take
+// their source ports from 32768 up, so a port picked there can be taken between
+// the probe and docker's bind (port-bands.test.ts has that history). It is clear
+// of the smoke and demo bands and of the products' own (15000-31800). The start
+// is random so two runs that probe at once rarely meet, and the probe is what
+// rules out the ports already published.
+import { createSocket } from "node:dgram";
+import { createServer } from "node:net";
+export const FREE_PORT_RANGE = { min: 32000, max: 32767 };
+function udpFree(port) {
+    return new Promise((resolve) => {
+        const sock = createSocket("udp4");
+        sock.once("error", () => {
+            try {
+                sock.close();
+            }
+            catch {
+                // never bound: nothing to release
+            }
+            resolve(false);
+        });
+        sock.bind(port, "0.0.0.0", () => sock.close(() => resolve(true)));
+    });
+}
+function tcpFree(port) {
+    return new Promise((resolve) => {
+        const srv = createServer();
+        srv.once("error", () => resolve(false));
+        srv.listen(port, "0.0.0.0", () => srv.close(() => resolve(true)));
+    });
+}
+/** Is `port` bindable on 0.0.0.0 right now, for both TCP and UDP? Advisory, as
+ *  ctl's own probe is: docker's bind at container start is the real test. Both
+ *  protocols because the caller does not know which one the template publishes. */
+export async function hostPortFree(port) {
+    return (await udpFree(port)) && (await tcpFree(port));
+}
+/** A port in FREE_PORT_RANGE that is free on this host and not in `taken`. */
+export async function freeHostPort(opts = {}) {
+    const { min, max } = opts.range ?? FREE_PORT_RANGE;
+    const size = max - min + 1;
+    const start = opts.start?.() ?? min + Math.floor(Math.random() * size);
+    const probe = opts.probe ?? hostPortFree;
+    for (let i = 0; i < size; i++) {
+        const port = min + ((start - min + i) % size);
+        if (opts.taken?.has(port))
+            continue;
+        if (await probe(port))
+            return port;
+    }
+    throw new Error(`no free host port in ${min}-${max}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "type": "module",
   "exports": {
     ".": {
@@ -19,6 +19,10 @@
       "types": "./daemon-stores.d.ts",
       "default": "./daemon-stores.js"
     },
+    "./free-port": {
+      "types": "./free-port.d.ts",
+      "default": "./free-port.js"
+    },
     "./image-surface": {
       "types": "./image-surface.d.ts",
       "default": "./image-surface.js"
@@ -85,8 +89,8 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "^22.10.0",
-    "@norskvideo/norsk-studio": "1.30.0-2026-10-08-8f4b6c11",
-    "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-08-8f4b6c11",
+    "@norskvideo/norsk-studio": "1.30.0-2026-10-09-0cd6f070",
+    "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-09-0cd6f070",
     "@norskvideo/norsk-sdk": "1.3.1-2026-10-08-846f25e3"
   },
   "peerDependenciesMeta": {

package/smoke.d.ts

@@ -115,6 +115,12 @@ export interface SmokeSpec {
     /** Extra `--param NAME=value`. INSTANCE_NAME is always passed; STUDIO_HOST_PORT
      *  when the template declares it (else the port is pinned with --host-ports). */
     params?: string[];
+    /** Further template params that publish a host port the journey never dials
+     *  (relay's RTMP_PORT, say), each launched on a free one. MOQ_PORT and any
+     *  `*_PORT` defaulting to `auto` are freed without being named; a param
+     *  `params` sets is left as set. Not for a port a source or the surface
+     *  dials: the param moves the container's listener too. */
+    freePorts?: string[];
     hardware?: "nvidia" | "none";
     networkMode?: "docker";
     /** `port` is the container-internal listener port. May be empty. */
@@ -148,6 +154,10 @@ export interface SmokeDeps {
         ready: Promise<void>;
         running?: Promise<RunningDaemon>;
     };
+    /** A host port free right now and outside `taken` (free-port.ts). Optional so
+     *  an existing custom-deps consumer keeps working; absent = the banded surface
+     *  port and the template's own port values, as before. */
+    freePort?(taken: ReadonlySet<number>): Promise<number>;
     /** Does the resolved ctl run its daemon and proxy on system-assigned ports?
      *  Optional so an existing custom-deps consumer keeps working; absent = no,
      *  and the band decides both, as before. */

package/smoke.js

@@ -22,6 +22,7 @@ import { join } from "node:path";
 import { dumpInstanceContainerLogs, preserveEngineLogs, preserveInstanceContainerLogs } from "./container-logs.js";
 import { authority, ensureRunnerOnNetwork, netReachMode, resolveEndpoint, STUDIO_INTERNAL_PORT, studioBaseFrom, } from "./container-net.js";
 import { cleanupDaemon, ctlSupportsEphemeralPorts, PROXY_PORT_FILE, requireLicenseFile, runCli, startDaemon, } from "./daemon.js";
+import { freeHostPort } from "./free-port.js";
 import { hashSlot } from "./harness-config.js";
 import { ctlSupportsNoPublish, ctlSupportsPublishDebugPorts, runnerContainerUser } from "./launch.js";
 import { pollUntil } from "./poll.js";
@@ -40,6 +41,12 @@ const SMOKE_PORT_BASE = 21000;
 const SMOKE_BAND_WIDTH = 20;
 const SMOKE_BANDS = 50;
 const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";
+/** The MoQ listener's param in every product that has one. Freed whatever its
+ *  default: relay fixes it at 4443, the port the node MoQ relay also holds. */
+const MOQ_PORT_PARAM = "MOQ_PORT";
+/** ctl's allocated host port: a `*_PORT` param defaulting to `auto`, which it
+ *  resolves to the first free port from a PREFERRED value every run shares. */
+const isAllocatedPortParam = (name, dflt) => dflt === "auto" && /_PORT$/.test(name);
 export function smokePorts(slug, overrides = {}) {
     const daemonPort = SMOKE_PORT_BASE + hashSlot(`smoke:${slug}`, SMOKE_BANDS) * SMOKE_BAND_WIDTH;
     return {
@@ -57,6 +64,7 @@ export const defaultSmokeDeps = {
     writeFile: (path, contents) => writeFileSync(path, contents),
     startDaemon,
     supportsEphemeralPorts: ctlSupportsEphemeralPorts,
+    freePort: (taken) => freeHostPort({ taken }),
     cli: (storeDir, argv) => runCli(storeDir, ...argv),
     startSources: startSrtSources,
     stopSources: async (handles) => {
@@ -359,29 +367,59 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         // with a host-port binding on the studio service. In direct mode with an
         // internal-only launch the target dials the service name instead.
         const shown = await cli(["template", "show", templateName], { output: "json" });
-        const declared = new Set(shown.exitCode === 0
-            ? (parseJson(shown, "template show").parameters ?? []).map((p) => p.name)
+        const declared = new Map(shown.exitCode === 0
+            ? (parseJson(shown, "template show").parameters ??
+                []).map((p) => [p.name, p.default])
             : []);
-        const params = [`INSTANCE_NAME=${instanceId}`, ...(spec.params ?? [])];
-        const launchArgv = ["instance", "launch-template", instanceId, "--template", templateName];
         const internalOnly = mode === "direct" && (await deps.supportsNoPublish());
+        const specParams = new Set((spec.params ?? []).map((p) => p.split("=")[0]));
+        for (const name of spec.freePorts ?? []) {
+            if (!declared.has(name)) {
+                throw new Error(`freePorts names ${name}, but template '${templateName}' does not declare it`);
+            }
+        }
+        // Ports a concurrent run on this host could also be using get a free one
+        // each (free-port.ts). An internal-only launch publishes none, so it keeps
+        // the template's values.
+        const freed = internalOnly
+            ? []
+            : [...declared]
+                .filter(([name, dflt]) => !specParams.has(name) &&
+                (name === MOQ_PORT_PARAM || isAllocatedPortParam(name, dflt) || (spec.freePorts ?? []).includes(name)))
+                .map(([name]) => name);
+        const taken = new Set();
+        const pick = async () => {
+            if (!deps.freePort)
+                return undefined;
+            const port = await deps.freePort(taken);
+            taken.add(port);
+            return port;
+        };
+        if (!internalOnly && spec.ports?.studioHostPort === undefined) {
+            const port = await pick();
+            if (port !== undefined) {
+                ports.studioHostPort = port;
+                studio.studioHostPort = port;
+            }
+        }
+        const baseArgv = ["instance", "launch-template", instanceId, "--template", templateName];
+        const params = [`INSTANCE_NAME=${instanceId}`, ...(spec.params ?? [])];
+        const flags = [];
         if (studioSurface && declared.has(STUDIO_HOST_PORT_PARAM)) {
             params.push(`${STUDIO_HOST_PORT_PARAM}=${ports.studioHostPort}`);
         }
         else if (!internalOnly && surface.hostPort === undefined) {
-            launchArgv.push("--host-ports", `${ports.studioHostPort}:${surface.internalPort}@${surface.service}`);
+            baseArgv.push("--host-ports", `${ports.studioHostPort}:${surface.internalPort}@${surface.service}`);
         }
-        for (const p of params)
-            launchArgv.push("--param", p);
         if (spec.hardware)
-            launchArgv.push("--hardware", spec.hardware);
+            flags.push("--hardware", spec.hardware);
         if (spec.networkMode)
-            launchArgv.push("--network-mode", spec.networkMode);
+            flags.push("--network-mode", spec.networkMode);
         const user = deps.containerUser();
         if (user)
-            launchArgv.push("--container-user", user);
+            flags.push("--container-user", user);
         if (internalOnly)
-            launchArgv.push("--internal-only");
+            flags.push("--internal-only");
         // ctl binds a product's OPERATOR compose ports (STUDIO_HOST_PORT among
         // them) to 127.0.0.1. `fetchStudio` dials NORSK_TEST_HOST in publish mode;
         // when that is not loopback the test process is a container reaching a host
@@ -389,8 +427,21 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         // fetchers already use rather than a second thing to configure.
         else if ((process.env.NORSK_TEST_HOST ?? "localhost") !== "localhost" &&
             (await (deps.supportsPublishDebugPorts ?? ctlSupportsPublishDebugPorts)())) {
-            launchArgv.push("--publish-debug-ports");
+            flags.push("--publish-debug-ports");
         }
+        // Picked per attempt, so a launch that loses the bind race retries on
+        // fresh ports rather than the one it lost.
+        const launchArgv = async () => {
+            const freedParams = [];
+            for (const name of freed) {
+                const port = await pick();
+                if (port !== undefined)
+                    freedParams.push(`${name}=${port}`);
+            }
+            if (freedParams.length > 0)
+                deps.log(`${slug}: free host ports ${freedParams.join(" ")}`);
+            return [...baseArgv, ...[...params, ...freedParams].flatMap((p) => ["--param", p]), ...flags];
+        };
         launched = true;
         // Same advisory-check race as the demo tier, same remedy: reap this id's
         // orphans from a run that was killed before teardown, then retry once if the
@@ -398,7 +449,7 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         reapInstance(instanceId);
         await launchWithPortConflictRetry({
             instanceId,
-            attempt: () => cliOk(launchArgv),
+            attempt: async () => cliOk(await launchArgv()),
             log: deps.log,
         });
         await pollUntil(async () => {