@norskvideo/ctl-test-harness 0.1.7 → 0.1.8

package/container-net.d.ts

@@ -0,0 +1,110 @@
+export declare const DOCKER_NETWORK_NAME = "norsk-net";
+export declare const STUDIO_INTERNAL_PORT = 8000;
+export declare const MEDIA_HTTP_INTERNAL_PORT = 8080;
+export type NetReachMode = "publish" | "direct";
+/** How the suite reaches instance containers. `direct` = norsk-net service DNS
+ *  (no host publish, no collision) — only viable on a Linux DooD runner whose
+ *  test container is on norsk-net. `publish` = today's host-published port,
+ *  the Docker-Desktop-safe default. Read from NORSK_TEST_NET. */
+export declare function netReachMode(env?: Record<string, string | undefined>): NetReachMode;
+export interface Endpoint {
+    host: string;
+    port: number;
+}
+export declare const authority: (e: Endpoint) => string;
+/** Compose's container DNS for a template-launched instance: `<id>-<service>-1`.
+ *  Byte-identical to norsk-ctl's productInstanceHost — the compose project is the
+ *  instance id and each service runs a single replica. */
+export declare function productServiceHost(instanceId: string, service: string): string;
+export interface ResolveOpts {
+    instanceId: string;
+    service: "studio" | "media";
+    /** Port the listener binds INSIDE the container (studio 8000, media SRT its
+     *  own configured port). Used in `direct` mode. */
+    internalPort: number;
+    /** Host + port the container is published on today. Used in `publish` mode. */
+    publishHost: string;
+    publishPort: number;
+    /** Defaults to netReachMode() so a suite flips the whole harness with one env var. */
+    mode?: NetReachMode;
+}
+/** The seam: one function every reach decision goes through. `publish` returns
+ *  the host-published endpoint unchanged (zero behaviour change); `direct`
+ *  returns the unique service DNS at the internal port. */
+export declare function resolveEndpoint(o: ResolveOpts): Endpoint;
+/** Base URL for Studio's `/live/api/*` control surface. Publish mode reaches the
+ *  host-published studioHostPort (as studio-state.ts does today); direct mode
+ *  reaches `<id>-studio-1:8000`. Drop-in for the `http://${STUDIO_HOST}:${port}`
+ *  prefix the studio fetchers build. */
+export declare function studioApiBase(o: {
+    instanceId: string;
+    publishHost: string;
+    publishPort: number;
+    mode?: NetReachMode;
+}): string;
+/** Base URL for the Norsk media container's HTTP surface (HLS/CMAF pull —
+ *  `/ts/*.m3u8`, `/cmaf/*`). Publish mode dials the host-published media port on
+ *  TEST_HOST (as funke's hls-capture does today); direct mode dials
+ *  `<id>-media-1:8080`. Mirrors studio-state.mediaDirectUrl, generalised for the
+ *  direct-pull capture path. */
+export declare function mediaHttpBase(o: {
+    instanceId: string;
+    publishHost: string;
+    publishPort: number;
+    mode?: NetReachMode;
+}): string;
+/** Caller-mode SRT URL for an output.srt egress listener. Publish mode dials the
+ *  host-published egress port on TEST_HOST (as output-capture.ts does today);
+ *  direct mode dials `<id>-media-1:<internalPort>`. Because remapConfigPorts
+ *  currently sets the internal listener port == the published port, `internalPort`
+ *  and `publishPort` are the same band value today — going direct is what later
+ *  lets that band be dropped entirely. */
+export declare function srtEgressUrl(o: {
+    instanceId: string;
+    internalPort: number;
+    publishHost: string;
+    publishPort: number;
+    mode?: NetReachMode;
+}): string;
+/** What a caller needs to reach an instance's Studio control surface under
+ *  either mode: the published port (publish) plus the instance id (direct, to
+ *  form `<id>-studio-1`). Threaded in place of a bare `studioHostPort: number`. */
+export interface StudioTarget {
+    instanceId: string;
+    studioHostPort: number;
+}
+/** What a fetcher/control helper accepts to reach Studio: EITHER a bare published
+ *  port (legacy — every existing caller, other products included) OR a
+ *  StudioTarget (instanceId-aware, opts the call into direct-net). */
+export type StudioReach = number | StudioTarget;
+/** Resolve Studio's base URL from EITHER a bare published port (legacy — dials
+ *  `publishHost:port`, exactly today's behaviour) OR a StudioTarget (instanceId-
+ *  aware, so direct mode dials `<id>-studio-1:8000`). The union is the whole
+ *  migration story: every existing `studioHostPort: number` caller — including
+ *  other products' suites — keeps working untouched, and a suite opts a call into
+ *  direct-net simply by passing the target instead of the number. */
+export declare function studioBaseFrom(studio: StudioReach, publishHost: string, mode?: NetReachMode): string;
+/** 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
+ *  both cgroup v1 (`/docker/<id>`) and v2 (`docker-<id>.scope`) layouts. */
+export declare function parseOwnContainerId(cgroupText: string): string | null;
+export declare function ownContainerId(read?: () => string): 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. */
+export declare function isAlreadyOnNetworkError(stderr: string): boolean;
+type RunResult = {
+    status: number | null;
+    stderr: string;
+};
+type Runner = (cmd: string, args: string[]) => RunResult;
+/** Idempotently join the test container to norsk-net so `direct` service DNS
+ *  resolves. Returns a verdict rather than throwing: `not-in-container` (nothing
+ *  to attach — publish mode is the only sane choice), `attached`, `already`, or
+ *  `failed` (a real error the caller should surface). */
+export declare function ensureRunnerOnNetwork(opts?: {
+    network?: string;
+    /** Explicit id (tests). Omitted -> read from /proc/self/cgroup. `null` forces the not-in-container branch. */
+    containerId?: string | null;
+    run?: Runner;
+}): "attached" | "already" | "not-in-container" | "failed";
+export {};

