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

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;
@@ -159,6 +170,7 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
     isStudio: z.ZodOptional<z.ZodBoolean>;
     supportsCustomAssets: z.ZodOptional<z.ZodBoolean>;
     requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
+    studioAccessModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sideload: z.ZodOptional<z.ZodObject<{
         gpuInference: z.ZodOptional<z.ZodBoolean>;
         models: z.ZodOptional<z.ZodBoolean>;
@@ -267,8 +279,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: {};
@@ -354,6 +377,7 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
         isStudio: z.ZodOptional<z.ZodBoolean>;
         supportsCustomAssets: z.ZodOptional<z.ZodBoolean>;
         requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
+        studioAccessModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         sideload: z.ZodOptional<z.ZodObject<{
             gpuInference: z.ZodOptional<z.ZodBoolean>;
             models: z.ZodOptional<z.ZodBoolean>;
@@ -462,6 +486,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),
@@ -292,6 +306,9 @@ export const ProductTemplateManifestSchema = z
     requiresWorkingDirectory: z.boolean().optional().meta({
         description: "When true, the operator must choose a working directory at launch (a dev product template they own and keep), rather than getting the auto-assigned per-instance default. The runner's launch UI makes the working-directory field mandatory.",
     }),
+    studioAccessModes: z.array(z.string().min(1)).optional().meta({
+        description: "The NORSK_STUDIO_ACCESS values the Studio image THIS product template pins understands. The launcher sets that variable only when the mode it is in appears here; absent, it sets nothing and Studio runs with its gate dormant, as it does today. Declared here rather than on the product manifest because this template's compose.yml is what pins the Studio image, so the declaration and the image it vouches for travel in one tar. A list rather than a boolean: a launcher must never send a word this image predates, and an unrecognised value resolves to refusing everything inside Studio.",
+    }),
     sideload: ProductTemplateSideloadSchema.optional().meta({
         description: "CUDA sideload bundle needs. Only gpu-inference is declared (gpu-video follows the GPU reservation automatically). The runner mounts the matching bundle when the image is slimmed and the GPU is reserved.",
     }),
@@ -304,8 +321,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.21",
   "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",