@serve.zone/interfaces 32.68.0 → 32.69.0

package/ts/data/sparkfleettarget.ts

@@ -0,0 +1,138 @@
+import { readExactDataRecord } from '../private/dataproperties.js';
+import { compareReleaseVersions, isReleaseVersion, parseReleaseVersion } from './releaseversion.js';
+
+/**
+ * The Spark release every node of the fleet should run: one row in Cloudly's database, the only
+ * source of the release a fresh node's bootstrap installs and an update moves a node to.
+ *
+ * An administrator names the version and the revision they read; Cloudly reads the SHA-256 of the
+ * release's `install.sh` from the release's published `SHA256SUMS.txt`, checks it against the
+ * `install.sh` it downloads, and stores the pair. Nobody types a hash. A database without the row
+ * holds no target, and every reader refuses by name (`spark-target-unset`) rather than falling
+ * back to a release of its own.
+ *
+ * A target below the release a node runs is admitted: that node reads `ahead` of it, and an update
+ * that would move it down is refused (`spark-target-below-node`).
+ */
+export interface ISparkFleetTarget {
+  /** `MAJOR.MINOR.PATCH`, without `v`. */
+  version: string;
+  /** The SHA-256 the release's `SHA256SUMS.txt` states for `install.sh`, lowercase hex. */
+  installerSha256: string;
+  /** Advances by one with every change; the first target is revision 1. */
+  revision: number;
+  /** Who set it: `admin:<userId>`, or `migration:<step>` for the target a data step seeded. */
+  setBy: string;
+  setAt: number;
+}
+
+/**
+ * One change of the fleet target, kept in an append-only history: the target as it was set, and
+ * the version it replaced (`null` for the first). The history is the audit; nothing else records
+ * why a target moved.
+ */
+export interface ISparkFleetTargetChange extends ISparkFleetTarget {
+  previousVersion: string | null;
+}
+
+/**
+ * One node held at the release it runs: it reads `held` rather than behind or ahead, and an update
+ * of it is refused (`spark-target-held`) until the hold is released. There is no per-node or
+ * per-cluster target; a hold is the only exception to the one fleet target.
+ */
+export interface ISparkNodeTargetHold {
+  nodeId: string;
+  /** Operator text naming why the node is held. */
+  reason: string;
+  heldBy: string;
+  heldAt: number;
+}
+
+export const sparkFleetTargetContract = Object.freeze({
+  /** Changes one `getSparkFleetTarget` answers, newest first. */
+  historyLimit: 50,
+  /** Characters of one hold's reason. */
+  maximumHoldReasonLength: 256,
+} as const);
+
+/**
+ * Every reason Cloudly answers instead of reading or changing the fleet target or a hold. Each
+ * travels by name as a `TypedResponseError`, and a refused request changes nothing.
+ */
+export const sparkFleetTargetRefusals = Object.freeze([
+  /** The request is not well-formed (`validateSetSparkFleetTargetInput`, `validateSparkNodeTargetHoldInput`). */
+  'spark-target-request-invalid',
+  /** The target moved since the revision the request names (`0` while there is none). */
+  'spark-target-revision-stale',
+  /** The release, its `SHA256SUMS.txt` or its `install.sh` could not be downloaded. */
+  'spark-release-unavailable',
+  /** The release's `SHA256SUMS.txt` states no SHA-256 for `install.sh`. */
+  'spark-release-checksum-missing',
+  /** The downloaded `install.sh` does not have the SHA-256 its `SHA256SUMS.txt` states. */
+  'spark-release-checksum-mismatch',
+  /** No node of that id exists. */
+  'node-missing',
+] as const);
+
+export type TSparkFleetTargetRefusalCode = typeof sparkFleetTargetRefusals[number];
+
+/**
+ * Where one node stands against the fleet target.
+ *
+ * - `at-target`, `behind`, `ahead`: the Spark bundle version it reports, compared to the target.
+ * - `held`: the node is held (`ISparkNodeTargetHold`), whatever it runs.
+ * - `unreported`: the node reports no Spark bundle version (it never reported through the node
+ *   runtime).
+ * - `untargeted`: there is no fleet target.
+ */
+export type TSparkNodeTargetStanding = 'at-target' | 'behind' | 'ahead' | 'held' | 'unreported' | 'untargeted';
+
+export const readSparkNodeTargetStanding = (argsArg: {
+  bundleVersion: string | null;
+  target: Pick<ISparkFleetTarget, 'version'> | null;
+  held: boolean;
+}): TSparkNodeTargetStanding => {
+  if (argsArg.held) return 'held';
+  if (argsArg.target === null) return 'untargeted';
+  const running = parseReleaseVersion(argsArg.bundleVersion);
+  const target = parseReleaseVersion(argsArg.target.version);
+  if (running === null || target === null) return 'unreported';
+  const order = compareReleaseVersions(running, target);
+  return order === 0 ? 'at-target' : order < 0 ? 'behind' : 'ahead';
+};
+
+/**
+ * Validates one `setSparkFleetTarget` input and names every reason it is refused: a release version
+ * and the revision of the target the administrator read, `0` while there is none.
+ */
+export const validateSetSparkFleetTargetInput = (
+  valueArg: unknown,
+  pathArg = 'spark fleet target input',
+): string[] => {
+  const value = readExactDataRecord(valueArg, ['version', 'expectedRevision']);
+  if (value === null) return [`${pathArg} must use its exact schema`];
+  const errors: string[] = [];
+  if (!isReleaseVersion(value.version)) errors.push(`${pathArg} version must be a MAJOR.MINOR.PATCH release version`);
+  if (!Number.isSafeInteger(value.expectedRevision) || Object.is(value.expectedRevision, -0)
+    || (value.expectedRevision as number) < 0) {
+    errors.push(`${pathArg} expectedRevision must be a non-negative integer`);
+  }
+  return errors;
+};
+
+/**
+ * Validates one hold a request states: `{ reason }` to hold the node, `null` to release it.
+ */
+export const validateSparkNodeTargetHoldInput = (
+  valueArg: unknown,
+  pathArg = 'spark node target hold',
+): string[] => {
+  if (valueArg === null) return [];
+  const value = readExactDataRecord(valueArg, ['reason']);
+  if (value === null) return [`${pathArg} must be null or use its exact schema`];
+  return typeof value.reason === 'string' && value.reason.length > 0
+    && value.reason.length <= sparkFleetTargetContract.maximumHoldReasonLength
+    && /^[\x20-\x7e]+$/.test(value.reason)
+    ? []
+    : [`${pathArg} reason must be printable text of 1 to ${sparkFleetTargetContract.maximumHoldReasonLength} characters`];
+};

