@norskvideo/ctl-test-harness 0.1.74 → 0.1.76

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

@@ -18,7 +18,9 @@ export declare const authority: (e: Endpoint) => string;
 export declare function productServiceHost(instanceId: string, service: string): string;
 export interface ResolveOpts {
     instanceId: string;
-    service: "studio" | "media";
+    /** A compose service name: "studio" and "media" for a Studio product, or a
+     *  direct-SDK product's own control service (the smoke `surface`). */
+    service: string;
     /** Port the listener binds INSIDE the container (studio 8000, media SRT its
      *  own configured port). Used in `direct` mode. */
     internalPort: number;
@@ -116,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
@@ -137,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.74",
+  "version": "0.1.76",
   "type": "module",
   "exports": {
     ".": {

package/smoke.d.ts

@@ -33,6 +33,25 @@ export interface SmokeContext {
         output?: "json" | "yaml";
     }): Promise<CliResult>;
     fetchStudio(path: string): Promise<Response>;
+    /** The spec's `surface` (Studio's by default), reached the same two ways:
+     *  the banded published port, or `<id>-<service>-1:<internalPort>` direct. */
+    surfaceUrl(path: string): string;
+    /** GET surfaceUrl(path) through the injected reader -- for observations. A
+     *  prepare step that acts (POST, DELETE) uses fetch(ctx.surfaceUrl(...)). */
+    fetchSurface(path: string): Promise<Response>;
+}
+/** The instance service whose HTTP surface the journey publishes and reaches.
+ *  Studio's by default; a direct-SDK product (no Studio, e.g. norsk-relay)
+ *  names its own control API. */
+export interface SmokeSurface {
+    service: string;
+    internalPort: number;
+    /** The host port the TEMPLATE publishes the surface on (a `--param` the spec
+     *  sets). ctl emits `--host-ports` only for Studio and media -- one naming any
+     *  other service is persisted but never wired -- so a direct-SDK product's
+     *  surface is published by its own compose. Given, no `--host-ports` is
+     *  passed and publish mode dials this port. */
+    hostPort?: number;
 }
 /** Set on any observation that holds with or without a source — a resilient
  *  switch that keeps a ladder fed from a slate, a control surface that is up
@@ -85,6 +104,14 @@ export interface SmokeSpec {
         licenseFile?: string;
     };
     template: SmokeTemplate;
+    /** Default { service: "studio", internalPort: 8000 }. Published on the banded
+     *  studioHostPort; STUDIO_HOST_PORT is passed instead only for Studio's. */
+    surface?: SmokeSurface;
+    /** Runs once the instance reports running, before the not-yet phase: what a
+     *  product needs in place before its sources can be accepted (the relay
+     *  refuses SRT for a stream nobody declared). Not an observation -- it may
+     *  act, and a throw fails the journey. */
+    prepare?(ctx: SmokeContext): Promise<void>;
     /** 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[];
@@ -206,5 +233,15 @@ export declare function assertManifestRoutesServed(opts: {
 export declare function sourceDependent(o: SmokeObservation): boolean;
 /** One sample of an observation — the predicate the three phases poll. */
 export declare function observationSatisfied(o: SmokeObservation, ctx: SmokeContext, readers: SmokeReaders): Promise<boolean>;
+/** A direct-SDK product's licence identity -- the sdk-client cert and key it
+ *  answers the engine's V2 handshake with, base64 -- from what smoke.yml
+ *  exports (repo secrets NORSK_SDK_CLIENT_CERT_B64 / NORSK_SDK_CLIENT_KEY_B64).
+ *  Undefined when neither is set (a Studio product, or a local run without
+ *  one); half a pair is a misconfigured repo, so it throws rather than
+ *  launching an instance that restarts on "License handshake required". */
+export declare function sdkClientIdentityFromEnv(env?: Record<string, string | undefined>): {
+    certB64: string;
+    keyB64: string;
+} | undefined;
 export declare function runProductSmoke(slug: string, spec: SmokeSpec, deps?: SmokeDeps): Promise<void>;
 export {};

package/smoke.js

@@ -20,7 +20,7 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { dumpInstanceContainerLogs, preserveEngineLogs, preserveInstanceContainerLogs } from "./container-logs.js";
-import { ensureRunnerOnNetwork, netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom, } from "./container-net.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 { hashSlot } from "./harness-config.js";
 import { ctlSupportsNoPublish, ctlSupportsPublishDebugPorts, runnerContainerUser } from "./launch.js";
@@ -191,6 +191,22 @@ function parseJson(r, what) {
         throw new Error(`${what}: not JSON: ${r.stdout.slice(0, 200)}`);
     }
 }
