@norskvideo/ctl-sdk 0.1.18 → 0.1.20

package/docker-runner.d.ts

@@ -11,6 +11,10 @@ export declare function productRunArgs(image: string, hostPort: number): string[
  *  `docker ps` shows `norsk-product-studio` instead of a random docker alias.
  *  Mirrors the singleton naming of norsk-proxy / norsk-ctl-cpu-monitor. */
 export declare function productContainerName(productName: string): string;
+/** An `@sha256:...` (or any `@algo:hex`) reference names one immutable image,
+ *  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 dockerRm(containerId: string): Promise<void>;
 /** Best-effort rename of a running container. The product is tracked by

package/docker-runner.js

@@ -30,6 +30,19 @@ export function productContainerName(productName) {
         .replace(/^-+|-+$/g, "");
     return `norsk-product-${slug || "unnamed"}`;
 }
+/** An `@sha256:...` (or any `@algo:hex`) reference names one immutable image,
+ *  so there is nothing to refresh; a tag can move under a registration. */
+export function isDigestRef(image) {
+    return /@[a-z0-9]+:[0-9a-f]+$/i.test(image);
+}
+export async function dockerPull(image) {
+    const proc = Bun.spawn(["docker", "pull", image], { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    if (exitCode !== 0) {
+        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" });
     const exitCode = await proc.exited;

package/package.json

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

package/product-error.d.ts

@@ -1,4 +1,4 @@
 export declare class ProductError extends Error {
-    code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "PRODUCT_TEMPLATE_FETCH_FAILED";
-    constructor(code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "PRODUCT_TEMPLATE_FETCH_FAILED", message: string);
+    code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "PRODUCT_TEMPLATE_FETCH_FAILED";
+    constructor(code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "PRODUCT_TEMPLATE_FETCH_FAILED", message: string);
 }

package/product-service.d.ts

@@ -11,6 +11,22 @@ export interface AddProductResult {
     registration: ProductRegistration;
     warnings: string[];
 }
+/** Result of `reload`. `containerRestarted` is false for dev products, which
+ *  are externally owned. `productTemplates` reports the manifest-declared
+ *  default templates handed to the host's refresh callback: `skipped` carries
+ *  the host's reason (typically "in use"), and every skip is also a warning. */
+export interface ReloadProductResult {
+    registration: ProductRegistration;
+    warnings: string[];
+    containerRestarted: boolean;
+    productTemplates: {
+        refreshed: string[];
+        skipped: Array<{
+            name: string;
+            reason: string;
+        }>;
+    };
+}
 export interface AddProductOpts {
     /** Per-product license stored on the registration record (#313). Callers
      *  typically seed this from their global license setting when the operator
@@ -49,17 +65,28 @@ export type ImportProductTemplateBytesFn = (opts: {
         kind: "product-default";
     }>;
 }) => Promise<void>;
+/** `reload`'s counterpart to ImportProductTemplateBytesFn: re-render the
+ *  stored snapshot of a product-default template from fresh bytes, or store
+ *  it if the product only started declaring it. The host owns the refusal
+ *  rules (a template an instance is using, one that is not product-default);
+ *  it throws, and the SDK reports the message as a skip rather than failing
+ *  the reload. */
+export type RefreshProductTemplateBytesFn = ImportProductTemplateBytesFn;
 /** Every container operation this service performs, behind an interface so
  *  tests can drive them without shelling out to Docker. Defaults wire straight
  *  to docker-runner + the readiness probe. Reach for these rather than the
  *  module functions: calling docker-runner directly re-creates the bypass that
  *  made an injected fake silently inert on add/remove. */
 export interface ProductContainerOps {
+    pull(image: string): Promise<void>;
     run(image: string, hostPort: number): Promise<string>;
     remove(containerId: string): Promise<void>;
     rename(containerId: string, name: string): Promise<void>;
     waitForReady(baseUrl: string): Promise<void>;
 }
+/** The real docker-runner wiring. Exported so a host can override one op
+ *  (typically `pull`, onto its own docker adapter) and keep the rest. */
+export declare const defaultProductContainerOps: ProductContainerOps;
 export interface ProductServiceOptions {
     store: ProductStore;
     allocatePort: AllocatePortFn;
@@ -67,6 +94,9 @@ export interface ProductServiceOptions {
      *  registration time. Omit on hosts that don't store product templates
      *  (defaultProductTemplates is then silently skipped). */
     importProductTemplateBytes?: ImportProductTemplateBytesFn;
+    /** Optional: called once per `manifest.defaultProductTemplates` entry by
+     *  `reload`. Omit on hosts that don't store product templates. */
+    refreshProductTemplateBytes?: RefreshProductTemplateBytesFn;
     /** Optional: copy a byol licence somewhere the host owns, so the path
      *  recorded in the registry outlives whatever the operator passed in.
      *  Omit on hosts that don't stage (the operator's path is then recorded). */
@@ -97,11 +127,17 @@ export declare class ProductService {
     private readonly store;
     private readonly allocatePort;
     private readonly importProductTemplateBytes?;
+    private readonly refreshProductTemplateBytes?;
     private readonly stageLicense?;
     private readonly isDevUrlAlive;
     private readonly containerOps;
     constructor(opts: ProductServiceOptions);
     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.
+     *  Best-effort: a locally built image is in no registry, and the run that
+     *  follows must still get its turn. */
+    private refreshImage;
     /** Whether the product is actually up. Container-mode: we started it, so a
      *  tracked containerId means running. Dev-mode: externally owned, so probe
      *  the dev URL — registered no longer implies running. */
@@ -110,7 +146,15 @@ export declare class ProductService {
     private addSerialised;
     remove(name: string): Promise<void>;
     private removeSerialised;
-    reload(name: string): Promise<ProductRegistration>;
+    /** Bring a registration up to date with what its image now serves. For a
+     *  container product: pull the tag (digests cannot move), re-run the
+     *  control plane on its recorded port, re-read the manifest, then hand every
+     *  manifest-declared default template to the host to re-render. Dev products
+     *  are externally owned, so only the manifest is re-read. This is the verb
+     *  the per-product "remove template, remove product, add again" scripts
+     *  stood in for. Like restart, the new container id is persisted before the
+     *  readiness wait so a timed-out reload leaves a tracked container. */
+    reload(name: string): Promise<ReloadProductResult>;
     private reloadSerialised;
     /** Stop every running container-kind product and clear its tracked
      *  containerId (model B: the daemon owns container lifecycle, so it reaps

package/product-service.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { logger, Mutex } from "@norskvideo/ctl-foundation";
 import { validateDevUrl } from "./dev-url.js";
-import { dockerRename, dockerRm, dockerRun, productContainerName } from "./docker-runner.js";
+import { 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";
@@ -24,7 +24,10 @@ async function fetchProductTemplateBytes(baseUrl, url) {
     }
     return new Uint8Array(await response.arrayBuffer());
 }
-const defaultContainerOps = {
+/** The real docker-runner wiring. Exported so a host can override one op
+ *  (typically `pull`, onto its own docker adapter) and keep the rest. */
+export const defaultProductContainerOps = {
+    pull: dockerPull,
     run: dockerRun,
     remove: dockerRm,
     rename: dockerRename,
@@ -49,6 +52,7 @@ export class ProductService {
     store;
     allocatePort;
     importProductTemplateBytes;
+    refreshProductTemplateBytes;
     stageLicense;
     isDevUrlAlive;
     containerOps;
@@ -56,13 +60,30 @@ export class ProductService {
         this.store = opts.store;
         this.allocatePort = opts.allocatePort;
         this.importProductTemplateBytes = opts.importProductTemplateBytes;
+        this.refreshProductTemplateBytes = opts.refreshProductTemplateBytes;
         this.stageLicense = opts.stageLicense;
         this.isDevUrlAlive = opts.isDevUrlAlive ?? isDevUrlAlive;
-        this.containerOps = opts.containerOps ?? defaultContainerOps;
+        this.containerOps = opts.containerOps ?? defaultProductContainerOps;
     }
     list() {
         return this.store.read();
     }
+    /** Docker's default `--pull=missing` keeps whatever a moving tag resolved to
+     *  last time, so a rebuilt `:latest`/`:dev` never reached a new registration.
+     *  Best-effort: a locally built image is in no registry, and the run that
+     *  follows must still get its turn. */
+    async refreshImage(image) {
+        if (isDigestRef(image))
+            return;
+        logger.info(`Pulling product image: ${image}`);
+        try {
+            await this.containerOps.pull(image);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            logger.warn(`Pull of ${image} did not complete (${msg}); continuing with the local image if present`);
+        }
+    }
     /** Whether the product is actually up. Container-mode: we started it, so a
      *  tracked containerId means running. Dev-mode: externally owned, so probe
      *  the dev URL — registered no longer implies running. */
@@ -93,6 +114,7 @@ export class ProductService {
                 throw new ProductError("PORT_EXHAUSTED", `no free port available for new product`);
             }
             port = allocated;
+            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);
@@ -252,23 +274,76 @@ export class ProductService {
         await this.store.update((products) => products.filter((p) => p.name !== name));
         logger.info(`Product '${name}' removed`);
     }
+    /** Bring a registration up to date with what its image now serves. For a
+     *  container product: pull the tag (digests cannot move), re-run the
+     *  control plane on its recorded port, re-read the manifest, then hand every
+     *  manifest-declared default template to the host to re-render. Dev products
+     *  are externally owned, so only the manifest is re-read. This is the verb
+     *  the per-product "remove template, remove product, add again" scripts
+     *  stood in for. Like restart, the new container id is persisted before the
+     *  readiness wait so a timed-out reload leaves a tracked container. */
     async reload(name) {
         return this.mutations.run(() => this.reloadSerialised(name));
     }
     async reloadSerialised(name) {
-        const existing = this.store.read();
-        const target = existing.find((p) => p.name === name);
+        const target = this.store.read().find((p) => p.name === name);
         if (!target)
             throw new ProductError("NOT_FOUND", `product '${name}' not registered`);
+        let containerRestarted = false;
+        if (target.spec.kind === "container") {
+            if (target.port === undefined) {
+                throw new ProductError("NOT_RESTARTABLE", `product '${name}' has no recorded port — cannot reload`);
+            }
+            await this.refreshImage(target.spec.image);
+            if (target.containerId) {
+                try {
+                    await this.containerOps.remove(target.containerId);
+                }
+                catch {
+                    // Already gone (crashed / --rm reaped) — nothing to stop.
+                }
+            }
+            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));
+            await this.containerOps.rename(containerId, productContainerName(name));
+            containerRestarted = true;
+        }
         const baseUrl = specBaseUrl(target.spec, target.port);
         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`);
         }
-        const next = { ...target, manifest };
-        await this.store.update((products) => products.map((p) => (p.name === name ? next : p)));
-        logger.info(`Product '${name}' manifest reloaded`);
-        return next;
+        const updated = await this.store.update((products) => products.map((p) => (p.name === name ? { ...p, manifest } : p)));
+        const registration = updated.find((p) => p.name === name);
+        logger.info(`Product '${name}' reloaded${containerRestarted ? " (container re-run)" : ""}`);
+        // Same downgrade as add's default-template import: the product itself is
+        // healthy, so a template the host refuses (in use, foreign) or a fetch
+        // that fails is a warning the operator acts on, not a failed reload.
+        const warnings = [];
+        const productTemplates = { refreshed: [], skipped: [] };
+        if (this.refreshProductTemplateBytes) {
+            for (const entry of manifest.defaultProductTemplates) {
+                try {
+                    const bytes = await fetchProductTemplateBytes(baseUrl, entry.url);
+                    await this.refreshProductTemplateBytes({
+                        name: entry.name,
+                        bytes,
+                        source: { kind: "product-default", productName: manifest.name, url: entry.url },
+                    });
+                    productTemplates.refreshed.push(entry.name);
+                    logger.info(`Product '${name}': refreshed default product template '${entry.name}' from ${entry.url}`);
+                }
+                catch (e) {
+                    const reason = e instanceof Error ? e.message : String(e);
+                    productTemplates.skipped.push({ name: entry.name, reason });
+                    warnings.push(`default product template '${entry.name}' not refreshed: ${reason}`);
+                }
+            }
+        }
+        for (const w of warnings)
+            logger.warn(`[product:${name}] ${w}`);
+        return { registration, warnings, containerRestarted, productTemplates };
     }
     /** Stop every running container-kind product and clear its tracked
      *  containerId (model B: the daemon owns container lifecycle, so it reaps