@norskvideo/ctl-sdk 0.1.23 → 0.1.25

package/docker-runner.d.ts

@@ -4,10 +4,17 @@ export declare const CONTAINER_INTERNAL_PORT = 4321;
  *  `norsk-ctl.role` label (proxy, proxy-oauth2, cpu-monitor, product); the
  *  value doubles as the card's component name. */
 export declare const PRODUCT_ROLE_LABEL = "norsk-ctl.role=product";
+/** How to place a product container. The network is the host's call: ctl puts
+ *  the control plane on the same bridge as nginx and every launched instance,
+ *  which is what makes it reachable from a daemon that is itself a container
+ *  (see product-reach.ts). Omitted leaves it on docker's default bridge. */
+export interface ProductRunOpts {
+    network?: string;
+}
 /** argv (sans leading "docker") that launches a product container: detached,
  *  auto-removed, loopback-published to its internal 4321, and role-labelled so
  *  it shows up in the Infrastructure tab. */
-export declare function productRunArgs(image: string, hostPort: number): string[];
+export declare function productRunArgs(image: string, hostPort: number, opts?: ProductRunOpts): string[];
 /** Stable container name for a product, derived from its manifest name, so
  *  `docker ps` shows `norsk-product-studio` instead of a random docker alias.
  *  Mirrors the singleton naming of norsk-proxy / norsk-ctl-cpu-monitor. */
@@ -16,7 +23,7 @@ export declare function productContainerName(productName: string): string;
  *  so there is nothing to refresh; a tag can move under a registration. */
 export declare function isDigestRef(image: string): boolean;
 export declare function dockerPull(image: string): Promise<void>;
-export declare function dockerRun(image: string, hostPort: number): Promise<string>;
+export declare function dockerRun(image: string, hostPort: number, opts?: ProductRunOpts): Promise<string>;
 /** The container's address on its first network (the default bridge for a
  *  product container), or undefined when docker cannot say. */
 export declare function dockerAddress(containerId: string): Promise<string | undefined>;

package/docker-runner.js

@@ -8,13 +8,14 @@ export const PRODUCT_ROLE_LABEL = "norsk-ctl.role=product";
 /** argv (sans leading "docker") that launches a product container: detached,
  *  auto-removed, loopback-published to its internal 4321, and role-labelled so
  *  it shows up in the Infrastructure tab. */