package/ts/data/sparknodereport.ts

@@ -3,6 +3,8 @@ import { readDataProperties, readExactDataRecord } from '../private/dataproperti
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';
 import { isClusterNodeHostname } from './clusternodehostname.js';
+import type { TNodeActionName } from './clusternode.js';
+import { isHostBootId, isNodeActionNameList } from './nodeaction.js';
 
 /** Host observations only. Container and workload readiness belong to Pallet. */
 export interface ISparkNodeReport {
@@ -28,6 +30,25 @@ export interface ISparkNodeReport {
    * it made one since it started. Whether the node carries the hostname is `runtime.hostname`.
    */
   hostApply?: ISparkNodeHostApply;
+  /**
+   * The host's boot, stated by a Spark that executes node actions: how Cloudly verifies an action
+   * that reboots (`nodeActionVerification`) and whether the host waits for a reboot.
+   */
+  boot?: ISparkNodeBoot;
+  /**
+   * The node actions this Spark executes (`sparkNodeActionContracts`), in canonical order. Cloudly
+   * admits a node runtime action only for a node whose report states its executor, so an action
+   * Spark cannot execute is refused when it is requested rather than left to expire.
+   */
+  actionExecutors?: TNodeActionName[];
+}
+
+/** One boot of the host. */
+export interface ISparkNodeBoot {
+  /** The kernel's `boot_id` (`/proc/sys/kernel/random/boot_id`), a lowercase UUID; it changes with every boot. */
+  id: string;
+  /** Whether the host states that a package it installed waits for a reboot (`/var/run/reboot-required`). */
+  rebootRequired: boolean;
 }
 
 /** Whether Spark applied a desired hostname: `applied` once the host carries it. */
@@ -146,8 +167,10 @@ export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport =>
   const reportKeys = ['observedAt', 'metrics', 'runtime'];
   const properties = readDataProperties(valueArg);
   requireValue(properties !== null);
-  const hasHostApply = Object.hasOwn(properties, 'hostApply');
-  const value = record(valueArg, hasHostApply ? [...reportKeys, 'hostApply'] : reportKeys);
+  // Each optional member is read exactly when the report states it, so a report without them is
+  // the report an earlier Spark sends and is read the way an earlier reader read it.
+  const optionalKeys = ['hostApply', 'boot', 'actionExecutors'].filter((keyArg) => Object.hasOwn(properties, keyArg));
+  const value = record(valueArg, [...reportKeys, ...optionalKeys]);
   const metrics = record(value.metrics, ['cpuUsagePercent', 'memoryUsedMB', 'memoryAvailableMB',
     'diskUsedGB', 'diskAvailableGB']);
   const runtime = record(value.runtime, ['hostname', 'platform', 'arch', 'osRelease', 'bundle',
@@ -174,10 +197,26 @@ export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport =>
       }),
       localRuntimeReady: true, workloadReadiness: 'unverified',
     }),
