@norskvideo/ctl-product-template-schema 0.1.26 → 0.1.28

package/index.d.ts

@@ -155,9 +155,9 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
         runtimeScreenLabel: z.ZodOptional<z.ZodString>;
         runtimeScreenService: z.ZodOptional<z.ZodString>;
         runtimeScreenReadyWhen: z.ZodOptional<z.ZodEnum<{
+            never: "never";
             running: "running";
             healthy: "healthy";
-            never: "never";
         }>>;
         runtimeReadyPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
@@ -297,6 +297,25 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
         preferred: z.ZodNumber;
         label: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    logs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodEnum<{
+            json: "json";
+            text: "text";
+            none: "none";
+        }>>;
+        files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            format: z.ZodEnum<{
+                json: "json";
+                text: "text";
+            }>;
+        }, z.core.$strict>>>;
+        fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            configFlag: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            configPath: z.ZodString;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>>>;
     migration: z.ZodOptional<z.ZodObject<{
         strategy: z.ZodEnum<{
             overlap: "overlap";
@@ -371,9 +390,9 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             runtimeScreenLabel: z.ZodOptional<z.ZodString>;
             runtimeScreenService: z.ZodOptional<z.ZodString>;
             runtimeScreenReadyWhen: z.ZodOptional<z.ZodEnum<{
+                never: "never";
                 running: "running";
                 healthy: "healthy";
-                never: "never";
             }>>;
             runtimeReadyPath: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
@@ -513,6 +532,25 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             preferred: z.ZodNumber;
             label: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        logs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            stdout: z.ZodOptional<z.ZodEnum<{
+                json: "json";
+                text: "text";
+                none: "none";
+            }>>;
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                format: z.ZodEnum<{
+                    json: "json";
+                    text: "text";
+                }>;
+            }, z.core.$strict>>>;
+            fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                configFlag: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                configPath: z.ZodString;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>>>;
         migration: z.ZodOptional<z.ZodObject<{
             strategy: z.ZodEnum<{
                 overlap: "overlap";
@@ -560,4 +598,4 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ProductTemplateMaterials = z.infer<typeof ProductTemplateMaterialsSchema>;
-export {};
+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 { 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
 // the unpacked tar.
@@ -335,6 +336,7 @@ 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.",
     }),
+    logs: ProductTemplateLogsSchema.optional(),
     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.",
     }),
@@ -442,3 +444,4 @@ export const ProductTemplateMaterialsSchema = z
     }),
 })
     .meta({ id: "ProductTemplateMaterials" });
+export { composeServiceNamesOf, logsDeclarationProblems, NORSK_MEDIA_SERVICE_LOGS, ProductTemplateLogsSchema, productTemplateLogsProblems, ServiceLogsSchema, STANDARD_LOGS, STUDIO_SERVICE_LOGS, servicesWithoutLogs, } from "./logs.js";

