@norskvideo/ctl-product-template-schema 0.1.51 → 0.1.53

package/index.d.ts

@@ -150,6 +150,11 @@ export declare const ProductTemplateMigrationSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export type ProductTemplateMigration = z.infer<typeof ProductTemplateMigrationSchema>;
+export declare const ProductTemplateLeaseSchema: z.ZodObject<{
+    protected: z.ZodLiteral<true>;
+    graceMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ProductTemplateLease = z.infer<typeof ProductTemplateLeaseSchema>;
 export declare const PRODUCT_TEMPLATE_WORKLOAD_ROLES: readonly ["viewer", "operator", "builder"];
 export declare const ProductTemplateWorkloadSchema: z.ZodObject<{
     role: z.ZodEnum<{
@@ -352,6 +357,10 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
         name: z.ZodString;
         version: z.ZodNumber;
     }, z.core.$catchall<z.ZodUnknown>>>>;
+    lease: z.ZodOptional<z.ZodObject<{
+        protected: z.ZodLiteral<true>;
+        graceMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
     migration: z.ZodOptional<z.ZodObject<{
         strategy: z.ZodEnum<{
             overlap: "overlap";
@@ -609,6 +618,10 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             name: z.ZodString;
             version: z.ZodNumber;
         }, z.core.$catchall<z.ZodUnknown>>>>;
+        lease: z.ZodOptional<z.ZodObject<{
+            protected: z.ZodLiteral<true>;
+            graceMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
         migration: z.ZodOptional<z.ZodObject<{
             strategy: z.ZodEnum<{
                 overlap: "overlap";
@@ -658,5 +671,5 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ProductTemplateMaterials = z.infer<typeof ProductTemplateMaterialsSchema>;
-export { declareMediaConversion, interfaceDeclarationProblems, MEDIA_CONVERSION_INTERFACE, type MediaConversionV1, MediaConversionV1Schema, mediaConversionOf, type ProductTemplateInterface, ProductTemplateInterfaceSchema, } from "./interfaces.js";
+export { CONVERSION_TARGET_FORMAT, declareMediaConversion, interfaceDeclarationProblems, MEDIA_CONVERSION_INTERFACE, MEDIA_CONVERSION_VERSION, type MediaConversion, MediaConversionSchema, mediaConversionOf, type ProductTemplateInterface, ProductTemplateInterfaceSchema, } from "./interfaces.js";
 export { composeServiceNamesOf, logsDeclarationProblems, NORSK_MEDIA_SERVICE_LOGS, type ProductTemplateLogs, ProductTemplateLogsSchema, productTemplateLogsProblems, type ServiceLogs, ServiceLogsSchema, STANDARD_LOGS, STUDIO_SERVICE_LOGS, servicesWithoutLogs, } from "./logs.js";

package/index.js

@@ -320,6 +320,24 @@ export const ProductTemplateMigrationSchema = z
     }),
 })
     .meta({ id: "ProductTemplateMigration", outputId: "ProductTemplateMigration" });
+// Lease-protected instances (norsk task 115 Phase 6; protocol 1.6). A product
+// whose instance holds something that must never be in use by two encoders
+// at once — an Akamai entry point, a multicast address, a SIP number —
+// declares it here; the Manager does not need to know what the thing is.
+// An instance lost uncleanly (its worker dropped off the network) is then
+// not started again until `graceMs` has passed (absent: the deployment's,
+// 60 s by default), and its worker stops it when it can no longer reach a
+// live Manager. A clean stop needs no grace. Pair it with the default
+// `stopThenStart` migration: an `overlap` migration would run two at once,
+// which the Manager refuses for a lease-protected instance.
+export const ProductTemplateLeaseSchema = z
+    .object({
+    protected: z.literal(true).meta({ description: "This product's instances are lease-protected." }),
+    graceMs: z.number().int().positive().max(3_600_000).optional().meta({
+        description: "How long an instance whose worker was lost uncleanly waits before it may start elsewhere, in ms. Must exceed the workers' lease deadline (30 s by default) by a margin. Absent: the deployment's (60 s by default).",
+    }),
+})
+    .meta({ id: "ProductTemplateLease", outputId: "ProductTemplateLease" });
 // The roles a template may declare for its instances' workload: at most
 // builder, since registering a template takes builder and that registration is
 // the consent. Built-in names only, whose meaning every host agrees on.
@@ -388,6 +406,9 @@ export const ProductTemplateManifestSchema = z
     interfaces: z.array(ProductTemplateInterfaceSchema).optional().meta({
         description: "Named, versioned contracts this template implements (e.g. norsk.io/media-conversion), so a client can find the templates that implement one whatever product built them. Each entry is carried verbatim; the runner checks only contracts it knows, so a template declaring one an older ctl does not know still launches. Absent = implements none.",
     }),
+    lease: ProductTemplateLeaseSchema.optional().meta({
+        description: "Lease-protected instances: each holds something that must never be in use by two encoders at once. An instance lost uncleanly is not started again until its grace has passed; a clean stop needs none.",
+    }),
     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.",
     }),
@@ -503,5 +524,5 @@ export const ProductTemplateMaterialsSchema = z
     }),
 })
     .meta({ id: "ProductTemplateMaterials" });
