@norskvideo/ctl-test-harness 0.1.75 → 0.1.77

package/compose-advancing.js

@@ -6,7 +6,8 @@
 // -> nodes[].mediaIn). Playout's scripts/ensure-sources.sh:52-64 as TypeScript
 // (05-demo s7 step 2), pure over an injected fetch so it is unit-tested and
 // reachable through whichever base the caller has: the daemon proxy's
-// `/instance/<id>/visualiser`, or `<id>-media-1:6791/visualiser` on norsk-net.
+// `/instance/<id>/visualiser`, or `<id>-media-1:6791/visualiser` from the
+// instance network `<id>_default` (media is on no other).
 export const DEFAULT_COMPOSE_NODE = "video_compose";
 const DEFAULT_SETTLE_MS = 6000;
 /** The highest mediaIn across every node of that name; 0 when none. */

package/container-net.d.ts

@@ -118,11 +118,13 @@ export declare function ownContainerId(opts?: {
     isDockerObject?: (id: string) => boolean;
 }): string | null;
 /** `docker network connect` is not idempotent — a second attach errors. Treat
- *  the "already attached" variants as success so setup can call this blindly. */
+ *  the "already attached" variants as success so setup can call this blindly.
+ *  Twin of norsk-ctl backend/src/docker/container-ops.ts isAlreadyOnNetwork. */
 export declare function isAlreadyOnNetworkError(stderr: string): boolean;
 type RunResult = {
     status: number | null;
     stderr: string;
+    stdout?: string;
 };
 type Runner = (cmd: string, args: string[]) => RunResult;
 /** Idempotently join the test container to norsk-net so `direct` service DNS
@@ -139,4 +141,44 @@ export declare function ensureRunnerOnNetwork(opts?: {
     detect?: Parameters<typeof ownContainerId>[0];
     run?: Runner;
 }): "attached" | "already" | "not-in-container" | "failed";
+/** The compose project is the instance id, so its network is `<id>_default`.
+ *  Mirrors norsk-ctl's instanceNetworkName. */
+export declare function instanceNetworkName(instanceId: string): string;
+/** docker's wording for a disconnect that has nothing to do. Twin of norsk-ctl
+ *  backend/src/docker/container-ops.ts isNotOnNetwork: change both together. */
+export declare function isNotOnNetworkError(stderr: string): boolean;
+export declare class InstanceNetworks {
+    private readonly opts;
+    private readonly ids;
+    private resolvedId;
+    constructor(opts?: {
+        /** Explicit id (tests). Omitted -> resolved once by `ownContainerId`. */
+        containerId?: string | null;
+        run?: Runner;
+    });
+    private containerId;
+    /** Join the runner to the instance's network. Connects on every call rather
+     *  than trusting the record: an instance deleted and relaunched under the
+     *  same id has a new network the runner is not on. One `docker network
+     *  connect` costs the same as the inspect that checking the record would. */
+    join(instanceId: string): "attached" | "already" | "not-in-container" | "failed";
+    /** Leave a network joined here. Never throws: teardown carries on regardless.
+     *  `force` leaves even if this process did not record the join (a later
+     *  `demo down` in a fresh process). */
+    leave(instanceId: string, opts?: {
+        force?: boolean;
+    }): void;
+    /** The runner's IP on the instance network, for something media dials back
+     *  (a capture server). Joins first. Null off-container or on failure. */
+    addressOn(instanceId: string): string | null;
+    leaveAll(): void;
+    joined(): string[];
+}
+/** The process-wide registry the address helpers join through. */
+export declare function currentInstanceNetworks(): InstanceNetworks;
+/** Swap the registry (tests); returns a restore function. */
+export declare function useInstanceNetworks(next: InstanceNetworks): () => void;
+/** Make `<id>-media-1` resolvable in direct mode. Publish mode reaches media by
+ *  published port and needs nothing. */
+export declare function reachInstanceMedia(instanceId: string, mode?: NetReachMode): void;
 export {};

package/container-net.js

@@ -23,12 +23,14 @@
 // makes for media HTTP — generalised to the studio-control + SRT-egress ports
 // that are the actual colliders.
 //
