@norskvideo/ctl-sdk 0.1.54 → 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/package.json

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