@serve.zone/interfaces 32.50.0 → 32.52.0

package/ts/data/deploymentlegacyimport.ts

@@ -4,15 +4,22 @@ import type {
   TSha256Digest,
 } from './immutableimage.js';
 import { normalizeSha256Digest } from './immutableimage.js';
-import { hasExactKeys, isPlainRecord } from '../private/dataproperties.js';
+import {
+  hasExactKeys,
+  isPlainRecord,
+  readDataElements,
+  readDataProperties,
+} from '../private/dataproperties.js';
 
 /**
  * Legacy image import: a greenfield deployment whose image is the one a legacy `deployOnPush`
  * service already runs, instead of one built from a source revision.
  *
  * A legacy service without deployable source still has an image in Cloudly's registry and, until
- * its runtime is frozen, healthy replicas running it. An administrator captures that fact once as
- * a {@link ILegacyServiceRuntimeAttestation} while the replicas still run. A greenfield successor
+ * its runtime is frozen, replicas running it. An administrator observes those replicas on the
+ * hosts that run them ({@link ILegacyServiceHostObservation}) while they still run, and Cloudly
+ * captures that observation once as a {@link ILegacyServiceRuntimeAttestation} after it verified
+ * the observed root against its own registry. A greenfield successor
  * reservation names the attestation in `legacyImport` instead of a `sourceRevision`, and Cloudly
  * then imports the attested image into the successor's own repository and release tag itself:
  * the bytes never leave the registry and the release records that it was imported, not built.
@@ -60,19 +67,98 @@ export interface ILegacyServiceImageSource {
   platforms: ILegacyImagePlatformManifest[];
 }
 
-/** One healthy replica of the legacy service, observed running the attested digest. */
+/**
+ * One replica of the legacy service, observed running the attested digest in its own stated
+ * health: healthy, or running with no healthcheck that could state one.
+ */
 export interface ILegacyServiceRuntimeTaskAttestation {
+  /** The replica's runtime identity: the Swarm task it was observed as. */
   deploymentId: string;
+  /** The hostname of the node the replica was observed on. */
   nodeName: string;
   observedDigest: TSha256Digest;
 }
 