package/logs.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+export declare const ServiceLogFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    format: z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>;
+}, z.core.$strict>;
+export declare const ServiceFluentBitSchema: z.ZodUnion<readonly [z.ZodObject<{
+    configFlag: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    configPath: z.ZodString;
+}, z.core.$strict>]>;
+export declare const ServiceLogsSchema: z.ZodObject<{
+    stdout: z.ZodOptional<z.ZodEnum<{
+        json: "json";
+        text: "text";
+        none: "none";
+    }>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        format: z.ZodEnum<{
+            json: "json";
+            text: "text";
+        }>;
+    }, z.core.$strict>>>;
+    fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        configFlag: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        configPath: z.ZodString;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+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";
+    }>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        format: z.ZodEnum<{
+            json: "json";
+            text: "text";
+        }>;
+    }, z.core.$strict>>>;
+    fluentBit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        configFlag: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        configPath: z.ZodString;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>>;
+export type ProductTemplateLogs = z.infer<typeof ProductTemplateLogsSchema>;
+/** The service names a compose file defines (empty if it is not a compose
+ *  document with `services`). */
+export declare function composeServiceNamesOf(composeYaml: string): string[];
+/** Problems that make a `logs` block unusable: a service compose.yml does not
+ *  define, or two files of one service in the same directory with different
+ *  formats (they are mounted together, so they would be read one way). */
+export declare function logsDeclarationProblems(logs: ProductTemplateLogs | undefined, composeYaml: string): string[];
+/** Compose services with no `logs` entry — what the dev-kit refuses, so a new
+ *  sidecar cannot ship nothing (or garbage) without anyone deciding so. */
+export declare function servicesWithoutLogs(logs: ProductTemplateLogs | undefined, composeYaml: string): string[];
+/** Everything wrong with a product template's logging, for a product's own
+ *  tests (the dev-kit's drift gate requires one to call this): an unusable
+ *  `logs` block, and every compose service without an entry. Empty = fine. */
+export declare function productTemplateLogsProblems(materials: {
+    manifest: {
+        logs?: ProductTemplateLogs;
+    };
+    composeYaml: string;
+}): string[];
+/** Norsk Studio (the `studio` service every Studio-based product runs): its
+ *  winston logger writes one JSON object per line to debug.log under the
+ *  config's server.logs — /usr/src/app/logs in the image — while its stdout is
+ *  a coloured, multi-line copy for humans, so it is not shipped. (error.log
+ *  beside it repeats debug.log's errors, so it is not declared.) */
+export declare const STUDIO_SERVICE_LOGS: ServiceLogs;
+/** The Norsk engine (the `media` service): it runs its own fluent-bit, which
+ *  already collects its logs and stdout/stderr (tags media-erlang,
+ *  media-rust, media-stderr), and @INCLUDEs the outputs file named by
+ *  --log-config-file. */
+export declare const NORSK_MEDIA_SERVICE_LOGS: ServiceLogs;
+/** The `logs:` block for the reserved studio + media pair. A product with
+ *  more services spreads this and declares its own beside it. */
+export declare const STANDARD_LOGS: ProductTemplateLogs;

package/logs.js

