@norskvideo/ctl-sdk 0.1.50 → 0.1.52

package/fleet.d.ts

@@ -0,0 +1,76 @@
+export interface FleetEndpoint {
+    transport: string;
+    address: string;
+    params: Record<string, string>;
+}
+/** What norsk-discovery holds. */
+export interface FleetResource {
+    name: string;
+    kind: string;
+    labels: Record<string, string>;
+    endpoints: FleetEndpoint[];
+}
+/** A runtime as the platform knows it: under norsk-mgr its job id,
+ *  production, replica and job name; under norsk-ctl alone its instance id
+ *  and product. */
+export interface FleetRuntime {
+    id: string;
+    namespace: string;
+    [field: string]: unknown;
+}
+export interface FleetItem {
+    runtime: FleetRuntime;
+    /** The platform's own registration of the runtime (`norsk.runtime`), with
+     *  its `norsk.state`. */
+    presence?: FleetResource;
+    entries: FleetResource[];
+}
+export interface FleetDirectory {
+    items: FleetItem[];
+    /** Whether discovery's replay has landed: before it, entries are partial. */
+    synced: boolean;
+}
+export interface FleetSelection {
+    /** The kinds to read, as literals. `norsk.runtime` lists runtimes by their
+     *  own registration. */
+    kind: string | readonly string[];
+    /** Every one present on an entry, with the same value. */
+    labels?: Readonly<Record<string, string>>;
+}
+export interface FleetWatchHandlers {
+    /** The whole current set, after the snapshot and after every change. */
+    onChange?: (items: FleetItem[]) => void;
+    onSynced?: (synced: boolean) => void;
+    /** The stream failed; the browser retries it. */
+    onError?: () => void;
+}
+export interface FleetWatch {
+    current(): FleetItem[];
+    synced(): boolean;
+    close(): void;
+}
+interface EventSourceLike {
+    addEventListener(name: string, listener: (e: {
+        data: string;
+    }) => void): void;
+    close(): void;
+}
+export interface FleetOptions {
+    /** Where the directory is: `/_fleet` on a dashboard host (the default),
+     *  `/api/v1/fleet` on the platform's own origin. */
+    base?: string;
+    fetch?: (url: string, init?: {
+        credentials?: "same-origin";
+    }) => Promise<Response>;
+    EventSource?: new (url: string, init?: {
+        withCredentials?: boolean;
+    }) => EventSourceLike;
+}
+export interface Fleet {
+    query(selection: FleetSelection): Promise<FleetDirectory>;
+    watch(selection: FleetSelection, handlers?: FleetWatchHandlers): FleetWatch;
+}
+export declare function fleetClient(options?: FleetOptions): Fleet;
+/** The directory on the page's own origin, as a dashboard host serves it. */
+export declare const fleet: Fleet;
+export {};

package/fleet.js

