@norskvideo/ctl-sdk 0.1.52 → 0.1.54

package/manifest-schema.d.ts

@@ -9,6 +9,29 @@ declare const DefaultProductTemplateSchema: z.ZodObject<{
     url: z.ZodString;
 }, z.core.$strip>;
 export type DefaultProductTemplate = z.infer<typeof DefaultProductTemplateSchema>;
+declare const DefaultDashboardSchema: z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    hosting: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"own">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"shared">;
+        group: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"pattern">;
+        pattern: z.ZodString;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"production">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"production-template">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"label">;
+            label: z.ZodString;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>], "mode">>;
+}, z.core.$strip>;
+export type DefaultDashboard = z.infer<typeof DefaultDashboardSchema>;
 /** One product role (RFC 0003 D5a). The name rule is foundation's, so the
  *  runner that stamps it and the manifest that declares it cannot disagree. */
 declare const ProductRoleSchema: z.ZodObject<{
@@ -202,6 +225,28 @@ export declare const ManifestSchema: z.ZodObject<{
         name: z.ZodString;
         url: z.ZodString;
     }, z.core.$strip>>>;
+    defaultDashboards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+        hosting: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"own">;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"shared">;
+            group: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"pattern">;
+            pattern: z.ZodString;
+            scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"production">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"production-template">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"label">;
+                label: z.ZodString;
+            }, z.core.$strip>], "kind">;
+        }, z.core.$strip>], "mode">>;
+    }, z.core.$strip>>>;
     export: z.ZodOptional<z.ZodObject<{
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/manifest-schema.js

@@ -82,6 +82,38 @@ const DefaultProductTemplateSchema = z.object({
         description: "Path on the product's HTTP surface that returns the product-template tar. Resolved against the product's base URL — relative paths only (no scheme/host).",
     }),
 });
+/** A fleet dashboard the product brings (norsk-ctl task 123, RFC 0006): a
+ *  static bundle its control plane serves, registered with norsk-mgr when the
+ *  product is added and replaced in place on every reload. The hosting is a
+ *  proposal: the operator's choice, once made, is kept. norsk-ctl serving
+ *  alone hosts no dashboards and ignores these. */
+const DashboardLabel = z
+    .string()
+    .regex(/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/, "one DNS label: lowercase letters, digits and hyphens, 1-63 chars");
+const DefaultDashboardSchema = z.object({
+    name: DashboardLabel.meta({ description: "The dashboard's name, and its host's label when it has one of its own." }),
+    displayName: z.string().min(1).optional(),
+    url: z
+        .string()
+        .regex(/^\/[^/]/, "a path on the product's own HTTP surface")
+        .meta({ description: "Path on the product's HTTP surface that returns the dashboard's bundle tar." }),
+    hosting: z
+        .discriminatedUnion("mode", [
+        z.object({ mode: z.literal("own") }),
+        z.object({ mode: z.literal("shared"), group: DashboardLabel }),
+        z.object({
+            mode: z.literal("pattern"),
+            pattern: z.string().min(1),
+            scope: z.discriminatedUnion("kind", [
+                z.object({ kind: z.literal("production") }),
+                z.object({ kind: z.literal("production-template") }),
+                z.object({ kind: z.literal("label"), label: z.string().min(1) }),
+            ]),
+        }),
+    ])
+        .optional()
+        .meta({ description: "The hosting proposed; absent is a host of its own." }),
+});
 /** Save-as-product-template file selection. When the runner exports a running
  *  instance's working directory into a new product template, it packs only files
  *  matching `include` and not matching `exclude` (glob patterns, relative to the
@@ -178,5 +210,8 @@ export const ManifestSchema = z.object({
     defaultProductTemplates: z.array(DefaultProductTemplateSchema).default([]).meta({
         description: "Product templates the runner auto-fetches at product-registration time. Each entry is GET'd against the product's base URL and stored under its `name` via the runner's product-template store. Lets a product offer 'zero-config' launch paths — operators add the product and immediately have a launchable product template without visiting configure.",
     }),
+    defaultDashboards: z.array(DefaultDashboardSchema).optional().meta({
+        description: "Fleet dashboards the product brings: norsk-mgr fetches each bundle from the product at registration and on every reload, registers it as the product's, and removes it with the product. norsk-ctl serving alone ignores them.",
+    }),
     export: ExportSchema.optional(),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "type": "module",
   "exports": {
     ".": {

package/product-service.d.ts

@@ -1,7 +1,7 @@
 import { type Result } from "@norskvideo/ctl-foundation";
 import { type ProductPlacement } from "./docker-runner.js";
 import { type LicenseStager } from "./license-registration.js";
-import type { Manifest, ProductRoleDeclaration } from "./manifest-schema.js";
+import type { DefaultDashboard, Manifest, ProductRoleDeclaration } from "./manifest-schema.js";
 import { type ProductReach } from "./product-reach.js";
 import type { ProductTemplateSource } from "./product-template-record.js";
 import type { ProductLicense, ProductRegistration, ProductSpec, RoleDefault } from "./product-types.js";
@@ -99,8 +99,22 @@ export interface ProductContainerOps {
 /** The real docker-runner wiring. Exported so a host can override one op
  *  (typically `pull`, onto its own docker adapter) and keep the rest. */
 export declare const defaultProductContainerOps: ProductContainerOps;
