@norskvideo/ctl-product-template-schema 0.1.19 → 0.1.20

package/index.d.ts

@@ -122,6 +122,17 @@ export declare const ProductTemplateRequirementsSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ProductTemplateRequirements = z.infer<typeof ProductTemplateRequirementsSchema>;
+export declare const PRODUCT_TEMPLATE_MIGRATION_STRATEGIES: readonly ["overlap", "stopThenStart", "handover"];
+export type MigrationStrategy = (typeof PRODUCT_TEMPLATE_MIGRATION_STRATEGIES)[number];
+export declare const DEFAULT_MIGRATION_STRATEGY: MigrationStrategy;
+export declare const ProductTemplateMigrationSchema: z.ZodObject<{
+    strategy: z.ZodEnum<{
+        overlap: "overlap";
+        stopThenStart: "stopThenStart";
+        handover: "handover";
+    }>;
+}, z.core.$strip>;
+export type ProductTemplateMigration = z.infer<typeof ProductTemplateMigrationSchema>;
 export declare const ProductTemplateManifestSchema: z.ZodObject<{
     productTemplateSchemaVersion: z.ZodLiteral<1>;
     productName: z.ZodString;
@@ -267,8 +278,19 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
         preferred: z.ZodNumber;
         label: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    migration: z.ZodOptional<z.ZodObject<{
+        strategy: z.ZodEnum<{
+            overlap: "overlap";
+            stopThenStart: "stopThenStart";
+            handover: "handover";
+        }>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ProductTemplateManifest = z.infer<typeof ProductTemplateManifestSchema>;
+/** The migration strategy a manifest promises — `stopThenStart` when it
+ *  declares none, since that is the only strategy safe for a product that
+ *  has said nothing about how it tolerates being moved. */
+export declare function migrationStrategyOf(manifest: Pick<ProductTemplateManifest, "migration">): MigrationStrategy;
 export declare const STANDARD_ADVANCED_OVERRIDES: {
     readonly containerUser: {};
     readonly publicHost: {};
@@ -462,6 +484,13 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             preferred: z.ZodNumber;
             label: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        migration: z.ZodOptional<z.ZodObject<{
+            strategy: z.ZodEnum<{
+                overlap: "overlap";
+                stopThenStart: "stopThenStart";
+                handover: "handover";
+            }>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     composeYaml: z.ZodString;
     parameters: z.ZodOptional<z.ZodObject<{

package/index.js

@@ -262,6 +262,20 @@ export const ProductTemplateRequirementsSchema = z
         .meta({ description: "Fixed host sockets the job binds (exclusive)." }),
 })
     .meta({ id: "ProductTemplateRequirements", outputId: "ProductTemplateRequirements" });
+// How a running instance of the product may be moved between nodes
+// (norsk-mgr/docs/internal/design/job-migration.md §6). The manifest
+// declares the strongest promise the product keeps; a migrate request may
+// only down-grade to a safer strategy. Absent means `stopThenStart`, the
+// one that is safe for any product.
+export const PRODUCT_TEMPLATE_MIGRATION_STRATEGIES = ["overlap", "stopThenStart", "handover"];
+export const DEFAULT_MIGRATION_STRATEGY = "stopThenStart";
+export const ProductTemplateMigrationSchema = z
+    .object({
+    strategy: z.enum(PRODUCT_TEMPLATE_MIGRATION_STRATEGIES).meta({
+        description: "`overlap`: the target is started before the source is stopped, so both instances may produce briefly — a promise only a product whose outputs tolerate a second writer can make. `stopThenStart` (the default when absent): the target is prepared but not started, the source is stopped, then the target is started — safe for any product, at the cost of a gap. `handover`: the job speaks the worker's migration socket and hands over at an exact position, so the output continues seamlessly — a promise the job's own code keeps.",
+    }),
+})
+    .meta({ id: "ProductTemplateMigration", outputId: "ProductTemplateMigration" });
 export const ProductTemplateManifestSchema = z
     .object({
     productTemplateSchemaVersion: z.literal(1),
@@ -304,8 +318,17 @@ export const ProductTemplateManifestSchema = z
     allocatedPorts: z.array(ProductTemplateAllocatedPortSchema).optional().meta({
         description: "Host-port bindings whose value rides a product-template parameter. Opt-in per launch via the param value: absent = closed, 'auto' = allocate a free port from `preferred`, number = use it. When opened the port is published as a managed host binding and surfaced to the containers via compose interpolation. Alongside the per-param scalars the runner sets NORSK_ALLOCATED_PORTS: a JSON object keyed by param, each value {port, protocol, service?}, describing every opened port ('{}' when none opted in; unset when nothing is declared) — so a product needing the allocation as data maps one var instead of folding scalars into JSON via interpolation.",
     }),
+    migration: ProductTemplateMigrationSchema.optional().meta({
+        description: "How a running instance may be moved between nodes. `strategy` is the strongest promise the product keeps: `overlap` (target started, then source stopped — both may produce briefly), `stopThenStart` (the default when absent — target prepared but not started, source stopped, target started), or `handover` (the job speaks the worker's migration socket and hands over at an exact position). A migrate request may down-grade to a safer strategy but never up-grade past the declaration. Only the manager reads this; the worker never does.",
+    }),
 })
     .meta({ id: "ProductTemplateManifest", outputId: "ProductTemplateManifest" });
+/** The migration strategy a manifest promises — `stopThenStart` when it
+ *  declares none, since that is the only strategy safe for a product that
+ *  has said nothing about how it tolerates being moved. */
+export function migrationStrategyOf(manifest) {
+    return manifest.migration?.strategy ?? DEFAULT_MIGRATION_STRATEGY;
+}
 // Container user and external URL are runner knobs every product wants
 // overridable per instance — the runner only holds their default values.
 // Spread this into a manifest's `advanced` (adding product-specific keys

package/migration-socket.d.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+export declare const JOB_SOCKET_DEFAULT_PORT = 6797;
+export declare const JOB_SOCKET_MAX_FRAME_BYTES: number;
+export declare const JOB_SOCKET_HELLO_TIMEOUT_MS = 5000;
+/** The name a container reaches its own worker's host under. Injected as an
+ *  `extra_hosts` mapping on every service so it resolves on native Linux too. */
+export declare const JOB_SOCKET_CONTAINER_HOST = "host.docker.internal";
+/** The NodeInventory capability a worker advertises while its listener is up,
+ *  so placement can require it for a handover target. */
+export declare const JOB_SOCKET_CAPABILITY = "norsk.io/job-socket";
+/** The two reserved env names a job reads. Absent when the worker runs
+ *  without a listener (`--no-job-socket`), which is what `connectMigration`
+ *  turns into its no-op client. */
+export declare const JOB_SOCKET_ENV: {
+    readonly url: "NORSK_WORKER_WS_URL";
+    readonly token: "NORSK_WORKER_TOKEN";
+};
+/** Close codes the worker uses. All in the 4000–4999 application range so a
+ *  client can tell them from transport failures. */
+export declare const JobSocketCloseCode: {
+    /** A frame that breaks the protocol: unparseable, wrong side, wrong phase. */
+    readonly protocolError: 4400;
+    /** No hello in time, a wrong token, or a path naming no instance. */
+    readonly unauthorized: 4401;
+    /** A newer connection for the same instance replaced this one. */
+    readonly replaced: 4409;
+    /** A frame over the size cap. */
+    readonly frameTooLarge: 4413;
+};
+export declare function jobSocketPath(jobId: string, role: string): string;
+/** The inverse of {@link jobSocketPath}. Query strings are ignored. */
+export declare function parseJobSocketPath(path: string): {
+    jobId: string;
+    role: string;
+} | undefined;
+export declare function jobSocketUrl(args: {
+    host: string;
+    port: number;
+    jobId: string;
+    role: string;
+}): string;
+declare const JsonPayload: z.ZodJSONSchema;
+/** Any JSON value — what a job may put in `payload`. */
+export type MigrationPayload = z.infer<typeof JsonPayload>;
+export declare const JobToWorkerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    token: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"state">;
+    payload: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"state-refused">;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"target-ready">;
+    payload: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"source-stopped-output">;
+    payload: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"target-applied">;
+    applied: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    skewMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"abort">;
+    reason: z.ZodString;
+}, z.core.$strip>], "type">;
+export type JobToWorkerMessage = z.infer<typeof JobToWorkerMessageSchema>;
+export declare const WorkerToJobMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"hello-ack">;
+    migration: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        side: z.ZodLiteral<"target">;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"get-state">;
+    migrationId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"initial-state">;
+    migrationId: z.ZodString;
+    payload: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cutover-ready">;
+    migrationId: z.ZodString;
+    payload: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cutover-apply">;
+    migrationId: z.ZodString;
+    payload: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"abort">;
+    migrationId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>], "type">;
+export type WorkerToJobMessage = z.infer<typeof WorkerToJobMessageSchema>;
+export type ParsedFrame<T> = {
+    ok: true;
+    message: T;
+} | {
+    ok: false;
+    reason: string;
+};
+/** What the worker does with a text frame from a job. */
+export declare function parseJobToWorkerFrame(text: string): ParsedFrame<JobToWorkerMessage>;
+/** What the job does with a text frame from the worker. */
+export declare function parseWorkerToJobFrame(text: string): ParsedFrame<WorkerToJobMessage>;
+/** A socket payload as it rides the gRPC `bytes payload` field: the UTF-8 of
+ *  its JSON. `undefined` (a job that sent nothing) is carried as `null` so the
+ *  bytes are always valid JSON. */
+export declare function encodeMigrationPayload(payload: unknown): Uint8Array;
+/** The inverse of {@link encodeMigrationPayload}. Empty bytes — a gRPC
+ *  message with the field unset — read as `null`; bytes that are not JSON
+ *  come back as the raw string rather than being dropped, so a foreign
+ *  Manager's opaque payload still reaches the job. */
+export declare function decodeMigrationPayload(bytes: Uint8Array | undefined): MigrationPayload;
+export {};