package/container-net.js

@@ -0,0 +1,172 @@
+// Reach launched product instances by their norsk-net service DNS instead of a
+// host-published port. Dissolves the cross-product host-port collision the
+// release gate trips on. Consumed by the playout, funke, and commentary
+// integration harnesses (studioApiBase / mediaHttpBase / srtEgressUrl /
+// studioBaseFrom); commentary's WHIP path already reaches media directly.
+//
+// WHY host ports collide: in the docker-outside-of-docker CI runner the test
+// process is itself a container and studio/media run as HOST-sibling containers,
+// so their published ports live on the shared host. Two products' harnesses band
+// their ports off `hashSlot(slug, 50)` over an IDENTICAL base, so two slugs that
+// land in the same slot publish the same host port and the second launch dies
+// with "Bind for 0.0.0.0:<port> failed: port is already allocated". The slug->slot
+// map is deterministic, so re-running never dodges it.
+//
+// WHY direct-net removes the whole class: every product instance is its own
+// compose project on the shared external `norsk-net`, so compose names its
+// containers `<id>-studio-1` / `<id>-media-1` (see norsk-ctl's productInstanceHost).
+// Reaching those by name at the container-INTERNAL port (studio 8000, media
+// 8080, the SRT egress listener's own port) needs NO host publish: internal
+// ports live in per-container network namespaces, so a thousand instances can
+// all bind 8000 internally without clashing, and the unique service DNS keeps
+// them addressable. This is the same move `studio-state.mediaDirectUrl` already
+// 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`.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+// Mirrors of norsk-ctl's @norsk-ctl/shared constants — re-declared (not imported)
+// because this package doesn't depend on the ctl backend, exactly as
+// studio-state.ts re-declares MEDIA_HTTP_PORT. Source of truth:
+// packages/norsk-ctl/shared/src/base-constants.ts.
+export const DOCKER_NETWORK_NAME = "norsk-net";
+export const STUDIO_INTERNAL_PORT = 8000;
+export const MEDIA_HTTP_INTERNAL_PORT = 8080;
+/** How the suite reaches instance containers. `direct` = norsk-net service DNS
+ *  (no host publish, no collision) — only viable on a Linux DooD runner whose
+ *  test container is on norsk-net. `publish` = today's host-published port,
+ *  the Docker-Desktop-safe default. Read from NORSK_TEST_NET. */
+export function netReachMode(env = process.env) {
+    return env.NORSK_TEST_NET === "direct" ? "direct" : "publish";
+}
+export const authority = (e) => `${e.host}:${e.port}`;
+/** Compose's container DNS for a template-launched instance: `<id>-<service>-1`.
+ *  Byte-identical to norsk-ctl's productInstanceHost — the compose project is the
+ *  instance id and each service runs a single replica. */
+export function productServiceHost(instanceId, service) {
+    return `${instanceId}-${service}-1`;
+}
+/** The seam: one function every reach decision goes through. `publish` returns
+ *  the host-published endpoint unchanged (zero behaviour change); `direct`
+ *  returns the unique service DNS at the internal port. */
+export function resolveEndpoint(o) {
+    const mode = o.mode ?? netReachMode();
+    return mode === "direct"
+        ? { host: productServiceHost(o.instanceId, o.service), port: o.internalPort }
+        : { host: o.publishHost, port: o.publishPort };
+}
+/** Base URL for Studio's `/live/api/*` control surface. Publish mode reaches the
+ *  host-published studioHostPort (as studio-state.ts does today); direct mode
+ *  reaches `<id>-studio-1:8000`. Drop-in for the `http://${STUDIO_HOST}:${port}`
+ *  prefix the studio fetchers build. */
+export function studioApiBase(o) {
+    const e = resolveEndpoint({
+        instanceId: o.instanceId,
+        service: "studio",
+        internalPort: STUDIO_INTERNAL_PORT,
+        publishHost: o.publishHost,
+        publishPort: o.publishPort,
+        ...(o.mode !== undefined ? { mode: o.mode } : {}),
+    });
+    return `http://${authority(e)}`;
+}
+/** Base URL for the Norsk media container's HTTP surface (HLS/CMAF pull —
+ *  `/ts/*.m3u8`, `/cmaf/*`). Publish mode dials the host-published media port on
+ *  TEST_HOST (as funke's hls-capture does today); direct mode dials
+ *  `<id>-media-1:8080`. Mirrors studio-state.mediaDirectUrl, generalised for the
+ *  direct-pull capture path. */
+export function mediaHttpBase(o) {
+    const e = resolveEndpoint({
+        instanceId: o.instanceId,
+        service: "media",
+        internalPort: MEDIA_HTTP_INTERNAL_PORT,
+        publishHost: o.publishHost,
+        publishPort: o.publishPort,
+        ...(o.mode !== undefined ? { mode: o.mode } : {}),
+    });
+    return `http://${authority(e)}`;
+}
+/** Caller-mode SRT URL for an output.srt egress listener. Publish mode dials the
+ *  host-published egress port on TEST_HOST (as output-capture.ts does today);
+ *  direct mode dials `<id>-media-1:<internalPort>`. Because remapConfigPorts
+ *  currently sets the internal listener port == the published port, `internalPort`
+ *  and `publishPort` are the same band value today — going direct is what later
+ *  lets that band be dropped entirely. */
+export function srtEgressUrl(o) {
+    const e = resolveEndpoint({
+        instanceId: o.instanceId,
+        service: "media",
+        internalPort: o.internalPort,
+        publishHost: o.publishHost,
+        publishPort: o.publishPort,
+        ...(o.mode !== undefined ? { mode: o.mode } : {}),
+    });
+    return `srt://${authority(e)}?mode=caller`;
+}
+/** Resolve Studio's base URL from EITHER a bare published port (legacy — dials
+ *  `publishHost:port`, exactly today's behaviour) OR a StudioTarget (instanceId-
+ *  aware, so direct mode dials `<id>-studio-1:8000`). The union is the whole
+ *  migration story: every existing `studioHostPort: number` caller — including
+ *  other products' suites — keeps working untouched, and a suite opts a call into
+ *  direct-net simply by passing the target instead of the number. */
+export function studioBaseFrom(studio, publishHost, mode) {
+    if (typeof studio === "number")
+        return `http://${publishHost}:${studio}`;
+    return studioApiBase({
+        instanceId: studio.instanceId,
+        publishHost,
+        publishPort: studio.studioHostPort,
+        ...(mode !== undefined ? { 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
+// 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
+ *  both cgroup v1 (`/docker/<id>`) and v2 (`docker-<id>.scope`) layouts. */
+export function parseOwnContainerId(cgroupText) {
+    const m = cgroupText.match(/[0-9a-f]{64}/);
+    return m ? m[0] : null;
+}
+export function ownContainerId(read = () => readFileSync("/proc/self/cgroup", "utf-8")) {
+    try {
+        return parseOwnContainerId(read());
+    }
+    catch {
+        return null;
+    }
+}
+/** `docker network connect` is not idempotent — a second attach errors. Treat
+ *  the "already attached" variants as success so setup can call this blindly. */
+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 ?? "" };
+};
+/** Idempotently join the test container to norsk-net so `direct` service DNS
+ *  resolves. Returns a verdict rather than throwing: `not-in-container` (nothing
+ *  to attach — publish mode is the only sane choice), `attached`, `already`, or
+ *  `failed` (a real error the caller should surface). */
+export function ensureRunnerOnNetwork(opts = {}) {
+    const network = opts.network ?? DOCKER_NETWORK_NAME;
+    const id = opts.containerId === undefined ? ownContainerId() : opts.containerId;
+    if (!id)
+        return "not-in-container";
+    const run = opts.run ?? defaultRunner;
+    const r = run("docker", ["network", "connect", network, id]);
+    if (r.status === 0)
+        return "attached";
+    if (isAlreadyOnNetworkError(r.stderr))
+        return "already";
+    return "failed";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "exports": {
     "./daemon": {
@@ -26,6 +26,10 @@
     "./studio-load": {
       "types": "./studio-load.d.ts",
       "default": "./studio-load.js"
+    },
+    "./container-net": {
+      "types": "./container-net.d.ts",
+      "default": "./container-net.js"
     }
   },
   "dependencies": {

package/studio-state.d.ts

@@ -1,3 +1,5 @@
+import { type StudioReach, type StudioTarget } from "./container-net.js";
+export type { StudioReach, StudioTarget };
 export interface ComponentSummary {
     componentId: string;
     componentType: string;
@@ -9,8 +11,8 @@ export interface ComponentsResponse {
 }
 export declare function applyTestHost(rawUrl: string): string;
 export declare function mediaDirectUrl(rawUrl: string): string;
-export declare function fetchComponents(studioHostPort: number): Promise<ComponentsResponse | null>;
-export declare function fetchComponentState(studioHostPort: number, componentId: string): Promise<unknown | null>;
+export declare function fetchComponents(studio: StudioReach): Promise<ComponentsResponse | null>;
+export declare function fetchComponentState(studio: StudioReach, componentId: string): Promise<unknown | null>;
 /** SRT-listener state shape — see
  *  ~/src/norsk-studio/workspaces/built-ins/src/input.srt-listener/types.source.yaml:192-235.
  *  Required fields per the YAML schema; harness asserts on the first two. */
@@ -50,12 +52,12 @@ export interface StreamMappingEntry {
     preview_jpeg?: string;
     [k: string]: unknown;
 }
-export declare function fetchStreamMappings(studioHostPort: number, componentId: string): Promise<StreamMappingEntry[] | null>;
-export declare function fetchStreamSources(studioHostPort: number, componentId: string): Promise<unknown | null>;
-export declare function fetchStreamUnmapped(studioHostPort: number, componentId: string): Promise<unknown | null>;
-export declare function fetchStreamFill(studioHostPort: number, componentId: string): Promise<unknown | null>;
+export declare function fetchStreamMappings(studioHostPort: StudioReach, componentId: string): Promise<StreamMappingEntry[] | null>;
+export declare function fetchStreamSources(studioHostPort: StudioReach, componentId: string): Promise<unknown | null>;
+export declare function fetchStreamUnmapped(studioHostPort: StudioReach, componentId: string): Promise<unknown | null>;
+export declare function fetchStreamFill(studioHostPort: StudioReach, componentId: string): Promise<unknown | null>;
 export interface AssertStreamOutputOpts {
-    studioHostPort: number;
+    studioHostPort: StudioReach;
     componentId: string;
     media: "video" | "audio" | "playlist";
     /** Optional — pin the stream's name. For input.srt-listener it is the
@@ -72,7 +74,7 @@ export declare function assertStreamOutput(opts: AssertStreamOutputOpts): Promis
 /** Polls Studio's per-component state for an SRT-listener until at least one
  *  stream is reported as connected with a non-zero connectedAt timestamp. */
 export declare function assertSrtConnected(opts: {
-    studioHostPort: number;
+    studioHostPort: StudioReach;
     componentId: string;
     timeoutMs?: number;
     intervalMs?: number;
@@ -89,7 +91,7 @@ export interface CmafMultiVariantState {
  *  `#EXT-X-MEDIA:TYPE=AUDIO ... URI="<rendition>/norsk.m3u8"` line. The caller
  *  passes the set of expected labels; the body must reference every one. */
 export declare function assertMultivariantHasRenditions(opts: {
-    studioHostPort: number;
+    studioHostPort: StudioReach;
     componentId: string;
     expectedRenditionLabels: readonly string[];
     timeoutMs?: number;
@@ -97,7 +99,7 @@ export declare function assertMultivariantHasRenditions(opts: {
     resolveFetchUrl?: (url: string) => string;
 }): Promise<void>;
 export declare function assertNoUnmapped(opts: {
-    studioHostPort: number;
+    studioHostPort: StudioReach;
     componentId: string;
     timeoutMs?: number;
     intervalMs?: number;

package/studio-state.js

@@ -15,6 +15,10 @@
 // fetchers). Extracted verbatim from the playout copy — the canonical text.
 // Commentary's WHIP-driver tail (RemoteCommentary*, discoverCommentaryWhipUrls,
 // assertCommentaryChannelOccupied) stays local to commentary.
+// 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";
 // 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
@@ -74,8 +78,8 @@ export function mediaDirectUrl(rawUrl) {
     }
     return applyTestHost(rawUrl);
 }
-export async function fetchComponents(studioHostPort) {
-    const r = await fetch(`http://${STUDIO_HOST}:${studioHostPort}/live/api/components`, {
+export async function fetchComponents(studio) {
+    const r = await fetch(`${studioBaseFrom(studio, STUDIO_HOST)}/live/api/components`, {
         signal: AbortSignal.timeout(5000),
     });
     if (r.status === 503)
@@ -84,8 +88,8 @@ export async function fetchComponents(studioHostPort) {
         throw new Error(`GET /live/api/components -> ${r.status}: ${await r.text()}`);
     return (await r.json());
 }
-export async function fetchComponentState(studioHostPort, componentId) {
-    const r = await fetch(`http://${STUDIO_HOST}:${studioHostPort}/live/api/${encodeURIComponent(componentId)}/state`, {
+export async function fetchComponentState(studio, componentId) {
+    const r = await fetch(`${studioBaseFrom(studio, STUDIO_HOST)}/live/api/${encodeURIComponent(componentId)}/state`, {
         signal: AbortSignal.timeout(5000),
     });
     if (r.status === 503 || r.status === 404)
@@ -100,8 +104,8 @@ export function isSrtListenerState(value) {
     const v = value;
     return Array.isArray(v.connectedStreams) && typeof v.connectedAt === "object" && v.connectedAt !== null;
 }
-async function fetchComponentStreamRoute(studioHostPort, componentId, route) {
-    const r = await fetch(`http://${STUDIO_HOST}:${studioHostPort}/live/api/${encodeURIComponent(componentId)}/streams/${route}`, { signal: AbortSignal.timeout(5000) });
+async function fetchComponentStreamRoute(studio, componentId, route) {
+    const r = await fetch(`${studioBaseFrom(studio, STUDIO_HOST)}/live/api/${encodeURIComponent(componentId)}/streams/${route}`, { signal: AbortSignal.timeout(5000) });
     if (r.status === 503 || r.status === 404)
         return null;
     if (!r.ok)