@serve.zone/interfaces 32.68.0 → 32.69.0

package/dist_ts/data/nodeaction.d.ts

@@ -0,0 +1,439 @@
+import { type IProtocolOffer } from '../protocol.js';
+import type { TNodeActionName, TNodeActionStatus } from './clusternode.js';
+/**
+ * Every node action, in canonical token order, so a list of them (a Spark's `actionExecutors`)
+ * is compared byte for byte.
+ */
+export declare const nodeActionNames: readonly ["reboot", "serveZoneServiceUpdate", "systemUpgrade"];
+export declare const isNodeActionName: (valueArg: unknown) => valueArg is TNodeActionName;
+/**
+ * Whether each action state is still open or ended.
+ *
+ * The four values the Swarm-era carrier shipped keep their meaning: `pending` is the requested
+ * state of every action, `running` is a Swarm-era action its daemon started, and `succeeded` and
+ * `failed` end one. The node runtime's lifecycle (`INodeActionLifecycle`) adds the rest:
+ *
+ * - `claimed`: the node's Spark took the action (`claim`), stating the boot it took it in.
+ * - `executing`, `draining`, `rebooting`: the phase Spark reports, only ever forward
+ *   (`sparkNodeActionPhaseOrder`).
+ * - `verifying`: Cloudly saw the evidence the action changed the node (`nodeActionVerification`)
+ *   and waits for the node's runtime to come back.
+ * - `expired`: never claimed in its claim window, or a Swarm-era record no carrier can deliver
+ *   (`TNodeActionExpiryReason`).
+ * - `cancelled`: an operator withdrew it while it was still `pending`.
+ * - `unverified`: its deadline passed before Cloudly could verify it. An operator judges the node;
+ *   Cloudly never retries it.
+ */
+export declare const nodeActionStatusKinds: Readonly<{
+    readonly pending: 'open';
+    readonly running: 'open';
+    readonly claimed: 'open';
+    readonly executing: 'open';
+    readonly draining: 'open';
+    readonly rebooting: 'open';
+    readonly verifying: 'open';
+    readonly succeeded: 'terminal';
+    readonly failed: 'terminal';
+    readonly expired: 'terminal';
+    readonly cancelled: 'terminal';
+    readonly unverified: 'terminal';
+}>;
+/** Every open state, the ones the one-open-action-per-node rule counts. */
+export declare const nodeActionOpenStatuses: readonly TNodeActionStatus[];
+export declare const isNodeActionOpen: (statusArg: TNodeActionStatus) => boolean;
+/**
+ * The phases Spark reports while it executes a claimed action, in the only order it may report
+ * them. A phase may be skipped, never repeated or reported after a later one.
+ */
+export declare const sparkNodeActionPhaseOrder: readonly ["claimed", "executing", "draining", "rebooting"];
+/** A phase Spark reports with a `phase` transition. */
+export type TSparkNodeActionPhase = Exclude<typeof sparkNodeActionPhaseOrder[number], 'claimed'>;
+/**
+ * Time budgets of the node runtime's action lifecycle, in milliseconds.
+ *
+ * A requested action waits `claimWindowMs` for its node's Spark to claim it, then expires. A claimed
+ * action must be verified within its completion budget (`nodeActionCompletionBudgetMs`), measured
+ * from the claim, or it ends `unverified`. Each budget is the sum of the steps the action takes. One
+ * budget is read from Spark's code; every other one is chosen here, and each member says which.
+ */
+export declare const nodeActionContract: Readonly<{
+    /** Chosen: how long a requested action waits for its node's Spark to claim it (10 min). */
+    readonly claimWindowMs: 600000;
+    /**
+     * Spark code: `sparkNodeStopTimeoutSeconds`, the node unit's `TimeoutStopSec=` (522 s), in which
+     * Pallet stops every workload it runs.
+     */
+    readonly drainMs: 522000;
+    /** Chosen: a host's reboot until Spark reports from the new boot (10 min). */
+    readonly bootMs: 600000;
+    /**
+     * Chosen: how long Pallet takes to start and register again after the node runtime starts
+     * (712 s, from the 2026-11-05 survey; Spark states no start budget of its own).
+     */
+    readonly startMs: 712000;
+    /** Chosen: downloading and checking the target's node bundle before anything stops (10 min). */
+    readonly downloadMs: 600000;
+    /** Chosen: the host's package upgrade (30 min). */
+    readonly hostUpgradeMs: 1800000;
+    /** Entries an action's timeline keeps; each state is entered at most once. */
+    readonly maximumTimelineEntries: 16;
+    /** Characters of operator text one timeline entry or failure carries. */
+    readonly maximumDetailLength: 512;
+    /** Services one impact names; a node holding more is answered `impact-unreadable`. */
+    readonly maximumImpactServices: 1024;
+    /** Characters of one service name an impact carries. */
+    readonly maximumServiceNameLength: 256;
+}>;
+/**
+ * How long a claimed action has until Cloudly must have verified it, from the claim.
+ *
+ * A reboot drains, boots and starts the node. An update downloads the target, then restarts the
+ * node runtime on it: a drain and a start, no boot. A host upgrade runs the package upgrade and,
+ * with `reboot`, the reboot after it.
+ */
+export declare const nodeActionCompletionBudgetMs: (actionNameArg: TNodeActionName, rebootArg: boolean) => number;
+/** Whether an action reboots the host, which is how Cloudly verifies it (`nodeActionVerification`). */
+export declare const nodeActionReboots: (actionNameArg: TNodeActionName, rebootArg: boolean) => boolean;
+/**
+ * What Cloudly accepts as evidence that a claimed action changed the node, by what the action does.
+ *
+ * - `new-boot`: an action that reboots is verified by a heartbeat, accepted after the claim, whose
+ *   `boot.id` differs from the boot the claim stated.
+ * - `target-version`: an update is verified by a heartbeat, accepted after the claim, whose bundle
+ *   version is the action's target version.
+ * - `upgrade-complete`: a host upgrade without a reboot is verified by Spark's `complete` and a
+ *   heartbeat accepted after it; a heartbeat that states `boot.rebootRequired` fails the action
+ *   `reboot-required` instead, because applying the upgrade needs a reboot the operator did not
+ *   request. Cloudly never escalates to one.
+ *
+ * An action that restarts the node runtime (every action but a host upgrade without a reboot) is
+ * then only `succeeded` once the node's Pallet registered a runtime session after the claim and
+ * Cloudly accepted an observation of every replica slot on the node after that registration.
+ */
+export type TNodeActionVerification = 'new-boot' | 'target-version' | 'upgrade-complete';
+export declare const nodeActionVerification: (actionNameArg: TNodeActionName, rebootArg: boolean) => TNodeActionVerification;
+/** Whether the action restarts the node runtime and is verified by its return (see `nodeActionVerification`). */
+export declare const nodeActionRestartsRuntime: (actionNameArg: TNodeActionName, rebootArg: boolean) => boolean;
+/**
+ * Why an action ended `failed`, each with the remedy an operator is told.
+ *
+ * The first group is stated by Spark (`TSparkNodeActionFailureCode`), the second by Cloudly.
+ */
+export declare const nodeActionFailureRemedies: Readonly<{
+    readonly 'download-failed': string;
+    readonly 'installer-mismatch': string;
+    readonly 'install-failed': string;
+    readonly 'drain-failed': string;
+    readonly 'reboot-failed': 'The host did not accept the reboot. Read the node\'s Spark journal.';
+    readonly 'host-upgrade-failed': string;
+    readonly 'executor-failed': 'Spark could not run the action. Read the node\'s Spark journal.';
+    readonly 'reboot-required': string;
+    readonly 'target-below-node': string;
+}>;
+export type TNodeActionFailureCode = keyof typeof nodeActionFailureRemedies;
+/** The failure codes Spark may state with a `fail` transition. */
+export declare const sparkNodeActionFailureCodes: readonly ["download-failed", "drain-failed", "executor-failed", "host-upgrade-failed", "install-failed", "installer-mismatch", "reboot-failed"];
+export type TSparkNodeActionFailureCode = typeof sparkNodeActionFailureCodes[number];
+/**
+ * Why an action ended `expired`.
+ *
+ * - `claim-window-passed`: no Spark claimed it within `nodeActionContract.claimWindowMs`.
+ * - `carrier-retired`: a Swarm-era record on a node that holds no Swarm-era session, which no
+ *   carrier delivers: it states none of the frozen parameters and target the node runtime's
+ *   lifecycle needs. Cloudly keeps the record.
+ */
+export type TNodeActionExpiryReason = 'claim-window-passed' | 'carrier-retired';
+export interface INodeActionExpiry {
+    reason: TNodeActionExpiryReason;
+    at: number;
+}
+/**
+ * The Spark release an update moves a node to: the fleet Spark target as it stood when the
+ * operator requested the action, frozen into the action.
+ */
+export interface INodeActionTarget {
+    /** `MAJOR.MINOR.PATCH`, without `v`. */
+    version: string;
+    /** The SHA-256 of the release's `install.sh`, as `SHA256SUMS.txt` states it (lowercase hex). */
+    installerSha256: string;
+    /** The fleet target's revision this copy was taken from. */
+    targetRevision: number;
+}
+/**
+ * What an operator confirmed when requesting a node runtime action, frozen into the action.
+ *
+ * The consent is the typed hostname and the digest of the impact preview the operator read:
+ * Cloudly refuses the request when either no longer matches what it reads now.
+ */
+export interface INodeActionConfirmation {
+    /** The hostname the operator typed; must equal the node's reported hostname. */
+    confirmedHostname: string;
+    /** `impactDigest` of the preview the operator confirmed (`computeNodeActionImpactDigest`). */
+    impactDigest: string;
+    /**
+     * Consent to restarting the Corestore the preview names on this node. Required `true` when the
+     * impact names one (`corestore`), and never assumed: a Corestore restart is never a default.
+     */
+    corestoreRestart: boolean;
+    /** `systemUpgrade` only: reboot after the upgrade, as part of this one action. */
+    reboot: boolean;
+    /**
+     * `serveZoneServiceUpdate` only, and required there: the revision of the fleet Spark target the
+     * preview showed (`INodeActionPreview.target.targetRevision`). Cloudly refuses the update
+     * (`target-changed`) when the target it would freeze into the action has another revision, so the
+     * consent names the exact release the node is moved to. Absent for every other action.
+     */
+    targetRevision?: number;
+}
+/** One service the action interrupts, as the impact preview names it. */
+export interface INodeActionImpactService {
+    serviceId: string;
+    name: string;
+    /** Replica slots of this service on the node. */
+    slotsOnNode: number;
+    /** Replica slots of this service on other nodes; `0` means the service is down while the node is. */
+    slotsElsewhere: number;
+    /** The service is the cluster's designated ingress. */
+    clusterIngress: boolean;
+}
+/**
+ * What a node action interrupts, read from Cloudly's database when it is previewed and again when
+ * it is requested.
+ *
+ * - `clusterNodeCount` 1: the node is its cluster, so the action is a full cluster outage.
+ * - `relayHost`: the node hosts its cluster's relay, so every inter-node connection of the cluster
+ *   is interrupted while it is down. The relay never moves for an action.
+ * - `corestore`: the node runs a Corestore (`IClusterNode.data.corestore`), which restarts with it.
+ * - `services`: every service with a replica slot on the node, sorted by `serviceId`.
+ */
+export interface INodeActionImpact {
+    nodeId: string;
+    clusterId: string;
+    /** The hostname the node reports, which a confirmation types; `null` while it reports none. */
+    hostname: string | null;
+    clusterNodeCount: number;
+    relayHost: boolean;
+    corestore: boolean;
+    services: INodeActionImpactService[];
+}
+/** The SHA-256 (lowercase hex) of one impact's canonical JSON, which a confirmation names. */
+export declare const computeNodeActionImpactDigest: (impactArg: INodeActionImpact) => Promise<string>;
+/** When Spark claimed an action, and in which boot of the host. */
+export interface INodeActionClaim {
+    claimedAt: number;
+    /** The host's `boot.id` the claim stated. */
+    bootId: string;
+    /** The Spark bundle version the node reported when it claimed. */
+    bundleVersion: string | null;
+}
+/** Why an action failed, and the remedy the operator was told (`nodeActionFailureRemedies`). */
+export interface INodeActionFailure {
+    code: TNodeActionFailureCode;
+    remedy: string;
+    /** Spark's or Cloudly's own text, bounded by `nodeActionContract.maximumDetailLength`. */
+    detail: string | null;
+}
+/** Who moved an action into a state. */
+export type TNodeActionActor = 'operator' | 'spark' | 'cloudly';
+/** One state an action entered, in order. */
+export interface INodeActionTransition {
+    status: TNodeActionStatus;
+    at: number;
+    actor: TNodeActionActor;
+    detail: string | null;
+}
+/**
+ * The node runtime's lifecycle of one action: what was confirmed and frozen at the request, and
+ * every state since. Absent on a Swarm-era record, which no carrier but the Swarm-era daemon's
+ * delivers.
+ *
+ * `revision` advances with every state change. Each change is one transaction that matches the
+ * action on its expected state and revision, so two writers never both move one action.
+ */
+export interface INodeActionLifecycle {
+    clusterId: string;
+    revision: number;
+    confirmation: INodeActionConfirmation;
+    impact: INodeActionImpact;
+    /** `serveZoneServiceUpdate` only. */
+    target: INodeActionTarget | null;
+    /** The claim window's end while `pending`; the completion deadline once claimed. */
+    deadlineAt: number;
+    claim: INodeActionClaim | null;
+    failure: INodeActionFailure | null;
+    timeline: INodeActionTransition[];
+}
+/**
+ * Every reason Cloudly answers instead of admitting, previewing or cancelling a node action. Each
+ * travels by name as a `TypedResponseError`, and a refused request changes nothing.
+ */
+export declare const nodeActionRefusals: readonly ["node-missing", "node-action-undeliverable", "node-action-unsupported", "system-upgrade-unqualified", "node-action-open", "cluster-action-open", "spark-target-unset", "spark-target-below-node", "spark-target-held", "confirmation-invalid", "confirmation-hostname-mismatch", "impact-changed", "target-changed", "corestore-consent-required", "impact-unreadable", "node-action-missing", "node-action-not-cancellable", "node-action-revision-stale"];
+export type TNodeActionRefusalCode = typeof nodeActionRefusals[number];
+/** What requesting one action on one node would do, and whether Cloudly would admit it now. */
+export interface INodeActionPreview {
+    nodeId: string;
+    actionName: TNodeActionName;
+    impact: INodeActionImpact;
+    /** What a confirmation names (`INodeActionConfirmation.impactDigest`). */
+    impactDigest: string;
+    /** The Spark bundle version the node reports; `null` while it reports none. */
+    nodeBundleVersion: string | null;
+    /** Whether the node's Spark states that the host needs a reboot; `null` while it states nothing. */
+    rebootRequired: boolean | null;
+    /** `serveZoneServiceUpdate` only: the fleet target the update moves the node to. */
+    target: INodeActionTarget | null;
+    /** Why a request would be refused now, in `nodeActionRefusals` order; empty when it would be admitted. */
+    refusals: TNodeActionRefusalCode[];
+}
+/**
+ * Validates one confirmation for one action and names every reason it is refused.
+ *
+ * Shape only: an update must state `targetRevision`, every other action must not. Whether it
+ * matches the node, the impact and the fleet target Cloudly reads now is Cloudly's decision
+ * (`confirmation-hostname-mismatch`, `impact-changed`, `target-changed`, `corestore-consent-required`).
+ */
+export declare const validateNodeActionConfirmation: (valueArg: unknown, actionNameArg: TNodeActionName, pathArg?: string) => string[];
+/** HTTPS POST body asking for the action Cloudly holds for this node. Never log, persist, or return nodeToken. */
+export interface ISparkNodeActionOfferRequest {
+    nodeId: string;
+    nodeToken: string;
+    /** Read and negotiated before the node is authenticated; see `sparkNodeActionContracts`. */
+    protocol: IProtocolOffer;
+}
+/**
+ * One action as Spark executes it: the node runtime's view of an open action.
+ *
+ * `status` is the action's state when Cloudly answered; `revision` is what Spark's next transition
+ * names. `claim` states the boot Spark claimed it in, so a Spark that restarted mid-action resumes
+ * by replaying the transition it had sent rather than claiming again.
+ */
+export interface ISparkNodeActionAssignment {
+    id: string;
+    actionName: TNodeActionName;
+    status: Extract<TNodeActionStatus, 'pending' | 'claimed' | 'executing' | 'draining' | 'rebooting' | 'verifying'>;
+    revision: number;
+    deadlineAt: number;
+    /** `systemUpgrade` only: reboot after the upgrade. */
+    reboot: boolean;
+    /** `serveZoneServiceUpdate` only: install exactly this release, after checking its installer's SHA-256. */
+    target: INodeActionTarget | null;
+    claim: {
+        bootId: string;
+    } | null;
+}
+/** What Cloudly answers the offer route: the node's one open action, or `null`. */
+export interface ISparkNodeActionOffer {
+    nodeId: string;
+    action: ISparkNodeActionAssignment | null;
+    /** The controller's offer, so the node judges the answer it acts on. */
+    protocol: IProtocolOffer;
+}
+/**
+ * One step Spark states about the action it executes.
+ *
+ * - `claim`: take a `pending` action, in the boot `bootId` names.
+ * - `phase`: the action entered a later phase (`sparkNodeActionPhaseOrder`). A reboot drains and
+ *   then reboots; an update executes (downloads and installs) and then drains (restarts the node
+ *   runtime on the new release); a host upgrade executes and, with `reboot`, drains and reboots.
+ * - `complete`: a host upgrade without a reboot finished; Cloudly verifies it from the next heartbeat.
+ * - `fail`: the action failed with one of `sparkNodeActionFailureCodes`.
+ *
+ * Every other ending is Cloudly's: it verifies an action from what the node reports
+ * (`nodeActionVerification`), and a deadline that passes ends one `unverified`.
+ */
+export type TSparkNodeActionTransition = {
+    kind: 'claim';
+    bootId: string;
+} | {
+    kind: 'phase';
+    phase: TSparkNodeActionPhase;
+} | {
+    kind: 'complete';
+} | {
+    kind: 'fail';
+    code: TSparkNodeActionFailureCode;
+    detail: string;
+};
+/** HTTPS POST body stating one transition. Never log, persist, or return nodeToken. */
+export interface ISparkNodeActionTransitionRequest {
+    nodeId: string;
+    nodeToken: string;
+    /** Read and negotiated before the node is authenticated; see `sparkNodeActionContracts`. */
+    protocol: IProtocolOffer;
+    actionId: string;
+    /** The revision of the assignment the transition was decided from. */
+    expectedRevision: number;
+    transition: TSparkNodeActionTransition;
+}
+/**
+ * Why Cloudly did not apply a transition.
+ *
+ * - `action-unknown`: no action of that id on this node.
+ * - `action-closed`: the action ended; `action` states it no more, Spark stops executing it.
+ * - `revision-stale`: the action moved since `expectedRevision`; `action` states where it stands.
+ * - `transition-invalid`: the action's state or kind does not admit this transition.
+ */
+export type TSparkNodeActionTransitionRefusal = 'action-unknown' | 'action-closed' | 'revision-stale' | 'transition-invalid';
+/**
+ * What Cloudly answers a transition with.
+ *
+ * `replayed` answers a transition Cloudly had already applied at exactly that revision, so a
+ * Spark that lost the answer and sends it again is told it took effect. `action` is the action as
+ * it stands after the answer, `null` once it is no longer open.
+ */
+export type TSparkNodeActionTransitionAnswer = {
+    outcome: 'applied' | 'replayed';
+    action: ISparkNodeActionAssignment | null;
+    protocol: IProtocolOffer;
+} | {
+    outcome: 'refused';
+    reason: TSparkNodeActionTransitionRefusal;
+    action: ISparkNodeActionAssignment | null;
+    protocol: IProtocolOffer;
+};
+/**
+ * The node runtime's action routes.
+ *
+ * Spark asks the offer route after each accepted heartbeat and states every step on the transition
+ * route. Both are authenticated with the node's Spark credential exactly like
+ * `sparkNodeHeartbeatContract` and judged in the same server order: the offer first, within
+ * `maxRequestBytes`, answered with `protocolRefusalStatus` and an `IProtocolRefusal` body on
+ * refusal, before the node is authenticated. The server's offer on these routes names, as its
+ * minimum, the release that introduced them, so a Spark below it is refused by name and is never
+ * handed an action.
+ */
+export declare const sparkNodeActionContracts: Readonly<{
+    readonly offer: Readonly<{
+        readonly endpoint: '/spark/nodes/action';
+        readonly maxRequestBytes: 1024;
+        readonly maxResponseBytes: 4096;
+    }>;
+    readonly transition: Readonly<{
+        readonly endpoint: '/spark/nodes/action/transition';
+        readonly maxRequestBytes: 2048;
+        readonly maxResponseBytes: 4096;
+    }>;
+    readonly protocolRefusalStatus: 422;
+}>;
+/** The kernel's `boot_id`: one lowercase UUID. */
+export declare const isHostBootId: (valueArg: unknown) => valueArg is string;
+/** One assignment, exactly its keys; detached and frozen. */
+export declare const snapshotSparkNodeActionAssignment: (valueArg: unknown) => ISparkNodeActionAssignment;
+export declare const snapshotSparkNodeActionOfferRequest: (valueArg: unknown) => ISparkNodeActionOfferRequest;
+export declare const snapshotSparkNodeActionOffer: (valueArg: unknown) => ISparkNodeActionOffer;
+export declare const snapshotSparkNodeActionTransitionRequest: (valueArg: unknown) => ISparkNodeActionTransitionRequest;
+export declare const snapshotSparkNodeActionTransitionAnswer: (valueArg: unknown) => TSparkNodeActionTransitionAnswer;
+/**
+ * Whether an open action admits one transition from Spark, judged from its state alone.
+ *
+ * `claim` takes a `pending` action. A `phase` moves strictly forward in `sparkNodeActionPhaseOrder`
+ * from `claimed` or an earlier phase, and only into a phase the action has: `rebooting` only for
+ * an action that reboots, `draining` for every action but a host upgrade without a reboot.
+ * `complete` ends the execution of a host upgrade without a reboot. `fail` ends any claimed action
+ * that Cloudly is not yet verifying.
+ */
+export declare const admitsSparkNodeActionTransition: (actionArg: Pick<ISparkNodeActionAssignment, 'actionName' | 'status' | 'reboot'>, transitionArg: TSparkNodeActionTransition) => boolean;
+/** True when a value is a canonical list of action names: known names, strictly increasing, at least one. */
+export declare const isNodeActionNameList: (valueArg: unknown) => valueArg is TNodeActionName[];
+/** Sorts action names into canonical order, so a list built from a set compares byte for byte. */
+export declare const sortNodeActionNames: (namesArg: Iterable<TNodeActionName>) => TNodeActionName[];