-export { declareMediaConversion, interfaceDeclarationProblems, MEDIA_CONVERSION_INTERFACE, MediaConversionV1Schema, mediaConversionOf, ProductTemplateInterfaceSchema, } from "./interfaces.js";
+export { CONVERSION_TARGET_FORMAT, declareMediaConversion, interfaceDeclarationProblems, MEDIA_CONVERSION_INTERFACE, MEDIA_CONVERSION_VERSION, MediaConversionSchema, mediaConversionOf, ProductTemplateInterfaceSchema, } from "./interfaces.js";
 export { composeServiceNamesOf, logsDeclarationProblems, NORSK_MEDIA_SERVICE_LOGS, ProductTemplateLogsSchema, productTemplateLogsProblems, ServiceLogsSchema, STANDARD_LOGS, STUDIO_SERVICE_LOGS, servicesWithoutLogs, } from "./logs.js";

package/interfaces.d.ts

@@ -6,9 +6,17 @@ export declare const ProductTemplateInterfaceSchema: z.ZodObject<{
 }, z.core.$catchall<z.ZodUnknown>>;
 export type ProductTemplateInterface = z.infer<typeof ProductTemplateInterfaceSchema>;
 export declare const MEDIA_CONVERSION_INTERFACE = "norsk.io/media-conversion";
-export declare const MediaConversionV1Schema: z.ZodObject<{
+/** The version of norsk.io/media-conversion this package knows. Version 1 (a
+ *  fixed list of outputs, flat parameters) was retired before any caller used
+ *  it; its number is not reused, so a reader of the old v1 never misreads this. */
+export declare const MEDIA_CONVERSION_VERSION = 2;
+/** The format a conversion's target follows: the conversion core's
+ *  ConversionTarget (@norskvideo/norsk-studio-standards-conversion). Naming it
+ *  tells a caller it can plan the conversion itself, with the same core. */
+export declare const CONVERSION_TARGET_FORMAT = "norsk.io/conversion-target";
+export declare const MediaConversionSchema: z.ZodObject<{
     name: z.ZodLiteral<"norsk.io/media-conversion">;
-    version: z.ZodLiteral<1>;
+    version: z.ZodLiteral<2>;
     inputs: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         kinds: z.ZodRecord<z.ZodEnum<{
@@ -21,47 +29,50 @@ export declare const MediaConversionV1Schema: z.ZodObject<{
             max: z.ZodNumber;
         }, z.core.$strip>]>>;
     }, z.core.$strip>>;
-    outputs: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodEnum<{
-            video: "video";
-            audio: "audio";
-            subtitle: "subtitle";
-            ancillary: "ancillary";
-        }>;
-        count: z.ZodOptional<z.ZodNumber>;
-        format: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    }, z.core.$strip>>;
+    returns: z.ZodLiteral<"programme">;
     transports: z.ZodArray<z.ZodString>;
     timeline: z.ZodString;
