@serve.zone/interfaces 32.51.0 → 32.52.0

package/dist_ts/data/sparknodereport.js

@@ -1,7 +1,12 @@
 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 } from '../protocol.js';
+import { isClusterNodeHostname } from './clusternodehostname.js';
+/** Bounds of `ISparkNodeHostApply.reason`. */
+export const sparkNodeHostApplyContract = Object.freeze({
+    maximumReasonLength: 512,
+});
 /**
  * The node runtime's own heartbeat route.
  *
@@ -48,9 +53,27 @@ const integer = (valueArg, minimumArg) => {
     requireValue(Number.isSafeInteger(value) && value >= minimumArg);
     return value;
 };
+/** One `hostApply`: exactly its keys, a reason exactly when it failed. */
+const snapshotSparkNodeHostApply = (valueArg) => {
+    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) => {
-    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',
@@ -77,6 +100,7 @@ export const snapshotSparkNodeReport = (valueArg) => {
             }),
             localRuntimeReady: true, workloadReadiness: 'unverified',
         }),
+        ...(hasHostApply ? { hostApply: snapshotSparkNodeHostApply(value.hostApply) } : {}),
     });
 };
 export const snapshotSparkNodeHeartbeatRequest = (valueArg) => {
@@ -100,4 +124,43 @@ export const snapshotSparkNodeHeartbeatReceipt = (valueArg) => {
         protocol: readProtocolOffer(value),
     });
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3Bhcmtub2RlcmVwb3J0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9zcGFya25vZGVyZXBvcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDdkQsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDbkUsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBQy9ELE9BQU8sRUFBRSx5QkFBeUIsRUFBRSxpQkFBaUIsRUFBdUIsTUFBTSxnQkFBZ0IsQ0FBQztBQWlEbkc7Ozs7Ozs7O0dBUUc7QUFDSCxNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ3RELFFBQVEsRUFBRSx3QkFBd0I7SUFDbEMsZUFBZSxFQUFFLElBQUk7SUFDckIsZ0JBQWdCLEVBQUUsSUFBSTtJQUN0QixxQkFBcUIsRUFBRSx5QkFBeUI7Q0FDeEMsQ0FBQyxDQUFDO0FBRVosTUFBTSxJQUFJLEdBQUcsR0FBVSxFQUFFLEdBQUcsTUFBTSxJQUFJLEtBQUssQ0FBQyx5Q0FBeUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQzFGLFNBQVMsWUFBWSxDQUFDLFFBQWlCO0lBQ3JDLElBQUksQ0FBQyxRQUFRO1FBQUUsSUFBSSxFQUFFLENBQUM7QUFDeEIsQ0FBQztBQUNELHNHQUFzRztBQUN0RyxNQUFNLE1BQU0sR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBMEIsRUFBMkIsRUFBRTtJQUN4RixNQUFNLE1BQU0sR0FBRyxtQkFBbUIsQ0FBQyxRQUFRLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDdEQsWUFBWSxDQUFDLE1BQU0sS0FBSyxJQUFJLENBQUMsQ0FBQztJQUM5QixPQUFPLE1BQU0sQ0FBQztBQUNoQixDQUFDLENBQUM7QUFDRixNQUFNLElBQUksR0FBRyxDQUFDLFFBQWlCLEVBQUUs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
+/**
+ * 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,
+});
+export const snapshotSparkNodeHostRequest = (valueArg) => {
+    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) => {
+    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),
+    });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3Bhcmtub2RlcmVwb3J0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9zcGFya25vZGVyZXBvcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDdkQsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDdkYsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBQy9ELE9BQU8sRUFBRSx5QkFBeUIsRUFBRSxpQkFBaUIsRUFBdUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNuRyxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQTBDakUsOENBQThDO0FBQzlDLE1BQU0sQ0FBQyxNQUFNLDBCQUEwQixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDdEQsbUJBQW1CLEVBQUUsR0FBRztDQUNoQixDQUFDLENBQUM7QUE0Qlo7Ozs7Ozs7O0dBUUc7QUFDSCxNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ3RELFFBQVEsRUFBRSx3QkFBd0I7SUFDbEMsZUFBZSxFQUFFLElBQUk7SUFDckIsZ0JBQWdCLEVBQUUsSUFBSTtJQUN0QixxQkFBcUIsRUFBRSx5QkFBeUI7Q0FDeEMsQ0FBQyxDQUFDO0FBRVosTUFBTSxJQUFJLEdBQUcsR0FBVSxFQUFFLEdBQUcsTUFBTSxJQUFJLEtBQUssQ0FBQyx5Q0FBeUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQzFGLFNBQVMsWUFBWSxDQUFDLFFBQWlCO0lBQ3JDLElBQUksQ0FBQyxRQUFRO1FBQUUsSUFBSSxFQUFFLENBQUM7QUFDeEIsQ0FBQztBQUNELHNHQUFzRztBQUN0RyxNQUFNLE1BQU0sR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBMEIsRUFBMkIsRUFBRTtJQUN4RixNQUFN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

package/dist_ts/requests/node.d.ts

@@ -110,6 +110,13 @@ export interface IReq_Any_Cloudly_CreateNodeJumpCommand extends plugins.typedreq
         role?: IClusterNode['data']['role'];
         nodeType?: IClusterNode['data']['nodeType'];
         ttlMs?: number;
+        /**
+         * The new node's name (`data.isClusterNodeName`). The setup command names the host
+         * `cloudly-worker-<nodeName>` (`data.deriveDefaultClusterNodeHostname`) before it enrolls, so
+         * the node enrolls under its default hostname. Absent, the node keeps the hostname it has and
+         * its name is proposed from that (`data.proposeClusterNodeName`).
+         */
+        nodeName?: string;
     };
     response: {
         jumpCode: string;
@@ -283,6 +290,58 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint extend
         node: IClusterNode;
     };
 }
