@norskvideo/ctl-sdk 0.1.31 → 0.1.33

package/docker-runner.d.ts

@@ -10,6 +10,10 @@ export declare const PRODUCT_ROLE_LABEL = "norsk-ctl.role=product";
  *  (see product-reach.ts). Omitted leaves it on docker's default bridge. */
 export interface ProductRunOpts {
     network?: string;
+    /** Deploy-time environment for the control-plane container, passed as
+     *  `-e KEY=VALUE` (e.g. `FUNKE_HARDWARE=software`). The map is the caller's;
+     *  what a product reads from it is the product's own contract. */
+    env?: Record<string, string>;
 }
 /** argv (sans leading "docker") that launches a product container: detached,
  *  auto-removed, loopback-published to its internal 4321, and role-labelled so

package/docker-runner.js

@@ -27,6 +27,7 @@ export function productRunArgs(image, opts = {}) {
         "--label",
         PRODUCT_ROLE_LABEL,
         ...(opts.network ? ["--network", opts.network] : []),
+        ...Object.entries(opts.env ?? {}).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
         "-p",
         `127.0.0.1::${CONTAINER_INTERNAL_PORT}`,
         image,

package/index.d.ts

@@ -11,6 +11,7 @@ export * from "./license-stager.js";
 export * from "./license-v2.js";
 export * from "./manifest-fetch.js";
 export * from "./manifest-router.js";
+export * from "./migration-client.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
 export * from "./product-hub.js";

package/index.js

@@ -13,6 +13,7 @@ export * from "./license-stager.js";
 export * from "./license-v2.js";
 export * from "./manifest-fetch.js";
 export * from "./manifest-router.js";
+export * from "./migration-client.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
 export * from "./product-hub.js";

package/manifest-schema.d.ts

@@ -130,6 +130,23 @@ export declare const ManifestSchema: z.ZodObject<{
                 model: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        accelerator: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"fixed">;
+            value: z.ZodEnum<{
+                none: "none";
+                nvidia: "nvidia";
+                quadra: "quadra";
+            }>;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"default">;
+            value: z.ZodEnum<{
+                none: "none";
+                nvidia: "nvidia";
+                quadra: "quadra";
+            }>;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"required">;
+        }, z.core.$strip>], "mode">>;
         capabilities: z.ZodOptional<z.ZodObject<{
             mode: z.ZodEnum<{
                 default: "default";

package/migration-client.d.ts

@@ -0,0 +1,60 @@
+export interface MigrationHandlers {
+    /** Source side: the target is ready at `payload`. Stop output at or after
+     *  it, then `reportStoppedOutput`. */
+    onCutoverReady?(payload: unknown, migrationId: string): void | Promise<void>;
+    /** Target side: the source stopped at `payload`. Take over from it, then
+     *  `reportApplied`. */
+    onCutoverApply?(payload: unknown, migrationId: string): void | Promise<void>;
+    /** Either side. A source resumes output; a target expects to be stopped. */
+    onAbort?(reason: string, migrationId: string): void | Promise<void>;
+}
+export interface MigrationClient {
+    /** "target" iff the worker's hello-ack said so (the instance was launched
+     *  as a migration target); "none" when there is no socket at all. A source
+     *  is "source" — every connected instance that is not a target may be
+     *  asked to hand over. */
+    readonly role: "source" | "target" | "none";
+    /** The migration a target belongs to, or the one a source is in once a
+     *  cutover-ready has named it. */
+    readonly migrationId?: string;
+    /** True while the socket is open and hello-acked. */
+    readonly connected: boolean;
+    /** Target: ready to take over at `payload` (a position). Once. */
+    reportReady(payload: unknown): void;
+    /** Source: output stopped at `payload` (a position). */
+    reportStoppedOutput(payload: unknown): void;
+    /** Target: the handover has been applied. */
+    reportApplied(): void;
+    /** Either side: give up on the migration. */
+    abort(reason: string): void;
+    /** Stop reconnecting and close. */
+    close(): void;
+}
+/** The subset of the WHATWG WebSocket API the client uses. `ws`'s WebSocket
+ *  and the Node/Bun/browser globals all satisfy it. */
+export interface MigrationSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+export type MigrationSocketCtor = new (url: string) => MigrationSocket;
+export interface ConnectMigrationOptions {
+    /** Override the socket implementation (tests; a runtime with neither a
+     *  global WebSocket nor `ws`). */
+    WebSocket?: MigrationSocketCtor;
+    /** Backoff bounds. */
+    reconnectMinMs?: number;
+    reconnectMaxMs?: number;
+    /** Where the client reports what it does; default: console.error, one
+     *  line per event, prefixed. */
+    log?: (line: string) => void;
+}
+export declare function connectMigration(handlers: MigrationHandlers, env?: NodeJS.ProcessEnv, opts?: ConnectMigrationOptions): MigrationClient;

