@norskvideo/ctl-product-template-schema 0.1.34 → 0.1.35

package/index.d.ts

@@ -317,15 +317,15 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     logs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         stdout: z.ZodOptional<z.ZodEnum<{
-            json: "json";
-            text: "text";
             none: "none";
+            text: "text";
+            json: "json";
         }>>;
         files: z.ZodOptional<z.ZodArray<z.ZodObject<{
             path: z.ZodString;
             format: z.ZodEnum<{
-                json: "json";
                 text: "text";
+                json: "json";
             }>;
         }, z.core.$strict>>>;
         fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
@@ -348,6 +348,10 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
         }>;
         on: z.ZodLiteral<"product">;
     }, z.core.$strip>>;
+    interfaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$catchall<z.ZodUnknown>>>>;
     migration: z.ZodOptional<z.ZodObject<{
         strategy: z.ZodEnum<{
             overlap: "overlap";
@@ -381,6 +385,8 @@ export declare const ProductTemplateParameterSchema: z.ZodObject<{
     min: z.ZodOptional<z.ZodNumber>;
     max: z.ZodOptional<z.ZodNumber>;
     values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    label: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProductTemplateParameter = z.infer<typeof ProductTemplateParameterSchema>;
 export declare const ParametersFileSchema: z.ZodObject<{
@@ -400,6 +406,8 @@ export declare const ParametersFileSchema: z.ZodObject<{
         min: z.ZodOptional<z.ZodNumber>;
         max: z.ZodOptional<z.ZodNumber>;
         values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        label: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ParametersFile = z.infer<typeof ParametersFileSchema>;
@@ -566,15 +574,15 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         logs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             stdout: z.ZodOptional<z.ZodEnum<{
-                json: "json";
-                text: "text";
                 none: "none";
+                text: "text";
+                json: "json";
             }>>;
             files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
                 format: z.ZodEnum<{
-                    json: "json";
                     text: "text";
+                    json: "json";
                 }>;
             }, z.core.$strict>>>;
             fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
@@ -597,6 +605,10 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             }>;
             on: z.ZodLiteral<"product">;
         }, z.core.$strip>>;
+        interfaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodNumber;
+        }, z.core.$catchall<z.ZodUnknown>>>>;
         migration: z.ZodOptional<z.ZodObject<{
             strategy: z.ZodEnum<{
                 overlap: "overlap";
@@ -623,6 +635,8 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             min: z.ZodOptional<z.ZodNumber>;
             max: z.ZodOptional<z.ZodNumber>;
             values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            label: z.ZodOptional<z.ZodString>;
+            group: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     workflow: z.ZodOptional<z.ZodString>;
@@ -644,4 +658,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 { 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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ProductTemplateInterfaceSchema } from "./interfaces.js";
 import { ProductTemplateLogsSchema } from "./logs.js";
 // ProductTemplate format v1. A product template is a tar file at the wire; the schemas
 // below describe its parts before packing and how the runner validates
@@ -384,6 +385,9 @@ export const ProductTemplateManifestSchema = z
     workload: ProductTemplateWorkloadSchema.optional().meta({
         description: "The role each instance's own workload (`urn:norsk:workload:instance:<id>`) holds on its product (`product/<productName>`), granted when it launches, whoever launches it — for an instance that creates or manages its product's other instances (a capture launching recorders). At most `builder`: registering a template takes builder, and that registration is the consent. Absent = the workload holds nothing it was not passed at launch. An older ctl ignores it, and its instances hold nothing.",
     }),
+    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.",
+    }),
     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.",
     }),
@@ -421,6 +425,14 @@ export const ProductTemplateParameterSchema = z
     max: z.number().optional(),
     /** Allowed values for `enum` parameters (rendered as a dropdown). */
     values: z.array(z.string()).optional(),