+/**
+ * An administrator renames a node: the static hostname Cloudly wants it to carry
+ * (`IClusterNode.data.hostnameIntent.hostname`).
+ *
+ * The node's name stays as it is: the new intent keeps the name of the node's current intent. A
+ * node without an intent takes the name `data.proposeClusterNodeName(hostname)` (`foo` names the
+ * node `foo`, `cloudly-worker-grasberg` names it `grasberg`), and is refused `name-invalid` when
+ * that is `null`.
+ *
+ * Cloudly records the intent and answers at once; Spark applies the intent of the latest
+ * generation on the host and the node has converged when its report states the new hostname. A new
+ * intent may replace one the node has not converged to, whether it is still applying, failed or
+ * never reached the node. `expectedGeneration` is the generation of the node's current intent, `0`
+ * when it has none, and serializes concurrent changes. Every refusal is one of
+ * `data.clusterNodeHostnameRefusals` and changes nothing.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeHostname extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetClusterNodeHostname> {
+    method: 'setClusterNodeHostname';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        expectedGeneration: number;
+        /** One lowercase RFC 1123 label (`data.isClusterNodeHostname`). */
+        hostname: string;
+    };
+    response: {
+        /** The node as it now stands, carrying the new intent. */
+        node: IClusterNode;
+    };
+}
+/**
+ * An administrator resets a node to the default scheme: hostname `cloudly-worker-<name>`
+ * (`data.deriveDefaultClusterNodeHostname`).
+ *
+ * `name` replaces the node's name when stated; absent, the name of the node's current intent is
+ * used, and a node without an intent is refused `name-invalid`. Recorded, applied and replaceable
+ * exactly like `setClusterNodeHostname`, with the same refusals.
+ */
+export interface IReq_Any_Cloudly_ResetClusterNodeHostname extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_ResetClusterNodeHostname> {
+    method: 'resetClusterNodeHostname';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        expectedGeneration: number;
+        /** The node's name (`data.isClusterNodeName`). */
+        name?: string;
+    };
+    response: {
+        /** The node as it now stands, carrying the new intent. */
+        node: IClusterNode;
+    };
+}
 export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateNodeAction> {
     method: 'createNodeAction';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.51.0",
+  "version": "32.52.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -203,6 +203,19 @@ current authority or workload readiness. Persist only the report and receipt in
 `IClusterNode.data.sparkNodeReport`, never the bearer. Keep legacy reporting
 separate. This endpoint does not deliver or acknowledge operator actions.
 
+`data.sparkNodeHostContract` defines the node's desired-host route,
+`/spark/nodes/host`, with 1024-byte request and response bounds, authenticated and
+judged in the same order as the heartbeat. `ISparkNodeHostRequest` carries the
+Spark bearer and the sender's offer; `ISparkNodeDesiredHost` answers with the whole
+desired value of `IClusterNode.data.hostnameIntent` — the hostname and its
+generation — never a change, and `hostname: null` with generation `0` states that
+Cloudly holds no intent, so Spark leaves the host's hostname as it is. Spark applies
+the latest generation and states the outcome of its last attempt as the optional
+`ISparkNodeReport.hostApply` (`applied`, or `failed` with a bounded reason) on its
+next heartbeat; the node has converged when `runtime.hostname` states the intent's
+hostname. A Spark that sends `hostApply` raises its `minimumPeerVersion` so it
+reaches only a Cloudly that reads it.
+
 The snapshot functions reject unknown keys, accessors, malformed identities and
 nonfinite/out-of-range numbers, then return detached frozen records. Transports
 own byte limits, timeouts and cancellation. These contracts do not implement a
@@ -2921,6 +2934,11 @@ Common data contracts include:
 
 - `ICluster` and `IClusterNode` for cluster membership and provisioning state, including the
   optional `ICluster.data.relay` block described below.
+- `clusternodehostname` for the static hostname Cloudly wants a node to carry:
+  `IClusterNodeHostnameIntent` on `IClusterNode.data.hostnameIntent`, the default scheme
+  `cloudly-worker-<name>` (`clusterNodeHostnameContract`, `deriveDefaultClusterNodeHostname`,
+  `proposeClusterNodeName`) and the named `clusterNodeHostnameRefusals` of
+  `setClusterNodeHostname` and `resetClusterNodeHostname`.
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
 - Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.51.0',
+  version: '32.52.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/clusternode.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
 import { isSha256Digest, type TSha256Digest, type TImmutableContainerPlatform } from './immutableimage.js';
 import type { ISparkNodeReportRecord } from './sparknodereport.js';
+import type { IClusterNodeHostnameIntent } from './clusternodehostname.js';
 import type { IPlatformObjectStorageEndpoint } from '../platform/objectstorage.js';
 import type { IPlatformDatabaseEndpoint } from '../platform/database.js';
 import {
@@ -1765,6 +1766,13 @@ export interface IClusterNode {
 
     /** Separately accepted Pallet-era host report; never grants workload readiness. */
     sparkNodeReport?: ISparkNodeReportRecord;
+
+    /**
+     * The static hostname Cloudly wants this node to carry, which Spark applies on the host. The
+     * node has converged when `sparkNodeReport` states the same hostname. Absent until enrollment
+     * or a migration records one; Spark then leaves the host's hostname as it is.
+     */
+    hostnameIntent?: IClusterNodeHostnameIntent;
     
     /**
      * Docker swarm node ID if part of swarm

package/ts/data/clusternodehostname.ts

@@ -0,0 +1,153 @@
+import { readExactDataRecord } from '../private/dataproperties.js';
+
+/**
+ * The static hostname a cluster node runs under, and the scheme Cloudly names a node by default.
+ *
+ * Cloudly owns the hostname a node should carry (`IClusterNode.data.hostnameIntent`); Spark applies
+ * it on the host and reports the hostname it observes, so a node has converged when its report
+ * states the intent's hostname. The default scheme is `cloudly-worker-<name>`: `name` is the
+ * operator's short name for the node (`ottilie`, `grasberg`), kept beside the hostname so the node
+ * can always be reset to the default however it was renamed.
+ *
+ * A hostname here is one RFC 1123 label, lowercase: the node's short static hostname, which is
+ * what enrollment already requires of a host. A fully qualified name is DNS, not the host's name.
+ */
+export const clusterNodeHostnameContract = Object.freeze({
+  /** The default hostname is this prefix followed by the node's name. */
+  defaultPrefix: 'cloudly-worker-',
+  /** One DNS label. */
+  maximumHostnameLength: 63,
+  /** What is left of one label after `defaultPrefix`. */
+  maximumNameLength: 48,
+  /** `requestedBy` is an identity's user id. */
+  maximumRequestedByLength: 256,
+  error: 'Cluster node hostname contract rejected.',
+} as const);
+
+const hostnameLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** True for one lowercase RFC 1123 label of 1 to 63 characters: a node's static hostname. */
+export const isClusterNodeHostname = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= clusterNodeHostnameContract.maximumHostnameLength
+  && hostnameLabel.test(valueArg)
+);
+
+/** True for a node name the default scheme can carry: a label of at most 48 characters. */
+export const isClusterNodeName = (valueArg: unknown): valueArg is string => (
+  isClusterNodeHostname(valueArg) && valueArg.length <= clusterNodeHostnameContract.maximumNameLength
+);
+
+/** `cloudly-worker-<name>`; throws for a name the scheme cannot carry. */
+export const deriveDefaultClusterNodeHostname = (nameArg: string): string => {
+  if (!isClusterNodeName(nameArg)) {
+    throw new Error(clusterNodeHostnameContract.error);
+  }
+  return `${clusterNodeHostnameContract.defaultPrefix}${nameArg}`;
+};
+
+/**
+ * The node name an observed hostname suggests, or `null` when it suggests none.
+ *
+ * It reads the first label of the hostname, so a report that states a dotted name proposes its
+ * short name. A label already in the default scheme proposes what follows the prefix
+ * (`cloudly-worker-ottilie` → `ottilie`); any other valid label proposes itself unchanged
+ * (`cloudlyworkergrasberg` stays `cloudlyworkergrasberg`). It never guesses a name out of a
+ * label in another scheme: an operator states that name when resetting the node to the default.
+ */
+export const proposeClusterNodeName = (hostnameArg: string): string | null => {
+  const label = hostnameArg.split('.')[0];
+  if (!isClusterNodeHostname(label)) {
+    return null;
+  }
+  const prefix = clusterNodeHostnameContract.defaultPrefix;
+  if (label.startsWith(prefix) && isClusterNodeName(label.slice(prefix.length))) {
+    return label.slice(prefix.length);
+  }
+  return isClusterNodeName(label) ? label : null;
+};
+
+/** The hostname Cloudly wants a node to carry; `IClusterNode.data.hostnameIntent`. */
+export interface IClusterNodeHostnameIntent {
+  /** The node's name: the input of the default scheme, and what a reset to the default uses. */
+  name: string;
+  /** The static hostname the node should carry; the default derived from `name` or any other label. */
+  hostname: string;
+  /** Counts accepted intents from 1; a change names the generation it replaces. */
+  generation: number;
+  /** Unix milliseconds on Cloudly's clock when this intent was accepted. */
+  requestedAt: number;
+  /** The administrator who asked for it; absent for the intent enrollment or a migration recorded. */
+  requestedBy?: string;
+}
+
+/** True when the intent's hostname is the default its name derives. */
+export const isDefaultClusterNodeHostname = (intentArg: IClusterNodeHostnameIntent): boolean => (
+  isClusterNodeName(intentArg.name) && intentArg.hostname === deriveDefaultClusterNodeHostname(intentArg.name)
+);
+
+const fail = (): never => { throw new Error(clusterNodeHostnameContract.error); };
+function requireValue(valueArg: unknown): asserts valueArg {
+  if (!valueArg) fail();
+}
+const counter = (valueArg: unknown, minimumArg: number): number => {
+  requireValue(typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= minimumArg);
+  return valueArg;
+};
+
+/** Exact, detached and frozen; refuses every key and value this contract does not state. */
+export const snapshotClusterNodeHostnameIntent = (valueArg: unknown): IClusterNodeHostnameIntent => {
+  const keys = ['name', 'hostname', 'generation', 'requestedAt'];
+  const value = readExactDataRecord(valueArg, keys) ?? readExactDataRecord(valueArg, [...keys, 'requestedBy']);
+  requireValue(value !== null);
+  requireValue(isClusterNodeName(value.name) && isClusterNodeHostname(value.hostname));
+  const intent: IClusterNodeHostnameIntent = {
+    name: value.name, hostname: value.hostname,
+    generation: counter(value.generation, 1), requestedAt: counter(value.requestedAt, 1),
+  };
+  if (Object.hasOwn(value, 'requestedBy')) {
+    const requestedBy = value.requestedBy;
+    requireValue(typeof requestedBy === 'string' && requestedBy.length > 0
+      && requestedBy.length <= clusterNodeHostnameContract.maximumRequestedByLength
+      && /^[\x21-\x7e]+$/.test(requestedBy));
+    intent.requestedBy = requestedBy;
+  }
+  return Object.freeze(intent);
+};
+
+/**
+ * Every reason Cloudly answers instead of renaming a node or resetting it to the default. Each
+ * travels by name as a `TypedResponseError`, and a refused request changes nothing.
+ */
+export const clusterNodeHostnameRefusals = Object.freeze([
+  /** No node of that id exists. */
+  'node-missing',
+  /** The requested hostname is not one lowercase RFC 1123 label (`isClusterNodeHostname`). */
+  'hostname-invalid',
+  /**
+   * The node would carry no name the default scheme can carry (`isClusterNodeName`). A rename keeps
+   * the name of the node's intent; a node without an intent takes
+   * `proposeClusterNodeName(<requested hostname>)`, and is refused when that is `null`. A reset
+   * names no valid name, or names none while the node has no intent whose name it could reuse.
+   */
+  'name-invalid',
+  /** Another node of the cluster carries that hostname, as reported or as its intent. */
+  'hostname-in-use',
+  /** The node's intent already is that hostname under that name. */
+  'hostname-unchanged',
+  /**
+   * Cloudly holds state naming the node by its current hostname that it cannot move to the new
+   * hostname with the change, such as a rollout in flight that targets the node.
+   */
+  'node-hostname-referenced',
+  /** The node does not run the Pallet-era node runtime, the only one that applies a hostname. */
+  'node-runtime-unsupported',
+  /**
+   * `expectedGeneration` is not the node's current intent generation: read the node again. This
+   * fence alone serializes changes; an intent the node has not converged to may always be replaced.
+   */
+  'conflict',
+] as const);
+
+/** One of the reasons Cloudly answers instead of a hostname change. */
+export type TClusterNodeHostnameRefusalCode = typeof clusterNodeHostnameRefusals[number];

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),
+  });
+};