@norskvideo/ctl-dev-kit 0.2.38 → 0.2.40

package/conventions/CLAUDE.core.md

@@ -37,6 +37,14 @@
   mounts don't forward host->guest inotify events, so file watchers never fire —
   a failure that looks exactly like a code bug. Unit tests that don't bind-mount
   may keep using `os.tmpdir()`.
+- **Address another container by its unique `<id>-<service>-1`, never a bare
+  service name, unless the caller is on the instance's own network only.** A
+  bare name (`studio`, `media`) resolves on every network the caller is on, and
+  on `norsk-net` it matches every instance's container: a call silently lands on
+  another instance. `media` sits on `<id>_default` only (Docker Desktop UDP
+  replies break on a dual-homed container), so never add `norsk-net` to it or to
+  a sidecar. Full rules: norsk-ctl `docs/product-template-format.md`,
+  "Networking: how services address each other".
 - **Don't pipe test runs to `tail`** — you lose the failure context. Write output
   to a temp file, then tail _that_ file for the results.
 - **Evolve the ctl<->product contract additively.** An older ctl must launch a

package/conventions/integration-testing.md

@@ -19,11 +19,11 @@ socket), with their ports **published on the host**.
 
 Consequence — two address classes the harness must not confuse:
 
-| Reaching…                            | Address                                   |
-| ------------------------------------ | ----------------------------------------- |
-| the daemon, the product backend      | `localhost:<port>` (in-process)           |
-| studio / media host-published ports  | `${NORSK_TEST_HOST}:<port>`               |
-| a launched container by compose name | `<instance>-<service>-1` **on norsk-net** |
+| Reaching…                            | Address                                                                                               |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| the daemon, the product backend      | `localhost:<port>` (in-process)                                                                       |
+| studio / media host-published ports  | `${NORSK_TEST_HOST}:<port>`                                                                           |
+| a launched container by compose name | `<instance>-<service>-1` on its **instance network** (`<instance>_default`); studio also on norsk-net |
 
 `NORSK_TEST_HOST` is `host.docker.internal` in CI and unset (→ `localhost`)
 locally. Set it in the workflow env. The shared `studio-state` fetchers
@@ -43,8 +43,13 @@ runner, one of these must hold:
 
 - `NORSK_TEST_NET=direct` — the preferred answer, and what the canonical
   `integration.yml` / `smoke.yml` / `build-docs.yml` topology step already sets.
-  Instances are reached by compose name on `norsk-net` at the **container** port,
-  so no host publish is involved at all.
+  Instances are reached by compose name at the **container** port, so no host
+  publish is involved at all. Studio is on `norsk-net`; **media is on its
+  instance network `<instance>_default` only** (Docker Desktop delivers published
+  UDP to either IP of a dual-homed container and breaks SRT replies, see
+  norsk-ctl `docs/product-template-format.md`, Networking). The harness's media helpers
+  (`mediaHttpBase`, `srtEgressUrl`, `mediaDirectUrl`) join the runner to that
+  network for you, and `cleanupDaemon` leaves it before deleting the instance.
 - the launch passes `--publish-debug-ports`, restoring the old binding. The
   shared `runProductSmoke` and demo drivers do this for you when the host they
   fetch from is not loopback, and only after probing that the resolved ctl
@@ -147,24 +152,39 @@ reach. Two cases:
   for `NORSK_TEST_HOST`). `assertMultivariantHasRenditions` does this by default.
 - **Proxy-less harness** — the advertised `/instance/<id>/media/...` route is
   served **only by the daemon's nginx proxy**; with no proxy, nothing answers on
-  `:443`. Reach the media container **directly on norsk-net** instead:
-  `mediaDirectUrl(url)` rewrites it to `http://<id>-media-1:8080/<native-path>`
-  (the same bypass `whip-driver` uses; the media route is unauthenticated). Pass
-  it via `assertMultivariantHasRenditions`'s `resolveFetchUrl` hook, and **join
-  the runner to norsk-net** in setup so the compose service name resolves:
-
-  ```ts
-  spawnSync("docker", ["network", "create", "norsk-net"]);          // idempotent
-  spawnSync("docker", ["network", "connect", "norsk-net", hostname()]);
-  ```
+  `:443`. Reach the media container **directly** instead: `mediaDirectUrl(url)`
+  rewrites it to `http://<id>-media-1:8080/<native-path>` (the same bypass
+  `whip-driver` uses; the media route is unauthenticated) and joins the runner to
+  the instance network `<id>_default`, where that name resolves. Pass it via
+  `assertMultivariantHasRenditions`'s `resolveFetchUrl` hook. Anything else that
+  addresses `<id>-media-1` by hand (a sibling container, a browser in the runner)
+  must be on `<id>_default` too: `currentInstanceNetworks().join(id)` for the
+  runner, `docker network connect <id>_default <container>` for a sibling, and
+  leave or remove it before the instance is deleted, or `compose down` cannot
+  remove the network.
 
 ## Capture servers (studio pushes → the runner)
 
