@norskvideo/ctl-sdk 0.1.53 → 0.1.55

package/fleet.d.ts

@@ -49,6 +49,44 @@ export interface FleetWatch {
     synced(): boolean;
     close(): void;
 }
+/** A declared operation the runtime offers this dashboard. */
+export interface FleetOperation {
+    operationId: string;
+    method: string;
+    /** Under the runtime's instance root, with `{param}`s. */
+    path: string;
+    live: boolean;
+}
+export interface FleetCallInput {
+    params?: Readonly<Record<string, string | number>>;
+    query?: Readonly<Record<string, string>>;
+    body?: unknown;
+}
+export interface FleetLiveHandlers {
+    onOpen?: () => void;
+    onMessage?: (data: unknown) => void;
+    onClose?: () => void;
+}
+export interface FleetLive {
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(): void;
+}
+export interface FleetStateDocument<T = unknown> {
+    value: T;
+    revision: number;
+}
+/** Someone else wrote the document since it was read: `current` is theirs. */
+export declare class FleetStateConflict extends Error {
+    readonly current: FleetStateDocument;
+    constructor(current: FleetStateDocument);
+}
+interface WebSocketLike {
+    addEventListener(name: string, listener: (e: {
+        data?: unknown;
+    }) => void): void;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(): void;
+}
 interface EventSourceLike {
     addEventListener(name: string, listener: (e: {
         data: string;
@@ -60,15 +98,31 @@ export interface FleetOptions {
      *  `/api/v1/fleet` on the platform's own origin. */
     base?: string;
     fetch?: (url: string, init?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
         credentials?: "same-origin";
     }) => Promise<Response>;
     EventSource?: new (url: string, init?: {
         withCredentials?: boolean;
     }) => EventSourceLike;
+    WebSocket?: new (url: string) => WebSocketLike;
+    /** The page's origin, for a live operation's ws(s) URL; the page's own by default. */
+    origin?: string;
 }
 export interface Fleet {
     query(selection: FleetSelection): Promise<FleetDirectory>;
     watch(selection: FleetSelection, handlers?: FleetWatchHandlers): FleetWatch;
+    /** Call a runtime's declared operation; its JSON answer, or its text. */
+    call<T = unknown>(runtimeId: string, operationId: string, input?: FleetCallInput): Promise<T>;
+    /** Open a runtime's declared live operation. */
+    live(runtimeId: string, operationId: string, handlers: FleetLiveHandlers, input?: FleetCallInput): Promise<FleetLive>;
+    state: {
+        get<T = unknown>(key: string): Promise<FleetStateDocument<T> | undefined>;
+        /** Write at `revision` (omit for a new key); a FleetStateConflict when
+         *  someone else wrote since. */
+        put<T = unknown>(key: string, value: T, revision?: number): Promise<FleetStateDocument<T>>;
+    };
 }
 export declare function fleetClient(options?: FleetOptions): Fleet;
 /** The directory on the page's own origin, as a dashboard host serves it. */

package/fleet.js

@@ -7,10 +7,34 @@
 // dashboard's dev loop it is the platform's API, `/api/v1/fleet/`. The calls
 // are the same either way.
 //
-// Name the kinds a call reads with literals: ctl-dev-kit's dashboard build
-// derives the registration's `uses` from them, and refuses one it cannot read.
+// A dashboard also calls a runtime's declared operations (`fleet.call`),
+// opens its live ones (`fleet.live`), and keeps shared state on its host
+// (`fleet.state`); the platform decides each for the signed-in user.
+//
+// Name the kinds a query or watch reads, and the operation a call or live
+// opens, with literals: ctl-dev-kit's dashboard build derives the
+// registration's `uses` from them, and refuses one it cannot read.
 //
 // Browser-only, with no imports, so a dashboard's bundle carries nothing else.
+/** Someone else wrote the document since it was read: `current` is theirs. */
+export class FleetStateConflict extends Error {
+    current;
+    constructor(current) {
+        super("the dashboard state changed since it was read");
+        this.current = current;
+        this.name = "FleetStateConflict";
+    }
+}
+function resolvePath(template, input) {
+    const path = template.replace(/\{([^}]+)\}/g, (_m, name) => {
+        const value = input.params?.[name];
+        if (value === undefined)
+            throw new Error(`the operation needs parameter ${name}`);
+        return encodeURIComponent(String(value));
+    });
+    const query = input.query && Object.keys(input.query).length > 0 ? `?${new URLSearchParams(input.query)}` : "";
+    return `${path}${query}`;
+}
 function queryString(selection) {
     const kinds = typeof selection.kind === "string" ? [selection.kind] : [...selection.kind];
     const params = new URLSearchParams({ kinds: kinds.join(",") });
@@ -21,9 +45,79 @@ function queryString(selection) {
 }
 export function fleetClient(options = {}) {
     const base = (options.base ?? "/_fleet").replace(/\/+$/, "");
+    const doFetch = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+    const tables = new Map();
+    const operationOf = async (runtimeId, operationId) => {
+        let table = tables.get(runtimeId);
+        if (table === undefined) {
+            table = doFetch(`${base}/operations/${encodeURIComponent(runtimeId)}`, { credentials: "same-origin" }).then(async (res) => {
+                if (!res.ok)
+                    throw new Error(`the runtime's operations answered ${res.status}`);
+                return (await res.json()).operations;
+            });
+            tables.set(runtimeId, table);
+            table.catch(() => tables.delete(runtimeId));
+        }
+        const op = (await table).find((o) => o.operationId === operationId);
+        if (op === undefined)
+            throw new Error(`runtime ${runtimeId} offers this dashboard no operation ${operationId}`);
+        return op;
+    };
     return {
+        async call(runtimeId, operationId, input = {}) {
+            const op = await operationOf(runtimeId, operationId);
+            if (op.live)
+                throw new Error(`${operationId} is a live operation: open it with fleet.live`);
+            const hasBody = input.body !== undefined && op.method !== "GET" && op.method !== "HEAD";
+            const res = await doFetch(`${base}/api/${encodeURIComponent(runtimeId)}${resolvePath(op.path, input)}`, {
+                method: op.method,
+                credentials: "same-origin",
+                ...(hasBody ? { headers: { "content-type": "application/json" }, body: JSON.stringify(input.body) } : {}),
+            });
+            if (!res.ok)
+                throw new Error(`${operationId} answered ${res.status}: ${await res.text()}`);
+            const type = res.headers.get("content-type") ?? "";
+            return (type.includes("json") ? await res.json() : await res.text());
+        },
+        async live(runtimeId, operationId, handlers, input = {}) {
+            const op = await operationOf(runtimeId, operationId);
+            if (!op.live)
+                throw new Error(`${operationId} is not a live operation: call it with fleet.call`);
+            const Socket = options.WebSocket ?? globalThis.WebSocket;
+            if (Socket === undefined)
+                throw new Error("this environment has no WebSocket");
+            const origin = options.origin ?? globalThis.location?.origin ?? "";
+            const ws = origin.replace(/^http/, "ws");
+            const socket = new Socket(`${ws}${base}/live/${encodeURIComponent(runtimeId)}${resolvePath(op.path, input)}`);
+            socket.addEventListener("open", () => handlers.onOpen?.());
+            socket.addEventListener("message", (e) => handlers.onMessage?.(e.data));
+            socket.addEventListener("close", () => handlers.onClose?.());
+            return { send: (data) => socket.send(data), close: () => socket.close() };
+        },
+        state: {
+            async get(key) {
+                const res = await doFetch(`${base}/state/${encodeURIComponent(key)}`, { credentials: "same-origin" });
+                if (res.status === 404)
+                    return undefined;
+                if (!res.ok)
+                    throw new Error(`the dashboard state answered ${res.status}`);
+                return (await res.json());
+            },
+            async put(key, value, revision) {
+                const res = await doFetch(`${base}/state/${encodeURIComponent(key)}`, {
+                    method: "PUT",
+                    credentials: "same-origin",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ value, ...(revision !== undefined ? { revision } : {}) }),
+                });
+                if (res.status === 409)
+                    throw new FleetStateConflict((await res.json()).current);
+                if (!res.ok)
+                    throw new Error(`the dashboard state answered ${res.status}: ${await res.text()}`);
+                return (await res.json());
+            },
+        },
         async query(selection) {
-            const doFetch = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
             const res = await doFetch(`${base}/directory?${queryString(selection)}`, { credentials: "same-origin" });
             if (!res.ok)
                 throw new Error(`the directory answered ${res.status}`);

package/manifest-schema.d.ts

@@ -225,7 +225,7 @@ export declare const ManifestSchema: z.ZodObject<{
         name: z.ZodString;
         url: z.ZodString;
     }, z.core.$strip>>>;
-    defaultDashboards: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    defaultDashboards: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         displayName: z.ZodOptional<z.ZodString>;
         url: z.ZodString;

package/manifest-schema.js

@@ -210,7 +210,7 @@ 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).default([]).meta({
+    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.53",
+  "version": "0.1.55",
   "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 };