@norskvideo/ctl-sdk 0.1.33 → 0.1.34

package/migration-client.d.ts

@@ -1,4 +1,27 @@
+/** 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>;
@@ -19,6 +42,13 @@ export interface MigrationClient {
     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). */
@@ -56,5 +86,8 @@ export interface ConnectMigrationOptions {
     /** 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

@@ -3,12 +3,22 @@
 // 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.
@@ -19,6 +29,15 @@
 // 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 = {}) {
@@ -26,13 +45,16 @@ export function connectMigration(handlers, env = process.env, opts = {}) {
     const token = env[JOB_SOCKET_ENV.token];
     if (!url || !token)
         return noopClient();
-    return new SocketMigrationClient(url, token, handlers, opts);
+    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: () => { },
@@ -53,6 +75,10 @@ class SocketMigrationClient {
     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;
@@ -66,6 +92,12 @@ class SocketMigrationClient {
         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) });
     }
@@ -94,6 +126,67 @@ class SocketMigrationClient {
         }
     }
     // ── 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;
@@ -169,6 +262,8 @@ class SocketMigrationClient {
                 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}` : ""})`);
@@ -186,6 +281,7 @@ class SocketMigrationClient {
                 return;
             this.socket = undefined;
             this.connected = false;
+            this.stateRequest = undefined;
             if (this.closed)
                 return;
             this.log("socket error; will reconnect");
@@ -219,6 +315,17 @@ class SocketMigrationClient {
             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);
@@ -228,6 +335,10 @@ class SocketMigrationClient {
                     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;

package/package.json

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