-    ...(hasHostApply ? { hostApply: snapshotSparkNodeHostApply(value.hostApply) } : {}),
+    ...(optionalKeys.includes('hostApply') ? { hostApply: snapshotSparkNodeHostApply(value.hostApply) } : {}),
+    ...(optionalKeys.includes('boot') ? { boot: snapshotSparkNodeBoot(value.boot) } : {}),
+    ...(optionalKeys.includes('actionExecutors')
+      ? { actionExecutors: snapshotActionExecutors(value.actionExecutors) } : {}),
   });
 };
 
+/** One `boot`: exactly its keys. */
+const snapshotSparkNodeBoot = (valueArg: unknown): ISparkNodeBoot => {
+  const value = record(valueArg, ['id', 'rebootRequired']);
+  requireValue(isHostBootId(value.id) && typeof value.rebootRequired === 'boolean');
+  return Object.freeze({ id: value.id, rebootRequired: value.rebootRequired });
+};
+
+/** One `actionExecutors`: a canonical list of at least one action name, detached and frozen. */
+const snapshotActionExecutors = (valueArg: unknown): TNodeActionName[] => {
+  requireValue(isNodeActionNameList(valueArg));
+  return Object.freeze([...valueArg]) as TNodeActionName[];
+};
+
 export const snapshotSparkNodeHeartbeatRequest = (valueArg: unknown): ISparkNodeHeartbeatRequest => {
   const value = record(valueArg, ['nodeId', 'nodeToken', 'protocol', 'report']);
   return Object.freeze({

package/ts/requests/node.ts

@@ -3,6 +3,8 @@ import type { IBareMetal } from '../data/baremetal.js';
 import type { ICluster } from '../data/cluster.js';
 import type { IClusterNode, INodeAction, INodeMetricsSample, TNodeActionName } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
+import type { INodeActionConfirmation, INodeActionPreview } from '../data/nodeaction.js';
+import type { ISparkFleetTarget, ISparkFleetTargetChange, ISparkNodeTargetHold } from '../data/sparkfleettarget.js';
 import type { IIdentity } from '../data/user.js';
 import type { IPlatformObjectStorageEndpoint } from '../platform/objectstorage.js';
 import type { IPlatformDatabaseEndpoint } from '../platform/database.js';
@@ -423,6 +425,18 @@ export interface IReq_Any_Cloudly_ResetClusterNodeHostname extends plugins.typed
   };
 }
 
+/**
+ * An administrator requests one action on one node.
+ *
+ * A node whose Swarm-era daemon reports last receives it as before, in the metrics-sample answer;
+ * `confirmation` is not read for it. A node that reports through the node runtime is sent the
+ * action only with a `confirmation` (`data.validateNodeActionConfirmation`) of the preview the
+ * administrator read (`getNodeActionPreview`): the typed hostname, the impact digest, when the
+ * impact names a Corestore on the node the consent to restart it, and for an update the fleet Spark
+ * target revision the preview showed. The action then carries
+ * `lifecycle`, with the confirmation, the impact and, for an update, the fleet target frozen in it.
+ * Every refusal is one of `data.nodeActionRefusals` and changes nothing.
+ */
 export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_Cloudly_CreateNodeAction
@@ -433,12 +447,116 @@ export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestI
     nodeId: string;
     actionName: TNodeActionName;
     payload?: INodeAction['payload'];
+    confirmation?: INodeActionConfirmation;
+  };
+  response: {
+    action: INodeAction;
+  };
+}
+
+/**
+ * An administrator previews one action on one node that reports through the node runtime: what it
+ * interrupts, read from Cloudly's database, the digest a confirmation names, and every reason a
+ * request would be refused now. A preview changes nothing.
+ */
+export interface IReq_Any_Cloudly_GetNodeActionPreview extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetNodeActionPreview
+> {
+  method: 'getNodeActionPreview';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    actionName: TNodeActionName;
+  };
+  response: {
+    preview: INodeActionPreview;
+  };
+}
+
+/**
+ * An administrator withdraws one node runtime action while it is still `pending`, at the revision
+ * they read. A claimed action is never withdrawn: Spark may already have stopped the node.
+ */
+export interface IReq_Any_Cloudly_CancelNodeAction extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_CancelNodeAction
+> {
+  method: 'cancelNodeAction';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    actionId: string;
+    expectedRevision: number;
   };
   response: {
     action: INodeAction;
   };
 }
 
