@fnndsc/salsa 4.4.4 → 4.5.1

package/dist/plugins/plugin_sync.d.ts

@@ -0,0 +1,276 @@
+/**
+ * @file Filling a CUBE from a plugin index: `plugin sync`.
+ *
+ * A sync is a plan, then the plan's adds. The plan compares every descriptor
+ * in the index with what the connected CUBE holds and puts each plugin in
+ * one group:
+ *
+ * | group | what it means | action |
+ * |---|---|---|
+ * | add | not in the CUBE | add |
+ * | newer | the index has a newer version | add beside the older one |
+ * | skip | same name and version, same descriptor | nothing |
+ * | cubeNewer | the CUBE has a newer version | report |
+ * | drift | same name and version, different descriptor | report, never touched |
+ * | imageTaken | the image is registered under another version | report: CUBE would refuse it |
+ * | cubeOnly | in the CUBE, not in the index | report |
+ * | invalid | fails rules 1–4 of `plugin validate` | report, never uploaded |
+ *
+ * A sync never deletes and never changes a plugin already there: deleting
+ * cascades to its runs and to its nodes in every pipeline, and CUBE's admin
+ * `PUT` changes only compute resources, so a descriptor cannot be corrected
+ * in place anyway. Drift ignores what only reflects CUBE's defaults (a limit
+ * the index leaves out because it equals the default, `1000m` against a
+ * stored `1000`, a field CUBE fills in when it is not given).
+ *
+ * Applying uploads the plan's adds four at a time, each failure contained to
+ * its plugin; what landed stays, so a rerun continues where a stopped one
+ * left off. Every CUBE read and the upload go through {@link SyncSeams}, so
+ * the plan and the apply are testable without a CUBE.
+ *
+ * Key components:
+ * - SyncGroup / SyncPlanEntry / SyncPlan: the plan.
+ * - SyncResult / SyncReceipt: what applying it did.
+ * - SyncSeams / syncSeams_cube: the CUBE reads and the upload.
+ * - syncPlan_build: compare an index with the CUBE.
+ * - syncPlanAdds_list: the entries a plan would upload.
+ * - syncPlan_apply: upload them, four at a time.
+ * - descriptorDrift_find: how two descriptors of one version differ, defaults aside.
+ * - version_compare: dotted-number ordering.
+ *
+ * Typical usage:
+ * ```ts
+ * const plan: SyncPlan = await syncPlan_build(index, ['host'], syncSeams_cube);
+ * const receipt: SyncReceipt = await syncPlan_apply(plan, syncSeams_cube, (r: SyncResult): void => console.log(r));
+ * ```
+ *
+ * Dependencies: cumin's CUBE reads (plugin pages, parameters) and the
+ * administrative upload; the index and its local checks.
+ *
+ * @module
+ */
+import type { PluginIndex } from './plugin_index.js';
+/** The groups a plan's entries fall in, in the order a plan lists them. */
+export declare const SYNC_GROUPS: readonly ["add", "newer", "skip", "cubeNewer", "drift", "imageTaken", "cubeOnly", "invalid"];
+/** One group of the plan. */
+export type SyncGroup = typeof SYNC_GROUPS[number];
+/** The groups that upload. */
+export declare const SYNC_ADD_GROUPS: readonly SyncGroup[];
+/**
+ * One plugin's place in the plan.
+ *
+ * @example
+ * ```ts
+ * const entry: SyncPlanEntry = { group: 'newer', name: 'pl-x', version: '1.2.0', cubeVersions: ['1.1.0'] };
+ * ```
+ */
+export interface SyncPlanEntry {
+    /** Its group. */
+    readonly group: SyncGroup;
+    /** The plugin's name (the file's, for an invalid descriptor that names none). */
+    readonly name: string;
+    /** The index's version, when the entry comes from the index. */
+    readonly version?: string;
+    /** The versions the CUBE holds of this name. */
+    readonly cubeVersions?: string[];
+    /** The index file it comes from. */
+    readonly file?: string;
+    /** Why it is in a report group, in a line. */
+    readonly detail?: string;
+    /** The descriptor's text, for the entries that upload. */
+    readonly descriptor?: string;
+}
+/**
+ * The plan.
+ *
+ * @example
+ * ```ts
+ * const plan: SyncPlan = await syncPlan_build(index, ['host'], seams);
+ * plan.entries.filter((e: SyncPlanEntry): boolean => e.group === 'add').length;
+ * ```
+ */
+export interface SyncPlan {
+    /** The index's short name (`chris-plugins @ 8c9a1f6`). */
+    readonly label: string;
+    /** The index's source word. */
+    readonly source: string;
+    /** The commit read, when known. */
+    readonly commit: string | null;
+    /** How many descriptors the index holds. */
+    readonly indexed: number;
+    /** The compute resources adds are registered on. */
+    readonly computes: string[];
+    /** Every entry, by group then name. */
+    readonly entries: SyncPlanEntry[];
+}
+/**
+ * One upload's outcome.
+ *
+ * @example
+ * ```ts
+ * const result: SyncResult = { name: 'pl-x', version: '1.2.0', ok: false, reason: 'Plugin with name pl-x and version 1.2.0 already exists.' };
+ * ```
+ */
+export interface SyncResult {
+    /** The plugin. */
+    readonly name: string;
+    /** Its version. */
+    readonly version: string;
+    /** True when CUBE registered it. */
+    readonly ok: boolean;
+    /** CUBE's reason, when it refused. */
+    readonly reason?: string;
+}
+/**
+ * What applying a plan did.
+ *
+ * @example
+ * ```ts
+ * const receipt: SyncReceipt = await syncPlan_apply(plan, seams, () => undefined);
+ * receipt.failed === 0;
+ * ```
+ */
+export interface SyncReceipt {
+    /** The plan applied. */
+    readonly plan: SyncPlan;
+    /** Each upload's outcome, in plan order. */
+    readonly results: SyncResult[];
+    /** Plugins registered. */
+    readonly added: number;
+    /** Plugins already there, the same. */
+    readonly skipped: number;
+    /** Plugins in a report group. */
+    readonly reported: number;
+    /** Uploads that should have worked and did not. */
+    readonly failed: number;
+    /** Whether a stop (`kill %N`, Ctrl-C) ended it before every add was sent. */
+    readonly stopped: boolean;
+    /** Adds the plan had that were never sent, because it was stopped. */
+    readonly unsent: number;
+}
+/**
+ * One plugin row the CUBE holds.
+ *
+ * @example
+ * ```ts
+ * const row: CubePluginRow = { name: 'pl-x', version: '1.0.0', dock_image: 'fnndsc/pl-x:1.0.0' };
+ * ```
+ */
+export interface CubePluginRow {
+    /** Its name. */
+    readonly name: string;
+    /** Its version. */
+    readonly version: string;
+    /** Its image. */
+    readonly dock_image: string;
+}
+/** What an upload answered. */
+export type UploadAnswer = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * The CUBE reads and the upload a sync needs.
+ *
+ * @example
+ * ```ts
+ * const seams: SyncSeams = { ...syncSeams_cube, descriptor_upload: async () => ({ ok: true }) };
+ * ```
+ */
+export interface SyncSeams {
+    /**
+     * Reads every plugin the CUBE holds.
+     *
+     * @returns The rows, every page.
+     */
+    cubePlugins_read(): Promise<CubePluginRow[]>;
+    /**
+     * Reads one registered version whole: its fields and every parameter.
+     *
+     * @param name - The plugin's name.
+     * @param version - The version.
+     * @returns The plugin's fields with `parameters`, or null when CUBE has no such version.
+     */
+    cubeDescriptor_read(name: string, version: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Uploads one descriptor.
+     *
+     * @param descriptor - The descriptor's text.
+     * @param computes - Compute resources to register it on.
+     * @returns Whether CUBE registered it, and why not.
+     */
+    descriptor_upload(descriptor: string, computes: string[]): Promise<UploadAnswer>;
+}
+/** The connected CUBE's reads and upload. */
+export declare const syncSeams_cube: SyncSeams;
+/**
+ * Builds the plan: compares an index with the connected CUBE.
+ *
+ * @param index - The index.
+ * @param computes - The compute resources adds would be registered on.
+ * @param seams - The CUBE reads.
+ * @returns The plan.
+ * @throws {Error} When the CUBE cannot be read.
+ *
+ * @example
+ * ```ts
+ * const plan: SyncPlan = await syncPlan_build(index, ['host'], syncSeams_cube);
+ * ```
+ */
+export declare function syncPlan_build(index: PluginIndex, computes: string[], seams: SyncSeams): Promise<SyncPlan>;
+/**
+ * Lists the entries a plan would upload.
+ *
+ * @param plan - The plan.
+ * @returns Its add and newer entries, in plan order.
+ *
+ * @example
+ * ```ts
+ * syncPlanAdds_list(plan).length; // how many plugins a yes registers
+ * ```
+ */
+export declare function syncPlanAdds_list(plan: SyncPlan): SyncPlanEntry[];
+/**
+ * Applies a plan: uploads its adds, four at a time.
+ *
+ * @param plan - The plan.
+ * @param seams - The upload.
+ * @param note - Called once per upload as it lands, in the order they land.
+ * @param signal - A stop: the uploads in flight finish, no more start, and
+ *   what landed stays (a rerun continues from it).
+ * @returns What it did, `stopped` when the signal ended it early.
+ *
+ * @example
+ * ```ts
+ * const receipt: SyncReceipt = await syncPlan_apply(plan, syncSeams_cube, (r: SyncResult): void => console.log(r.name, r.ok));
+ * ```
+ */
+export declare function syncPlan_apply(plan: SyncPlan, seams: SyncSeams, note: (result: SyncResult) => void, signal?: AbortSignal): Promise<SyncReceipt>;
+/**
+ * Finds how two descriptors of one version differ, CUBE's defaults aside.
+ *
+ * @param indexed - The index's descriptor.
+ * @param held - The CUBE's plugin fields with its `parameters`.
+ * @returns The differing fields (`dock_image`, `parameters.--dir.help`), empty when none.
+ *
+ * @example
+ * ```ts
+ * descriptorDrift_find({ min_cpu_limit: '1000m' }, { min_cpu_limit: 1000 }); // []
+ * ```
+ */
+export declare function descriptorDrift_find(indexed: Record<string, unknown>, held: Record<string, unknown>): string[];
+/**
+ * Orders two dotted-number versions.
+ *
+ * @param a - One version.
+ * @param b - The other.
+ * @returns Negative when `a` is older, positive when newer, zero when equal.
+ *
+ * @example
+ * ```ts
+ * ['1.10.0', '1.2.0'].sort(version_compare); // ['1.2.0', '1.10.0']
+ * ```
+ */
+export declare function version_compare(a: string, b: string): number;