package/migration-socket.js

@@ -0,0 +1,157 @@
+// The job socket — the contract between a worker and a job it may hand over
+// (norsk-mgr/docs/internal/design/job-migration.md §5). One module, used by
+// BOTH ends: the worker's listener validates inbound frames with these
+// schemas, and the SDK client (`connectMigration`) validates what the worker
+// sends it. Neither side re-declares a message shape.
+//
+// Transport: a WebSocket on the worker host, default port 6797, reached from
+// a container as `host.docker.internal`. Path `/instances/<jobId>/<role>`
+// where `role` is the instance KEY (unique per migration target), both
+// url-encoded. JSON text frames, each ≤ 64 KiB. `payload` is any JSON, opaque
+// to the worker; on the gRPC wire it becomes the UTF-8 bytes of its
+// JSON.stringify and comes back the same way.
+import { z } from "zod";
+export const JOB_SOCKET_DEFAULT_PORT = 6797;
+export const JOB_SOCKET_MAX_FRAME_BYTES = 64 * 1024;
+export const JOB_SOCKET_HELLO_TIMEOUT_MS = 5_000;
+/** The name a container reaches its own worker's host under. Injected as an
+ *  `extra_hosts` mapping on every service so it resolves on native Linux too. */
+export const JOB_SOCKET_CONTAINER_HOST = "host.docker.internal";
+/** The NodeInventory capability a worker advertises while its listener is up,
+ *  so placement can require it for a handover target. */
+export const JOB_SOCKET_CAPABILITY = "norsk.io/job-socket";
+/** The two reserved env names a job reads. Absent when the worker runs
+ *  without a listener (`--no-job-socket`), which is what `connectMigration`
+ *  turns into its no-op client. */
+export const JOB_SOCKET_ENV = {
+    url: "NORSK_WORKER_WS_URL",
+    token: "NORSK_WORKER_TOKEN",
+};
+/** Close codes the worker uses. All in the 4000–4999 application range so a
+ *  client can tell them from transport failures. */
+export const JobSocketCloseCode = {
+    /** A frame that breaks the protocol: unparseable, wrong side, wrong phase. */
+    protocolError: 4400,
+    /** No hello in time, a wrong token, or a path naming no instance. */
+    unauthorized: 4401,
+    /** A newer connection for the same instance replaced this one. */
+    replaced: 4409,
+    /** A frame over the size cap. */
+    frameTooLarge: 4413,
+};
+export function jobSocketPath(jobId, role) {
+    return `/instances/${encodeURIComponent(jobId)}/${encodeURIComponent(role)}`;
+}
+/** The inverse of {@link jobSocketPath}. Query strings are ignored. */
+export function parseJobSocketPath(path) {
+    const m = /^\/instances\/([^/?#]+)\/([^/?#]+)\/?(?:[?#].*)?$/.exec(path);
+    if (!m?.[1] || !m[2])
+        return undefined;
+    try {
+        return { jobId: decodeURIComponent(m[1]), role: decodeURIComponent(m[2]) };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function jobSocketUrl(args) {
+    return `ws://${args.host}:${args.port}${jobSocketPath(args.jobId, args.role)}`;
+}
+// ── frames ───────────────────────────────────────────────────────────────
+const JsonPayload = z.json();
+export const JobToWorkerMessageSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("hello"), token: z.string() }),
+    // The propose, answered by the SOURCE. Exactly one of these two goes
+    // back for a `get-state`: `state` accepts (a `null` payload is a
+    // perfectly good acceptance — a job with nothing to hand over still
+    // takes part), `state-refused` declines and the whole migration ends
+    // with no target ever placed. The refusal is its own frame rather than
+    // a field inside `payload`, so the worker can act on it without ever
+    // opening the opaque blob.
+    z.object({ type: z.literal("state"), payload: JsonPayload }),
+    z.object({ type: z.literal("state-refused"), reason: z.string() }),
+    z.object({ type: z.literal("target-ready"), payload: JsonPayload }),
+    z.object({ type: z.literal("source-stopped-output"), payload: JsonPayload }),
+    // The handover has been applied — and, past the point of no return, WHAT
+    // was applied. A job with more than one migration participant applies them
+    // in declared bands and cannot roll back once the source has stopped, so a
+    // participant that fails to apply is REPORTED rather than fatal. The three
+    // fields are envelope fields, outside any participant's opaque document, so
+    // the worker and the Manager can relay them without opening a blob.
+    //
+    // All three are optional: a job built before there was more than one
+    // participant sends the bare frame. And note that `z.object` STRIPS unknown
+    // keys rather than rejecting them — without these fields declared here the
+    // worker would accept the frame and silently drop the summary, which is why
+    // this and Studio's own copy
+    // (`norsk-studio workspaces/core/src/migration/socket-contract.ts`) have to
+    // move together.
+    z.object({
+        type: z.literal("target-applied"),
+        applied: z.array(z.string()).optional(),
+        failed: z.array(z.object({ id: z.string(), reason: z.string() })).optional(),
+        skewMs: z.number().optional(),
+    }),
+    z.object({ type: z.literal("abort"), reason: z.string() }),
+]);
+export const WorkerToJobMessageSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("hello-ack"),
+        /** Present only when the instance was launched as a migration target. */
+        migration: z.object({ id: z.string(), side: z.literal("target") }).optional(),
+    }),
+    // The propose, asked of the SOURCE before any target has been placed.
+    z.object({ type: z.literal("get-state"), migrationId: z.string() }),
+    // The source's state, handed to the TARGET. Always the first frame
+    // after `hello-ack` when the instance was started with one, so a
+    // target's `ready` can depend on having applied it.
+    z.object({ type: z.literal("initial-state"), migrationId: z.string(), payload: JsonPayload }),
+    z.object({ type: z.literal("cutover-ready"), migrationId: z.string(), payload: JsonPayload }),
+    z.object({ type: z.literal("cutover-apply"), migrationId: z.string(), payload: JsonPayload }),
+    z.object({ type: z.literal("abort"), migrationId: z.string(), reason: z.string() }),
+]);
+function parseFrame(schema, text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "frame is not valid JSON" };
+    }
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success)
+        return { ok: false, reason: `invalid frame: ${z.prettifyError(parsed.error)}` };
+    return { ok: true, message: parsed.data };
+}
+/** What the worker does with a text frame from a job. */
+export function parseJobToWorkerFrame(text) {
+    return parseFrame(JobToWorkerMessageSchema, text);
+}
+/** What the job does with a text frame from the worker. */
+export function parseWorkerToJobFrame(text) {
+    return parseFrame(WorkerToJobMessageSchema, text);
+}
+// ── payload ↔ gRPC bytes ─────────────────────────────────────────────────
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+/** A socket payload as it rides the gRPC `bytes payload` field: the UTF-8 of
+ *  its JSON. `undefined` (a job that sent nothing) is carried as `null` so the
+ *  bytes are always valid JSON. */
+export function encodeMigrationPayload(payload) {
+    return utf8Encoder.encode(JSON.stringify(payload === undefined ? null : payload));
+}
+/** The inverse of {@link encodeMigrationPayload}. Empty bytes — a gRPC
+ *  message with the field unset — read as `null`; bytes that are not JSON
+ *  come back as the raw string rather than being dropped, so a foreign
+ *  Manager's opaque payload still reaches the job. */
+export function decodeMigrationPayload(bytes) {
+    if (!bytes || bytes.byteLength === 0)
+        return null;
+    const text = utf8Decoder.decode(bytes);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "type": "module",
   "exports": {
     ".": {
@@ -26,6 +26,10 @@
     "./workdir-path": {
       "types": "./workdir-path.d.ts",
       "default": "./workdir-path.js"
+    },
+    "./migration-socket": {
+      "types": "./migration-socket.d.ts",
+      "default": "./migration-socket.js"
     }
   },
   "main": "./index.js",