@norskvideo/ctl-test-harness 0.1.103 → 0.1.105

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,26 @@ 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 on the host's loopback. */
230
+ statusUrl: string;
231
+ }
209
232
  export interface SessionOptions {
210
233
  mode: DemoMode;
211
234
  daemon: DemoDaemonPolicy;
@@ -230,6 +253,8 @@ export interface SessionOptions {
230
253
  * port from this session: one holding its own copy of the band would be
231
254
  * left pointing at nothing. */
232
255
  ephemeralPorts?: boolean;
256
+ /** Private: the daemon's own node MoQ relay. */
257
+ moqRelay?: MoqRelayOptions;
233
258
  }
234
259
  /** The host a demo's daemon-port URLs name.
235
260
  *
@@ -309,6 +334,9 @@ export declare class DemoSession {
309
334
  private readonly proxyScheme;
310
335
  private readonly proxyHost;
311
336
  private readonly ephemeralPorts;
337
+ private readonly moqRelayOptions;
338
+ /** Set once attachDaemon has given the private daemon its relay. */
339
+ moqRelay: MoqRelayHandle | undefined;
312
340
  daemon: DaemonProcess | null;
313
341
  dev: ProcessHandle | null;
314
342
  extras: string[];
@@ -338,6 +366,11 @@ export declare class DemoSession {
338
366
  /** Private: init a virgin store and start a daemon on the band. Reuse: the
339
367
  * developer's daemon must already answer. */
340
368
  attachDaemon(): Promise<void>;
369
+ /** Name the relay for this run, find it three free ports, and store the
370
+ * auth setting the daemon reads at boot. Returns the daemon's relay env. */
371
+ private prepareMoqRelay;
372
+ /** The daemon never removes its relay, on shutdown or otherwise. */
373
+ private removeMoqRelay;
341
374
  startDev(): Promise<void>;
342
375
  /** The reuse policy's mandatory sequence: `product add` refuses an existing
343
376
  * 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,13 @@ export function defaultDemoDeps(cwd) {
330
333
  log: (line) => console.log(`[demo] ${line}`),
331
334
  };
332
335
  }
336
+ /** Where the store's config is: what `config set` with no daemon writes. */
337
+ const CONFIG_FILE = "config.yaml";
338
+ /** `config set` aimed at a port nothing listens on, so it takes its no-daemon
339
+ * path and writes the store's config.yaml before the daemon reads it at boot.
340
+ * The daemon port is no good: it is 0 until assigned, and on the band a
341
+ * previous run's daemon may still answer there. */
342
+ const NO_DAEMON_PORT = "1";
333
343
  /** The host a demo's daemon-port URLs name.
334
344
  *
335
345
  * NORSK_TEST_HOST is a STUDIO-port setting: on a docker-outside-of-docker
@@ -416,6 +426,9 @@ export class DemoSession {
416
426
  proxyScheme;
417
427
  proxyHost;
418
428
  ephemeralPorts;
429
+ moqRelayOptions;
430
+ /** Set once attachDaemon has given the private daemon its relay. */
431
+ moqRelay;
419
432
  daemon = null;
420
433
  dev = null;
421
434
  extras = [];
@@ -440,6 +453,10 @@ export class DemoSession {
440
453
  this.proxyHost = proxyHost;
441
454
  this.band = demoPorts(slug);
442
455
  this.ephemeralPorts = opts.ephemeralPorts === true;
456
+ if (opts.moqRelay && opts.daemon === "reuse") {
457
+ throw new Error("moqRelay needs a private daemon: the developer's daemon keeps the relay and the moqRelayAuth it already has");
458
+ }
459
+ this.moqRelayOptions = opts.moqRelay;
443
460
  if (opts.daemon === "reuse") {
444
461
  const daemonPort = opts.daemonPort ?? (Number(process.env.NORSK_CTL_PORT) || DEFAULT_DAEMON_PORT);
445
462
  this.storeDir = deps.realStoreDir();
@@ -539,10 +556,11 @@ export class DemoSession {
539
556
  "--no-start-server",
540
557
  ...(this.publicHost ? ["--public-host", this.publicHost] : []),
541
558
  ]);
559
+ const relayEnv = this.moqRelayOptions ? await this.prepareMoqRelay(this.moqRelayOptions) : {};
542
560
  const started = this.deps.startDaemon(this.storeDir, {
543
561
  port: this.ports.daemonPort,
544
562
  seedConfig: false,
545
- env: { ...this.daemonEnv },
563
+ env: { ...this.daemonEnv, ...relayEnv },
546
564
  });
547
565
  this.daemon = started.daemon;
548
566
  await started.ready;
@@ -559,6 +577,66 @@ export class DemoSession {
559
577
  throw new Error("could not join the runner to norsk-net for direct reach");
560
578
  }
561
579
  }
580
+ /** Name the relay for this run, find it three free ports, and store the
581
+ * auth setting the daemon reads at boot. Returns the daemon's relay env. */
582
+ async prepareMoqRelay(opts) {
583
+ const auth = opts.auth ?? "off";
584
+ if (auth !== "off") {
585
+ const argv = ["config", "set", "--moq-relay-auth", auth];
586
+ const r = await this.deps.cli(this.storeDir, ["--port", NO_DAEMON_PORT, ...argv]);
587
+ this.transcript.push({ argv, stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode });
588
+ if (r.exitCode !== 0) {
589
+ throw new Error(`norsk-ctl ${argv.join(" ")} failed (exit ${r.exitCode}):\n${r.stderr || r.stdout}`);
590
+ }
591
+ const config = this.deps.readFile(join(this.storeDir, CONFIG_FILE)) ?? "";
592
+ if (!new RegExp(`^moqRelayAuth:\\s*["']?${auth}["']?\\s*$`, "m").test(config)) {
593
+ throw new Error(`norsk-ctl ${argv.join(" ")} left no moqRelayAuth: ${auth} in ${join(this.storeDir, CONFIG_FILE)} — the resolved ctl predates the moqRelayAuth setting`);
594
+ }
595
+ }
596
+ const freePort = this.deps.freePort ?? ((taken) => freeHostPort({ taken }));
597
+ const taken = new Set();
598
+ const next = async () => {
599
+ const p = await freePort(taken);
600
+ taken.add(p);
601
+ return p;
602
+ };
603
+ const port = await next();
604
+ const quicPort = await next();
605
+ const statusPort = await next();
606
+ // Per run, not just per slug: the store dir is, and a relay a cancelled
607
+ // run left behind must not be adopted by the next one.
608
+ const container = `norsk-moq-relay-${this.slug}-${createHash("sha256").update(this.storeDir).digest("hex").slice(0, 8)}`;
609
+ this.moqRelay = {
610
+ auth,
611
+ container,
612
+ // ctl's nodeMoqRelayDaemonSpec: a named relay's volume is `<name>-certs`.
613
+ certVolume: `${container}-certs`,
614
+ port,
615
+ quicPort,
616
+ statusPort,
617
+ statusUrl: `http://127.0.0.1:${statusPort}`,
618
+ };
619
+ this.deps.log(`MoQ relay ${container}: :${port}, quic :${quicPort}, status :${statusPort}, auth ${auth}`);
620
+ return {
621
+ NORSK_CTL_MOQ_RELAY_ENABLE: "1",
622
+ NORSK_CTL_MOQ_RELAY_CONTAINER: container,
623
+ NORSK_CTL_MOQ_RELAY_PORT: String(port),
624
+ NORSK_CTL_MOQ_RELAY_QUIC_PORT: String(quicPort),
625
+ NORSK_CTL_MOQ_RELAY_STATUS_PORT: String(statusPort),
626
+ };
627
+ }
628
+ /** The daemon never removes its relay, on shutdown or otherwise. */
629
+ removeMoqRelay() {
630
+ const relay = this.moqRelay;
631
+ if (!relay)
632
+ return;
633
+ const rm = this.deps.docker(["rm", "-f", relay.container]);
634
+ if (rm.exitCode !== 0)
635
+ this.deps.log(`docker rm ${relay.container}: ${rm.stderr.trim()}`);
636
+ const vol = this.deps.docker(["volume", "rm", "-f", relay.certVolume]);
637
+ if (vol.exitCode !== 0)
638
+ this.deps.log(`docker volume rm ${relay.certVolume}: ${vol.stderr.trim()}`);
639
+ }
562
640
  async startDev() {
563
641
  this.dev = this.deps.startProcess(this.spec.dev.command, {
564
642
  cwd: this.cwd,
@@ -799,6 +877,7 @@ export class DemoSession {
799
877
  this.deps.log(`cleanup could not remove the store itself (${e instanceof Error ? e.message : String(e)}); nuking as root`);
800
878
  reportForeignOwners(this.storeDir, (l) => this.deps.log(l));
801
879
  }
880
+ this.removeMoqRelay();
802
881
  this.stopExtras();
803
882
  this.dev?.kill();
804
883
  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.103",
3
+ "version": "0.1.105",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -107,7 +107,7 @@
107
107
  "@types/node": "^22.10.0",
108
108
  "@norskvideo/norsk-studio": "1.30.0-2026-10-20-6fb182ff",
109
109
  "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-20-6fb182ff",
110
- "@norskvideo/norsk-sdk": "1.3.1-2026-10-21-c97178c2"
110
+ "@norskvideo/norsk-sdk": "1.3.1-2026-10-22-aeac91a4"
111
111
  },
112
112
  "peerDependenciesMeta": {
113
113
  "@norskvideo/norsk-studio": {