@@ -0,0 +1,116 @@
+// How each of a product's compose services logs, so the node's log agent can
+// ship it (norsk-mgr docs/internal/design/product-logs.md). The worker reads
+// this; the product never names a destination.
+import { parse as yamlParse } from "yaml";
+import { z } from "zod";
+const absolutePath = z.string().regex(/^\/[^\0]*[^/]$/, "an absolute path to a file (not a directory, no trailing /)");
+export const ServiceLogFileSchema = z
+    .strictObject({
+    path: absolutePath.meta({
+        description: "The log file inside the container. Its directory is mounted onto the host.",
+    }),
+    format: z
+        .enum(["json", "text"])
+        .meta({ description: "json = one JSON object per line; text = one event per line." }),
+})
+    .meta({ id: "ServiceLogFile" });
+export const ServiceFluentBitSchema = z
+    .union([
+    z.strictObject({
+        configFlag: z
+            .string()
+            .regex(/^--?[A-Za-z0-9][A-Za-z0-9-]*$/, "a command-line flag, e.g. --log-config-file")
+            .meta({ description: "Appended to the service's command, followed by the mounted outputs file's path." }),
+    }),
+    z.strictObject({
+        configPath: absolutePath.meta({
+            description: "Where the outputs file is mounted; the image reads it from there.",
+        }),
+    }),
+])
+    .meta({
+    id: "ServiceFluentBit",
+    description: "The service runs its own fluent-bit and reads an [OUTPUT] file: the worker hands it the node's (forward to the log agent, or the operator's config without one).",
+});
+export const ServiceLogsSchema = z
+    .strictObject({
+    stdout: z.enum(["text", "json", "none"]).optional().meta({
+        description: "The service's stdout/stderr: text (default; one event per line), json (one JSON object per line), none (not shipped — e.g. a human-readable copy of a log declared under files).",
+    }),
+    files: z.array(ServiceLogFileSchema).optional(),
+    fluentBit: ServiceFluentBitSchema.optional(),
+})
+    .meta({ id: "ServiceLogs" });
+export const ProductTemplateLogsSchema = z.record(z.string().min(1), ServiceLogsSchema).meta({
+    id: "ProductTemplateLogs",
+    description: "Per compose service: how it logs, so the node's log agent ships it. Absent = the runner's defaults (the `media` service gets --log-config-file, Studio's log directory is mounted). The dev-kit requires every service to have an entry.",
+});
+/** The service names a compose file defines (empty if it is not a compose
+ *  document with `services`). */
+export function composeServiceNamesOf(composeYaml) {
+    const doc = yamlParse(composeYaml);
+    return doc?.services && typeof doc.services === "object" ? Object.keys(doc.services) : [];
+}
+/** Problems that make a `logs` block unusable: a service compose.yml does not
+ *  define, or two files of one service in the same directory with different
+ *  formats (they are mounted together, so they would be read one way). */
+export function logsDeclarationProblems(logs, composeYaml) {
+    if (!logs)
+        return [];
+    const services = new Set(composeServiceNamesOf(composeYaml));
+    const problems = [];
+    for (const [service, decl] of Object.entries(logs)) {
+        if (!services.has(service))
+            problems.push(`logs.${service}: compose.yml has no service '${service}'`);
+        const formatByDir = new Map();
+        for (const f of decl.files ?? []) {
+            const dir = f.path.slice(0, f.path.lastIndexOf("/")) || "/";
+            if (dir === "/")
+                problems.push(`logs.${service}: ${f.path} sits in / — a log file needs a directory of its own`);
+            const seen = formatByDir.get(dir);
+            if (seen !== undefined && seen !== f.format) {
+                problems.push(`logs.${service}: files in ${dir} are declared both ${seen} and ${f.format}`);
+            }
+            formatByDir.set(dir, f.format);
+        }
+    }
+    return problems;
+}
+/** Compose services with no `logs` entry — what the dev-kit refuses, so a new
+ *  sidecar cannot ship nothing (or garbage) without anyone deciding so. */
+export function servicesWithoutLogs(logs, composeYaml) {
+    const declared = new Set(Object.keys(logs ?? {}));
+    return composeServiceNamesOf(composeYaml).filter((s) => !declared.has(s));
+}
+/** Everything wrong with a product template's logging, for a product's own
+ *  tests (the dev-kit's drift gate requires one to call this): an unusable
+ *  `logs` block, and every compose service without an entry. Empty = fine. */
+export function productTemplateLogsProblems(materials) {
+    return [
+        ...logsDeclarationProblems(materials.manifest.logs, materials.composeYaml),
+        ...servicesWithoutLogs(materials.manifest.logs, materials.composeYaml).map((s) => `compose service '${s}' has no logs entry — say how it logs (stdout/files/fluentBit), or \`${s}: { stdout: none }\``),
+    ];
+}
+/** Norsk Studio (the `studio` service every Studio-based product runs): its
+ *  winston logger writes one JSON object per line to debug.log under the
+ *  config's server.logs — /usr/src/app/logs in the image — while its stdout is
+ *  a coloured, multi-line copy for humans, so it is not shipped. (error.log
+ *  beside it repeats debug.log's errors, so it is not declared.) */
+export const STUDIO_SERVICE_LOGS = {
+    stdout: "none",
+    files: [{ path: "/usr/src/app/logs/debug.log", format: "json" }],
+};
+/** The Norsk engine (the `media` service): it runs its own fluent-bit, which
+ *  already collects its logs and stdout/stderr (tags media-erlang,
+ *  media-rust, media-stderr), and @INCLUDEs the outputs file named by
+ *  --log-config-file. */
+export const NORSK_MEDIA_SERVICE_LOGS = {
+    stdout: "none",
+    fluentBit: { configFlag: "--log-config-file" },
+};
+/** The `logs:` block for the reserved studio + media pair. A product with
+ *  more services spreads this and declares its own beside it. */
+export const STANDARD_LOGS = {
+    studio: STUDIO_SERVICE_LOGS,
+    media: NORSK_MEDIA_SERVICE_LOGS,
+};

package/package.json

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