package/migration-client.js

@@ -0,0 +1,267 @@
+// The job side of the worker's job socket (norsk-ctl
+// packages/norsk-mgr/docs/internal/design/job-migration.md §5): what a
+// handover-migratable product calls at startup.
+//
+//   const migration = connectMigration({
+//     onCutoverReady: async (payload) => { /* source: stop at >= payload */ migration.reportStoppedOutput({...}) },
+//     onCutoverApply: async (payload) => { /* target: take over from payload */ migration.reportApplied() },
+//     onAbort: (reason) => { /* source: resume output */ },
+//   });
+//   if (migration.role === "target") migration.reportReady({...});
+//
+// Reads NORSK_WORKER_WS_URL / NORSK_WORKER_TOKEN. When they are absent — a
+// worker with `--no-job-socket`, a local `norsk-ctl` launch, a test — this is
+// a no-op client with role "none", so a product calls it unconditionally.
+//
+// Transport: a WHATWG-shaped WebSocket. Node ≥ 22 and Bun have one as a
+// global; on older Node the `ws` package supplies it. Reconnects with backoff
+// (1 s doubling to 30 s) after any drop, re-sends hello, and holds at most
+// the LATEST unsent report while disconnected — a newer position supersedes
+// an older one, and the worker acts on the first it hears.
+import { JOB_SOCKET_ENV, parseWorkerToJobFrame, } from "@norskvideo/ctl-product-template-schema/migration-socket";
+const DEFAULT_MIN_BACKOFF_MS = 1_000;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+export function connectMigration(handlers, env = process.env, opts = {}) {
+    const url = env[JOB_SOCKET_ENV.url];
+    const token = env[JOB_SOCKET_ENV.token];
+    if (!url || !token)
+        return noopClient();
+    return new SocketMigrationClient(url, token, handlers, opts);
+}
+function noopClient() {
+    return {
+        role: "none",
+        migrationId: undefined,
+        connected: false,
+        reportReady: () => { },
+        reportStoppedOutput: () => { },
+        reportApplied: () => { },
+        abort: () => { },
+        close: () => { },
+    };
+}
+class SocketMigrationClient {
+    url;
+    token;
+    handlers;
+    opts;
+    role = "source";
+    migrationId;
+    connected = false;
+    socket;
+    closed = false;
+    attempt = 0;
+    reconnectTimer;
+    pending;
+    minBackoffMs;
+    maxBackoffMs;
+    log;
+    constructor(url, token, handlers, opts) {
+        this.url = url;
+        this.token = token;
+        this.handlers = handlers;
+        this.opts = opts;
+        this.minBackoffMs = opts.reconnectMinMs ?? DEFAULT_MIN_BACKOFF_MS;
+        this.maxBackoffMs = opts.reconnectMaxMs ?? DEFAULT_MAX_BACKOFF_MS;
+        this.log = opts.log ?? ((line) => console.error(`[migration] ${line}`));
+        void this.connect();
+    }
+    reportReady(payload) {
+        this.report({ type: "target-ready", payload: asPayload(payload) });
+    }
+    reportStoppedOutput(payload) {
+        this.report({ type: "source-stopped-output", payload: asPayload(payload) });
+    }
+    reportApplied() {
+        this.report({ type: "target-applied" });
+    }
+    abort(reason) {
+        this.report({ type: "abort", reason });
+    }
+    close() {
+        this.closed = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        const s = this.socket;
+        this.socket = undefined;
+        this.connected = false;
+        try {
+            s?.close(1000, "job closing");
+        }
+        catch {
+            // already gone
+        }
+    }
+    // ── private ─────────────────────────────────────────────────────────
+    report(msg) {
+        if (this.closed)
+            return;
+        if (this.connected && this.socket) {
+            this.send(msg);
+            return;
+        }
+        // Disconnected: the latest report wins. A position reported twice is
+        // the newer position; the worker acts on whichever it hears first.
+        this.pending = msg;
+    }
+    send(msg) {
+        try {
+            this.socket?.send(JSON.stringify(msg));
+        }
+        catch (e) {
+            this.log(`send of '${msg.type}' failed: ${String(e)}`);
+        }
+    }
+    async connect() {
+        if (this.closed)
+            return;
+        let Ctor;
+        try {
+            Ctor = await resolveWebSocket(this.opts.WebSocket);
+        }
+        catch (e) {
+            this.log(`no WebSocket implementation: ${String(e)} — migration disabled`);
+            this.role = "none";
+            return;
+        }
+        if (this.closed)
+            return;
+        let socket;
+        try {
+            socket = new Ctor(this.url);
+        }
+        catch (e) {
+            this.log(`connect to ${this.url} failed: ${String(e)}`);
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        let acked = false;
+        socket.onopen = () => {
+            if (this.socket !== socket)
+                return;
+            this.send({ type: "hello", token: this.token });
+        };
+        socket.onmessage = (ev) => {
+            if (this.socket !== socket)
+                return;
+            const text = typeof ev.data === "string" ? ev.data : String(ev.data);
+            const parsed = parseWorkerToJobFrame(text);
+            if (!parsed.ok) {
+                this.log(`ignoring frame from the worker: ${parsed.reason}`);
+                return;
+            }
+            const msg = parsed.message;
+            if (!acked) {
+                if (msg.type !== "hello-ack") {
+                    this.log(`expected hello-ack, got '${msg.type}'; ignoring`);
+                    return;
+                }
+                acked = true;
+                this.onAcked(msg);
+                return;
+            }
+            void this.onMessage(msg);
+        };
+        socket.onclose = (ev) => {
+            if (this.socket !== socket)
+                return;
+            this.socket = undefined;
+            this.connected = false;
+            if (this.closed)
+                return;
+            this.log(`socket closed (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})`);
+            this.scheduleReconnect();
+        };
+        socket.onerror = () => {
+            // Node's WebSocket (undici, Node 22) fires `error` and NOT `close` when
+            // the connection itself fails — the socket stays CONNECTING for ever.
+            // Waiting for a close that never comes stranded every job whose worker
+            // restarted: the first refused reconnect ended the client's life
+            // (seen live 2026-09-07). Treat an error on the current socket as its
+            // end; a `close` that does follow finds `this.socket` moved on and is
+            // ignored by the guard above.
+            if (this.socket !== socket)
+                return;
+            this.socket = undefined;
+            this.connected = false;
+            if (this.closed)
+                return;
+            this.log("socket error; will reconnect");
+            try {
+                socket.close();
+            }
+            catch {
+                // never opened
+            }
+            this.scheduleReconnect();
+        };
+    }
+    onAcked(ack) {
+        this.attempt = 0;
+        this.connected = true;
+        if (ack.migration) {
+            this.role = "target";
+            this.migrationId = ack.migration.id;
+        }
+        else {
+            this.role = "source";
+        }
+        this.log(`connected as ${this.role}${this.migrationId ? ` (migration ${this.migrationId})` : ""}`);
+        const pending = this.pending;
+        this.pending = undefined;
+        if (pending)
+            this.send(pending);
+    }
+    async onMessage(msg) {
+        try {
+            switch (msg.type) {
+                case "hello-ack":
+                    return;
+                case "cutover-ready":
+                    this.migrationId = msg.migrationId;
+                    await this.handlers.onCutoverReady?.(msg.payload, msg.migrationId);
+                    return;
+                case "cutover-apply":
+                    this.migrationId = msg.migrationId;
+                    await this.handlers.onCutoverApply?.(msg.payload, msg.migrationId);
+                    return;
+                case "abort":
+                    await this.handlers.onAbort?.(msg.reason, msg.migrationId);
+                    if (this.role === "source")
+                        this.migrationId = undefined;
+                    return;
+            }
+        }
+        catch (e) {
+            this.log(`handler for '${msg.type}' threw: ${String(e)}`);
+        }
+    }
+    scheduleReconnect() {
+        if (this.closed || this.reconnectTimer)
+            return;
+        const delay = Math.min(this.maxBackoffMs, this.minBackoffMs * 2 ** this.attempt);
+        this.attempt = Math.min(this.attempt + 1, 30);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            void this.connect();
+        }, delay);
+    }
+}
+function asPayload(payload) {
+    // Anything JSON.stringify can carry. A non-JSON value (undefined, a
+    // function) becomes null rather than an invalid frame.
+    return payload === undefined ? null : JSON.parse(JSON.stringify(payload));
+}
+async function resolveWebSocket(explicit) {
+    if (explicit)
+        return explicit;
+    const global = globalThis.WebSocket;
+    if (global)
+        return global;
+    // Older Node: the `ws` package's WebSocket carries the same handler
+    // properties. A dynamic import so a runtime with the global never loads it.
+    const ws = await import("ws");
+    return ws.WebSocket;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "type": "module",
   "exports": {
     ".": {
@@ -31,7 +31,11 @@
       "types": "./workflow.d.ts",
       "default": "./workflow.js"
     },
-    "./base.css": "./base.css"
+    "./base.css": "./base.css",
+    "./migration": {
+      "types": "./migration-client.d.ts",
+      "default": "./migration-client.js"
+    }
   },
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -42,7 +46,8 @@
     "lucide-react": "^0.483.0",
     "react": "^19.0.0",
     "react-hot-toast": "^2.4.1",
-    "zod": "4.4.3"
+    "zod": "4.4.3",
+    "ws": "^8.20.1"
   },
   "publishConfig": {
     "access": "public"

package/parsing.js

@@ -15,7 +15,8 @@ export function parseSpec(raw, where, path) {
         if (typeof raw.image !== "string") {
             throw new ProductsParseError(path, `${where}.spec.image must be a string`);
         }
-        return { kind: "container", image: raw.image };
+        const env = parseEnv(raw.env, where, path);
+        return { kind: "container", image: raw.image, ...(env !== undefined ? { env } : {}) };
     }
     if (raw.kind === "dev") {
         if (typeof raw.url !== "string") {
@@ -25,6 +26,22 @@ export function parseSpec(raw, where, path) {
     }
     throw new ProductsParseError(path, `${where}.spec.kind must be 'container' or 'dev'`);
 }
+/** The container spec's deploy-time env, round-tripped from the store as a
+ *  `{ KEY: VALUE }` map of strings. Absent stays absent; a present value must
+ *  be an object of string→string. */
+function parseEnv(raw, where, path) {
+    if (raw === undefined)
+        return undefined;
+    if (!isRecord(raw))
+        throw new ProductsParseError(path, `${where}.spec.env must be an object`);
+    const env = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v !== "string")
+            throw new ProductsParseError(path, `${where}.spec.env.${k} must be a string`);
+        env[k] = v;
+    }
+    return env;
+}
 function parseLicense(raw, where, path) {
     if (!isRecord(raw))
         throw new ProductsParseError(path, `${where}.license must be an object`);

package/product-service.d.ts

@@ -82,8 +82,10 @@ export type RefreshProductTemplateBytesFn = ImportProductTemplateBytesFn;
 export interface ProductContainerOps {
     pull(image: string): Promise<void>;
     /** Start the container. The host port comes back from docker rather than
-     *  going in: docker owns the host port space (see docker-runner.ts). */
-    run(image: string): Promise<ProductPlacement>;
+     *  going in: docker owns the host port space (see docker-runner.ts). `env`
+     *  is the spec's deploy-time environment, passed straight through as
+     *  `-e KEY=VALUE`. */
+    run(image: string, env?: Record<string, string>): Promise<ProductPlacement>;
     remove(containerId: string): Promise<void>;
     rename(containerId: string, name: string): Promise<void>;
     waitForReady(baseUrl: string): Promise<void>;

package/product-service.js

@@ -29,7 +29,7 @@ async function fetchProductTemplateBytes(baseUrl, url) {
  *  (typically `pull`, onto its own docker adapter) and keep the rest. */
 export const defaultProductContainerOps = {
     pull: dockerPull,
-    run: dockerRun,
+    run: (image, env) => dockerRun(image, env ? { env } : {}),
     remove: dockerRm,
     rename: dockerRename,
     waitForReady,
@@ -117,7 +117,7 @@ export class ProductService {
         else {
             await this.refreshImage(spec.image);
             logger.info(`Starting product container: ${spec.image} (reach: ${this.reach})`);
-            const placement = await this.containerOps.run(spec.image);
+            const placement = await this.containerOps.run(spec.image, spec.env);
             containerId = placement.containerId;
             port = placement.hostPort;
             logger.info(`Product container ${containerId.slice(0, 12)} published on host port ${port}`);
@@ -309,7 +309,7 @@ export class ProductService {
                     // Already gone (crashed / --rm reaped) — nothing to stop.
                 }
             }
-            const { containerId, hostPort } = await this.containerOps.run(target.spec.image);
+            const { containerId, hostPort } = await this.containerOps.run(target.spec.image, target.spec.env);
             const reachHost = await this.reachHostFor(containerId);
             await this.store.update((products) => products.map((p) => (p.name === name ? withPlacement(p, containerId, hostPort, reachHost) : p)));
             await this.containerOps.waitForReady(specBaseUrl(target.spec, hostPort, reachHost));
@@ -400,7 +400,7 @@ export class ProductService {
                 return;
             }
             try {
-                const { containerId, hostPort } = await this.containerOps.run(reg.spec.image);
+                const { containerId, hostPort } = await this.containerOps.run(reg.spec.image, reg.spec.env);
                 const reachHost = await this.reachHostFor(containerId);
                 await this.containerOps.waitForReady(specBaseUrl(reg.spec, hostPort, reachHost));
                 await this.containerOps.rename(containerId, productContainerName(reg.name));
@@ -449,7 +449,7 @@ export class ProductService {
                 // Already gone (crashed / --rm reaped) — nothing to stop.
             }
         }
-        const { containerId, hostPort } = await this.containerOps.run(target.spec.image);
+        const { containerId, hostPort } = await this.containerOps.run(target.spec.image, target.spec.env);
         const reachHost = await this.reachHostFor(containerId);
         await this.store.update((products) => products.map((p) => (p.name === name ? withPlacement(p, containerId, hostPort, reachHost) : p)));
         await this.containerOps.waitForReady(specBaseUrl(target.spec, hostPort, reachHost));

package/product-template-record.d.ts

@@ -56,7 +56,8 @@ export interface ProductTemplateRecord {
      *  launch's parameter map beneath the operator's instance values —
      *  instance wins, template default wins over manifest default. Names
      *  must be env-var shaped and never `NORSK_`-prefixed (that namespace is
-     *  infra-injected: NORSK_RUNTIME_ROLE, NORSK_MATCHED_CAPABILITIES, …). */
+     *  infra-injected: NORSK_RUNTIME_ROLE, NORSK_MIGRATION_ID,
+     *  NORSK_MATCHED_CAPABILITIES, …). */
     parameterDefaults?: Record<string, string>;
     /** Template-author security-group suggestions, by discovery-tag LABEL
      *  (portable across deployments; ids are not). The launch UI pre-ticks

package/product-types.d.ts

@@ -1,7 +1,13 @@
 import type { Manifest } from "./manifest-schema.js";
-export type ProductSpec = {
+export type ProductSpec = 
+/** `env` is the deploy-time environment for the control-plane container,
+ *  supplied at `product add --env KEY=VALUE`. It lives on the spec (not just
+ *  the add call) so it persists with the registration and every later
+ *  restart/reload/restore re-runs the container with the same environment. */
+{
     kind: "container";
     image: string;
+    env?: Record<string, string>;
 } | {
     kind: "dev";
     url: string;