+/**
+ * An administrator reads the fleet Spark target (`data.ISparkFleetTarget`, `null` while there is
+ * none), its newest changes and every node hold.
+ */
+export interface IReq_Any_Cloudly_GetSparkFleetTarget extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetSparkFleetTarget
+> {
+  method: 'getSparkFleetTarget';
+  request: {
+    identity: IIdentity;
+  };
+  response: {
+    target: ISparkFleetTarget | null;
+    /** Newest first, at most `data.sparkFleetTargetContract.historyLimit`. */
+    history: ISparkFleetTargetChange[];
+    /** Sorted by node id. */
+    holds: ISparkNodeTargetHold[];
+  };
+}
+
+/**
+ * An administrator sets the fleet Spark target to one release version, at the revision they read
+ * (`0` while there is none). Cloudly reads the release's `SHA256SUMS.txt` and `install.sh`, refuses
+ * any mismatch between them, and stores the version with the SHA-256 it checked. Every refusal is
+ * one of `data.sparkFleetTargetRefusals`.
+ */
+export interface IReq_Any_Cloudly_SetSparkFleetTarget extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetSparkFleetTarget
+> {
+  method: 'setSparkFleetTarget';
+  request: {
+    identity: IIdentity;
+    /** `data.validateSetSparkFleetTargetInput` judges these two. */
+    version: string;
+    expectedRevision: number;
+  };
+  response: {
+    target: ISparkFleetTarget;
+  };
+}
+
+/**
+ * An administrator holds one node at the release it runs (`hold: { reason }`) or releases it
+ * (`hold: null`). Answers the hold as it now stands.
+ */
+export interface IReq_Any_Cloudly_SetSparkNodeTargetHold extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetSparkNodeTargetHold
+> {
+  method: 'setSparkNodeTargetHold';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    /** `data.validateSparkNodeTargetHoldInput` judges it. */
+    hold: { reason: string } | null;
+  };
+  response: {
+    hold: ISparkNodeTargetHold | null;
+  };
+}
+
 export interface IReq_Any_Cloudly_GetNodeActions extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_Cloudly_GetNodeActions