-When a test stands up an HLS/SCTE-35 capture server that **studio pushes to**,
-studio (a host sibling on norsk-net) can't reach the runner via the host LAN IP.
-Join norsk-net and hand studio the runner's **norsk-net IP** (`docker inspect`
-self), falling back to the host LAN IP only when `NORSK_TEST_HOST` is unset. See
-`manifest-capture.ts`'s `captureHost()`.
+When a test stands up an HLS/SCTE-35 capture server (or an SRT sink) that
+**media pushes to**, media sits on its instance network only and can't reach a
+containerised runner via the host LAN IP. Hand it the runner's address **on the
+instance network**: `currentInstanceNetworks().addressOn(instanceId)` joins that
+network and returns the runner's IP on it, or `null` when the runner is not in a
+container (or the join failed). The harness ships the primitive, not the policy:
+each product picks its own fallback for the `null` case, usually the address
+media already reaches the host by.
+
+```ts
+import { currentInstanceNetworks } from "@norskvideo/ctl-test-harness/container-net";
+
+function captureHost(instanceId: string): string {
+  // hostLanIp is the product's own off-container fallback.
+  return currentInstanceNetworks().addressOn(instanceId) ?? hostLanIp();
+}
+```
+
+The runner leaves every network it joined during `cleanupDaemon`, before the
+instance is deleted.
 
 ## Build the product image in the integration job
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",

package/publish/product-channel.ts

@@ -16,16 +16,72 @@
  * are not reliable yet: it skips only the guide half of the gate, must give a
  * reason, and the reason travels into the published row, so nobody reads
  * "passed" off an image whose guides never ran.
+ *
+ * Self-contained on purpose: it imports nothing outside node and this package.
+ * Products resolve the dev-kit's siblings from their OWN lockfiles, so a sibling
+ * import here bound the writer to whatever schema version a product happened to
+ * lock -- the first gated publish in every product died on a missing export.
+ * The object's contract is @norskvideo/ctl-product-template-schema's
+ * product-channels; product-channel.test.ts parses this module's output with it.
  */
 import { existsSync, readFileSync } from "node:fs";
-import {
-  type ProductChannelRow,
-  ProductChannelSchema,
-  parseProductChannels,
-  withChannelRow,
-} from "@norskvideo/ctl-product-template-schema/product-channels";
 import { builtImageName } from "../licence/check-template.ts";
 
+const CHANNELS = ["nightly", "rc", "latest"] as const;
+type Channel = (typeof CHANNELS)[number];
+
+export interface ProductChannelRow {
+  image: string;
+  sha: string;
+  publishedAt: string;
+  runtimeImages: string[];
+  gate: { checks: "passed"; guides: "passed" | { skipped: string }; run?: string };
+}
+
+interface ProductChannels {
+  schemaVersion: 1;
+  product: string;
+  imageRef: string;
+  updated: string;
+  channels: Partial<Record<Channel, unknown>>;
+}
+
+/** The current object, checked only as far as the merge needs: other channels'
+ *  rows are carried through untouched, so a newer writer's fields survive. */
+function parseCurrent(text: string): ProductChannels {
+  const raw = JSON.parse(text) as Partial<ProductChannels>;
+  if (raw.schemaVersion !== 1) throw new Error(`channels object has schemaVersion ${raw.schemaVersion}, not 1`);
+  if (typeof raw.product !== "string" || typeof raw.imageRef !== "string") {
+    throw new Error("channels object has no product/imageRef");
+  }
+  if (typeof raw.channels !== "object" || raw.channels === null) throw new Error("channels object has no channels");
+  return raw as ProductChannels;
+}
+
+/** `current` with `channel` set to `row`; every other channel is kept. */
+export function withChannelRow(
+  current: ProductChannels | null,
+  opts: { product: string; imageRef: string; channel: Channel; row: ProductChannelRow; updated: string },
+): ProductChannels {
+  if (current && (current.product !== opts.product || current.imageRef !== opts.imageRef)) {
+    throw new Error(
+      `channels object belongs to ${current.product} (${current.imageRef}), not ${opts.product} (${opts.imageRef})`,
+    );
+  }
+  return {
+    schemaVersion: 1,
+    product: opts.product,
+    imageRef: opts.imageRef,
+    updated: opts.updated,
+    channels: { ...(current?.channels ?? {}), [opts.channel]: opts.row },
+  };
+}
+
+function parseChannel(value: string): Channel {
+  if (!(CHANNELS as readonly string[]).includes(value)) throw new Error(`not a channel: ${value}`);
+  return value as Channel;
+}
+
 export type GuideGate = { run: true } | { run: false; reason: string };
 
 /** Whether the guides gate this product's publish, from its opt-out file. */
@@ -106,20 +162,12 @@ if (import.meta.main) {
     console.log(productForImage(readFileSync(need("template"), "utf8"), need("image")));
   } else if (cmd === "row") {
     const currentText = readIfPresent(flag("current"));
-    let current = null;
-    if (currentText !== undefined) {
-      const parsed = parseProductChannels(JSON.parse(currentText));
-      if (!parsed.ok) {
-        console.error(`product-channel row: the current object does not parse:\n${parsed.error}`);
-        process.exit(1);
-      }
-      current = parsed.value;
-    }
+    const current = currentText === undefined ? null : parseCurrent(currentText);
     const skipped = flag("skipped");
     const merged = withChannelRow(current, {
       product: need("product"),
       imageRef: need("image-ref"),
-      channel: ProductChannelSchema.parse(need("channel")),
+      channel: parseChannel(need("channel")),
       updated: need("published-at"),
       row: gateRow({
         image: need("image"),