+    target: z.ZodObject<{
+        format: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+    profiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        target: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>>;
     bindings: z.ZodObject<{
         sourceUrl: z.ZodString;
         returnName: z.ZodString;
+        target: z.ZodString;
         engineVersion: z.ZodOptional<z.ZodString>;
         conversionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
-export type MediaConversionV1 = z.infer<typeof MediaConversionV1Schema>;
+export type MediaConversion = z.infer<typeof MediaConversionSchema>;
 /** Everything wrong with a template's interface declarations, given the
  *  parameters it declares. Only known interfaces are checked. Empty = fine. */
 export declare function interfaceDeclarationProblems(template: {
     manifest: Pick<ProductTemplateManifest, "interfaces">;
     parameters: Pick<ProductTemplateParameter, "name">[];
 }): string[];
-/** The template's norsk.io/media-conversion v1 declaration, typed, if it
+/** The template's norsk.io/media-conversion declaration, typed, if it
  *  declares a valid one. */
-export declare function mediaConversionOf(manifest: Pick<ProductTemplateManifest, "interfaces">): MediaConversionV1 | undefined;
-type BindingRole = keyof MediaConversionV1["bindings"];
-/** A norsk.io/media-conversion v1 declaration and the parameters its
- *  bindings name, built together so a template cannot bind a parameter it
- *  never declared. Spread `parameters` into the template's parameters.yaml and
+export declare function mediaConversionOf(manifest: Pick<ProductTemplateManifest, "interfaces">): MediaConversion | undefined;
+type BindingRole = keyof MediaConversion["bindings"];
+/** A norsk.io/media-conversion declaration and the parameters its bindings
+ *  name, built together so a template cannot bind a parameter it never
+ *  declared. Spread `parameters` into the template's parameters.yaml and
  *  `interface` into its manifest's `interfaces`. Each binding defaults to a
- *  conventional parameter name; pass a name to use the template's own, or
- *  null to leave an optional role out. */
-export declare function declareMediaConversion(shape: Omit<MediaConversionV1, "name" | "version" | "bindings"> & {
+ *  conventional parameter name; pass a name to use the template's own, or null
+ *  to leave an optional role out. The target format defaults to the
+ *  conversion core's. */
+export declare function declareMediaConversion(shape: Omit<MediaConversion, "name" | "version" | "bindings" | "returns" | "target"> & {
+    target?: MediaConversion["target"];
     bindings?: Partial<Record<BindingRole, string | null>>;
 }): {
-    interface: MediaConversionV1;
+    interface: MediaConversion;
     parameters: ProductTemplateParameter[];
 };
 export {};

package/interfaces.js

@@ -25,6 +25,10 @@ export const ProductTemplateInterfaceSchema = z
     description: "A contract the template implements: its name and version, and the body that contract defines. Carried verbatim; a runner checks only the contracts it knows.",
 });
 export const MEDIA_CONVERSION_INTERFACE = "norsk.io/media-conversion";
+/** The version of norsk.io/media-conversion this package knows. Version 1 (a
+ *  fixed list of outputs, flat parameters) was retired before any caller used
+ *  it; its number is not reused, so a reader of the old v1 never misreads this. */
+export const MEDIA_CONVERSION_VERSION = 2;
 const PARAMETER_NAME = /^[A-Z][A-Z0-9_]*$/;
 const parameterName = z.string().regex(PARAMETER_NAME, "a parameter name");
 const MediaKindSchema = z.enum(["video", "audio", "subtitle", "ancillary"]);
@@ -34,53 +38,62 @@ const KindCountSchema = z.union([
         .object({ min: z.number().int().min(0), max: z.number().int().min(0) })
         .refine((r) => r.min <= r.max, { message: "min must be <= max" }),
 ]);
-export const MediaConversionV1Schema = z.object({
+/** The format a conversion's target follows: the conversion core's
+ *  ConversionTarget (@norskvideo/norsk-studio-standards-conversion). Naming it
+ *  tells a caller it can plan the conversion itself, with the same core. */
+export const CONVERSION_TARGET_FORMAT = "norsk.io/conversion-target";
+export const MediaConversionSchema = z.object({
     name: z.literal(MEDIA_CONVERSION_INTERFACE),
-    version: z.literal(1),
-    // What the converter takes from the relay: per named input, how many tracks
+    version: z.literal(MEDIA_CONVERSION_VERSION),
+    // What the converter takes from the caller: per named input, how many tracks
     // of each kind (a count, or a range).
     inputs: z
         .array(z.object({ name: z.string().min(1), kinds: z.partialRecord(MediaKindSchema, KindCountSchema) }))
         .min(1),
-    // What it hands back. A format value may refer to a parameter as ${NAME}, so
-    // a client can show the result of a launch before it happens.
-    outputs: z
-        .array(z.object({
-        name: z.string().min(1),
-        kind: MediaKindSchema,
-        count: z.number().int().min(1).optional(),
-        format: z.record(z.string(), z.string()).optional(),
-    }))
-        .min(1),
+    // What comes back: the input programme, each track converted as the target
+    // says or passed, under its own stream key.
+    returns: z.literal("programme"),
     // Free strings rather than an enum: a template offering a transport this ctl
     // does not know (srt, moq) must still validate; the client picks one it speaks.
     transports: z.array(z.string().min(1)).min(1),
     timeline: z.string().min(1),
+    // The format of the value the target binding carries, and its version.
+    target: z.object({ format: z.string().min(1), version: z.number().int().min(1) }),
+    // Named targets for the common jobs, which a client offers before the
+    // target's own fields. A profile's target is in the target's format.
+    profiles: z
+        .array(z.object({
+        name: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "a lower-case slug"),
+        label: z.string().min(1),
+        description: z.string().optional(),
+        target: z.record(z.string(), z.unknown()),
+    }))
+        .optional(),
     // The template's own parameters the client fills, by role.
     bindings: z.object({
         sourceUrl: parameterName,
         returnName: parameterName,
+        target: parameterName,
         engineVersion: parameterName.optional(),
         conversionId: parameterName.optional(),
     }),
 });
-const PARAMETER_REFERENCE = /\$\{([^}]*)\}/g;
 /** Everything wrong with a template's interface declarations, given the
  *  parameters it declares. Only known interfaces are checked. Empty = fine. */
 export function interfaceDeclarationProblems(template) {
     const declared = new Set(template.parameters.map((p) => p.name));
-    const seen = new Set();
+    let seen = false;
     const problems = [];
     (template.manifest.interfaces ?? []).forEach((decl, i) => {
-        if (decl.name !== MEDIA_CONVERSION_INTERFACE || decl.version !== 1)
+        if (decl.name !== MEDIA_CONVERSION_INTERFACE || decl.version !== MEDIA_CONVERSION_VERSION)
             return;
         const at = `interfaces[${i}] (${decl.name} v${decl.version})`;
-        if (seen.has(`${decl.name}@${decl.version}`)) {
+        if (seen) {
             problems.push(`${at}: declared more than once`);
             return;
         }
-        seen.add(`${decl.name}@${decl.version}`);
-        const parsed = MediaConversionV1Schema.safeParse(decl);
+        seen = true;
+        const parsed = MediaConversionSchema.safeParse(decl);
         if (!parsed.success) {
             for (const issue of parsed.error.issues) {
                 problems.push(`${at}: ${issue.path.join(".") || "(declaration)"}: ${issue.message}`);
@@ -92,25 +105,16 @@ export function interfaceDeclarationProblems(template) {
                 problems.push(`${at}: binding ${role} names ${param}, which is not a declared parameter`);
             }
         }
-        parsed.data.outputs.forEach((output, o) => {
-            for (const [key, value] of Object.entries(output.format ?? {})) {
-                for (const [, ref] of value.matchAll(PARAMETER_REFERENCE)) {
-                    if (!declared.has(ref)) {
-                        problems.push(`${at}: outputs[${o}].format.${key} refers to ${ref}, which is not a declared parameter`);
-                    }
-                }
-            }
-        });
     });
     return problems;
 }
-/** The template's norsk.io/media-conversion v1 declaration, typed, if it
+/** The template's norsk.io/media-conversion declaration, typed, if it
  *  declares a valid one. */
 export function mediaConversionOf(manifest) {
     for (const decl of manifest.interfaces ?? []) {
-        if (decl.name !== MEDIA_CONVERSION_INTERFACE || decl.version !== 1)
+        if (decl.name !== MEDIA_CONVERSION_INTERFACE || decl.version !== MEDIA_CONVERSION_VERSION)
             continue;
-        const parsed = MediaConversionV1Schema.safeParse(decl);
+        const parsed = MediaConversionSchema.safeParse(decl);
         if (parsed.success)
             return parsed.data;
     }
@@ -129,6 +133,12 @@ const BINDING_DEFAULTS = {
         purpose: "The name to publish the converted media under, for the caller to take it back. Filled by the caller.",
         required: true,
     },
+    target: {
+        name: "CONVERSION_TARGET",
+        label: "Conversion target",
+        purpose: "What the converted programme should be, as JSON in the declared target format. Filled by the caller.",
+        required: true,
+    },
     engineVersion: {
         name: "ENGINE_VERSION",
         label: "Engine version",
@@ -143,14 +153,15 @@ const BINDING_DEFAULTS = {
     },
 };
 const BINDING_GROUP = "Conversion link";
-/** A norsk.io/media-conversion v1 declaration and the parameters its
- *  bindings name, built together so a template cannot bind a parameter it
- *  never declared. Spread `parameters` into the template's parameters.yaml and
+/** A norsk.io/media-conversion declaration and the parameters its bindings
+ *  name, built together so a template cannot bind a parameter it never
+ *  declared. Spread `parameters` into the template's parameters.yaml and
  *  `interface` into its manifest's `interfaces`. Each binding defaults to a
- *  conventional parameter name; pass a name to use the template's own, or
- *  null to leave an optional role out. */
+ *  conventional parameter name; pass a name to use the template's own, or null
+ *  to leave an optional role out. The target format defaults to the
+ *  conversion core's. */
 export function declareMediaConversion(shape) {
-    const { bindings: chosen = {}, ...rest } = shape;
+    const { bindings: chosen = {}, target = { format: CONVERSION_TARGET_FORMAT, version: 1 }, ...rest } = shape;
     const bindings = {};
     const parameters = [];
     for (const role of Object.keys(BINDING_DEFAULTS)) {
@@ -168,9 +179,11 @@ export function declareMediaConversion(shape) {
             ...(fallback.required ? { required: true } : {}),
         });
     }
-    const declaration = MediaConversionV1Schema.parse({
+    const declaration = MediaConversionSchema.parse({
         name: MEDIA_CONVERSION_INTERFACE,
-        version: 1,
+        version: MEDIA_CONVERSION_VERSION,
+        returns: "programme",
+        target,
         ...rest,
         bindings,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "type": "module",
   "exports": {
     ".": {