@@ -0,0 +1,70 @@
+// The directory, for a dashboard (RFC 0006 §4.5, task 122 K): the runtimes
+// the signed-in user may see, each with what discovery holds under it, read
+// from the page's own origin and filtered by the platform, never by the
+// dashboard.
+//
+// On a dashboard host the directory is `/_fleet/`; in a product's own UI or a
+// 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.
+//
+// Browser-only, with no imports, so a dashboard's bundle carries nothing else.
+function queryString(selection) {
+    const kinds = typeof selection.kind === "string" ? [selection.kind] : [...selection.kind];
+    const params = new URLSearchParams({ kinds: kinds.join(",") });
+    const labels = Object.entries(selection.labels ?? {}).map(([k, v]) => `${k}=${v}`);
+    if (labels.length > 0)
+        params.set("labels", labels.join(","));
+    return params.toString();
+}
+export function fleetClient(options = {}) {
+    const base = (options.base ?? "/_fleet").replace(/\/+$/, "");
+    return {
+        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}`);
+            return (await res.json());
+        },
+        watch(selection, handlers = {}) {
+            const Source = options.EventSource ?? globalThis.EventSource;
+            if (Source === undefined)
+                throw new Error("this environment has no EventSource");
+            const items = new Map();
+            let isSynced = false;
+            const source = new Source(`${base}/directory/watch?${queryString(selection)}`, { withCredentials: true });
+            const changed = () => handlers.onChange?.([...items.values()]);
+            const on = (name, apply) => source.addEventListener(name, (e) => apply(JSON.parse(e.data)));
+            on("snapshot", (data) => {
+                items.clear();
+                for (const item of data.items)
+                    items.set(item.runtime.id, item);
+                isSynced = data.synced;
+                changed();
+            });
+            on("upsert", (item) => {
+                items.set(item.runtime.id, item);
+                changed();
+            });
+            on("remove", (data) => {
+                items.delete(data.id);
+                changed();
+            });
+            on("synced", (data) => {
+                isSynced = data.synced;
+                handlers.onSynced?.(isSynced);
+            });
+            source.addEventListener("error", () => handlers.onError?.());
+            return {
+                current: () => [...items.values()],
+                synced: () => isSynced,
+                close: () => source.close(),
+            };
+        },
+    };
+}
+/** The directory on the page's own origin, as a dashboard host serves it. */
+export const fleet = fleetClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "type": "module",
   "exports": {
     ".": {
@@ -15,6 +15,10 @@
       "types": "./components/index.d.ts",
       "default": "./components/index.js"
     },
+    "./fleet": {
+      "types": "./fleet.d.ts",
+      "default": "./fleet.js"
+    },
     "./frontend-spec": {
       "types": "./frontend-spec.d.ts",
       "default": "./frontend-spec.js"

package/product-service.d.ts

@@ -171,6 +171,9 @@ export interface ProductServiceOptions {
     /** Told once a registration is removed, so the host can drop whatever it
      *  holds against the product (role assignments on `product/<name>`). */
     onRemoved?: (productName: string) => void;
+    /** Told after every add, remove and reload that succeeds: the host keeps a
+     *  view of its products elsewhere (norsk-ctl's discovery entries). */
+    onChanged?: () => void;
     /**
      * What the daemon asserts when it dials a REGISTERED product's own routes —
      * the config-screen probe and the product-template fetches (RFC 0003 D7's
@@ -228,6 +231,7 @@ export declare class ProductService {
     private reachHostFor;
     private readonly onRolesDeclared?;
     private readonly onRemoved?;
+    private readonly onChanged?;
     private readonly reservedRoleNames?;
     /**
      * Product roles travel bare, so a name means one thing on a host. Two
@@ -248,6 +252,7 @@ export declare class ProductService {
      *  tracked containerId means running. Dev-mode: externally owned, so probe
      *  the dev URL — registered no longer implies running. */
     isRunning(reg: ProductRegistration): Promise<boolean>;
+    private changed;
     add(spec: ProductSpec, opts?: AddProductOpts): Promise<AddProductResult>;
     private addSerialised;
     remove(name: string): Promise<void>;

package/product-service.js

@@ -76,6 +76,7 @@ export class ProductService {
         this.onRolesDeclared = opts.onRolesDeclared;
         this.reservedRoleNames = opts.reservedRoleNames;
         this.onRemoved = opts.onRemoved;
+        this.onChanged = opts.onChanged;
         this.forgetIdentity = opts.forgetIdentity;
         this.probeHeadersFor = opts.probeHeadersFor;
     }
@@ -99,6 +100,7 @@ export class ProductService {
     }
     onRolesDeclared;
     onRemoved;
+    onChanged;
     reservedRoleNames;
     /**
      * Product roles travel bare, so a name means one thing on a host. Two
@@ -165,8 +167,12 @@ export class ProductService {
             return reg.containerId !== undefined;
         return this.isDevUrlAlive(productBaseUrl(reg));
     }
+    changed(result) {
+        this.onChanged?.();
+        return result;
+    }
     async add(spec, opts = {}) {
-        return this.mutations.run(() => this.addSerialised(spec, opts));
+        return this.changed(await this.mutations.run(() => this.addSerialised(spec, opts)));
     }
     async addSerialised(spec, opts) {
         const existing = this.store.read();
@@ -373,7 +379,7 @@ export class ProductService {
         return { registration, warnings };
     }
     async remove(name) {
-        return this.mutations.run(() => this.removeSerialised(name));
+        return this.changed(await this.mutations.run(() => this.removeSerialised(name)));
     }
     async removeSerialised(name) {
         const existing = this.store.read();
@@ -400,7 +406,7 @@ export class ProductService {
      *  stood in for. Like restart, the new container id is persisted before the
      *  readiness wait so a timed-out reload leaves a tracked container. */
     async reload(name) {
-        return this.mutations.run(() => this.reloadSerialised(name));
+        return this.changed(await this.mutations.run(() => this.reloadSerialised(name)));
     }
     async reloadSerialised(name) {
         const target = this.store.read().find((p) => p.name === name);