+/**
+ * Where the runtime part of an attestation comes from. `administrator-host-observation`: an
+ * administrator read the legacy Swarm service and its containers on the hosts that run them, and
+ * Cloudly judged that observation against its own registry.
+ */
+export type TLegacyServiceRuntimeEvidenceSource = 'administrator-host-observation';
+
+/** A container's state as the Docker engine reports it (`State.Status`). */
+export type TLegacyHostContainerState =
+  | 'created'
+  | 'running'
+  | 'paused'
+  | 'restarting'
+  | 'removing'
+  | 'exited'
+  | 'dead';
+
+/**
+ * A container's health as the Docker engine reports it (`State.Health.Status`). `none`: no
+ * healthcheck applies to the container — the image declares none and the service adds none — so
+ * the engine reports no health state at all.
+ */
+export type TLegacyHostContainerHealth = 'healthy' | 'unhealthy' | 'starting' | 'none';
+
+/**
+ * The image store of the Docker engine that runs a container. On the `containerd` store a
+ * container's image id is the digest of the root it was pulled as; on the `classic` store it is
+ * the image configuration digest of the platform manifest the engine pulled.
+ */
+export type TLegacyHostImageStore = 'containerd' | 'classic';
+
+/** A Swarm service's mode (`Spec.Mode`): a replicated service states its desired replicas. */
+export type TLegacyHostSwarmServiceMode =
+  | { kind: 'replicated'; desiredReplicas: number }
+  | { kind: 'global' };
+
+/** One replica of a legacy Swarm service, as an administrator read it on the node that runs it. */
+export interface ILegacyHostReplicaObservation {
+  /** The hostname of the node the task runs on. */
+  nodeHostname: string;
+  /** The Swarm task id (25 lowercase base-36 characters). */
+  swarmTaskId: string;
+  /** The full container id of the task (64 lowercase hex characters). */
+  containerId: string;
+  imageStore: TLegacyHostImageStore;
+  /** The container's image id (`Image`), a sha256 digest. */
+  containerImageId: TSha256Digest;
+  /** The `RepoDigests` of the container's image, exactly as the engine lists them. */
+  imageRepoDigests: string[];
+  state: TLegacyHostContainerState;
+  health: TLegacyHostContainerHealth;
+}
+
+/**
+ * An administrator's observation of the legacy Swarm service of one legacy service and of every
+ * container its tasks run, read on the hosts while the legacy runtime still runs.
+ *
+ * It states facts, not conclusions: Cloudly judges it against its own registry
+ * ({@link judgeLegacyServiceHostObservation}) before it attests anything.
+ */
+export interface ILegacyServiceHostObservation {
+  /** The Swarm service name. */
+  swarmServiceName: string;
+  /** The image reference of the Swarm service spec (`Spec.TaskTemplate.ContainerSpec.Image`). */
+  specImage: string;
+  mode: TLegacyHostSwarmServiceMode;
+  /** When the administrator read the hosts, in milliseconds since the epoch. */
+  observedAt: number;
+  /** Every running task's replica, sorted by `swarmTaskId`. */
+  replicas: ILegacyHostReplicaObservation[];
+}
+
 /**
  * Durable evidence, captured by an administrator while the legacy runtime still ran, that every
- * required replica of a legacy service was healthy and ran exactly the registry root it names.
+ * desired replica of a legacy service ran, in its own stated health, exactly the registry root it
+ * names.
  *
  * Cloudly writes one and never changes it. A capture only succeeds on complete evidence, so a
- * stored attestation is by construction one whose runtime digest is its source root digest.
+ * stored attestation is by construction one whose runtime digest is its source root digest and
+ * whose runtime part is exactly the host observation it records.
  */
 export interface ILegacyServiceRuntimeAttestation {
   id: string;
@@ -81,11 +167,16 @@ export interface ILegacyServiceRuntimeAttestation {
     organizationId: string;
     source: ILegacyServiceImageSource;
     runtime: {
+      /** The desired replicas of the observed replicated Swarm service. */
       requiredReplicaCount: number;
+      /** Replicas observed running healthy, or running with no healthcheck (`health: 'none'`). */
       healthyReplicaCount: number;
       runtimeDigest: TSha256Digest;
-      /** Sorted by deploymentId, one per required replica. */
+      /** Sorted by deploymentId, one per required replica: the observed replicas. */
       tasks: ILegacyServiceRuntimeTaskAttestation[];
+      evidenceSource: TLegacyServiceRuntimeEvidenceSource;
+      /** The observation the runtime part was built from, as the administrator submitted it. */
+      hostObservation: ILegacyServiceHostObservation;
     };
     capturedByUserId: string;
     capturedAt: number;
@@ -120,6 +211,31 @@ const legacyImageImportIndexMediaTypes: readonly TLegacyImageImportIndexMediaTyp
   'application/vnd.docker.distribution.manifest.list.v2+json',
 ];
 const legacyImagePlatforms: readonly TImmutableContainerPlatform[] = ['linux/amd64', 'linux/arm64'];
+const legacyHostContainerStates: readonly TLegacyHostContainerState[] = [
+  'created',
+  'running',
+  'paused',
+  'restarting',
+  'removing',
+  'exited',
+  'dead',
+];
+const legacyHostContainerHealths: readonly TLegacyHostContainerHealth[] = [
+  'healthy',
+  'unhealthy',
+  'starting',
+  'none',
+];
+/** The health states a replica may be attested in: healthy, or no healthcheck at all. */
+const attestableLegacyHostContainerHealths: readonly TLegacyHostContainerHealth[] = ['healthy', 'none'];
+const legacyHostImageStores: readonly TLegacyHostImageStore[] = ['containerd', 'classic'];
+const swarmTaskIdRegex = /^[a-z0-9]{25}$/;
+const containerIdRegex = /^[0-9a-f]{64}$/;
+const swarmServiceNameRegex = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/;
+const nodeHostnameRegex = /^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
+const imageReferenceRegex = /^\S{1,512}$/;
+const repoDigestRegex = /^[^\s@]{1,440}@sha256:[0-9a-f]{64}$/;
+const maximumRepoDigestCount = 32;
 
 const isIdentifier = (valueArg: unknown): valueArg is string => (
   typeof valueArg === 'string' && identifierRegex.test(valueArg)
@@ -168,6 +284,256 @@ export const validateLegacyImageImportReference = (referenceArg: unknown): strin
   return errors;
 };
 
+const validateHostReplicaObservation = (
+  replicaArg: unknown,
+  labelArg: string,
+): string[] => {
+  const replica = readDataProperties(replicaArg);
+  if (replica === null) return [`${labelArg} must be a plain data object`];
+  const errors: string[] = [];
+  if (!hasExactKeys(replica, [
+    'nodeHostname',
+    'swarmTaskId',
+    'containerId',
+    'imageStore',
+    'containerImageId',
+    'imageRepoDigests',
+    'state',
+    'health',
+  ])) {
+    errors.push(`${labelArg} must use its exact schema`);
+  }
+  if (typeof replica.nodeHostname !== 'string' || !nodeHostnameRegex.test(replica.nodeHostname)) {
+    errors.push(`${labelArg}.nodeHostname must be a host name`);
+  }
+  if (typeof replica.swarmTaskId !== 'string' || !swarmTaskIdRegex.test(replica.swarmTaskId)) {
+    errors.push(`${labelArg}.swarmTaskId must be a Swarm task id`);
+  }
+  if (typeof replica.containerId !== 'string' || !containerIdRegex.test(replica.containerId)) {
+    errors.push(`${labelArg}.containerId must be a full container id`);
+  }
+  if (!legacyHostImageStores.some((storeArg) => storeArg === replica.imageStore)) {
+    errors.push(`${labelArg}.imageStore must be containerd or classic`);
+  }
+  if (!isCanonicalDigest(replica.containerImageId)) {
+    errors.push(`${labelArg}.containerImageId must be a canonical sha256 digest`);
+  }
+  const repoDigests = readDataElements(replica.imageRepoDigests, maximumRepoDigestCount);
+  if (repoDigests === null
+    || repoDigests.some((entryArg) => typeof entryArg !== 'string' || !repoDigestRegex.test(entryArg))
+    || new Set(repoDigests).size !== repoDigests.length) {
+    errors.push(`${labelArg}.imageRepoDigests must be unique digested image references`);
+  }
+  if (!legacyHostContainerStates.some((stateArg) => stateArg === replica.state)) {
+    errors.push(`${labelArg}.state must be a Docker container state`);
+  }
+  if (!legacyHostContainerHealths.some((healthArg) => healthArg === replica.health)) {
+    errors.push(`${labelArg}.health must be healthy, unhealthy, starting or none`);
+  }
+  return errors;
+};
+
+const validateHostSwarmServiceMode = (modeArg: unknown, labelArg: string): string[] => {
+  const mode = readDataProperties(modeArg);
+  if (mode === null) return [`${labelArg} must be a plain data object`];
+  if (mode.kind === 'global') {
+    return hasExactKeys(mode, ['kind']) ? [] : [`${labelArg} must use its exact schema`];
+  }
+  if (mode.kind !== 'replicated') return [`${labelArg}.kind must be replicated or global`];
+  const errors: string[] = [];
+  if (!hasExactKeys(mode, ['kind', 'desiredReplicas'])) {
+    errors.push(`${labelArg} must use its exact schema`);
+  }
+  if (typeof mode.desiredReplicas !== 'number'
+    || !Number.isSafeInteger(mode.desiredReplicas)
+    || mode.desiredReplicas < 0
+    || mode.desiredReplicas > maximumReplicaCount) {
+    errors.push(`${labelArg}.desiredReplicas must be a bounded replica count`);
+  }
+  return errors;
+};
+
+/**
+ * The shape of a host observation: exact keys at every level, Docker's own value sets, at most 64
+ * replicas, unique and sorted by Swarm task id, each container observed once. It judges nothing
+ * against a registry; {@link judgeLegacyServiceHostObservation} does.
+ */
+export const validateLegacyServiceHostObservation = (
+  observationArg: unknown,
+  labelArg = 'hostObservation',
+): string[] => {
+  const observation = readDataProperties(observationArg);
+  if (observation === null) return [`${labelArg} must be a plain data object`];
+  const errors: string[] = [];
+  if (!hasExactKeys(observation, ['swarmServiceName', 'specImage', 'mode', 'observedAt', 'replicas'])) {
+    errors.push(`${labelArg} must use its exact schema`);
+  }
+  if (typeof observation.swarmServiceName !== 'string'
+    || !swarmServiceNameRegex.test(observation.swarmServiceName)) {
+    errors.push(`${labelArg}.swarmServiceName must be a Swarm service name`);
+  }
+  if (typeof observation.specImage !== 'string' || !imageReferenceRegex.test(observation.specImage)) {
+    errors.push(`${labelArg}.specImage must be a bounded image reference`);
+  }
+  errors.push(...validateHostSwarmServiceMode(observation.mode, `${labelArg}.mode`));
+  if (!isPositiveSafeInteger(observation.observedAt, Number.MAX_SAFE_INTEGER)) {
+    errors.push(`${labelArg}.observedAt must be a positive timestamp`);
+  }
+  const replicas = readDataElements(observation.replicas, maximumReplicaCount);
+  if (replicas === null) {
+    errors.push(`${labelArg}.replicas must be a list of at most ${maximumReplicaCount} replicas`);
+    return errors;
+  }
+  replicas.forEach((replicaArg, indexArg) => {
+    errors.push(...validateHostReplicaObservation(replicaArg, `${labelArg}.replicas[${indexArg}]`));
+  });
+  const readReplicaKey = (replicaArg: unknown, keyArg: string): unknown => (
+    readDataProperties(replicaArg)?.[keyArg]
+  );
+  const taskIds = replicas.map((replicaArg) => readReplicaKey(replicaArg, 'swarmTaskId'));
+  const sortedTaskIds = taskIds
+    .filter((idArg): idArg is string => typeof idArg === 'string')
+    .sort();
+  if (new Set(taskIds).size !== taskIds.length
+    || JSON.stringify(taskIds) !== JSON.stringify(sortedTaskIds)) {
+    errors.push(`${labelArg}.replicas must be unique and sorted by swarmTaskId`);
+  }
+  const containerIds = replicas.map((replicaArg) => readReplicaKey(replicaArg, 'containerId'));
+  if (new Set(containerIds).size !== containerIds.length) {
+    errors.push(`${labelArg}.replicas must observe each container once`);
+  }
+  return errors;
+};
+
+/** True when a value is a well-formed host observation. */
+export const isLegacyServiceHostObservation = (
+  valueArg: unknown,
+): valueArg is ILegacyServiceHostObservation => (
+  validateLegacyServiceHostObservation(valueArg).length === 0
+);
+
+/**
+ * The root digest one replica was pulled as from `registryHost/repository`.
+ *
+ * On the containerd store that is the container's image id, which the image's `RepoDigests` must
+ * list for the repository. On the classic store it is the one digest `RepoDigests` lists for the
+ * repository; none, or more than one, leaves the root unknown.
+ */
+const selectReplicaRootDigest = (
+  replicaArg: ILegacyHostReplicaObservation,
+  repositoryReferenceArg: string,
+): TSha256Digest | undefined => {
+  const prefix = `${repositoryReferenceArg}@`;
+  const repositoryDigests = replicaArg.imageRepoDigests
+    .filter((entryArg) => entryArg.startsWith(prefix))
+    .map((entryArg) => normalizeSha256Digest(entryArg.slice(prefix.length)))
+    .filter((digestArg): digestArg is TSha256Digest => digestArg !== undefined);
+  if (replicaArg.imageStore === 'containerd') {
+    return repositoryDigests.includes(replicaArg.containerImageId)
+      ? replicaArg.containerImageId
+      : undefined;
+  }
+  return repositoryDigests.length === 1 ? repositoryDigests[0] : undefined;
+};
+
+/**
+ * The one root digest every observed replica runs from the legacy service's own repository, which
+ * is the digest Cloudly then inspects in its registry. Refused when a replica's root from that
+ * repository is unknown, when the replicas run more than one root, or when nothing was observed.
+ */
+export const selectLegacyServiceHostObservationRootDigest = (argsArg: {
+  observation: ILegacyServiceHostObservation;
+  registryHost: string;
+  repository: string;
+}): { rootDigest?: TSha256Digest; errors: string[] } => {
+  const repositoryReference = `${argsArg.registryHost}/${argsArg.repository}`;
+  const errors: string[] = [];
+  const roots = new Set<TSha256Digest>();
+  argsArg.observation.replicas.forEach((replicaArg, indexArg) => {
+    const root = selectReplicaRootDigest(replicaArg, repositoryReference);
+    if (root === undefined) {
+      errors.push(replicaArg.imageStore === 'containerd'
+        ? `hostObservation.replicas[${indexArg}] image is not listed as ${repositoryReference}@<its image id>`
+        : `hostObservation.replicas[${indexArg}] image lists not exactly one digest of ${repositoryReference}`);
+      return;
+    }
+    roots.add(root);
+  });
+  if (argsArg.observation.replicas.length === 0) {
+    errors.push('hostObservation must observe at least one replica');
+  }
+  if (roots.size > 1) {
+    errors.push('hostObservation replicas run more than one root digest');
+  }
+  const [rootDigest] = [...roots];
+  return errors.length === 0 && rootDigest !== undefined ? { rootDigest, errors } : { errors };
+};
+
+/**
+ * Judges a well-formed host observation against the registry source Cloudly inspected for it.
+ * Every rule an attestation's runtime part must meet:
+ *
+ * - the Swarm service is replicated, with at least one desired replica, and exactly its desired
+ *   replicas were observed;
+ * - its spec image names the source repository by the source tag, by the root digest, or by both;
+ * - every replica is `running`, and `healthy` or without a healthcheck (`none`) — `unhealthy` and
+ *   `starting` are refused;
+ * - every replica runs the source root from the source repository: its image lists
+ *   `registryHost/repository@rootDigest`, and its image id is the root digest on the containerd
+ *   store or one of the root's platform image configuration digests on the classic store.
+ */
+export const judgeLegacyServiceHostObservation = (argsArg: {
+  observation: ILegacyServiceHostObservation;
+  source: ILegacyServiceImageSource;
+  label?: string;
+}): string[] => {
+  const label = argsArg.label ?? 'hostObservation';
+  const { observation, source } = argsArg;
+  const errors: string[] = [];
+  if (observation.mode.kind !== 'replicated') {
+    errors.push(`${label}.mode must be replicated: a legacy service runs as a replicated Swarm service`);
+  } else if (observation.mode.desiredReplicas < 1) {
+    errors.push(`${label}.mode must desire at least one replica`);
+  } else if (observation.replicas.length !== observation.mode.desiredReplicas) {
+    errors.push(`${label} must observe exactly the ${observation.mode.desiredReplicas} desired replicas`);
+  }
+  const repositoryReference = `${source.registryHost}/${source.repository}`;
+  const specImages = [
+    `${repositoryReference}:${source.tag}`,
+    `${repositoryReference}@${source.rootDigest}`,
+    `${repositoryReference}:${source.tag}@${source.rootDigest}`,
+  ];
+  if (!specImages.includes(observation.specImage)) {
+    errors.push(`${label}.specImage must name ${repositoryReference} by its source tag or root digest`);
+  }
+  const imageConfigDigests = source.platforms.map((platformArg) => platformArg.imageConfigDigest);
+  observation.replicas.forEach((replicaArg, indexArg) => {
+    const replicaLabel = `${label}.replicas[${indexArg}]`;
+    if (replicaArg.state !== 'running') {
+      errors.push(`${replicaLabel}.state must be running`);
+    }
+    if (!attestableLegacyHostContainerHealths.includes(replicaArg.health)) {
+      errors.push(`${replicaLabel}.health must be healthy or none`);
+    }
+    if (!replicaArg.imageRepoDigests.includes(`${repositoryReference}@${source.rootDigest}`)) {
+      errors.push(`${replicaLabel} image must be ${repositoryReference}@${source.rootDigest}`);
+    }
+    if (replicaArg.imageStore === 'containerd') {
+      if (replicaArg.containerImageId !== source.rootDigest) {
+        errors.push(`${replicaLabel}.containerImageId must be the root digest on the containerd image store`);
+      }
+      return;
+    }
+    if (!imageConfigDigests.includes(replicaArg.containerImageId)) {
+      errors.push(`${replicaLabel}.containerImageId must be a platform image configuration digest of the root on the classic image store`);
+    }
+    if (selectReplicaRootDigest(replicaArg, repositoryReference) === undefined) {
+      errors.push(`${replicaLabel} image must list exactly one digest of ${repositoryReference} on the classic image store`);
+    }
+  });
+  return errors;
+};
+
 const validatePlatformManifest = (
   manifestArg: unknown,
   indexArg: number,
@@ -270,17 +636,54 @@ const validateImageSource = (sourceArg: unknown): string[] => {
   return errors;
 };
 
-const validateRuntime = (runtimeArg: unknown, rootDigestArg: unknown): string[] => {
+const isLegacyServiceImageSource = (valueArg: unknown): valueArg is ILegacyServiceImageSource => (
+  validateImageSource(valueArg).length === 0
+);
+
+const validateRuntime = (runtimeArg: unknown, sourceArg: unknown): string[] => {
   if (!isPlainRecord(runtimeArg)) return ['runtime must be an object'];
+  const rootDigest = isPlainRecord(sourceArg) ? sourceArg.rootDigest : undefined;
   const errors: string[] = [];
   if (!hasExactKeys(runtimeArg, [
     'requiredReplicaCount',
     'healthyReplicaCount',
     'runtimeDigest',
     'tasks',
+    'evidenceSource',
+    'hostObservation',
   ])) {
     errors.push('runtime must use its exact schema');
   }
+  if (runtimeArg.evidenceSource !== 'administrator-host-observation') {
+    errors.push('runtime.evidenceSource must be administrator-host-observation');
+  }
+  const hostObservation = runtimeArg.hostObservation;
+  const observationErrors = validateLegacyServiceHostObservation(
+    hostObservation, 'runtime.hostObservation');
+  errors.push(...observationErrors);
+  if (observationErrors.length === 0
+    && isLegacyServiceHostObservation(hostObservation)
+    && isLegacyServiceImageSource(sourceArg)) {
+    errors.push(...judgeLegacyServiceHostObservation({
+      observation: hostObservation,
+      source: sourceArg,
+      label: 'runtime.hostObservation',
+    }));
+    if (hostObservation.mode.kind === 'replicated'
+      && runtimeArg.requiredReplicaCount !== hostObservation.mode.desiredReplicas) {
+      errors.push('runtime.requiredReplicaCount must be the observed desired replicas');
+    }
+    const recordedTasks = readDataElements(runtimeArg.tasks, maximumReplicaCount) ?? [];
+    if (recordedTasks.length !== hostObservation.replicas.length
+      || hostObservation.replicas.some((replicaArg, indexArg) => {
+        const task = recordedTasks[indexArg];
+        return !isPlainRecord(task)
+          || task.deploymentId !== replicaArg.swarmTaskId
+          || task.nodeName !== replicaArg.nodeHostname;
+      })) {
+      errors.push('runtime.tasks must be the observed replicas: each Swarm task on its node');
+    }
+  }
   if (!isPositiveSafeInteger(runtimeArg.requiredReplicaCount, maximumReplicaCount)) {
     errors.push('runtime.requiredReplicaCount must be a positive bounded replica count');
   }
@@ -289,7 +692,7 @@ const validateRuntime = (runtimeArg: unknown, rootDigestArg: unknown): string[]
   }
   if (!isCanonicalDigest(runtimeArg.runtimeDigest)) {
     errors.push('runtime.runtimeDigest must be a canonical sha256 digest');
-  } else if (runtimeArg.runtimeDigest !== rootDigestArg) {
+  } else if (runtimeArg.runtimeDigest !== rootDigest) {
     errors.push('runtime.runtimeDigest must be the attested source root digest');
   }
   if (!Array.isArray(runtimeArg.tasks) || runtimeArg.tasks.length !== runtimeArg.requiredReplicaCount) {
@@ -363,9 +766,6 @@ export const validateLegacyServiceRuntimeAttestation = (attestationArg: unknown)
     errors.push('capturedAt must be a positive timestamp');
   }
   errors.push(...validateImageSource(data.source));
-  errors.push(...validateRuntime(
-    data.runtime,
-    isPlainRecord(data.source) ? data.source.rootDigest : undefined,
-  ));
+  errors.push(...validateRuntime(data.runtime, data.source));
   return errors;
 };

package/ts/data/index.ts

@@ -72,6 +72,7 @@ export * from './baremetal.js';
 export * from './baseos.js';
 export * from './backup.js';
 export * from './clusternode.js';
+export * from './clusternodehostname.js';
 export * from './settings.js';
 export * from './sparklegacyretirement.js';
 export * from './sparknodereport.js';

package/ts/data/sparknodereport.ts

@@ -1,7 +1,8 @@
 import { isReleaseVersion } from './releaseversion.js';
-import { readExactDataRecord } from '../private/dataproperties.js';
+import { readDataProperties, readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';
+import { isClusterNodeHostname } from './clusternodehostname.js';
 
 /** Host observations only. Container and workload readiness belong to Pallet. */
 export interface ISparkNodeReport {
@@ -22,8 +23,32 @@ export interface ISparkNodeReport {
     localRuntimeReady: true;
     workloadReadiness: 'unverified';
   };
+  /**
+   * The outcome of Spark's last attempt to apply a desired hostname (`sparkNodeHostContract`), when
+   * it made one since it started. Whether the node carries the hostname is `runtime.hostname`.
+   */
+  hostApply?: ISparkNodeHostApply;
 }
 
+/** Whether Spark applied a desired hostname: `applied` once the host carries it. */
+export type TSparkNodeHostApplyOutcome = 'applied' | 'failed';
+
+/** One attempt to apply the desired hostname of one generation. */
+export interface ISparkNodeHostApply {
+  /** The `ISparkNodeDesiredHost.generation` the attempt applied. */
+  generation: number;
+  /** The hostname it applied. */
+  hostname: string;
+  outcome: TSparkNodeHostApplyOutcome;
+  /** `failed` only, and required there: why, as operator text. */
+  reason?: string;
+}
+
+/** Bounds of `ISparkNodeHostApply.reason`. */
+export const sparkNodeHostApplyContract = Object.freeze({
+  maximumReasonLength: 512,
+} as const);
+
 /** HTTPS POST body. Never log, persist, or return nodeToken. */
 export interface ISparkNodeHeartbeatRequest {
   nodeId: string;
@@ -101,9 +126,28 @@ const integer = (valueArg: unknown, minimumArg: number): number => {
   return value;
 };
 
+/** One `hostApply`: exactly its keys, a reason exactly when it failed. */
+const snapshotSparkNodeHostApply = (valueArg: unknown): ISparkNodeHostApply => {
+  const keys = ['generation', 'hostname', 'outcome'];
+  const value = readExactDataRecord(valueArg, keys) ?? record(valueArg, [...keys, 'reason']);
+  requireValue(isClusterNodeHostname(value.hostname));
+  const generation = integer(value.generation, 1);
+  if (value.outcome === 'applied') {
+    requireValue(value.reason === undefined);
+    return Object.freeze({ generation, hostname: value.hostname, outcome: 'applied' });
+  }
+  requireValue(value.outcome === 'failed');
+  return Object.freeze({ generation, hostname: value.hostname, outcome: 'failed',
+    reason: text(value.reason, /^[\x20-\x7e]+$/, sparkNodeHostApplyContract.maximumReasonLength) });
+};
+
 /** Exact inert JSON records; detaches and freezes before any consumer awaits. */
 export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport => {
-  const value = record(valueArg, ['observedAt', 'metrics', 'runtime']);
+  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);
   const metrics = record(value.metrics, ['cpuUsagePercent', 'memoryUsedMB', 'memoryAvailableMB',
     'diskUsedGB', 'diskAvailableGB']);
   const runtime = record(value.runtime, ['hostname', 'platform', 'arch', 'osRelease', 'bundle',
@@ -130,6 +174,7 @@ export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport =>
       }),
       localRuntimeReady: true, workloadReadiness: 'unverified',
     }),
+    ...(hasHostApply ? { hostApply: snapshotSparkNodeHostApply(value.hostApply) } : {}),
   });
 };
 
