@norskvideo/ctl-sdk 0.1.32 → 0.1.34

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/migration-client.d.ts

@@ -0,0 +1,93 @@
+/** A source declining the propose. Return it from `onGetState` (see
+ *  {@link stateRefusal}); it goes to the worker as `state-refused{reason}`
+ *  and the migration ends with no target ever placed. */
+export interface StateRefusal {
+    readonly refused: true;
+    readonly reason: string;
+}
+export declare function stateRefusal(reason: string): StateRefusal;
+export declare function isStateRefusal(value: unknown): value is StateRefusal;
+export interface MigrationHandlers {
+    /** Source side, first on every handover: the propose. Return the state a
+     *  target would need to take over (any JSON; `undefined`/`null` is a yes
+     *  with nothing to hand over), or {@link stateRefusal} to decline. A throw
+     *  is a refusal too. The answer goes back as `state` / `state-refused`;
+     *  a product that answers from elsewhere calls `reportState` /
+     *  `refuseState` inside the handler instead, and the return value is
+     *  then ignored. Without this handler the client refuses every propose,
+     *  naming the product — a product that cannot hand over is told so at
+     *  once rather than timing out the migration. */
+    onGetState?(migrationId: string): unknown | Promise<unknown>;
+    /** Target side, first after the hello-ack when the source handed
+     *  something over: adopt `payload` before reporting ready. Nothing is sent
+     *  back for it. */
+    onInitialState?(payload: unknown, migrationId: string): void | Promise<void>;
+    /** 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;
+    /** Source: answer the propose with `payload` (any JSON; null is a yes with
+     *  nothing to hand over). Only meaningful while a `get-state` is in
+     *  flight — i.e. from inside `onGetState`, before it returns or resolves;
+     *  otherwise dropped with a log line. */
+    reportState(payload: unknown): void;
+    /** Source: decline the propose. Same window as `reportState`. */
+    refuseState(reason: string): void;
+    /** 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;
+    /** How the product is named in a refusal the client makes on its behalf;
+     *  default: `NORSK_RUNTIME_ID` from the env, else "this product". */
+    name?: string;
+}
+export declare function connectMigration(handlers: MigrationHandlers, env?: NodeJS.ProcessEnv, opts?: ConnectMigrationOptions): MigrationClient;

package/migration-client.js

