@norskvideo/ctl-test-harness 0.1.104 → 0.1.106

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/daemon.js CHANGED
@@ -246,7 +246,8 @@ export function daemonSpawnEnv(o) {
246
246
  // No node MoQ relay: the daemon never removes it, so a test daemon would
247
247
  // leave one behind (probe's smoke ran in relay mode on 2026-10-10).
248
248
  // Instances keep their own MoQ listener. A caller that wants the relay
249
- // sets it explicitly, with NORSK_CTL_MOQ_RELAY_CONTAINER and its ports.
249
+ // sets it explicitly, with NORSK_CTL_MOQ_RELAY_CONTAINER and its ports
250
+ // (ProductHarness's `moqRelay` does, and removes it at teardown).
250
251
  NORSK_CTL_MOQ_RELAY_ENABLE: "0",
251
252
  ...inherited,
252
253
  NORSK_CTL_STORE_DIR: o.storeDir,
package/demo/harness.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { type StudioTarget } from "../container-net.js";
2
2
  import type { SourceHandle } from "../source-pump.js";
3
- import { type CliStep, type DemoDeps, type DemoPorts, type DemoRunOptions, type DemoRunResult, DemoSession, type DemoTimeouts, type IngestPortRow } from "./run.js";
3
+ import { type CliStep, type DemoDeps, type DemoPorts, type DemoRunOptions, type DemoRunResult, DemoSession, type DemoTimeouts, type IngestPortRow, type MoqRelayHandle, type MoqRelayOptions } from "./run.js";
4
4
  import type { DemoContext, DemoDaemonPolicy, DemoIngest, DemoMode, DemoReady, DemoSpec, DemoTemplate } from "./spec.js";
5
5
  export interface ProductHarnessOptions {
6
6
  /** The product repo root: dev command cwd, relative inputs, manifest.seed.json. */
@@ -39,6 +39,10 @@ export interface ProductHarnessOptions {
39
39
  * cancelled run, when teardown never ran. Default `$NORSK_LAUNCHED_MANIFEST`;
40
40
  * unset (local dev) writes nothing. */
41
41
  launchedManifest?: string;
42
+ /** Private daemon: give it a node MoQ relay of its own (the test default is
43
+ * none), named per run, on free ports, removed with its certificate volume
44
+ * at teardown. `auth: "required"` sets the daemon's moqRelayAuth. */
45
+ moqRelay?: MoqRelayOptions;
42
46
  }
43
47
  export interface LaunchOverrides {
44
48
  /** Default `demo-<slug>`. */
@@ -87,6 +91,8 @@ export declare class ProductHarness {
87
91
  /** Every CLI step this fixture ran, as a reader would type it, with its output. */
88
92
  get transcript(): readonly CliStep[];
89
93
  get ports(): DemoPorts;
94
+ /** The private daemon's own relay, once setup() has run with `moqRelay`. */
95
+ get moqRelay(): MoqRelayHandle | undefined;
90
96
  get storeDir(): string;
91
97
  get mode(): DemoMode;
92
98
  get policy(): DemoDaemonPolicy;
package/demo/harness.js CHANGED
@@ -62,6 +62,7 @@ export class ProductHarness {
62
62
  ...(opts.daemonEnv !== undefined ? { daemonEnv: opts.daemonEnv } : {}),
63
63
  ...(opts.extraContainers !== undefined ? { extraContainers: opts.extraContainers } : {}),
64
64
  ...(opts.ephemeralPorts !== undefined ? { ephemeralPorts: opts.ephemeralPorts } : {}),
65
+ ...(opts.moqRelay !== undefined ? { moqRelay: opts.moqRelay } : {}),
65
66
  });
66
67
  }
67
68
  /** Every CLI step this fixture ran, as a reader would type it, with its output. */
@@ -71,6 +72,10 @@ export class ProductHarness {
71
72
  get ports() {
72
73
  return this.session.ports;
73
74
  }
75
+ /** The private daemon's own relay, once setup() has run with `moqRelay`. */
76
+ get moqRelay() {
77
+ return this.session.moqRelay;
78
+ }
74
79
  get storeDir() {
75
80
  return this.session.storeDir;
76
81
  }
package/demo/index.d.ts CHANGED
@@ -7,7 +7,7 @@ export type { LaunchedInstance, LaunchOverrides, ProductHarnessOptions } from ".
7
7
  export { ProductHarness, runDemo } from "./harness.js";
8
8
  export type { DemoPane, DemoPaneOptions, DemoUi, DevLoopPaneOptions, PaneLayout, StandaloneDirs } from "./panes.js";
9
9
  export { DEV_LOOP_SOURCES, DEV_LOOP_STAMP, demoPaneList, devLoopPaneList, launchLayout, paneArgv, paneCommandLine, paneShellLine, renderLayout, shellQuote, standaloneDirs, } from "./panes.js";
10
- export type { CliResult, CliStep, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateKind, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
10
+ export type { CliResult, CliStep, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateKind, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, MoqRelayHandle, MoqRelayOptions, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
11
11
  export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runExportCheck, } from "./run.js";
12
12
  export type { DemoContext, DemoDaemonPolicy, DemoExtra, DemoIngest, DemoLaunchContext, DemoMode, DemoOpen, DemoPortPolicy, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
13
13
  export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";
package/demo/run.d.ts CHANGED
@@ -58,6 +58,9 @@ export interface DemoDeps {
58
58
  /** Does the resolved ctl run its daemon and proxy on system-assigned ports?
59
59
  * Optional so an existing custom-deps consumer keeps working; absent = no. */
60
60
  supportsEphemeralPorts?(): Promise<boolean>;
61
+ /** A host port free for TCP and UDP that is not in `taken` (free-port.ts).
62
+ * Optional so an existing custom-deps consumer keeps working; absent = probe. */
63
+ freePort?(taken: ReadonlySet<number>): Promise<number>;
61
64
  /** Does a daemon answer /api/ready on this port? (A stale state file otherwise.) */
62
65
  daemonAnswers(port: number): Promise<boolean>;
63
66
  cli(storeDir: string, argv: string[]): Promise<CliResult>;
@@ -206,6 +209,27 @@ export interface CliStep {
206
209
  stderr: string;
207
210
  exitCode: number;
208
211
  }
212
+ /** Private daemon: run the node MoQ relay, as a production node does, instead
213
+ * of the test default of none. */
214
+ export interface MoqRelayOptions {
215
+ /** The daemon's `moqRelayAuth` setting. Default off. */
216
+ auth?: "off" | "required";
217
+ }
218
+ /** The relay a private daemon was given: what a test reads its evidence from
219
+ * (`<statusUrl>/relay/info`, `docker logs <container>`). */
220
+ export interface MoqRelayHandle {
221
+ auth: "off" | "required";
222
+ container: string;
223
+ certVolume: string;
224
+ /** Browsers' WebTransport port (UDP) and the relay's /fingerprint (TCP). */
225
+ port: number;
226
+ /** Engines publish into the relay on this one. */
227
+ quicPort: number;
228
+ statusPort: number;
229
+ /** The relay's operator surface: the host's loopback, or the relay by name
230
+ * on norsk-net in direct reach. */
231
+ statusUrl: string;
232
+ }
209
233
  export interface SessionOptions {
210
234
  mode: DemoMode;
211
235
  daemon: DemoDaemonPolicy;
@@ -230,6 +254,8 @@ export interface SessionOptions {
230
254
  * port from this session: one holding its own copy of the band would be
231
255
  * left pointing at nothing. */
232
256
  ephemeralPorts?: boolean;
257
+ /** Private: the daemon's own node MoQ relay. */
258
+ moqRelay?: MoqRelayOptions;
233
259
  }
234
260
  /** The host a demo's daemon-port URLs name.
235
261
  *
@@ -309,6 +335,9 @@ export declare class DemoSession {
309
335
  private readonly proxyScheme;
310
336
  private readonly proxyHost;
311
337
  private readonly ephemeralPorts;
338
+ private readonly moqRelayOptions;
339
+ /** Set once attachDaemon has given the private daemon its relay. */
340
+ moqRelay: MoqRelayHandle | undefined;
312
341
  daemon: DaemonProcess | null;
313
342
  dev: ProcessHandle | null;
314
343
  extras: string[];
@@ -338,6 +367,11 @@ export declare class DemoSession {
338
367
  /** Private: init a virgin store and start a daemon on the band. Reuse: the
339
368
  * developer's daemon must already answer. */
340
369
  attachDaemon(): Promise<void>;
370
+ /** Name the relay for this run, find it three free ports, and store the
371
+ * auth setting the daemon reads at boot. Returns the daemon's relay env. */
372
+ private prepareMoqRelay;
373
+ /** The daemon never removes its relay, on shutdown or otherwise. */
374
+ private removeMoqRelay;
341
375
  startDev(): Promise<void>;
342
376
  /** The reuse policy's mandatory sequence: `product add` refuses an existing
343
377
  * name and stored templates are immutable, so the instance, every template
package/demo/run.js CHANGED
@@ -25,6 +25,7 @@
25
25
  // fakes; defaultDemoDeps wires the real harness. Argv, not Command: this
26
26
  // package does not depend on @norskvideo/ctl-commands (smoke.ts, daemon.ts).
27
27
  import { spawn, spawnSync } from "node:child_process";
28
+ import { createHash } from "node:crypto";
28
29
  import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync, } from "node:fs";
29
30
  import { homedir } from "node:os";
30
31
  import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -32,6 +33,7 @@ import { parseManifestSeed, repoOf } from "@norskvideo/ctl-sdk/manifest-seed";
32
33
  import { preserveInstanceContainerLogs } from "../container-logs.js";
33
34
  import { currentInstanceNetworks, DOCKER_NETWORK_NAME, ensureRunnerOnNetwork, instanceNetworkName, isAlreadyOnNetworkError, netReachMode, } from "../container-net.js";
34
35
  import { cleanupDaemon, ctlSupportsEphemeralPorts, PROXY_PORT_FILE, requireLicenseFile, runCli, startDaemon, } from "../daemon.js";
36
+ import { freeHostPort } from "../free-port.js";
35
37
  import { hashSlot } from "../harness-config.js";
36
38
  import { ctlSupportsNoPublish, ctlSupportsPublishDebugPorts, runnerContainerUser } from "../launch.js";
37
39
  import { pollUntil } from "../poll.js";
@@ -253,6 +255,7 @@ export function defaultDemoDeps(cwd) {
253
255
  },
254
256
  fileExists: (path) => existsSync(path),
255
257
  startDaemon,
258
+ freePort: (taken) => freeHostPort({ taken }),
256
259
  supportsEphemeralPorts: ctlSupportsEphemeralPorts,
257
260
  daemonAnswers: async (port) => {
258
261
  try {
@@ -330,6 +333,15 @@ export function defaultDemoDeps(cwd) {
330
333
  log: (line) => console.log(`[demo] ${line}`),
331
334
  };
332
335
  }
336
+ /** ctl's MOQ_RELAY_STATUS_INTERNAL_PORT: the relay's status surface inside its container. */
337
+ const MOQ_RELAY_STATUS_INTERNAL_PORT = 6791;
338
+ /** Where the store's config is: what `config set` with no daemon writes. */
339
+ const CONFIG_FILE = "config.yaml";
340
+ /** `config set` aimed at a port nothing listens on, so it takes its no-daemon
341
+ * path and writes the store's config.yaml before the daemon reads it at boot.
342
+ * The daemon port is no good: it is 0 until assigned, and on the band a
343
+ * previous run's daemon may still answer there. */
344
+ const NO_DAEMON_PORT = "1";
333
345
  /** The host a demo's daemon-port URLs name.
334
346
  *
335
347
  * NORSK_TEST_HOST is a STUDIO-port setting: on a docker-outside-of-docker
@@ -416,6 +428,9 @@ export class DemoSession {
416
428
  proxyScheme;
417
429
  proxyHost;
418
430
  ephemeralPorts;
431
+ moqRelayOptions;
432
+ /** Set once attachDaemon has given the private daemon its relay. */
433
+ moqRelay;
419
434
  daemon = null;
420
435
  dev = null;
421
436
  extras = [];
@@ -440,6 +455,10 @@ export class DemoSession {
440
455
  this.proxyHost = proxyHost;
441
456
  this.band = demoPorts(slug);
442
457
  this.ephemeralPorts = opts.ephemeralPorts === true;
458
+ if (opts.moqRelay && opts.daemon === "reuse") {
459
+ throw new Error("moqRelay needs a private daemon: the developer's daemon keeps the relay and the moqRelayAuth it already has");
460
+ }
461
+ this.moqRelayOptions = opts.moqRelay;
443
462
  if (opts.daemon === "reuse") {
444
463
  const daemonPort = opts.daemonPort ?? (Number(process.env.NORSK_CTL_PORT) || DEFAULT_DAEMON_PORT);
445
464
  this.storeDir = deps.realStoreDir();
@@ -539,10 +558,11 @@ export class DemoSession {
539
558
  "--no-start-server",
540
559
  ...(this.publicHost ? ["--public-host", this.publicHost] : []),
541
560
  ]);
561
+ const relayEnv = this.moqRelayOptions ? await this.prepareMoqRelay(this.moqRelayOptions) : {};
542
562
  const started = this.deps.startDaemon(this.storeDir, {
543
563
  port: this.ports.daemonPort,
544
564
  seedConfig: false,
545
- env: { ...this.daemonEnv },
565
+ env: { ...this.daemonEnv, ...relayEnv },
546
566
  });
547
567
  this.daemon = started.daemon;
548
568
  await started.ready;
@@ -559,6 +579,70 @@ export class DemoSession {
559
579
  throw new Error("could not join the runner to norsk-net for direct reach");
560
580
  }
561
581
  }
582
+ /** Name the relay for this run, find it three free ports, and store the
583
+ * auth setting the daemon reads at boot. Returns the daemon's relay env. */
584
+ async prepareMoqRelay(opts) {
585
+ const auth = opts.auth ?? "off";
586
+ if (auth !== "off") {
587
+ const argv = ["config", "set", "--moq-relay-auth", auth];
588
+ const r = await this.deps.cli(this.storeDir, ["--port", NO_DAEMON_PORT, ...argv]);
589
+ this.transcript.push({ argv, stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode });
590
+ if (r.exitCode !== 0) {
591
+ throw new Error(`norsk-ctl ${argv.join(" ")} failed (exit ${r.exitCode}):\n${r.stderr || r.stdout}`);
592
+ }
593
+ const config = this.deps.readFile(join(this.storeDir, CONFIG_FILE)) ?? "";
594
+ if (!new RegExp(`^moqRelayAuth:\\s*["']?${auth}["']?\\s*$`, "m").test(config)) {
595
+ throw new Error(`norsk-ctl ${argv.join(" ")} left no moqRelayAuth: ${auth} in ${join(this.storeDir, CONFIG_FILE)} — the resolved ctl predates the moqRelayAuth setting`);
596
+ }
597
+ }
598
+ const freePort = this.deps.freePort ?? ((taken) => freeHostPort({ taken }));
599
+ const taken = new Set();
600
+ const next = async () => {
601
+ const p = await freePort(taken);
602
+ taken.add(p);
603
+ return p;
604
+ };
605
+ const port = await next();
606
+ const quicPort = await next();
607
+ const statusPort = await next();
608
+ // Per run, not just per slug: the store dir is, and a relay a cancelled
609
+ // run left behind must not be adopted by the next one.
610
+ const container = `norsk-moq-relay-${this.slug}-${createHash("sha256").update(this.storeDir).digest("hex").slice(0, 8)}`;
611
+ this.moqRelay = {
612
+ auth,
613
+ container,
614
+ // ctl's nodeMoqRelayDaemonSpec: a named relay's volume is `<name>-certs`.
615
+ certVolume: `${container}-certs`,
616
+ port,
617
+ quicPort,
618
+ statusPort,
619
+ // Published on the host's loopback only, which a runner container
620
+ // cannot reach; on norsk-net with it, it reaches the relay by name.
621
+ statusUrl: netReachMode() === "direct"
622
+ ? `http://${container}:${MOQ_RELAY_STATUS_INTERNAL_PORT}`
623
+ : `http://127.0.0.1:${statusPort}`,
624
+ };
625
+ this.deps.log(`MoQ relay ${container}: :${port}, quic :${quicPort}, status :${statusPort}, auth ${auth}`);
626
+ return {
627
+ NORSK_CTL_MOQ_RELAY_ENABLE: "1",
628
+ NORSK_CTL_MOQ_RELAY_CONTAINER: container,
629
+ NORSK_CTL_MOQ_RELAY_PORT: String(port),
630
+ NORSK_CTL_MOQ_RELAY_QUIC_PORT: String(quicPort),
631
+ NORSK_CTL_MOQ_RELAY_STATUS_PORT: String(statusPort),
632
+ };
633
+ }
634
+ /** The daemon never removes its relay, on shutdown or otherwise. */
635
+ removeMoqRelay() {
636
+ const relay = this.moqRelay;
637
+ if (!relay)
638
+ return;
639
+ const rm = this.deps.docker(["rm", "-f", relay.container]);
640
+ if (rm.exitCode !== 0)
641
+ this.deps.log(`docker rm ${relay.container}: ${rm.stderr.trim()}`);
642
+ const vol = this.deps.docker(["volume", "rm", "-f", relay.certVolume]);
643
+ if (vol.exitCode !== 0)
644
+ this.deps.log(`docker volume rm ${relay.certVolume}: ${vol.stderr.trim()}`);
645
+ }
562
646
  async startDev() {
563
647
  this.dev = this.deps.startProcess(this.spec.dev.command, {
564
648
  cwd: this.cwd,
@@ -799,6 +883,7 @@ export class DemoSession {
799
883
  this.deps.log(`cleanup could not remove the store itself (${e instanceof Error ? e.message : String(e)}); nuking as root`);
800
884
  reportForeignOwners(this.storeDir, (l) => this.deps.log(l));
801
885
  }
886
+ this.removeMoqRelay();
802
887
  this.stopExtras();
803
888
  this.dev?.kill();
804
889
  this.deps.nukeStoreAsRoot(this.storeDir);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@norskvideo/ctl-test-harness",
3
- "version": "0.1.104",
3
+ "version": "0.1.106",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {