@norskvideo/ctl-sdk 0.1.20 → 0.1.22

package/docker-runner.d.ts

@@ -1,3 +1,4 @@
+export declare const CONTAINER_INTERNAL_PORT = 4321;
 /** Role label stamped on every product control-plane container. The daemon's
  *  infrastructure view discovers managed singletons by the presence of a
  *  `norsk-ctl.role` label (proxy, proxy-oauth2, cpu-monitor, product); the
@@ -16,6 +17,9 @@ export declare function productContainerName(productName: string): string;
 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>;
+/** 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>;
 export declare function dockerRm(containerId: string): Promise<void>;
 /** Best-effort rename of a running container. The product is tracked by
  *  container id, never by name, so a rename failure (e.g. a stale container

package/docker-runner.js

@@ -1,5 +1,5 @@
 import { ProductError } from "./product-error.js";
-const CONTAINER_INTERNAL_PORT = 4321;
+export const CONTAINER_INTERNAL_PORT = 4321;
 /** Role label stamped on every product control-plane container. The daemon's
  *  infrastructure view discovers managed singletons by the presence of a
  *  `norsk-ctl.role` label (proxy, proxy-oauth2, cpu-monitor, product); the
@@ -53,6 +53,16 @@ export async function dockerRun(image, hostPort) {
     }
     return stdout;
 }
+/** The container's address on its first network (the default bridge for a
+ *  product container), or undefined when docker cannot say. */
+export async function dockerAddress(containerId) {
+    const proc = Bun.spawn(["docker", "inspect", "-f", "{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}", containerId], { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    if (exitCode !== 0 || !stdout)
+        return undefined;
+    return stdout.split(/\s+/)[0];
+}
 export async function dockerRm(containerId) {
     const proc = Bun.spawn(["docker", "rm", "-f", containerId], { stdout: "pipe", stderr: "pipe" });
     await proc.exited;

package/docs-router.d.ts

@@ -0,0 +1,21 @@
+import { type Express } from "express";
+/**
+ * Where a product's docs bundle (dev-kit doc-guide `buildBundle`) is, given the
+ * backend's own directory — or null when the product shipped none.
+ *
+ * Two layouts, one relative path: the image bakes the bundle at `<app>/docs`
+ * beside `backend/` (Dockerfile.bundle), a repo checkout has it at
+ * `<repo>/docs/generated/bundle`; from `backend/dist` and `backend/src`
+ * respectively both are `../../docs`. The image's `docs/` exists even when
+ * empty, so presence is judged by `bundle.json`, not the directory.
+ */
+export declare function docsBundleDir(fromDir: string): string | null;
+/**
+ * Mount the docs bundle at `/docs`: `manual.html` as the index, `bundle.json`,
+ * `pages/*.md` and `captures/*` by path. Returns whether anything was mounted,
+ * so a product without a bundle boots exactly as before. `/docs` redirects to
+ * `/docs/` with a root-absolute Location, which the daemon's product proxy
+ * rewrites under `/products/<name>` — so the manual's hash routing works
+ * through the daemon too.
+ */
+export declare function serveDocs(app: Express, dir: string | null): boolean;

package/docs-router.js

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import express from "express";
+/**
+ * Where a product's docs bundle (dev-kit doc-guide `buildBundle`) is, given the
+ * backend's own directory — or null when the product shipped none.
+ *
+ * Two layouts, one relative path: the image bakes the bundle at `<app>/docs`
+ * beside `backend/` (Dockerfile.bundle), a repo checkout has it at
+ * `<repo>/docs/generated/bundle`; from `backend/dist` and `backend/src`
+ * respectively both are `../../docs`. The image's `docs/` exists even when
+ * empty, so presence is judged by `bundle.json`, not the directory.
+ */
+export function docsBundleDir(fromDir) {
+    const docs = resolve(fromDir, "../../docs");
+    for (const candidate of [docs, resolve(docs, "generated/bundle")]) {
+        if (existsSync(resolve(candidate, "bundle.json")))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Mount the docs bundle at `/docs`: `manual.html` as the index, `bundle.json`,
+ * `pages/*.md` and `captures/*` by path. Returns whether anything was mounted,
+ * so a product without a bundle boots exactly as before. `/docs` redirects to
+ * `/docs/` with a root-absolute Location, which the daemon's product proxy
+ * rewrites under `/products/<name>` — so the manual's hash routing works
+ * through the daemon too.
+ */
+export function serveDocs(app, dir) {
+    if (!dir)
+        return false;
+    app.use("/docs", express.static(dir, { index: "manual.html" }));
+    return true;
+}

package/index.d.ts

@@ -3,6 +3,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./docs-router.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-staged.js";
@@ -12,6 +13,7 @@ export * from "./manifest-fetch.js";
 export * from "./manifest-router.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
+export * from "./product-reach.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";

package/index.js

@@ -5,6 +5,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./docs-router.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-staged.js";
@@ -14,6 +15,7 @@ export * from "./manifest-fetch.js";
 export * from "./manifest-router.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
+export * from "./product-reach.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";

package/manifest-fetch.d.ts

@@ -1,5 +1,5 @@
 import { type Manifest } from "./manifest-schema.js";
-import type { ProductSpec } from "./product-types.js";
+import type { ProductRegistration, ProductSpec } from "./product-types.js";
 /**
  * Fast liveness probe for a registered product. A dev-mode product is
  * externally owned, so the only way to know it's actually up is to ask it.
@@ -8,7 +8,14 @@ import type { ProductSpec } from "./product-types.js";
  * because it runs on the product-list render path.
  */
 export declare function isDevUrlAlive(baseUrl: string): Promise<boolean>;
-export declare function specBaseUrl(spec: ProductSpec, port?: number): string;
+/** Where the daemon dials a product. A container product is loopback-published
+ *  on `port`; a daemon that itself runs in a container cannot reach that
+ *  loopback and dials the container's own address (`reachHost`) on the internal
+ *  port instead — see product-reach.ts. */
+export declare function specBaseUrl(spec: ProductSpec, port?: number, reachHost?: string): string;
+/** specBaseUrl for a registration — the one call every dial site should make,
+ *  so a recorded reachHost is never forgotten. */
+export declare function productBaseUrl(reg: Pick<ProductRegistration, "spec" | "port" | "reachHost">): string;
 export declare function fetchManifest(baseUrl: string): Promise<Manifest>;
 export declare function waitForReady(baseUrl: string): Promise<void>;
 /**

package/manifest-fetch.js

@@ -1,3 +1,4 @@
+import { CONTAINER_INTERNAL_PORT } from "./docker-runner.js";
 import { ManifestSchema } from "./manifest-schema.js";
 import { ProductError } from "./product-error.js";
 const READINESS_TIMEOUT_MS = 60_000;
@@ -19,13 +20,24 @@ export async function isDevUrlAlive(baseUrl) {
         return false;
     }
 }
-export function specBaseUrl(spec, port) {
+/** Where the daemon dials a product. A container product is loopback-published
+ *  on `port`; a daemon that itself runs in a container cannot reach that
+ *  loopback and dials the container's own address (`reachHost`) on the internal
+ *  port instead — see product-reach.ts. */
+export function specBaseUrl(spec, port, reachHost) {
     if (spec.kind === "dev")
         return spec.url.replace(/\/$/, "");
+    if (reachHost !== undefined)
+        return `http://${reachHost}:${CONTAINER_INTERNAL_PORT}`;
     if (port === undefined)
         throw new Error("container spec requires port");
     return `http://127.0.0.1:${port}`;
 }
+/** specBaseUrl for a registration — the one call every dial site should make,
+ *  so a recorded reachHost is never forgotten. */
+export function productBaseUrl(reg) {
+    return specBaseUrl(reg.spec, reg.port, reg.reachHost);
+}
 export async function fetchManifest(baseUrl) {
     let response;
     try {

package/package.json

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

package/product-health-monitor.js

@@ -1,5 +1,5 @@
 import { logger } from "@norskvideo/ctl-foundation";
-import { specBaseUrl } from "./manifest-fetch.js";
+import { productBaseUrl } from "./manifest-fetch.js";
 const UNKNOWN = { status: "unknown", consecutiveFailures: 0, restartAttempts: 0 };
 /**
  * Periodically probes each container product's health endpoint and, after
@@ -123,7 +123,7 @@ export async function probeProductHealth(reg, timeoutMs = 3_000) {
     if (reg.spec.kind !== "container" || reg.port === undefined)
         return false;
     const path = reg.manifest.api?.healthCheckPath ?? "/healthz";
-    const base = specBaseUrl(reg.spec, reg.port);
+    const base = productBaseUrl(reg);
     try {
         const r = await fetch(`${base}${path.startsWith("/") ? path : `/${path}`}`, {
             signal: AbortSignal.timeout(timeoutMs),

package/product-reach.d.ts

@@ -0,0 +1,9 @@
+export type ProductReach = "host" | "container-address";
+/** The 64-hex docker container id from a /proc/self/cgroup dump, or null on a
+ *  bare host. Present in both cgroup v1 (`/docker/<id>`) and v2
+ *  (`docker-<id>.scope`) layouts. */
+export declare function parseContainerIdFromCgroup(text: string): string | null;
+export declare function detectProductReach(opts: {
+    cgroup?: () => string;
+    env?: Record<string, string | undefined>;
+}): ProductReach;

package/product-reach.js

@@ -0,0 +1,32 @@
+// How the daemon reaches a product's control-plane container. The container is
+// loopback-published (`-p 127.0.0.1:<host port>:4321`), which is right when the
+// daemon runs on the docker host. When the daemon itself runs in a container —
+// a docker-outside-of-docker CI runner — that loopback belongs to the docker
+// host, not to the daemon, and every registration times out at readiness. The
+// container's own bridge address on the internal port is what such a daemon
+// can dial, so a containerised daemon uses that and remembers it on the
+// registration (`reachHost`). Detection reads the daemon's own cgroup, the
+// same tell the test harness uses; NORSK_CTL_PRODUCT_REACH overrides it.
+import { readFileSync } from "node:fs";
+const CGROUP_PATH = "/proc/self/cgroup";
+const REACH_ENV = "NORSK_CTL_PRODUCT_REACH";
+/** The 64-hex docker container id from a /proc/self/cgroup dump, or null on a
+ *  bare host. Present in both cgroup v1 (`/docker/<id>`) and v2
+ *  (`docker-<id>.scope`) layouts. */
+export function parseContainerIdFromCgroup(text) {
+    const m = text.match(/[0-9a-f]{64}/);
+    return m ? m[0] : null;
+}
+export function detectProductReach(opts) {
+    const env = opts.env ?? process.env;
+    const forced = env[REACH_ENV];
+    if (forced === "host" || forced === "container-address")
+        return forced;
+    const read = opts.cgroup ?? (() => readFileSync(CGROUP_PATH, "utf-8"));
+    try {
+        return parseContainerIdFromCgroup(read()) ? "container-address" : "host";
+    }
+    catch {
+        return "host";
+    }
+}

package/product-service.d.ts

@@ -1,4 +1,5 @@
 import { type LicenseStager } from "./license-registration.js";
+import { type ProductReach } from "./product-reach.js";
 import type { ProductTemplateSource } from "./product-template-record.js";
 import type { ProductLicense, ProductRegistration, ProductSpec } from "./product-types.js";
 /**
@@ -83,6 +84,10 @@ export interface ProductContainerOps {
     remove(containerId: string): Promise<void>;
     rename(containerId: string, name: string): Promise<void>;
     waitForReady(baseUrl: string): Promise<void>;
+    /** The container's own address, consulted only under reach
+     *  "container-address" (see product-reach.ts). Optional: a host without it
+     *  falls back to the loopback host port. */
+    address?(containerId: string): Promise<string | undefined>;
 }
 /** The real docker-runner wiring. Exported so a host can override one op
  *  (typically `pull`, onto its own docker adapter) and keep the rest. */
@@ -107,6 +112,11 @@ export interface ProductServiceOptions {
     /** Container lifecycle ops used by add/remove/restart/stopAll/restoreAll.
      *  Injectable for tests; defaults to the real docker-runner functions. */
     containerOps?: ProductContainerOps;
+    /** How this daemon reaches a product container: the loopback host port
+     *  (a host daemon) or the container's own address (a daemon that is itself
+     *  in a container). Default: detected from the daemon's cgroup, overridable
+     *  with NORSK_CTL_PRODUCT_REACH. */
+    reach?: ProductReach;
 }
 export declare class ProductService {
     /**
@@ -131,7 +141,11 @@ export declare class ProductService {
     private readonly stageLicense?;
     private readonly isDevUrlAlive;
     private readonly containerOps;
+    private readonly reach;
     constructor(opts: ProductServiceOptions);
+    /** The address to record for a freshly started container: its own, when
+     *  this daemon cannot dial the host loopback; otherwise nothing. */
+    private reachHostFor;
     list(): ProductRegistration[];
     /** Docker's default `--pull=missing` keeps whatever a moving tag resolved to
      *  last time, so a rebuilt `:latest`/`:dev` never reached a new registration.

package/product-service.js

@@ -1,11 +1,12 @@
 import { readFile } from "node:fs/promises";
 import { logger, Mutex } from "@norskvideo/ctl-foundation";
 import { validateDevUrl } from "./dev-url.js";
-import { dockerPull, dockerRename, dockerRm, dockerRun, isDigestRef, productContainerName } from "./docker-runner.js";
+import { dockerAddress, dockerPull, dockerRename, dockerRm, dockerRun, isDigestRef, productContainerName, } from "./docker-runner.js";
 import { resolveLicenseFile } from "./license-registration.js";
 import { checkProductEntitlement, notV2EnvelopeMessage, parseLicenseContents } from "./license-v2.js";
-import { fetchManifest, isDevUrlAlive, probeConfigScreen, specBaseUrl, waitForReady } from "./manifest-fetch.js";
+import { fetchManifest, isDevUrlAlive, probeConfigScreen, productBaseUrl, specBaseUrl, waitForReady, } from "./manifest-fetch.js";
 import { ProductError } from "./product-error.js";
+import { detectProductReach } from "./product-reach.js";
 /** GET a product-template tar from a product. `url` is whatever the manifest
  *  declared; we treat it as a path on the product's HTTP surface and
  *  resolve against the product's base URL. Returns the raw tar bytes,
@@ -32,6 +33,7 @@ export const defaultProductContainerOps = {
     remove: dockerRm,
     rename: dockerRename,
     waitForReady,
+    address: dockerAddress,
 };
 export class ProductService {
     /**
@@ -56,6 +58,7 @@ export class ProductService {
     stageLicense;
     isDevUrlAlive;
     containerOps;
+    reach;
     constructor(opts) {
         this.store = opts.store;
         this.allocatePort = opts.allocatePort;
@@ -64,6 +67,14 @@ export class ProductService {
         this.stageLicense = opts.stageLicense;
         this.isDevUrlAlive = opts.isDevUrlAlive ?? isDevUrlAlive;
         this.containerOps = opts.containerOps ?? defaultProductContainerOps;
+        this.reach = opts.reach ?? detectProductReach({});
+    }
+    /** The address to record for a freshly started container: its own, when
+     *  this daemon cannot dial the host loopback; otherwise nothing. */
+    async reachHostFor(containerId) {
+        if (this.reach !== "container-address" || !this.containerOps.address)
+            return undefined;
+        return this.containerOps.address(containerId);
     }
     list() {
         return this.store.read();
@@ -90,7 +101,7 @@ export class ProductService {
     async isRunning(reg) {
         if (reg.spec.kind === "container")
             return reg.containerId !== undefined;
-        return this.isDevUrlAlive(specBaseUrl(reg.spec));
+        return this.isDevUrlAlive(productBaseUrl(reg));
     }
     async add(spec, opts = {}) {
         return this.mutations.run(() => this.addSerialised(spec, opts));
@@ -100,6 +111,7 @@ export class ProductService {
         let baseUrl;
         let port;
         let containerId;
+        let reachHost;
         if (spec.kind === "dev") {
             validateDevUrl(spec.url);
             baseUrl = specBaseUrl(spec);
@@ -117,7 +129,8 @@ export class ProductService {
             await this.refreshImage(spec.image);
             logger.info(`Starting product container: ${spec.image} on host port ${port}`);
             containerId = await this.containerOps.run(spec.image, port);
-            baseUrl = specBaseUrl(spec, port);
+            reachHost = await this.reachHostFor(containerId);
+            baseUrl = specBaseUrl(spec, port, reachHost);
         }
         try {
             await this.containerOps.waitForReady(baseUrl);
@@ -221,6 +234,7 @@ export class ProductService {
             manifest,
             ...(port !== undefined ? { port } : {}),
             ...(containerId !== undefined ? { containerId } : {}),
+            ...(reachHost !== undefined ? { reachHost } : {}),
             ...(opts.license !== undefined
                 ? {
                     license: opts.license.mode === "byol" && licenseFile !== undefined
@@ -304,12 +318,14 @@ export class ProductService {
                 }
             }
             const containerId = await this.containerOps.run(target.spec.image, target.port);
-            await this.store.update((products) => products.map((p) => (p.name === name ? withContainerId(p, containerId) : p)));
-            await this.containerOps.waitForReady(specBaseUrl(target.spec, target.port));
+            const reachHost = await this.reachHostFor(containerId);
+            await this.store.update((products) => products.map((p) => (p.name === name ? withContainerId(p, containerId, reachHost) : p)));
+            await this.containerOps.waitForReady(specBaseUrl(target.spec, target.port, reachHost));
             await this.containerOps.rename(containerId, productContainerName(name));
             containerRestarted = true;
         }
-        const baseUrl = specBaseUrl(target.spec, target.port);
+        const current = this.store.read().find((p) => p.name === name) ?? target;
+        const baseUrl = productBaseUrl(current);
         const manifest = await fetchManifest(baseUrl);
         if (manifest.name !== target.name) {
             throw new ProductError("NAME_CONFLICT", `manifest now reports name '${manifest.name}', was '${target.name}' — use remove + add`);
@@ -393,9 +409,10 @@ export class ProductService {
             }
             try {
                 const containerId = await this.containerOps.run(reg.spec.image, reg.port);
-                await this.containerOps.waitForReady(specBaseUrl(reg.spec, reg.port));
+                const reachHost = await this.reachHostFor(containerId);
+                await this.containerOps.waitForReady(specBaseUrl(reg.spec, reg.port, reachHost));
                 await this.containerOps.rename(containerId, productContainerName(reg.name));
-                restored.set(reg.name, containerId);
+                restored.set(reg.name, { containerId, reachHost });
                 logger.info(`Product '${reg.name}' container restored on host port ${reg.port}`);
             }
             catch (e) {
@@ -403,7 +420,12 @@ export class ProductService {
                 logger.warn(`Product '${reg.name}': failed to restore — ${e instanceof Error ? e.message : String(e)}`);
             }
         }));
-        await this.store.update((products) => products.map((p) => (restored.has(p.name) ? withContainerId(p, restored.get(p.name)) : p)));
+        await this.store.update((products) => products.map((p) => {
+            if (!restored.has(p.name))
+                return p;
+            const r = restored.get(p.name);
+            return withContainerId(p, r?.containerId, r?.reachHost);
+        }));
     }
     /** Stop (if still present) and relaunch a single container-kind product,
      *  recording the fresh containerId. Used by the health monitor to recover a
@@ -434,15 +456,20 @@ export class ProductService {
             }
         }
         const containerId = await this.containerOps.run(target.spec.image, target.port);
-        await this.store.update((products) => products.map((p) => (p.name === name ? withContainerId(p, containerId) : p)));
-        await this.containerOps.waitForReady(specBaseUrl(target.spec, target.port));
+        const reachHost = await this.reachHostFor(containerId);
+        await this.store.update((products) => products.map((p) => (p.name === name ? withContainerId(p, containerId, reachHost) : p)));
+        await this.containerOps.waitForReady(specBaseUrl(target.spec, target.port, reachHost));
         await this.containerOps.rename(containerId, productContainerName(name));
         logger.info(`Product '${name}' container restarted on host port ${target.port}`);
     }
 }
-/** Return a copy of `reg` with containerId set (or removed when undefined),
- *  preserving the "omit the key entirely" shape the store round-trips. */
-function withContainerId(reg, containerId) {
-    const { containerId: _drop, ...rest } = reg;
-    return containerId === undefined ? rest : { ...rest, containerId };
+/** Return a copy of `reg` with containerId (and the address it was reached at)
+ *  set, or both removed when undefined, preserving the "omit the key entirely"
+ *  shape the store round-trips. A stale reachHost would point the health
+ *  monitor at a container that no longer exists, so it travels with the id. */
+function withContainerId(reg, containerId, reachHost) {
+    const { containerId: _drop, reachHost: _dropHost, ...rest } = reg;
+    if (containerId === undefined)
+        return rest;
+    return { ...rest, containerId, ...(reachHost !== undefined ? { reachHost } : {}) };
 }

package/product-types.d.ts

@@ -25,6 +25,10 @@ export interface ProductRegistration {
     port?: number;
     /** Docker container ID (container mode only). */
     containerId?: string;
+    /** The container's own address, recorded when the daemon runs in a
+     *  container and cannot dial the loopback-published host port (see
+     *  product-reach.ts). Absent on a host daemon: 127.0.0.1:<port> is right. */
+    reachHost?: string;
     /** Absent on registrations that predate per-product licenses — launches
      *  fall back to the host's global license setting. */
     license?: ProductLicense;

package/proxy-middleware.js

@@ -1,8 +1,9 @@
 import { logger } from "@norskvideo/ctl-foundation";
 import { buildForwardHeaders, forwardUpstreamResponse, readRequestBody } from "./http-proxy.js";
+import { productBaseUrl } from "./manifest-fetch.js";
 function targetBaseUrl(reg) {
     if (reg.spec.kind === "container") {
-        return reg.port !== undefined ? `http://127.0.0.1:${reg.port}` : null;
+        return reg.port !== undefined ? productBaseUrl(reg) : null;
     }
     return reg.spec.url.replace(/\/$/, "");
 }