-// THE ONE CONSTRAINT: container-DNS reachability needs the test container joined
-// to norsk-net (bridge DNS is per-network). On Docker Desktop / OrbStack the
-// bridge is hidden inside a VM and is not routable from the host at all, so the
-// direct path can't work there — those runs MUST keep publishing. Hence the mode
-// switch: `direct` on the Linux DooD CI box, `publish` (the default) everywhere
-// else. Nothing here changes behaviour until a caller opts a suite into `direct`.
+// THE ONE CONSTRAINT: container-DNS reachability needs the test container on
+// the target's network (bridge DNS is per-network): norsk-net for studio, the
+// instance network `<id>_default` for media (see "Instance networks" below).
+// On Docker Desktop / OrbStack the bridge is hidden inside a VM and is not
+// routable from the host at all, so the direct path can't work there — those
+// runs MUST keep publishing. Hence the mode switch: `direct` on the Linux DooD
+// CI box, `publish` (the default) everywhere else. Nothing here changes
+// behaviour until a caller opts a suite into `direct`.
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { hostname } from "node:os";
@@ -83,6 +85,7 @@ export function studioApiBase(o) {
  *  `<id>-media-1:8080`. Mirrors studio-state.mediaDirectUrl, generalised for the
  *  direct-pull capture path. */
 export function mediaHttpBase(o) {
+    reachInstanceMedia(o.instanceId, o.mode);
     const e = resolveEndpoint({
         instanceId: o.instanceId,
         service: "media",
@@ -100,6 +103,7 @@ export function mediaHttpBase(o) {
  *  and `publishPort` are the same band value today — going direct is what later
  *  lets that band be dropped entirely. */
 export function srtEgressUrl(o) {
+    reachInstanceMedia(o.instanceId, o.mode);
     const e = resolveEndpoint({
         instanceId: o.instanceId,
         service: "media",
@@ -127,8 +131,8 @@ export function studioBaseFrom(studio, publishHost, mode) {
     });
 }
 // ── Runner network attach ───────────────────────────────────────────────────
-// `direct` DNS only resolves if the test container is on norsk-net. These
-// helpers attach it idempotently; all pure/injectable so the logic is tested
+// `direct` DNS for studio only resolves if the test container is on norsk-net.
+// These helpers attach it idempotently; all pure/injectable so the logic is tested
 // without touching docker.
 /** The 64-hex container id from a /proc/self/cgroup dump, or null on a bare host.
  *  In a container the id also appears as the hostname, but cgroup is present in
@@ -180,13 +184,14 @@ export function ownContainerId(opts = {}) {
     });
 }
 /** `docker network connect` is not idempotent — a second attach errors. Treat
- *  the "already attached" variants as success so setup can call this blindly. */
+ *  the "already attached" variants as success so setup can call this blindly.
+ *  Twin of norsk-ctl backend/src/docker/container-ops.ts isAlreadyOnNetwork. */
 export function isAlreadyOnNetworkError(stderr) {
     return /already exists in network|is already connected|endpoint with name .* already exists/i.test(stderr);
 }
 const defaultRunner = (cmd, args) => {
     const r = spawnSync(cmd, args, { encoding: "utf-8" });
-    return { status: r.status, stderr: r.stderr ?? "" };
+    return { status: r.status, stderr: r.stderr ?? "", stdout: r.stdout ?? "" };
 };
 /** Idempotently join the test container to norsk-net so `direct` service DNS
  *  resolves. Returns a verdict rather than throwing: `not-in-container` (nothing
@@ -205,3 +210,119 @@ export function ensureRunnerOnNetwork(opts = {}) {
         return "already";
     return "failed";
 }
+// ── Instance networks ───────────────────────────────────────────────────────
+// ctl attaches media to its instance's own compose network only, not to
+// norsk-net: Docker Desktop's port forwarder delivers published UDP to either IP
+// of a dual-homed container, and an SRT listener's reply then leaves by the
+// other interface and is dropped (norsk-ctl docs/product-template-format.md,
+// Networking). So `<id>-media-1` resolves only from `<id>_default`, and direct
+// mode joins the runner to that network whenever it addresses an instance's
+// media.
+//
+// The runner must leave again BEFORE the instance is deleted: a foreign
+// endpoint keeps `compose down` from removing the network, which then leaks.
+// cleanupDaemon does that for every network joined here.
+/** The compose project is the instance id, so its network is `<id>_default`.
+ *  Mirrors norsk-ctl's instanceNetworkName. */
+export function instanceNetworkName(instanceId) {
+    return `${instanceId}_default`;
+}
+/** docker's wording for a disconnect that has nothing to do. Twin of norsk-ctl
+ *  backend/src/docker/container-ops.ts isNotOnNetwork: change both together. */
+export function isNotOnNetworkError(stderr) {
+    return /is not connected to (the )?network|network .* not found|no such network/i.test(stderr);
+}
+export class InstanceNetworks {
+    opts;
+    ids = new Set();
+    resolvedId;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    containerId() {
+        if (this.opts.containerId !== undefined)
+            return this.opts.containerId;
+        if (this.resolvedId === undefined)
+            this.resolvedId = ownContainerId();
+        return this.resolvedId;
+    }
+    /** Join the runner to the instance's network. Connects on every call rather
+     *  than trusting the record: an instance deleted and relaunched under the
+     *  same id has a new network the runner is not on. One `docker network
+     *  connect` costs the same as the inspect that checking the record would. */
+    join(instanceId) {
+        const verdict = ensureRunnerOnNetwork({
+            network: instanceNetworkName(instanceId),
+            containerId: this.containerId(),
+            ...(this.opts.run ? { run: this.opts.run } : {}),
+        });
+        if (verdict === "attached" || verdict === "already")
+            this.ids.add(instanceId);
+        return verdict;
+    }
+    /** Leave a network joined here. Never throws: teardown carries on regardless.
+     *  `force` leaves even if this process did not record the join (a later
+     *  `demo down` in a fresh process). */
+    leave(instanceId, opts = {}) {
+        if (!this.ids.delete(instanceId) && !opts.force)
+            return;
+        const id = this.containerId();
+        if (!id)
+            return;
+        const r = (this.opts.run ?? defaultRunner)("docker", [
+            "network",
+            "disconnect",
+            instanceNetworkName(instanceId),
+            id,
+        ]);
+        if (r.status !== 0 && !isNotOnNetworkError(r.stderr))
+            console.error(`leaving ${instanceNetworkName(instanceId)} failed: ${r.stderr.trim()}`);
+    }
+    /** The runner's IP on the instance network, for something media dials back
+     *  (a capture server). Joins first. Null off-container or on failure. */
+    addressOn(instanceId) {
+        const verdict = this.join(instanceId);
+        if (verdict === "not-in-container" || verdict === "failed")
+            return null;
+        const id = this.containerId();
+        if (!id)
+            return null;
+        const net = instanceNetworkName(instanceId);
+        const r = (this.opts.run ?? defaultRunner)("docker", [
+            "inspect",
+            "-f",
+            `{{with index .NetworkSettings.Networks "${net}"}}{{.IPAddress}}{{end}}`,
+            id,
+        ]);
+        const ip = (r.stdout ?? "").trim();
+        return r.status === 0 && ip ? ip : null;
+    }
+    leaveAll() {
+        for (const id of [...this.ids])
+            this.leave(id);
+    }
+    joined() {
+        return [...this.ids];
+    }
+}
+let instanceNetworks = new InstanceNetworks();
+/** The process-wide registry the address helpers join through. */
+export function currentInstanceNetworks() {
+    return instanceNetworks;
+}
+/** Swap the registry (tests); returns a restore function. */
+export function useInstanceNetworks(next) {
+    const prev = instanceNetworks;
+    instanceNetworks = next;
+    return () => {
+        instanceNetworks = prev;
+    };
+}
+/** Make `<id>-media-1` resolvable in direct mode. Publish mode reaches media by
+ *  published port and needs nothing. */
+export function reachInstanceMedia(instanceId, mode = netReachMode()) {
+    if (mode !== "direct")
+        return;
+    if (instanceNetworks.join(instanceId) === "failed")
+        console.error(`could not join ${instanceNetworkName(instanceId)}: ${instanceId}-media-1 will not resolve`);
+}

package/daemon.d.ts

@@ -140,6 +140,10 @@ export declare function cleanupDaemon(opts: {
     containers: string[];
     /** Injected for tests; defaults to the Docker-label reap. */
     reapInstance?: (id: string) => string[];
+    /** Injected for tests; defaults to leaving the instance network the harness
+     *  joined (container-net InstanceNetworks). It must precede the delete: a
+     *  foreign endpoint keeps `compose down` from removing the network. */
+    leaveNetwork?: (id: string) => void;
     deleteTimeoutMs?: number;
 }): Promise<void>;
 /** Tear down a direct-API test: stop proxy, remove instances, rm temp dir. */

package/daemon.js

@@ -13,6 +13,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 { currentInstanceNetworks } from "./container-net.js";
 import { rememberDaemonStore } from "./daemon-stores.js";
 import { pollUntil } from "./poll.js";
 import { reapInstance } from "./reap.js";
@@ -339,7 +340,9 @@ export const INSTANCE_DELETE_TIMEOUT_MS = 20_000;
  */
 export async function cleanupDaemon(opts) {
     const deleteTimeoutMs = opts.deleteTimeoutMs ?? INSTANCE_DELETE_TIMEOUT_MS;
+    const leave = opts.leaveNetwork ?? ((id) => currentInstanceNetworks().leave(id));
     for (const id of opts.instances ?? []) {
+        leave(id);
         try {
             if ((await settleWithin(opts.deleteInstance(id), deleteTimeoutMs)) === "timeout")
                 console.error(`cleanup: delete ${id} gave no answer in ${deleteTimeoutMs}ms`);
@@ -348,6 +351,8 @@ export async function cleanupDaemon(opts) {
             console.error(`cleanup: delete ${id} failed: ${e}`);
         }
     }
+    if (!opts.leaveNetwork)
+        currentInstanceNetworks().leaveAll();
     const reap = opts.reapInstance ?? reapInstance;
     for (const id of opts.instances ?? []) {
         const left = reap(id);

package/demo/harness.js

@@ -179,6 +179,7 @@ export class ProductHarness {
             attempt: () => s.cliOk(launchArgv),
             log: deps.log,
         });
+        s.joinExtras(instanceId);
         await s.waitRunning(instanceId);
         const rows = await s.ingestPorts(instanceId);
         const templateParams = { declared, overrides: specParams };

package/demo/run.d.ts

@@ -356,6 +356,12 @@ export declare class DemoSession {
     /** name -> stringified default, from `template show`. */
     declaredParams(templateName: string): Promise<Map<string, string | undefined>>;
     startExtras(instanceId: string): void;
+    /** ctl puts media on its instance network only, so an extra media dials (a
+     *  capture origin) must join that network too. It exists only once the
+     *  launch has created the instance, so this runs after the launch, not with
+     *  startExtras. Extras are removed before the instance is deleted, so this
+     *  never holds the network open. */
+    joinExtras(instanceId: string): void;
     stopExtras(): void;
     waitRunning(instanceId: string): Promise<void>;
     instanceListed(instanceId: string): Promise<boolean>;

package/demo/run.js

@@ -30,7 +30,7 @@ import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { parseManifestSeed, repoOf } from "@norskvideo/ctl-sdk/manifest-seed";
 import { preserveInstanceContainerLogs } from "../container-logs.js";
-import { DOCKER_NETWORK_NAME, ensureRunnerOnNetwork, netReachMode } from "../container-net.js";
+import { currentInstanceNetworks, DOCKER_NETWORK_NAME, ensureRunnerOnNetwork, instanceNetworkName, isAlreadyOnNetworkError, netReachMode, } from "../container-net.js";
 import { cleanupDaemon, ctlSupportsEphemeralPorts, PROXY_PORT_FILE, requireLicenseFile, runCli, startDaemon, } from "../daemon.js";
 import { hashSlot } from "../harness-config.js";
 import { ctlSupportsNoPublish, ctlSupportsPublishDebugPorts, runnerContainerUser } from "../launch.js";
@@ -565,6 +565,7 @@ export class DemoSession {
      *  the product publishes (plus the spec's built one), the product and its
      *  control-plane container all go first. Each step tolerates absence. */
     async resetRegistration(instanceId) {
+        currentInstanceNetworks().leave(instanceId, { force: true });
         await this.cli(["instance", "delete", instanceId, "--purge"]);
         const listed = await this.cli(["template", "list"], { output: "json" });
         const names = listed.exitCode === 0
@@ -695,6 +696,19 @@ export class DemoSession {
             this.deps.log(`extra ${e.name}: ${e.image}`);
         }
     }
+    /** ctl puts media on its instance network only, so an extra media dials (a
+     *  capture origin) must join that network too. It exists only once the
+     *  launch has created the instance, so this runs after the launch, not with
+     *  startExtras. Extras are removed before the instance is deleted, so this
+     *  never holds the network open. */
+    joinExtras(instanceId) {
+        for (const name of this.extras) {
+            const c = this.deps.docker(["network", "connect", instanceNetworkName(instanceId), name]);
+            if (c.exitCode !== 0 && !isAlreadyOnNetworkError(c.stderr)) {
+                throw new Error(`extra '${name}' could not join ${instanceNetworkName(instanceId)}: ${c.stderr.trim()}`);
+            }
+        }
+    }
     stopExtras() {
         for (const name of this.extras)
             this.deps.docker(["rm", "-f", name]);
@@ -748,8 +762,11 @@ export class DemoSession {
         this.preserveContainerLogs(opts.instances);
         if (opts.handles.length)
             await this.deps.stopSources(opts.handles).catch(() => { });
+        // Extras sit on the instance networks; they go before any instance does.
+        this.stopExtras();
         if (this.policy === "reuse") {
             for (const id of opts.instances) {
+                currentInstanceNetworks().leave(id);
                 const r = await this.cli(["instance", "delete", id, "--purge"]);
                 if (r.exitCode !== 0)
                     this.deps.log(`instance delete ${id}: ${(r.stderr || r.stdout).trim()}`);
@@ -836,6 +853,7 @@ export async function demoDown(product, deps = defaultDemoDeps(process.cwd())) {
     const cli = (argv) => deps.cli(state.storeDir, ["--port", String(state.daemonPort), ...argv]);
     if (state.daemon === "reuse") {
         if (state.instanceId) {
+            currentInstanceNetworks().leave(state.instanceId, { force: true });
             const r = await cli(["instance", "delete", state.instanceId, "--purge"]);
             if (r.exitCode !== 0)
                 deps.log(`instance delete ${state.instanceId}: ${(r.stderr || r.stdout).trim()}`);

package/demo/spec.d.ts

@@ -93,7 +93,8 @@ export type DemoTemplate = {
 };
 /** A sidecar container the demo needs beside the instance (funke's ad-push
  *  capture origin): `docker run -d --name <name> --network norsk-net <args>
- *  <image> <command>`, started before the launch, removed at teardown. */
+ *  <image> <command>`, started before the launch, joined to the instance
+ *  network after it (media is on no other), removed at teardown. */
 export interface DemoExtra {
     name: string;
     image: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "type": "module",
   "exports": {
     ".": {
@@ -85,9 +85,9 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "^22.10.0",
-    "@norskvideo/norsk-studio": "1.30.0-2026-10-04-e672beb6",
-    "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-04-e672beb6",
-    "@norskvideo/norsk-sdk": "1.3.1-2026-10-04-dc313351"
+    "@norskvideo/norsk-studio": "1.30.0-2026-10-05-3d2846dc",
+    "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-05-3d2846dc",
+    "@norskvideo/norsk-sdk": "1.3.1-2026-10-04-f034e83d"
   },
   "peerDependenciesMeta": {
     "@norskvideo/norsk-studio": {

package/studio-state.js

@@ -18,7 +18,7 @@
 // Studio's /live/api/components returns each entry as `{ componentId, componentType, capabilities }`
 // — NOT `{ id, type }` (which is what the source-yaml schema uses internally).
 // Verified empirically against a live Studio instance.
-import { studioBaseFrom } from "./container-net.js";
+import { reachInstanceMedia, studioBaseFrom } from "./container-net.js";
 // The host the studio port is reachable on. Normally the product template
 // publishes it on the loopback of the machine running the tests, so localhost is
 // right. When the test process itself runs inside a container that launches the
@@ -55,11 +55,13 @@ export function applyTestHost(rawUrl) {
 // proxies `/instance/<id>/media/*` here; whip-driver hits the same port direct.
 const MEDIA_HTTP_PORT = 8080;
 // Rewrite a daemon-proxy-routed media URL to a direct hit on the Norsk media
-// container over the daemon's `norsk-net` bridge. Studio advertises playback
-// URLs as `http://<publicHost>/instance/<id>/media/<native>` — that route is
-// served ONLY by the daemon's nginx proxy. A harness that runs proxy-less (and
-// whose runner has joined norsk-net) can instead reach the media container
-// directly by its compose service name: `http://<id>-media-1:8080/<native>`.
+// container over its instance network `<id>_default`, the only one media is
+// on. Studio advertises playback URLs as
+// `http://<publicHost>/instance/<id>/media/<native>` — that route is served ONLY
+// by the daemon's nginx proxy. A harness that runs proxy-less can instead reach
+// the media container directly by its compose service name:
+// `http://<id>-media-1:8080/<native>`; in direct mode this joins the runner to
+// `<id>_default` so that name resolves.
 // The `/instance/<id>/media` prefix is the proxy's routing concern; Norsk's
 // native path is what follows it. Falls back to applyTestHost for URLs that
 // don't carry the proxy prefix. Mirrors whip-driver's dockerNetUrl.
@@ -70,6 +72,7 @@ export function mediaDirectUrl(rawUrl) {
         if (m) {
             const id = m[1];
             const rest = m[2] ?? "/";
+            reachInstanceMedia(id);
             return `http://${id}-media-1:${MEDIA_HTTP_PORT}${rest}${u.search}`;
         }
     }