@@ -155,3 +200,68 @@ export const snapshotSparkNodeHeartbeatReceipt = (valueArg: unknown): ISparkNode
     protocol: readProtocolOffer(value),
   });
 };
+
+/** HTTPS POST body asking for the hostname Cloudly wants the node to carry. Never log, persist, or return nodeToken. */
+export interface ISparkNodeHostRequest {
+  nodeId: string;
+  nodeToken: string;
+  /** Read and negotiated before the node is authenticated; see `sparkNodeHostContract`. */
+  protocol: IProtocolOffer;
+}
+
+/**
+ * The hostname Cloudly wants the node to carry: `IClusterNode.data.hostnameIntent`, as the node
+ * applies it.
+ *
+ * `hostname: null` with `generation: 0` states that Cloudly holds no intent for the node, and Spark
+ * leaves the host's hostname as it is. Applying is idempotent: a host that already carries the
+ * hostname is left alone, and every answer states the whole desired value rather than a change.
+ */
+export interface ISparkNodeDesiredHost {
+  nodeId: string;
+  hostname: string | null;
+  generation: number;
+  /** The controller's offer, so the node judges the answer it acts on. */
+  protocol: IProtocolOffer;
+}
+
+/**
+ * The node runtime's desired-host route.
+ *
+ * Authenticated with the node's Spark credential exactly like `sparkNodeHeartbeatContract`, and
+ * judged in the same server order: protocol offer first, against this server's `sparkNode` offer
+ * and within `maxRequestBytes`, answered with `protocolRefusalStatus` and an `IProtocolRefusal` body
+ * on refusal, before the node is authenticated. Spark reports the outcome of applying the answer as
+ * `ISparkNodeReport.hostApply` on its next heartbeat.
+ */
+export const sparkNodeHostContract = Object.freeze({
+  endpoint: '/spark/nodes/host',
+  maxRequestBytes: 1024,
+  maxResponseBytes: 1024,
+  protocolRefusalStatus: protocolRefusalHttpStatus,
+} as const);
+
+export const snapshotSparkNodeHostRequest = (valueArg: unknown): ISparkNodeHostRequest => {
+  const value = record(valueArg, ['nodeId', 'nodeToken', 'protocol']);
+  return Object.freeze({
+    nodeId: nodeId(value.nodeId),
+    nodeToken: text(value.nodeToken, /^secureToken[a-f0-9]{64}$/, 75),
+    protocol: readProtocolOffer(value),
+  });
+};
+
+export const snapshotSparkNodeDesiredHost = (valueArg: unknown): ISparkNodeDesiredHost => {
+  const value = record(valueArg, ['nodeId', 'hostname', 'generation', 'protocol']);
+  const hostname = value.hostname;
+  if (hostname === null) {
+    requireValue(value.generation === 0);
+  } else {
+    requireValue(isClusterNodeHostname(hostname));
+  }
+  return Object.freeze({
+    nodeId: nodeId(value.nodeId),
+    hostname,
+    generation: hostname === null ? 0 : integer(value.generation, 1),
+    protocol: readProtocolOffer(value),
+  });
+};