@serve.zone/interfaces 32.16.0 → 32.18.0

package/ts/data/sparklegacyretirement.ts

@@ -0,0 +1,436 @@
+import type { IFleetCutoverAcceptedEvidenceReference } from './fleetcutover.js';
+import type { TSha256Digest } from './immutableimage.js';
+import { isReleaseVersion } from './releaseversion.js';
+import {
+  captureNetwork,
+  networkCounter,
+  networkDigest,
+  networkEqual,
+  networkHash,
+  networkId,
+  networkNodeId,
+  networkRecord,
+  networkReference,
+  networkRevision,
+  requireNetwork,
+} from '../private/networkcontract.js';
+
+/** The two runtimes a released Spark could be put into by its `mode` configuration key. */
+export const sparkLegacyRuntimeModes = ['cloudly', 'coreflow-node'] as const;
+
+export type TSparkLegacyRuntimeMode = typeof sparkLegacyRuntimeModes[number];
+
+/**
+ * Which Docker services a released mode owns, sorted, so a refusal names a mode instead of
+ * restating a set. A record over the mode union: a mode cannot be added without naming its
+ * services, and a reader can never meet a mode whose services it does not know.
+ */
+export const sparkLegacyRuntimeModeServices = Object.freeze({
+  'cloudly': Object.freeze(['cloudly']),
+  'coreflow-node': Object.freeze(['coreflow', 'corestore', 'coretraffic']),
+} satisfies Record<TSparkLegacyRuntimeMode, readonly string[]>);
+
+/**
+ * Which verified Spark code is installed on one host and which systemd unit will boot it.
+ *
+ * Every member is read back from the installed tree and the installed unit file, never from the
+ * running process's own build constants: a build can state its own version, it cannot state that
+ * the host will start that same code again.
+ */
+export interface ISparkNodeBundleIdentity {
+  /** The installed bundle's release, exactly as its verified manifest names it. */
+  version: string;
+  /** The commit that manifest was built from, in the 40-hex form the manifest carries. */
+  sourceCommit: string;
+  /** The manifest digest the installed tree was verified against, in its bare 64-hex form. */
+  manifestSha256: string;
+  /** The systemd unit that starts this bundle at boot. */
+  unitName: string;
+  /** SHA-256 of the exact installed unit-file bytes. */
+  unitDigest: TSha256Digest;
+}
+
+/**
+ * What became of the released configuration source once this node stopped reading it.
+ *
+ * A tuple beside the union, exactly like `sparkLegacyRuntimeModes`: a reader that has to name the
+ * two states — a form, a migration, a refusal message — reads them from the contract instead of
+ * restating two string literals the contract could later disagree with.
+ */
+export const sparkLegacyConfigurationDispositions = ['retained-inert', 'removed'] as const;
+
+export type TSparkLegacyConfigurationDisposition =
+  typeof sparkLegacyConfigurationDispositions[number];
+
+/**
+ * The released key-value configuration source, by digest and disposition only.
+ *
+ * Never its bytes and never a decoded member: that file carries this node's released bearer and
+ * its jump code. `sourceSha256` covers the whole file, whose smallest unguessable part is a
+ * 256-bit token, so it identifies the file without stating anything that is in it.
+ */
+export interface ISparkLegacyConfigurationState {
+  /** The node's own monotonic counter; one accepted local disposition change advances it by one. */
+  ownerGeneration: number;
+  /** SHA-256 of the exact source bytes this node imported, once, under its fenced read. */
+  sourceSha256: string;
+  /** On disk and read by nothing, or unlinked. Erasure is not a cutover requirement. */
+  disposition: TSparkLegacyConfigurationDisposition;
+}
+
+/**
+ * What one node states about the released Spark runtime it is replacing, on one observation.
+ *
+ * Observed values and one statement the owner makes about its own behaviour. It names no node:
+ * Cloudly binds it to the reporter it already authenticated, so there is nothing to disagree
+ * with. It carries no digest of its own either, because the whole observation is digested by
+ * `computeSparkSwarmObservationDigest`.
+ */
+export interface ISparkLegacyRuntimeRetirement {
+  /** The released mode this process is configured in and no longer serves. */
+  refusedMode: TSparkLegacyRuntimeMode;
+  bundle: ISparkNodeBundleIdentity;
+  configuration: ISparkLegacyConfigurationState;
+}
+
+interface ISparkLegacyRetirementReceiptBase {
+  id: string;
+  generation: number;
+  previous: IFleetCutoverAcceptedEvidenceReference | null;
+  clusterId: string;
+  nodeId: string;
+  /** The accepted observation this was derived from; Cloudly read it, the node never named it. */
+  observation: IFleetCutoverAcceptedEvidenceReference;
+  reporterSessionId: string;
+  observationSequence: number;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/**
+ * Cloudly's accepted record that one node refuses its released owning mode.
+ *
+ * It is revisioned rather than written once: a node restates the refusal on every observation,
+ * and a bundle upgrade changes what the boot path is, which is a new fact about the same node.
+ */
+export interface ISparkLegacyModeRefusal extends ISparkLegacyRetirementReceiptBase {
+  refusedMode: TSparkLegacyRuntimeMode;
+  bundle: ISparkNodeBundleIdentity;
+}
+
+/**
+ * Cloudly's accepted record of one node's released configuration source at an exact generation.
+ *
+ * Two counters, deliberately: `generation` is contiguous because it is this record's own
+ * revision, while `configuration.ownerGeneration` is the node's and may skip — an observation
+ * that never arrived must not look like a skipped revision here.
+ */
+export interface ISparkLegacyConfigurationRetirement extends ISparkLegacyRetirementReceiptBase {
+  configuration: ISparkLegacyConfigurationState;
+}
+
+export const sparkLegacyRetirementContract = Object.freeze({
+  modeRefusalDigestDomain: 'serve.zone/spark-legacy-mode-refusal',
+  configurationRetirementDigestDomain: 'serve.zone/spark-legacy-configuration-retirement',
+} as const);
+
+/** Every reason Cloudly answers instead of advancing a node's legacy retirement state. */
+export const sparkLegacyRetirementRefusals = Object.freeze([
+  /** The observed owner generation is below the accepted one. */
+  'legacy-retirement-generation-stale',
+  /** The observed owner generation equals the accepted one and states something else. */
+  'legacy-retirement-generation-conflict',
+  /** A node imported one source once; another source digest describes another host. */
+  'legacy-retirement-source-changed',
+  /** A removed source cannot become a retained one. */
+  'legacy-retirement-disposition-reversed',
+  /** The stated bundle is below the release whose refusal this server accepts as real. */
+  'legacy-retirement-bundle-below-minimum',
+] as const);
+
+export type TSparkLegacyRetirementRefusal = typeof sparkLegacyRetirementRefusals[number];
+
+/**
+ * What the server did with the statement one observation carried, answered on that observation's
+ * own accepted receipt.
+ *
+ * The statement is judged against records, not against the message: a malformed one is already
+ * refused by `validateSparkLegacyRuntimeRetirement` before any of this, so everything left is a
+ * fact about this node's history. That is why a refusal here does not reject the observation —
+ * the node's liveness and census are true whatever its released runtime states — and why an
+ * accepted observation is the only place this outcome appears.
+ *
+ * `generation` is the revision both node-owned records stand at once the observation is accepted:
+ * `accepted` advanced it, `restated` is the replay that renewed nothing and left it where it was.
+ * A refusal carries no generation, because the counter a refused node has to reconcile with is
+ * its own `ownerGeneration`, which it already holds.
+ */
+export type TSparkLegacyRetirementOutcome =
+  | {
+      state: 'accepted';
+      /** The revision this observation advanced both records to. */
+      generation: number;
+    }
+  | {
+      state: 'restated';
+      /** The revision that stands; this observation added nothing to it. */
+      generation: number;
+    }
+  | {
+      state: 'refused';
+      refusal: TSparkLegacyRetirementRefusal;
+      /**
+       * Always false, and stated anyway.
+       *
+       * Every refusal of this family answers one exact statement, so resending it cannot change
+       * the answer; a server-side race is refused one level up, as the observation's own
+       * `acceptance-race`. It travels on the wire for the reason the rejected receipt carries its
+       * own flag: a node that meets a refusal name a later minor added still learns it must stop.
+       */
+      retryable: false;
+    };
+
+const fail = (): never => { throw new Error('Spark legacy retirement contract rejected.'); };
+const safe = <T>(operationArg: () => T): T => {
+  try { return operationArg(); } catch { return fail(); }
+};
+
+const sha256Hex = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && /^[a-f0-9]{64}$/.test(valueArg));
+  return valueArg;
+};
+
+const sourceCommit = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && /^[a-f0-9]{40}$/.test(valueArg));
+  return valueArg;
+};
+
+const releaseVersion = (valueArg: unknown): string => {
+  requireNetwork(isReleaseVersion(valueArg));
+  return valueArg;
+};
+
+const legacyRuntimeMode = (valueArg: unknown): TSparkLegacyRuntimeMode => {
+  requireNetwork(sparkLegacyRuntimeModes.includes(valueArg as TSparkLegacyRuntimeMode));
+  return valueArg as TSparkLegacyRuntimeMode;
+};
+
+const configurationDisposition = (
+  valueArg: unknown,
+): TSparkLegacyConfigurationDisposition => {
+  requireNetwork(sparkLegacyConfigurationDispositions
+    .includes(valueArg as TSparkLegacyConfigurationDisposition));
+  return valueArg as TSparkLegacyConfigurationDisposition;
+};
+
+const retirementRefusal = (valueArg: unknown): TSparkLegacyRetirementRefusal => {
+  requireNetwork(sparkLegacyRetirementRefusals
+    .includes(valueArg as TSparkLegacyRetirementRefusal));
+  return valueArg as TSparkLegacyRetirementRefusal;
+};
+
+/** Structural copy only; whether the tree it describes is installed is the node's to observe. */
+export const snapshotSparkNodeBundleIdentity = (
+  valueArg: unknown,
+): ISparkNodeBundleIdentity => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'version', 'sourceCommit', 'manifestSha256', 'unitName', 'unitDigest',
+  ]);
+  return {
+    version: releaseVersion(value.version),
+    sourceCommit: sourceCommit(value.sourceCommit),
+    manifestSha256: sha256Hex(value.manifestSha256),
+    unitName: networkId(value.unitName),
+    unitDigest: networkDigest(value.unitDigest),
+  };
+});
+
+export const snapshotSparkLegacyConfigurationState = (
+  valueArg: unknown,
+): ISparkLegacyConfigurationState => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'ownerGeneration', 'sourceSha256', 'disposition',
+  ]);
+  return {
+    ownerGeneration: networkCounter(value.ownerGeneration),
+    sourceSha256: sha256Hex(value.sourceSha256),
+    disposition: configurationDisposition(value.disposition),
+  };
+});
+
+export const snapshotSparkLegacyRuntimeRetirement = (
+  valueArg: unknown,
+): ISparkLegacyRuntimeRetirement => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'refusedMode', 'bundle', 'configuration',
+  ]);
+  return {
+    refusedMode: legacyRuntimeMode(value.refusedMode),
+    bundle: snapshotSparkNodeBundleIdentity(value.bundle),
+    configuration: snapshotSparkLegacyConfigurationState(value.configuration),
+  };
+});
+
+/**
+ * Synchronous because the member carries no digest: the observation that transports it is
+ * digested as a whole, so a second domain here would only be a second thing to keep in step.
+ */
+export const validateSparkLegacyRuntimeRetirement = (valueArg: unknown): string[] => {
+  try {
+    snapshotSparkLegacyRuntimeRetirement(valueArg);
+    return [];
+  } catch { return ['Spark legacy runtime retirement must use its exact canonical schema']; }
+};
+
+/** Exact-key per state, like every other shape here: an outcome states one answer and no other. */
+export const snapshotSparkLegacyRetirementOutcome = (
+  valueArg: unknown,
+): TSparkLegacyRetirementOutcome => safe(() => {
+  const captured = captureNetwork(valueArg);
+  requireNetwork(captured !== null && typeof captured === 'object');
+  const state = (captured as Record<string, unknown>).state;
+  requireNetwork(state === 'accepted' || state === 'restated' || state === 'refused');
+  if (state === 'refused') {
+    const value = networkRecord(captured, ['state', 'refusal', 'retryable']);
+    requireNetwork(value.retryable === false);
+    return { state, refusal: retirementRefusal(value.refusal), retryable: false };
+  }
+  const value = networkRecord(captured, ['state', 'generation']);
+  return { state, generation: networkCounter(value.generation) };
+});
+
+/** Synchronous for the same reason: the receipt that carries it is what a reader binds. */
+export const validateSparkLegacyRetirementOutcome = (valueArg: unknown): string[] => {
+  try {
+    snapshotSparkLegacyRetirementOutcome(valueArg);
+    return [];
+  } catch { return ['Spark legacy retirement outcome must use its exact canonical schema']; }
+};
+
+/** The revision rule every accepted receipt of this contract obeys, read once for both of them. */
+const retirementReceiptBase = (
+  valueArg: unknown,
+  ownKeysArg: string[],
+): { base: ISparkLegacyRetirementReceiptBase; record: Record<string, unknown> } => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'id', 'generation', 'previous', 'clusterId', 'nodeId', 'observation', 'reporterSessionId',
+    'observationSequence', 'acceptedAt', 'digest',
+    ...ownKeysArg,
+  ]);
+  const { id, generation, previous } = networkRevision(value);
+  return {
+    base: {
+      id,
+      generation,
+      previous,
+      clusterId: networkId(value.clusterId),
+      nodeId: networkNodeId(value.nodeId),
+      observation: networkReference(value.observation),
+      reporterSessionId: networkId(value.reporterSessionId),
+      observationSequence: networkCounter(value.observationSequence),
+      acceptedAt: networkCounter(value.acceptedAt),
+      digest: networkDigest(value.digest),
+    },
+    record: value,
+  };
+};
+
+export const snapshotSparkLegacyModeRefusal = (
+  valueArg: unknown,
+): ISparkLegacyModeRefusal => safe(() => {
+  const { base, record } = retirementReceiptBase(valueArg, ['refusedMode', 'bundle']);
+  return {
+    ...base,
+    refusedMode: legacyRuntimeMode(record.refusedMode),
+    bundle: snapshotSparkNodeBundleIdentity(record.bundle),
+  };
+});
+
+export const computeSparkLegacyModeRefusalDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => networkHash(
+  sparkLegacyRetirementContract.modeRefusalDigestDomain,
+  snapshotSparkLegacyModeRefusal(valueArg),
+);
+
+export const validateSparkLegacyModeRefusal = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const value = snapshotSparkLegacyModeRefusal(valueArg);
+    return value.digest === await computeSparkLegacyModeRefusalDigest(value)
+      ? [] : ['Spark legacy mode refusal digest does not match'];
+  } catch { return ['Spark legacy mode refusal must use its exact canonical schema']; }
+};
+
+export const snapshotSparkLegacyConfigurationRetirement = (
+  valueArg: unknown,
+): ISparkLegacyConfigurationRetirement => safe(() => {
+  const { base, record } = retirementReceiptBase(valueArg, ['configuration']);
+  return { ...base, configuration: snapshotSparkLegacyConfigurationState(record.configuration) };
+});
+
+export const computeSparkLegacyConfigurationRetirementDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => networkHash(
+  sparkLegacyRetirementContract.configurationRetirementDigestDomain,
+  snapshotSparkLegacyConfigurationRetirement(valueArg),
+);
+
+export const validateSparkLegacyConfigurationRetirement = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotSparkLegacyConfigurationRetirement(valueArg);
+    return value.digest === await computeSparkLegacyConfigurationRetirementDigest(value)
+      ? [] : ['Spark legacy configuration retirement digest does not match'];
+  } catch {
+    return ['Spark legacy configuration retirement must use its exact canonical schema'];
+  }
+};
+
+/**
+ * Whether one observed configuration state is a legal successor of the accepted one.
+ *
+ * `null` is a node's first accepted state. A replay states the accepted generation again and is
+ * therefore not an advance: it renews nothing, which is what keeps `acceptedAt` and the named
+ * observation from aging forward on a node that has stopped changing.
+ */
+export const advancesSparkLegacyConfigurationState = (
+  currentArg: ISparkLegacyConfigurationState | null,
+  nextArg: ISparkLegacyConfigurationState,
+): boolean => {
+  const next = snapshotSparkLegacyConfigurationState(nextArg);
+  if (currentArg === null) return true;
+  if (next.sourceSha256 !== currentArg.sourceSha256) return false;
+  if (next.ownerGeneration <= currentArg.ownerGeneration) return false;
+  return !(currentArg.disposition === 'removed' && next.disposition !== 'removed');
+};
+
+/**
+ * Joins the two accepted receipts a Coreflow retirement cites to the one observation they were
+ * derived from.
+ *
+ * Content join only. Whether each receipt is its node's current revision, and whether the
+ * observation it names is still fresh, remain Cloudly's to decide against its own records.
+ */
+export const bindSparkLegacyRetirement = async (
+  modeRefusalArg: unknown,
+  configurationRetirementArg: unknown,
+): Promise<{
+  modeRefusal: ISparkLegacyModeRefusal;
+  configurationRetirement: ISparkLegacyConfigurationRetirement;
+}> => {
+  try {
+    const modeRefusal = snapshotSparkLegacyModeRefusal(modeRefusalArg);
+    const configurationRetirement = snapshotSparkLegacyConfigurationRetirement(
+      configurationRetirementArg,
+    );
+    if ((await validateSparkLegacyModeRefusal(modeRefusal)).length
+      || (await validateSparkLegacyConfigurationRetirement(configurationRetirement)).length) fail();
+    requireNetwork(modeRefusal.clusterId === configurationRetirement.clusterId
+      && modeRefusal.nodeId === configurationRetirement.nodeId
+      && modeRefusal.reporterSessionId === configurationRetirement.reporterSessionId
+      && modeRefusal.observationSequence === configurationRetirement.observationSequence
+      && networkEqual(modeRefusal.observation, configurationRetirement.observation));
+    return { modeRefusal, configurationRetirement };
+  } catch { return fail(); }
+};