+/** A direct-SDK product's licence identity -- the sdk-client cert and key it
+ *  answers the engine's V2 handshake with, base64 -- from what smoke.yml
+ *  exports (repo secrets NORSK_SDK_CLIENT_CERT_B64 / NORSK_SDK_CLIENT_KEY_B64).
+ *  Undefined when neither is set (a Studio product, or a local run without
+ *  one); half a pair is a misconfigured repo, so it throws rather than
+ *  launching an instance that restarts on "License handshake required". */
+export function sdkClientIdentityFromEnv(env = process.env) {
+    const certB64 = env.NORSK_SDK_CLIENT_CERT_B64 ?? "";
+    const keyB64 = env.NORSK_SDK_CLIENT_KEY_B64 ?? "";
+    if (!certB64 && !keyB64)
+        return undefined;
+    if (!certB64 || !keyB64) {
+        throw new Error(`NORSK_SDK_CLIENT_${certB64 ? "KEY" : "CERT"}_B64 is empty but its pair is set -- set both repo secrets or neither`);
+    }
+    return { certB64, keyB64 };
+}
 export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
     const ports = smokePorts(slug, spec.ports);
     const storeDir = deps.storeDir(slug);
@@ -202,6 +218,8 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
     };
     const mode = netReachMode();
     const studio = { instanceId, studioHostPort: ports.studioHostPort };
+    const surface = spec.surface ?? { service: "studio", internalPort: STUDIO_INTERNAL_PORT };
+    const studioSurface = surface.service === "studio" && surface.internalPort === STUDIO_INTERNAL_PORT;
     const cli = async (argv, opts = {}) => {
         const full = ["--port", String(ports.daemonPort), ...argv, ...(opts.output ? ["-o", opts.output] : [])];
         return deps.cli(storeDir, full);
@@ -223,6 +241,18 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         studio,
         cli,
         fetchStudio: (path) => deps.readers.fetch(`${studioBaseFrom(studio, process.env.NORSK_TEST_HOST ?? "localhost", mode)}${path}`),
+        surfaceUrl: (path) => {
+            const e = resolveEndpoint({
+                instanceId,
+                service: surface.service,
+                internalPort: surface.internalPort,
+                publishHost: process.env.NORSK_TEST_HOST ?? "localhost",
+                publishPort: surface.hostPort ?? ports.studioHostPort,
+                mode,
+            });
+            return `http://${authority(e)}${path}`;
+        },
+        fetchSurface: (path) => deps.readers.fetch(ctx.surfaceUrl(path)),
     };
     let daemon = null;
     let launched = false;
@@ -335,10 +365,12 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         const params = [`INSTANCE_NAME=${instanceId}`, ...(spec.params ?? [])];
         const launchArgv = ["instance", "launch-template", instanceId, "--template", templateName];
         const internalOnly = mode === "direct" && (await deps.supportsNoPublish());
-        if (declared.has(STUDIO_HOST_PORT_PARAM))
+        if (studioSurface && declared.has(STUDIO_HOST_PORT_PARAM)) {
             params.push(`${STUDIO_HOST_PORT_PARAM}=${ports.studioHostPort}`);
-        else if (!internalOnly)
-            launchArgv.push("--host-ports", `${ports.studioHostPort}:${STUDIO_INTERNAL_PORT}@studio`);
+        }
+        else if (!internalOnly && surface.hostPort === undefined) {
+            launchArgv.push("--host-ports", `${ports.studioHostPort}:${surface.internalPort}@${surface.service}`);
+        }
         for (const p of params)
             launchArgv.push("--param", p);
         if (spec.hardware)
@@ -376,6 +408,10 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
             const inst = parseJson(r, "instance list").instances?.find((i) => i.id === instanceId);
             return inst?.status === "running" || inst?.status === "healthy";
         }, { timeoutMs: timeouts.healthyMs, intervalMs: 1000, label: `instance ${instanceId} never reported running` });
+        if (spec.prepare) {
+            await spec.prepare(ctx);
+            deps.log(`${slug}: prepare done`);
+        }
         // Phases.
         const vacuous = spec.sources.length === 0;
         if (vacuous) {

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}`;
         }
     }