@@ -0,0 +1,378 @@
+// 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({
+//     onGetState: async () => currentPosition(),               // source: the propose (or stateRefusal("why"))
+//     onInitialState: async (payload) => { /* target: adopt the source's state before ready */ },
+//     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({...});
+//
+// The worker asks `get-state` FIRST on every handover and waits for `state`
+// or `state-refused`; nothing on the worker times that out, so a client that
+// answered neither parked every migration in `proposing` until the
+// AutoManager's deadline (review 2026-09-16). This client therefore ALWAYS
+// answers: the handler's return value, its refusal, its exception, or — with
+// no handler at all — a refusal that names the product. A refusal costs
+// nothing; a park costs the deadline.
+//
+// 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";
+export function stateRefusal(reason) {
+    return { refused: true, reason };
+}
+export function isStateRefusal(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.refused === true &&
+        typeof value.reason === "string");
+}
+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();
+    const name = opts.name ?? env.NORSK_RUNTIME_ID ?? "this product";
+    return new SocketMigrationClient(url, token, handlers, { ...opts, name });
+}
+function noopClient() {
+    return {
+        role: "none",
+        migrationId: undefined,
+        connected: false,
+        reportState: () => { },
+        refuseState: () => { },
+        reportReady: () => { },
+        reportStoppedOutput: () => { },
+        reportApplied: () => { },
+        abort: () => { },
+        close: () => { },
+    };
+}
+class SocketMigrationClient {
+    url;
+    token;
+    handlers;
+    opts;
+    role = "source";
+    migrationId;
+    connected = false;
+    socket;
+    closed = false;
+    attempt = 0;
+    reconnectTimer;
+    pending;
+    /** The `get-state` being answered, while one is. `answered` flips when
+     *  the product calls reportState/refuseState from inside its handler, so
+     *  the handler's return value is not sent as a second answer. */
+    stateRequest;
+    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();
+    }
+    reportState(payload) {
+        this.answerState({ type: "state", payload: asPayload(payload) });
+    }
+    refuseState(reason) {
+        this.answerState({ type: "state-refused", reason });
+    }
+    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 ─────────────────────────────────────────────────────────
+    /** The one answer to the in-flight `get-state`. The worker closes the
+     *  socket 4400 on a `state` with no propose in flight, so an answer with
+     *  none is dropped here rather than sent. Not held while disconnected: a
+     *  socket that drops mid-propose is the source aborting, and the worker
+     *  asks again on the next migration. */
+    answerState(msg) {
+        if (this.closed)
+            return;
+        const req = this.stateRequest;
+        if (!req) {
+            this.log(`'${msg.type}' with no get-state in flight; dropped`);
+            return;
+        }
+        if (req.answered) {
+            this.log(`'${msg.type}' after get-state for ${req.migrationId} was already answered; dropped`);
+            return;
+        }
+        req.answered = true;
+        if (msg.type === "state-refused") {
+            // A source that refused is not in the migration; it may be asked again.
+            if (this.migrationId === req.migrationId)
+                this.migrationId = undefined;
+        }
+        if (!this.connected || !this.socket) {
+            this.log(`'${msg.type}' for ${req.migrationId} while disconnected; dropped — the worker will ask again`);
+            return;
+        }
+        this.send(msg);
+    }
+    /** The propose. Every path ends in exactly one `state` | `state-refused`. */
+    async onGetState(migrationId) {
+        if (this.stateRequest && !this.stateRequest.answered) {
+            // The worker never sends a second get-state while one is in flight;
+            // if it does, the newer one is the one it is waiting on.
+            this.log(`get-state for ${migrationId} while ${this.stateRequest.migrationId} is unanswered; superseded`);
+        }
+        this.stateRequest = { migrationId, answered: false };
+        this.migrationId = migrationId;
+        const handler = this.handlers.onGetState;
+        if (!handler) {
+            const reason = `${this.opts.name} registered no onGetState handler (connectMigration without onGetState); it cannot hand over`;
+            this.log(`get-state for ${migrationId}: ${reason}; refusing`);
+            this.refuseState(reason);
+            return;
+        }
+        let answer;
+        try {
+            answer = await handler.call(this.handlers, migrationId);
+        }
+        catch (e) {
+            this.log(`onGetState for ${migrationId} threw: ${String(e)}; refusing`);
+            this.refuseState(`onGetState threw: ${String(e)}`);
+            return;
+        }
+        if (this.stateRequest?.migrationId !== migrationId || this.stateRequest.answered)
+            return;
+        if (isStateRefusal(answer))
+            this.refuseState(answer.reason);
+        else
+            this.reportState(answer);
+    }
+    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;
+            // A drop mid-propose is the source aborting; the worker asks afresh.
+            this.stateRequest = undefined;
+            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;
+            this.stateRequest = undefined;
+            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 "get-state":
+                    await this.onGetState(msg.migrationId);
+                    return;
+                case "initial-state":
+                    this.migrationId = msg.migrationId;
+                    if (!this.handlers.onInitialState) {
+                        this.log(`initial-state for ${msg.migrationId} arrived but no onInitialState handler is registered; the source's state is dropped`);
+                        return;
+                    }
+                    await this.handlers.onInitialState(msg.payload, msg.migrationId);
+                    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":
+                    // An abort ends an unanswered propose too: an answer after it
+                    // would meet a worker with nothing in flight (4400).
+                    if (this.stateRequest?.migrationId === msg.migrationId)
+                        this.stateRequest = undefined;
+                    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.32",
+  "version": "0.1.34",
   "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/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