@norskvideo/ctl-dev-kit 0.2.38 → 0.2.39

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.39",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",