+    // Display metadata for a form built from the template. Declaration order is
+    // display order, so there is no `order` field to disagree with it.
+    label: z.string().min(1).optional().meta({
+        description: "Short name to show for the parameter in a form, e.g. `Width`. Absent = the form shows the parameter name. `purpose` stays the longer help text.",
+    }),
+    group: z.string().min(1).optional().meta({
+        description: "Section of a form the parameter belongs in, e.g. `Output`. Groups appear in the order their first parameter is declared; ungrouped parameters come first. Absent = ungrouped.",
+    }),
 })
     .superRefine((p, ctx) => {
     if (p.type === "enum" && (!p.values || p.values.length === 0)) {
@@ -491,4 +503,5 @@ export const ProductTemplateMaterialsSchema = z
     }),
 })
     .meta({ id: "ProductTemplateMaterials" });
+export { declareMediaConversion, interfaceDeclarationProblems, MEDIA_CONVERSION_INTERFACE, MediaConversionV1Schema, 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

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import type { ProductTemplateManifest, ProductTemplateParameter } from "./index.js";
+export declare const ProductTemplateInterfaceSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNumber;
+}, 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<{
+    name: z.ZodLiteral<"norsk.io/media-conversion">;
+    version: z.ZodLiteral<1>;
+    inputs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kinds: z.ZodRecord<z.ZodEnum<{
+            video: "video";
+            audio: "audio";
+            subtitle: "subtitle";
+            ancillary: "ancillary";
+        }> & z.core.$partial, z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            min: z.ZodNumber;
+            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>>;
+    transports: z.ZodArray<z.ZodString>;
+    timeline: z.ZodString;
+    bindings: z.ZodObject<{
+        sourceUrl: z.ZodString;
+        returnName: 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>;
+/** 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
+ *  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
+ *  `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"> & {
+    bindings?: Partial<Record<BindingRole, string | null>>;
+}): {
+    interface: MediaConversionV1;
+    parameters: ProductTemplateParameter[];
+};
+export {};

package/interfaces.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+// Interfaces: named, versioned contracts a product template says it implements,
+// so a client can find every template that implements one without knowing which
+// product built it. The first is norsk.io/media-conversion: the relay lists the
+// production templates whose runtime implements it, and any product or turnkey
+// can provide one.
+//
+// The manifest field accepts ANY well-formed declaration and carries it
+// verbatim. Only the interfaces (and versions) this package knows are checked,
+// by interfaceDeclarationProblems: a newer product declaring something this ctl
+// has never heard of must still launch (RFC 0001), and a client that does know
+// it must still see it.
+export const ProductTemplateInterfaceSchema = z
+    .object({
+    name: z
+        .string()
+        .regex(/^[a-z0-9]+(\.[a-z0-9]+)+\/[a-z0-9]+(-[a-z0-9]+)*$/, "<domain>/<name>, e.g. norsk.io/media-conversion")
+        .meta({ description: "The contract, as <domain>/<name>, e.g. norsk.io/media-conversion." }),
+    version: z.number().int().min(1).meta({ description: "The version of the contract this declaration follows." }),
+})
+    .catchall(z.unknown())
+    .meta({
+    id: "ProductTemplateInterface",
+    outputId: "ProductTemplateInterface",
+    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";
+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"]);
+const KindCountSchema = z.union([
+    z.number().int().min(0),
+    z
+        .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({
+    name: z.literal(MEDIA_CONVERSION_INTERFACE),
+    version: z.literal(1),
+    // What the converter takes from the relay: 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),
+    // 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 template's own parameters the client fills, by role.
+    bindings: z.object({
+        sourceUrl: parameterName,
+        returnName: 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();
+    const problems = [];
+    (template.manifest.interfaces ?? []).forEach((decl, i) => {
+        if (decl.name !== MEDIA_CONVERSION_INTERFACE || decl.version !== 1)
+            return;
+        const at = `interfaces[${i}] (${decl.name} v${decl.version})`;
+        if (seen.has(`${decl.name}@${decl.version}`)) {
+            problems.push(`${at}: declared more than once`);
+            return;
+        }
+        seen.add(`${decl.name}@${decl.version}`);
+        const parsed = MediaConversionV1Schema.safeParse(decl);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+                problems.push(`${at}: ${issue.path.join(".") || "(declaration)"}: ${issue.message}`);
+            }
+            return;
+        }
+        for (const [role, param] of Object.entries(parsed.data.bindings)) {
+            if (param !== undefined && !declared.has(param)) {
+                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
+ *  declares a valid one. */
+export function mediaConversionOf(manifest) {
+    for (const decl of manifest.interfaces ?? []) {
+        if (decl.name !== MEDIA_CONVERSION_INTERFACE || decl.version !== 1)
+            continue;
+        const parsed = MediaConversionV1Schema.safeParse(decl);
+        if (parsed.success)
+            return parsed.data;
+    }
+    return undefined;
+}
+const BINDING_DEFAULTS = {
+    sourceUrl: {
+        name: "SOURCE_URL",
+        label: "Source",
+        purpose: "Where to pull the media to convert from, e.g. link://host:port/name. Filled by the caller.",
+        required: true,
+    },
+    returnName: {
+        name: "RETURN_NAME",
+        label: "Return name",
+        purpose: "The name to publish the converted media under, for the caller to take it back. Filled by the caller.",
+        required: true,
+    },
+    engineVersion: {
+        name: "ENGINE_VERSION",
+        label: "Engine version",
+        purpose: "The caller's engine build, which this template's must match while norsk-link needs one build at both ends. Filled by the caller.",
+        required: false,
+    },
+    conversionId: {
+        name: "CONVERSION_ID",
+        label: "Conversion id",
+        purpose: "The caller's id for this conversion, for logs and correlation. Filled by the caller.",
+        required: false,
+    },
+};
+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
+ *  `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 function declareMediaConversion(shape) {
+    const { bindings: chosen = {}, ...rest } = shape;
+    const bindings = {};
+    const parameters = [];
+    for (const role of Object.keys(BINDING_DEFAULTS)) {
+        const fallback = BINDING_DEFAULTS[role];
+        const name = chosen[role] === undefined ? fallback.name : chosen[role];
+        if (name === null)
+            continue;
+        bindings[role] = name;
+        parameters.push({
+            name,
+            purpose: fallback.purpose,
+            type: "string",
+            label: fallback.label,
+            group: BINDING_GROUP,
+            ...(fallback.required ? { required: true } : {}),
+        });
+    }
+    const declaration = MediaConversionV1Schema.parse({
+        name: MEDIA_CONVERSION_INTERFACE,
+        version: 1,
+        ...rest,
+        bindings,
+    });
+    return { interface: declaration, parameters };
+}

package/logs.d.ts

@@ -2,8 +2,8 @@ import { z } from "zod";
 export declare const ServiceLogFileSchema: z.ZodObject<{
     path: z.ZodString;
     format: z.ZodEnum<{
-        json: "json";
         text: "text";
+        json: "json";
     }>;
 }, z.core.$strict>;
 export declare const ServiceFluentBitSchema: z.ZodUnion<readonly [z.ZodObject<{
@@ -13,15 +13,15 @@ export declare const ServiceFluentBitSchema: z.ZodUnion<readonly [z.ZodObject<{
 }, z.core.$strict>]>;
 export declare const ServiceLogsSchema: z.ZodObject<{
     stdout: z.ZodOptional<z.ZodEnum<{
-        json: "json";
-        text: "text";
         none: "none";
+        text: "text";
+        json: "json";
     }>>;
     files: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         format: z.ZodEnum<{
-            json: "json";
             text: "text";
+            json: "json";
         }>;
     }, z.core.$strict>>>;
     fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
@@ -33,15 +33,15 @@ export declare const ServiceLogsSchema: z.ZodObject<{
 export type ServiceLogs = z.infer<typeof ServiceLogsSchema>;
 export declare const ProductTemplateLogsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     stdout: z.ZodOptional<z.ZodEnum<{
-        json: "json";
-        text: "text";
         none: "none";
+        text: "text";
+        json: "json";
     }>>;
     files: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         format: z.ZodEnum<{
-            json: "json";
             text: "text";
+            json: "json";
         }>;
     }, z.core.$strict>>>;
     fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{

package/package.json

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