@norskvideo/ctl-sdk 0.1.54 → 0.1.56

package/components/ProductTemplateBuildForm.d.ts

@@ -22,6 +22,9 @@ export type ProductTemplateBuildRequest = {
      *  dev-kit-generated product splits off before its strict config parse
      *  and bakes into the manifest's `advanced` block. */
     formValues: Record<string, unknown>;
+    /** The template's labels (ADR-0015, norsk-ctl task 124), when the form was
+     *  asked for them (`withLabels`): the caller records them on the template. */
+    labels?: Record<string, string>;
 };
 export type ProductTemplateBuildOutcome<TProductTemplate> = {
     ok: true;
@@ -30,8 +33,10 @@ export type ProductTemplateBuildOutcome<TProductTemplate> = {
     ok: false;
     error: string;
 };
-export declare function ProductTemplateBuildForm<TProductTemplate>({ productName, configScreenUrl, onClose, sections, onSubmit, onSaved, onSavedAndLaunch, onRequirements, }: {
+export declare function ProductTemplateBuildForm<TProductTemplate>({ productName, configScreenUrl, onClose, sections, onSubmit, onSaved, onSavedAndLaunch, onRequirements, withLabels, }: {
     productName: string;
+    /** Ask for the template's labels too; the save carries them as `labels`. */
+    withLabels?: boolean;
     configScreenUrl: string | null;
     onClose: () => void;
     /** Forwarded from the config-screen iframe: the product's suggested placement

package/components/ProductTemplateBuildForm.js

@@ -3,6 +3,7 @@ import { ChevronDown, ChevronRight, X } from "lucide-react";
 import { useRef, useState } from "react";
 import toast from "react-hot-toast";
 import { validateInstanceId } from "../validate.js";
+import { parseLabelsText } from "./labels-text.js";
 import { ProductIframe } from "./ProductIframe.js";
 import { useUIPrimitives } from "./ui-primitives.js";
 const emptyAdvancedDefaults = {
@@ -34,9 +35,11 @@ function assembleAdvancedDefaults(d) {
         out.openFileLimit = { default: limit };
     return Object.keys(out).length > 0 ? out : undefined;
 }
-export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose, sections, onSubmit, onSaved, onSavedAndLaunch, onRequirements, }) {
+export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose, sections, onSubmit, onSaved, onSavedAndLaunch, onRequirements, withLabels = false, }) {
     const { Button, Input, Label } = useUIPrimitives();
     const [productTemplateName, setProductTemplateName] = useState("");
+    const [labelsDraft, setLabelsDraft] = useState("");
+    const labels = parseLabelsText(labelsDraft);
     // The iframe can suggest a name derived from its current choices (#317).
     // We prefill the field with it while the operator hasn't typed anything,
     // so changing template/release keeps the suggestion live; once they edit
@@ -58,7 +61,7 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
     };
     const nameValidation = productTemplateName ? validateInstanceId(productTemplateName) : null;
     const productTemplateNameError = nameValidation?.status === "error" ? nameValidation.message : null;
-    const canSubmit = !!productTemplateName && !productTemplateNameError && !submitting && iframeValid;
+    const canSubmit = !!productTemplateName && !productTemplateNameError && !submitting && iframeValid && (!withLabels || labels.ok);
     // Internal helper. Returns the saved product template on success (so the
     // caller can hand it off to its launch flow without waiting for a refetch),
     // null on failure.
@@ -81,7 +84,16 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
         const advanced = assembleAdvancedDefaults(advancedDraft);
         if (advanced)
             formValues = { ...formValues, $advancedDefaults: advanced };
-        const outcome = await onSubmit({ productName, productTemplateName, formValues });
+        if (withLabels && !labels.ok) {
+            toast.error(labels.error);
+            return null;
+        }
+        const outcome = await onSubmit({
+            productName,
+            productTemplateName,
+            formValues,
+            ...(withLabels && labels.ok && Object.keys(labels.labels).length > 0 ? { labels: labels.labels } : {}),
+        });
         if (!outcome.ok) {
             toast.error(`Save product template failed: ${outcome.error}`);
             return null;
@@ -118,5 +130,5 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
     return (_jsxs("div", { className: "mb-6 rounded-lg border border-zinc-700 bg-zinc-900 p-4", children: [_jsxs("div", { className: "flex items-center justify-between mb-4", children: [_jsxs("div", { children: [_jsxs("h4", { className: "text-sm font-semibold text-zinc-100", children: ["Create ", productName, " product template"] }), _jsx("p", { className: "text-xs text-zinc-500 mt-0.5", children: "Saves a reusable product template. Launch instances from it later." })] }), _jsx("button", { type: "button", onClick: onClose, className: "text-zinc-500 hover:text-zinc-300", children: _jsx(X, { size: 14 }) })] }), _jsxs("form", { onSubmit: handleSave, className: "space-y-4", children: [_jsxs("div", { children: [_jsx(Label, { children: "Product template name *" }), _jsx(Input, { value: productTemplateName, onChange: (e) => {
                                     setNameTouched(true);
                                     setProductTemplateName(e.target.value);
-                                }, placeholder: suggestedName || `e.g. ${productName}-prod`, required: true }), productTemplateNameError ? (_jsx("p", { className: "text-xs text-red-400 mt-1", children: productTemplateNameError })) : (_jsx("p", { className: "text-xs text-zinc-500 mt-1", children: "Lowercase letters, numbers, and hyphens only. Used to launch instances later." }))] }), configScreenUrl ? (_jsx(ProductIframe, { ref: iframeRef, productName: productName, configScreenUrl: configScreenUrl, onValidityChange: (v) => setIframeValid(v), onSuggestName: handleSuggestName, ...(onRequirements ? { onRequirements } : {}) })) : (_jsxs("p", { className: "text-xs text-zinc-500", children: ["Product manifest does not declare ", _jsx("code", { children: "ui.configScreenUrl" }), " \u2014 nothing to configure."] })), sections, _jsxs("div", { children: [_jsxs("button", { type: "button", onClick: () => setDefaultsOpen((v) => !v), className: "flex items-center gap-1.5 text-[10px] font-semibold uppercase tracking-widest text-zinc-500 hover:text-zinc-300", children: [defaultsOpen ? _jsx(ChevronDown, { size: 12 }) : _jsx(ChevronRight, { size: 12 }), "Custom defaults"] }), defaultsOpen && (_jsxs("div", { className: "mt-2", children: [_jsx("p", { className: "text-xs text-zinc-500 mb-2", children: "Launch-form defaults baked into this template's manifest. Operators can still override them per instance." }), _jsxs("div", { className: "flex flex-wrap gap-3", children: [_jsxs("div", { children: [_jsx(Label, { children: "Network mode" }), _jsxs("select", { "aria-label": "Network mode", value: advancedDraft.networkMode, onChange: (e) => patchDraft({ networkMode: e.target.value }), className: "block rounded border border-zinc-700 bg-zinc-900 px-3 py-1.5 text-sm text-zinc-100", children: [_jsx("option", { value: "", children: "product default" }), _jsx("option", { value: "docker", children: "docker" }), _jsx("option", { value: "hybrid", children: "hybrid" })] })] }), _jsxs("div", { className: "min-w-[14rem] flex-1", children: [_jsx(Label, { children: "Host ports" }), _jsx(Input, { "aria-label": "Host ports", placeholder: "e.g. 1935, 5001/udp, 9000:80@svc", value: advancedDraft.hostPorts, onChange: (e) => patchDraft({ hostPorts: e.target.value }) })] }), _jsxs("div", { children: [_jsx(Label, { children: "Container user" }), _jsx(Input, { "aria-label": "Container user", placeholder: "uid:gid", value: advancedDraft.containerUser, onChange: (e) => patchDraft({ containerUser: e.target.value }), className: "w-28" })] }), _jsxs("div", { children: [_jsx(Label, { children: "Shared memory size" }), _jsx(Input, { "aria-label": "Shared memory size", placeholder: "e.g. 8gb", value: advancedDraft.shmSize, onChange: (e) => patchDraft({ shmSize: e.target.value }), className: "w-24" })] }), _jsxs("div", { children: [_jsx(Label, { children: "Open file limit" }), _jsx(Input, { "aria-label": "Open file limit", type: "number", min: 1024, max: 1048576, placeholder: "runner default", value: advancedDraft.openFileLimit, onChange: (e) => patchDraft({ openFileLimit: e.target.value }), className: "w-32" })] })] })] }))] }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { type: "button", variant: "primary", disabled: !canSubmit, onClick: handleSaveAndLaunch, children: submitting ? "Working…" : "Save & Launch…" }), _jsx(Button, { type: "submit", variant: "default", disabled: !canSubmit, children: "Save" }), _jsx(Button, { type: "button", variant: "ghost", onClick: onClose, children: "Cancel" })] })] })] }));
+                                }, placeholder: suggestedName || `e.g. ${productName}-prod`, required: true }), productTemplateNameError ? (_jsx("p", { className: "text-xs text-red-400 mt-1", children: productTemplateNameError })) : (_jsx("p", { className: "text-xs text-zinc-500 mt-1", children: "Lowercase letters, numbers, and hyphens only. Used to launch instances later." }))] }), withLabels && (_jsxs("div", { children: [_jsx(Label, { children: "Labels" }), _jsx(Input, { "aria-label": "Labels", value: labelsDraft, onChange: (e) => setLabelsDraft(e.target.value), placeholder: "e.g. env=qa,team=news" }), labels.ok ? (_jsx("p", { className: "text-xs text-zinc-500 mt-1", children: "name=value pairs joined by commas. Instances launched from it start with them; they decide who may see it, and what walls show it." })) : (_jsx("p", { className: "text-xs text-red-400 mt-1", children: labels.error }))] })), configScreenUrl ? (_jsx(ProductIframe, { ref: iframeRef, productName: productName, configScreenUrl: configScreenUrl, onValidityChange: (v) => setIframeValid(v), onSuggestName: handleSuggestName, ...(onRequirements ? { onRequirements } : {}) })) : (_jsxs("p", { className: "text-xs text-zinc-500", children: ["Product manifest does not declare ", _jsx("code", { children: "ui.configScreenUrl" }), " \u2014 nothing to configure."] })), sections, _jsxs("div", { children: [_jsxs("button", { type: "button", onClick: () => setDefaultsOpen((v) => !v), className: "flex items-center gap-1.5 text-[10px] font-semibold uppercase tracking-widest text-zinc-500 hover:text-zinc-300", children: [defaultsOpen ? _jsx(ChevronDown, { size: 12 }) : _jsx(ChevronRight, { size: 12 }), "Custom defaults"] }), defaultsOpen && (_jsxs("div", { className: "mt-2", children: [_jsx("p", { className: "text-xs text-zinc-500 mb-2", children: "Launch-form defaults baked into this template's manifest. Operators can still override them per instance." }), _jsxs("div", { className: "flex flex-wrap gap-3", children: [_jsxs("div", { children: [_jsx(Label, { children: "Network mode" }), _jsxs("select", { "aria-label": "Network mode", value: advancedDraft.networkMode, onChange: (e) => patchDraft({ networkMode: e.target.value }), className: "block rounded border border-zinc-700 bg-zinc-900 px-3 py-1.5 text-sm text-zinc-100", children: [_jsx("option", { value: "", children: "product default" }), _jsx("option", { value: "docker", children: "docker" }), _jsx("option", { value: "hybrid", children: "hybrid" })] })] }), _jsxs("div", { className: "min-w-[14rem] flex-1", children: [_jsx(Label, { children: "Host ports" }), _jsx(Input, { "aria-label": "Host ports", placeholder: "e.g. 1935, 5001/udp, 9000:80@svc", value: advancedDraft.hostPorts, onChange: (e) => patchDraft({ hostPorts: e.target.value }) })] }), _jsxs("div", { children: [_jsx(Label, { children: "Container user" }), _jsx(Input, { "aria-label": "Container user", placeholder: "uid:gid", value: advancedDraft.containerUser, onChange: (e) => patchDraft({ containerUser: e.target.value }), className: "w-28" })] }), _jsxs("div", { children: [_jsx(Label, { children: "Shared memory size" }), _jsx(Input, { "aria-label": "Shared memory size", placeholder: "e.g. 8gb", value: advancedDraft.shmSize, onChange: (e) => patchDraft({ shmSize: e.target.value }), className: "w-24" })] }), _jsxs("div", { children: [_jsx(Label, { children: "Open file limit" }), _jsx(Input, { "aria-label": "Open file limit", type: "number", min: 1024, max: 1048576, placeholder: "runner default", value: advancedDraft.openFileLimit, onChange: (e) => patchDraft({ openFileLimit: e.target.value }), className: "w-32" })] })] })] }))] }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { type: "button", variant: "primary", disabled: !canSubmit, onClick: handleSaveAndLaunch, children: submitting ? "Working…" : "Save & Launch…" }), _jsx(Button, { type: "submit", variant: "default", disabled: !canSubmit, children: "Save" }), _jsx(Button, { type: "button", variant: "ghost", onClick: onClose, children: "Cancel" })] })] })] }));
 }

package/components/index.d.ts

@@ -1,4 +1,5 @@
 export { type ComposeLayer, ComposeLayerPreview, type ComposeLayerPreviewProps } from "./ComposeLayerPreview.js";
+export { type LabelsTextResult, labelsText, parseLabelsText } from "./labels-text.js";
 export { ProductIframe, type ProductIframeHandle, type SubmitResult } from "./ProductIframe.js";
 export { ProductTemplateBuildForm, type ProductTemplateBuildOutcome, type ProductTemplateBuildRequest, } from "./ProductTemplateBuildForm.js";
 export { SectionFold, type SectionFoldProps } from "./SectionFold.js";

package/components/index.js

@@ -1,4 +1,5 @@
 export { ComposeLayerPreview } from "./ComposeLayerPreview.js";
+export { labelsText, parseLabelsText } from "./labels-text.js";
 export { ProductIframe } from "./ProductIframe.js";
 export { ProductTemplateBuildForm, } from "./ProductTemplateBuildForm.js";
 export { SectionFold } from "./SectionFold.js";

package/components/labels-text.d.ts

@@ -0,0 +1,9 @@
+export type LabelsTextResult = {
+    ok: true;
+    labels: Record<string, string>;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseLabelsText(text: string): LabelsTextResult;
+export declare function labelsText(labels: Readonly<Record<string, string>>): string;

package/components/labels-text.js

@@ -0,0 +1,26 @@
+// Labels as an operator types them (norsk-ctl task 124): `name=value` pairs
+// joined by commas, the same form a runtime receives as NORSK_LABELS. The
+// platform still checks each set (ADR-0015's limits); this only reads the box.
+export function parseLabelsText(text) {
+    const labels = {};
+    for (const raw of text.split(",")) {
+        const pair = raw.trim();
+        if (pair === "")
+            continue;
+        const at = pair.indexOf("=");
+        const name = pair.slice(0, at).trim();
+        const value = pair.slice(at + 1).trim();
+        if (at <= 0 || name === "" || value === "")
+            return { ok: false, error: `'${pair}' is not name=value` };
+        if (name.startsWith("norsk."))
+            return { ok: false, error: `'${name}': names under norsk. are the platform's` };
+        labels[name] = value;
+    }
+    return { ok: true, labels };
+}
+export function labelsText(labels) {
+    return Object.entries(labels)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}=${v}`)
+        .join(",");
+}

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/package.json

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