@norskvideo/ctl-sdk 0.1.32 → 0.1.33

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,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.32",
+  "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/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