package/ts/data/sparknodereport.ts

@@ -1,4 +1,4 @@
-import { isReleaseVersion } from '../private/releaseversion.js';
+import { isReleaseVersion } from './releaseversion.js';
 import { readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';

package/ts/protocol.ts

@@ -8,7 +8,7 @@ import {
   maximumReleaseVersionLength,
   parseReleaseVersion,
   type IReleaseVersion,
-} from './private/releaseversion.js';
+} from './data/releaseversion.js';
 
 /**
  * The contract this build speaks: the installed `@serve.zone/interfaces` release.

package/ts/requests/cluster.ts

@@ -1,5 +1,6 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
+import type * as relayCredentialInterfaces from '../data/clusterrelaycredential.js';
 import type * as clusterVpnInterfaces from '../data/clustervpn.js';
 import type { IClusterRuntime, TClusterRuntimeBlocker } from '../data/clusterruntime.js';
 import type { IServiceRuntimeAssignmentView } from '../data/serviceruntime.js';
@@ -150,6 +151,74 @@ export interface IReq_Relay_Cloudly_RegisterClusterRelay extends plugins.typedre
   response: clusterInterfaces.IRegisterClusterRelayResponse;
 }
 
+/**
+ * Mints a cluster's relay credential, or rotates it at its exact current generation.
+ *
+ * Only the verified credential is read from the caller: a credential mutation trusts no identity
+ * member a caller states about itself. The bearer is never in the answer; it is delivered as the
+ * encrypted secret version `credential.delivery` names. The first mint also records the shared
+ * authority the cluster still carries, so a replacement never exists without a named predecessor.
+ * Cloudly refuses with one of `data.clusterRelayCredentialRefusals`.
+ */
+export interface IReq_Admin_Cloudly_MutateClusterRelayCredential
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_MutateClusterRelayCredential
+> {
+  method: 'mutateClusterRelayCredential';
+  request: {
+    identity: userInterfaces.IIdentityCredential;
+    mutation: relayCredentialInterfaces.TClusterRelayCredentialMutation;
+  };
+  response: relayCredentialInterfaces.IClusterRelayCredentialMutationResult;
+}
+
+/**
+ * One cluster's relay authority chain as Cloudly records it: the relay credential, the shared
+ * authority it replaces and the current accepted registration, each `null` while no record exists.
+ *
+ * Liveness is not here. It is a fact of a socket, which `getClusterRelayRegistrations` answers and
+ * which Cloudly checks for itself before it accepts a retirement.
+ */
+export interface IReq_Any_Cloudly_GetClusterRelayCredential
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetClusterRelayCredential
+> {
+  method: 'getClusterRelayCredential';
+  request: {
+    identity: userInterfaces.IIdentityCredential;
+    clusterId: string;
+  };
+  response: {
+    credential: relayCredentialInterfaces.IClusterRelayCredential | null;
+    legacy: relayCredentialInterfaces.IClusterLegacyRelayCredential | null;
+    registration: clusterInterfaces.IClusterRelayAcceptedRegistration | null;
+  };
+}
+
+/**
+ * Revokes a cluster's shared pre-relay authority, which is the last step of replacing it.
+ *
+ * Its own request rather than a mutation of the relay credential, because it is the one step that
+ * removes authority: Cloudly accepts it only while the named replacement is the current relay
+ * credential, the named registration is current and was made under that replacement, and a
+ * verified socket carries that registration. Every other answer is one of
+ * `data.clusterRelayCredentialRefusals`.
+ */
+export interface IReq_Admin_Cloudly_RetireLegacyClusterRelayCredential
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_RetireLegacyClusterRelayCredential
+> {
+  method: 'retireLegacyClusterRelayCredential';
+  request: {
+    identity: userInterfaces.IIdentityCredential;
+    retirement: relayCredentialInterfaces.IClusterLegacyRelayCredentialRetirementRequest;
+  };
+  response: relayCredentialInterfaces.IClusterLegacyRelayCredentialRetirementResult;
+}
+
 /**
  * Cloudly hands the cluster relay the DNS lease renewals it has signed ahead of time for one node.
  *