-export function productRunArgs(image, hostPort) {
+export function productRunArgs(image, hostPort, opts = {}) {
     return [
         "run",
         "-d",
         "--rm",
         "--label",
         PRODUCT_ROLE_LABEL,
+        ...(opts.network ? ["--network", opts.network] : []),
         "-p",
         `127.0.0.1:${hostPort}:${CONTAINER_INTERNAL_PORT}`,
         image,
@@ -43,8 +44,8 @@ export async function dockerPull(image) {
         throw new ProductError("DOCKER_PULL_FAILED", `docker pull failed (exit ${exitCode}): ${stderr || "no stderr"}`);
     }
 }
-export async function dockerRun(image, hostPort) {
-    const proc = Bun.spawn(["docker", ...productRunArgs(image, hostPort)], { stdout: "pipe", stderr: "pipe" });
+export async function dockerRun(image, hostPort, opts = {}) {
+    const proc = Bun.spawn(["docker", ...productRunArgs(image, hostPort, opts)], { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;
     const stdout = (await new Response(proc.stdout).text()).trim();
     const stderr = (await new Response(proc.stderr).text()).trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "type": "module",
   "exports": {
     ".": {

package/product-health-monitor.d.ts

@@ -8,14 +8,30 @@ export interface ProductHealthState {
     restartAttempts: number;
     /** Clock value of the most recent restart attempt; gates backoff. */
     lastRestartAt?: number;
+    /** URL the last failing probe dialled. Cleared on a healthy probe. */
+    lastProbeUrl?: string;
+    /** Why the last probe failed — status line or transport error. Cleared on
+     *  a healthy probe. */
+    lastProbeDetail?: string;
+}
+/** What one liveness probe saw. A bare boolean here cost three CI runs that
+ *  reported a product restart-looping with no record of what was dialled or
+ *  what came back, so the URL and the reason travel with the verdict. */
+export interface ProductProbeResult {
+    ok: boolean;
+    /** The address dialled, or "" when the probe declined to dial at all. */
+    url: string;
+    /** Present whenever `ok` is false: the HTTP status, the transport error, or
+     *  the reason no dial was attempted. */
+    detail?: string;
 }
 export interface ProductHealthMonitorOptions {
     /** Products to consider. Non-container products are ignored (externally
      *  owned), so this can safely be the unfiltered `productService.list`. */
     listProducts: () => ProductRegistration[];
-    /** Liveness probe — true means healthy. Injected so tests don't hit the
-     *  network; the daemon wires `probeProductHealth`. */
-    probe: (reg: ProductRegistration) => Promise<boolean>;
+    /** Liveness probe. Injected so tests don't hit the network; the daemon
+     *  wires `probeProductHealth`. */
+    probe: (reg: ProductRegistration) => Promise<ProductProbeResult>;
     /** Recovery action for a product over threshold. Typically
      *  `productService.restart`. Rejection counts as a failed attempt. */
     restart: (name: string) => Promise<void>;
@@ -69,4 +85,4 @@ export declare class ProductHealthMonitor {
  *  (default /healthz) with a short timeout. Any non-2xx, network error, or
  *  timeout reads as unhealthy. Container-only — dev products are externally
  *  owned and never reach here. */
-export declare function probeProductHealth(reg: ProductRegistration, timeoutMs?: number): Promise<boolean>;
+export declare function probeProductHealth(reg: ProductRegistration, timeoutMs?: number): Promise<ProductProbeResult>;

package/product-health-monitor.js

@@ -75,62 +75,83 @@ export class ProductHealthMonitor {
     }
     async checkOne(reg) {
         const prev = this.states.get(reg.name) ?? UNKNOWN;
-        let healthy;
+        let result;
         try {
-            healthy = await this.probe(reg);
+            result = await this.probe(reg);
         }
-        catch {
-            healthy = false;
+        catch (e) {
+            result = { ok: false, url: "", detail: `probe threw: ${e instanceof Error ? e.message : String(e)}` };
         }
-        if (healthy) {
+        if (result.ok) {
             this.set(reg.name, { status: "healthy", consecutiveFailures: 0, restartAttempts: 0 }, prev);
             return;
         }
         const consecutiveFailures = prev.consecutiveFailures + 1;
+        const probed = { lastProbeUrl: result.url, lastProbeDetail: result.detail };
+        // One line per unhealthy episode, not per sweep: enough to diagnose a
+        // restart loop without a warn every interval for a product known bad.
+        if (prev.consecutiveFailures === 0) {
+            logger.warn(`Product '${reg.name}' health probe failed: ${result.url || "not dialled"} — ${result.detail ?? "no detail"}`);
+        }
+        else {
+            logger.debug(`Product '${reg.name}' health probe failed (${consecutiveFailures}): ${result.url || "not dialled"} — ${result.detail ?? "no detail"}`);
+        }
         const belowThreshold = consecutiveFailures < this.failureThreshold;
         const gaveUp = prev.restartAttempts >= this.maxRestarts;
         const backoffElapsed = prev.lastRestartAt === undefined || this.now() - prev.lastRestartAt >= this.restartBackoffMs;
         if (belowThreshold || gaveUp || !backoffElapsed) {
-            this.set(reg.name, { ...prev, status: "unhealthy", consecutiveFailures }, prev);
+            this.set(reg.name, { ...prev, ...probed, status: "unhealthy", consecutiveFailures }, prev);
             return;
         }
         // Threshold reached, attempts left, backoff elapsed: attempt recovery.
         const at = this.now();
         const restartAttempts = prev.restartAttempts + 1;
-        this.set(reg.name, { status: "restarting", consecutiveFailures: 0, restartAttempts, lastRestartAt: at }, prev);
+        this.set(reg.name, { ...probed, status: "restarting", consecutiveFailures: 0, restartAttempts, lastRestartAt: at }, prev);
         try {
             await this.restart(reg.name);
             // Stay "restarting"; the next sweep re-probes to confirm recovery.
         }
         catch (e) {
             logger.warn(`Product '${reg.name}': restart failed — ${e instanceof Error ? e.message : String(e)}`);
-            this.set(reg.name, { status: "unhealthy", consecutiveFailures: 0, restartAttempts, lastRestartAt: at }, prev);
+            this.set(reg.name, { ...probed, status: "unhealthy", consecutiveFailures: 0, restartAttempts, lastRestartAt: at }, prev);
         }
     }
     set(name, next, prev) {
         this.states.set(name, next);
         if (next.status !== prev.status) {
-            logger.info(`Product '${name}' health: ${prev.status} -> ${next.status}`);
+            const why = next.status === "healthy" ? "" : detailSuffix(next);
+            logger.info(`Product '${name}' health: ${prev.status} -> ${next.status}${why}`);
             this.onChange?.(name, next);
         }
     }
 }
+/** Renders the recorded probe failure onto a transition log line, so the CI
+ *  log of a restart loop carries the address and the reason. */
+function detailSuffix(state) {
+    if (state.lastProbeUrl === undefined && state.lastProbeDetail === undefined)
+        return "";
+    return ` (${state.lastProbeUrl || "not dialled"} — ${state.lastProbeDetail ?? "no detail"})`;
+}
 /** Default liveness probe: GET the product's manifest-declared health path
  *  (default /healthz) with a short timeout. Any non-2xx, network error, or
  *  timeout reads as unhealthy. Container-only — dev products are externally
  *  owned and never reach here. */
 export async function probeProductHealth(reg, timeoutMs = 3_000) {
-    if (reg.spec.kind !== "container" || reg.port === undefined)
-        return false;
+    if (reg.spec.kind !== "container") {
+        return { ok: false, url: "", detail: `not a container product (kind '${reg.spec.kind}')` };
+    }
+    if (reg.port === undefined && reg.reachHost === undefined) {
+        return { ok: false, url: "", detail: "registration has no published port and no reachHost" };
+    }
     const path = reg.manifest.api?.healthCheckPath ?? "/healthz";
-    const base = productBaseUrl(reg);
+    const url = `${productBaseUrl(reg)}${path.startsWith("/") ? path : `/${path}`}`;
     try {
-        const r = await fetch(`${base}${path.startsWith("/") ? path : `/${path}`}`, {
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        return r.ok;
+        const r = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        if (r.ok)
+            return { ok: true, url };
+        return { ok: false, url, detail: `HTTP ${r.status} ${r.statusText}`.trim() };
     }
-    catch {
-        return false;
+    catch (e) {
+        return { ok: false, url, detail: e instanceof Error ? `${e.name}: ${e.message}` : String(e) };
     }
 }