+/** A fleet dashboard a product brings, handed to the host to register or
+ *  replace in place (norsk-ctl task 123 G). */
+export type ImportDashboardBytesFn = (input: {
+    productName: string;
+    entry: DefaultDashboard;
+    bytes: Uint8Array;
+}) => Promise<void>;
 export interface ProductServiceOptions {
     store: ProductStore;
+    /** Optional: called once per `manifest.defaultDashboards` entry at add and
+     *  at every reload, with the bundle fetched from the product. Omit on hosts
+     *  that host no dashboards (norsk-ctl serving alone): they are then skipped. */
+    importDashboardBytes?: ImportDashboardBytesFn;
+    /** Optional: told when a product is removed, so the host removes the
+     *  dashboards it brought. */
+    removeProductDashboards?: (productName: string) => Promise<void>;
     /** Optional: called once per `manifest.defaultProductTemplates` entry at
      *  registration time. Omit on hosts that don't store product templates
      *  (defaultProductTemplates is then silently skipped). */
@@ -211,6 +225,8 @@ export declare class ProductService {
     private readonly store;
     private readonly importProductTemplateBytes?;
     private readonly refreshProductTemplateBytes?;
+    private readonly importDashboardBytes?;
+    private readonly removeProductDashboards?;
     private readonly stageLicense?;
     private readonly isDevUrlAlive;
     private readonly containerOps;
@@ -255,6 +271,9 @@ export declare class ProductService {
     private changed;
     add(spec: ProductSpec, opts?: AddProductOpts): Promise<AddProductResult>;
     private addSerialised;
+    /** Each dashboard the manifest declares, fetched from the product and handed
+     *  to the host; the warnings for those that could not be. */
+    private bringDashboards;
     remove(name: string): Promise<void>;
     private removeSerialised;
     /** Bring a registration up to date with what its image now serves. For a

package/product-service.js

@@ -55,6 +55,8 @@ export class ProductService {
     store;
     importProductTemplateBytes;
     refreshProductTemplateBytes;
+    importDashboardBytes;
+    removeProductDashboards;
     stageLicense;
     isDevUrlAlive;
     containerOps;
@@ -67,6 +69,8 @@ export class ProductService {
         this.store = opts.store;
         this.importProductTemplateBytes = opts.importProductTemplateBytes;
         this.refreshProductTemplateBytes = opts.refreshProductTemplateBytes;
+        this.importDashboardBytes = opts.importDashboardBytes;
+        this.removeProductDashboards = opts.removeProductDashboards;
         this.stageLicense = opts.stageLicense;
         this.isDevUrlAlive = opts.isDevUrlAlive ?? isDevUrlAlive;
         this.containerOps = opts.containerOps ?? defaultProductContainerOps;
@@ -374,10 +378,29 @@ export class ProductService {
                 }
             }
         }
+        warnings.push(...(await this.bringDashboards(manifest, baseUrl)));
         for (const w of warnings)
             logger.warn(`[product:${manifest.name}] ${w}`);
         return { registration, warnings };
     }
+    /** Each dashboard the manifest declares, fetched from the product and handed
+     *  to the host; the warnings for those that could not be. */
+    async bringDashboards(manifest, baseUrl) {
+        if (!this.importDashboardBytes)
+            return [];
+        const warnings = [];
+        for (const entry of manifest.defaultDashboards ?? []) {
+            try {
+                const bytes = await fetchProductTemplateBytes(baseUrl, entry.url, this.probeHeadersFor?.(manifest.name) ?? {});
+                await this.importDashboardBytes({ productName: manifest.name, entry, bytes });
+                logger.info(`Product '${manifest.name}': dashboard '${entry.name}' from ${entry.url}`);
+            }
+            catch (e) {
+                warnings.push(`dashboard '${entry.name}' from ${entry.url} failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        return warnings;
+    }
     async remove(name) {
         return this.changed(await this.mutations.run(() => this.removeSerialised(name)));
     }
@@ -395,6 +418,11 @@ export class ProductService {
         // so a re-added product of the same name is stamped anew.
         this.forgetIdentity?.(name);
         this.onRemoved?.(name);
+        // The product's dashboards go with it; a failure leaves them registered,
+        // for the operator to remove, rather than the product half-removed.
+        await this.removeProductDashboards?.(name).catch((e) => {
+            logger.warn(`[product:${name}] its dashboards were not removed: ${e instanceof Error ? e.message : String(e)}`);
+        });
         logger.info(`Product '${name}' removed`);
     }
     /** Bring a registration up to date with what its image now serves. For a
@@ -478,6 +506,7 @@ export class ProductService {
                 }
             }
         }
+        warnings.push(...(await this.bringDashboards(manifest, baseUrl)));
         for (const w of warnings)
             logger.warn(`[product:${name}] ${w}`);
         return { registration, warnings, containerRestarted, productTemplates };