@serve.zone/interfaces 32.41.0 → 32.43.0

package/ts/data/noderetirement.ts

@@ -5,11 +5,29 @@ const nodeRuntimeRetirementStates = ['retiring', 'retired'] as const;
 
 /**
  * How far a node's retirement has come: `retiring` while the producer still stops and removes the
- * node's slots, the compiler quarantines its handoff and both node credentials are revoked;
- * `retired` once all of that has settled and nothing but the node document is left to delete.
+ * node's slots, the compiler quarantines its handoff and leases, both node credentials are revoked
+ * and the node's egress fence (`IRuntimeNetworkEgressRetirement`) is not yet recorded; `retired`
+ * once the protected authority no longer names the node and nothing but the node document is left
+ * to delete.
  */
 export type TNodeRuntimeRetirementState = typeof nodeRuntimeRetirementStates[number];
 
+/** Every way a node can leave its runtime, in the order an escalation moves through them. */
+export const nodeRuntimeRetirementDispositions = Object.freeze(['withdrawn', 'lost'] as const);
+
+/**
+ * How the node leaves.
+ *
+ * `withdrawn`: the node still runs and takes part. Its slots are removed against its own removal
+ * receipts, and its Pallet withdraws its protection receipt before its credentials are revoked.
+ *
+ * `lost`: an administrator states that the node will never report again — its host is gone, wiped
+ * or unreachable for good. Its slots are abandoned without removal receipts, which is the one thing
+ * this statement authorizes. It authorizes nothing about packets: a lost node leaves the protected
+ * authority behind exactly the same controller-owned fence as a withdrawn one.
+ */
+export type TNodeRuntimeRetirementDisposition = typeof nodeRuntimeRetirementDispositions[number];
+
 /**
  * That one node leaves its cluster's runtime, stored beside the node document rather than inside
  * it, because a node update merges caller data and no caller may retire a node with it.
@@ -24,7 +42,9 @@ export interface INodeRuntimeRetirement {
   /** The cluster the node is retiring from, copied by Cloudly; never caller-chosen. */
   clusterId: string;
   state: TNodeRuntimeRetirementState;
-  /** The administrator who asked for the retirement. */
+  /** How the node leaves; a `withdrawn` retirement still `retiring` may be escalated to `lost`. */
+  disposition: TNodeRuntimeRetirementDisposition;
+  /** The administrator who asked for the retirement, or for its escalation. */
   actorId: string;
   /** Unix milliseconds on Cloudly's clock, when the row entered its current state. */
   since: number;
@@ -42,22 +62,38 @@ export const nodeRuntimeRetirementRefusals = Object.freeze([
    * `pallet`. Which of the two it is, `getClusterRuntime` says.
    */
   'cluster-runtime-not-pallet',
-  /** The node already carries a retirement row; neither of its states is left by retiring again. */
+  /**
+   * The node already carries a retirement row that this request cannot move: anything but a
+   * `withdrawn` row still `retiring`, asked again as `lost`.
+   */
   'node-already-retired',
   /** `expectedGeneration` is not the cluster runtime's current generation, so a cutover moved underneath the caller. */
   'conflict',
+  /**
+   * A `lost` retirement of a node whose last accepted report is younger than
+   * `clusterNodeObservationFreshnessMs`: a node that still reports is not lost, and it leaves as
+   * `withdrawn`.
+   */
+  'node-still-reporting',
 ] as const);
 
 /** One of the reasons Cloudly answers instead of a retirement row. */
 export type TNodeRuntimeRetirementRefusal = typeof nodeRuntimeRetirementRefusals[number];
 
+/** One disposition, exactly as `nodeRuntimeRetirementDispositions` spells it. */
+export const snapshotNodeRuntimeRetirementDisposition = (value: unknown): TNodeRuntimeRetirementDisposition => producerSafe(() => {
+  requireNetwork(isOneOf(nodeRuntimeRetirementDispositions, value));
+  return value;
+});
+
 /**
  * Structural snapshot for exact persistence; whether the node exists and whether its cluster admits
  * the retirement is Cloudly's.
  */
 export const snapshotNodeRuntimeRetirement = (value: unknown): INodeRuntimeRetirement => producerSafe(() => {
-  const item = networkRecord(captureNetwork(value), ['id', 'clusterId', 'state', 'actorId', 'since']);
+  const item = networkRecord(captureNetwork(value), ['id', 'clusterId', 'state', 'disposition', 'actorId', 'since']);
   requireNetwork(isOneOf(nodeRuntimeRetirementStates, item.state));
   return { id: networkNodeId(item.id), clusterId: networkId(item.clusterId), state: item.state,
+    disposition: snapshotNodeRuntimeRetirementDisposition(item.disposition),
     actorId: networkId(item.actorId), since: networkCounter(item.since) };
 });

package/ts/private/networkcontract.ts

@@ -244,3 +244,12 @@ export const networkContains = (outer: string, inner: string): boolean => {
 export const networkOverlaps = (left: string, right: string): boolean => {
   const [a, b] = networkPrefixBounds(left), [c, d] = networkPrefixBounds(right); return a <= d && c <= b;
 };
+/** Whether the union of `prefixes`, which never overlap one another, covers every address of `prefix`. */
+export const networkCoveredBy = (prefixes: string[], prefix: string): boolean => {
+  const [first, last] = networkPrefixBounds(prefix);
+  const covered = prefixes.reduce((sum, candidate) => {
+    const [low, high] = networkPrefixBounds(candidate);
+    return sum + Math.max(0, Math.min(last, high) - Math.max(first, low) + 1);
+  }, 0);
+  return covered === last - first + 1;
+};

package/ts/requests/corestorecontrol.ts

@@ -0,0 +1,43 @@
+import * as plugins from '../plugins.js';
+import type * as userInterfaces from '../data/user.js';
+import type * as controlTokenInterfaces from '../data/corestorecontroltoken.js';
+
+/**
+ * Stores the Corestore control token for every cluster relay to read sealed, so an administrator
+ * sets it without an exec into Cloudly's process.
+ *
+ * One token for both Corestore provider configs, stored in one transaction: either both hold the
+ * new token or neither does. `expected` is the state `getCorestoreControlTokenState` answered, and
+ * Cloudly stores only while the token is still exactly there; a set that committed in between is
+ * refused, never overwritten. Only the verified credential of a freshly authenticated
+ * administrator is read, and Cloudly writes the `receipt` in the transaction that stores the token.
+ * The token is in this request and nowhere else: never in the answer, a log, a hook or a receipt.
+ * Cloudly refuses with one of `data.corestoreControlTokenSetRefusals`.
+ */
+export interface IReq_Admin_Cloudly_SetCorestoreControlToken
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_SetCorestoreControlToken
+> {
+  method: 'setCorestoreControlToken';
+  request: controlTokenInterfaces.ICorestoreControlTokenSetRequest & {
+    identity: userInterfaces.IIdentityCredential;
+  };
+  response: controlTokenInterfaces.ICorestoreControlTokenSetResult;
+}
+
+/**
+ * Whether Cloudly holds the Corestore control token, at which revision, and every receipt of a set,
+ * oldest first. Value-free: no token, no hash. Requires an administrator.
+ */
+export interface IReq_Admin_Cloudly_GetCorestoreControlTokenState
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_GetCorestoreControlTokenState
+> {
+  method: 'getCorestoreControlTokenState';
+  request: {
+    identity: userInterfaces.IIdentityCredential;
+  };
+  response: controlTokenInterfaces.ICorestoreControlTokenStateRead;
+}

package/ts/requests/index.ts

@@ -12,6 +12,7 @@ import * as configRequests from './config.js';
 import * as coreMailRequests from './coremail.js';
 import * as coreMailAdminRequests from './coremail.admin.js';
 import * as corestoreRequests from './corestore.js';
+import * as corestoreControlRequests from './corestorecontrol.js';
 import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
@@ -52,6 +53,7 @@ export {
   coreMailRequests as coremail,
   coreMailAdminRequests as coremailAdmin,
   corestoreRequests as corestore,
+  corestoreControlRequests as corestorecontrol,
   deploymentRequests as deployment,
   dnsRequests as dns,
   domainRequests as domain,

package/ts/requests/node.ts

@@ -12,7 +12,7 @@ import type {
   INodeCredentialMutationResult,
   TNodeCredentialPurpose,
 } from '../data/nodecredential.js';
-import type { INodeRuntimeRetirement } from '../data/noderetirement.js';
+import type { INodeRuntimeRetirement, TNodeRuntimeRetirementDisposition } from '../data/noderetirement.js';
 import type { INodeRuntimeBindingRead, INodeRuntimeBindingRequest } from '../data/noderuntimebinding.js';
 import type {
   INodeEnrollmentRequest,
@@ -232,6 +232,13 @@ export interface IReq_Any_Cloudly_DeleteNodeById extends plugins.typedrequestInt
  * `expectedGeneration` is the cluster runtime generation the caller read with `getClusterRuntime`:
  * retirement is a statement about a node of a Pallet cluster, so a cutover that moved the phase
  * meanwhile refuses the write instead of retiring a node out of a runtime it no longer runs in.
+ *
+ * `disposition` states how the node leaves (`data.TNodeRuntimeRetirementDisposition`). A request
+ * that states none asks for `withdrawn`, the retirement this request always described: the node
+ * takes part, and nothing is abandoned. `lost` is taken only when stated, is refused as
+ * `node-still-reporting` for a node that still reports, and escalates a `withdrawn` retirement that
+ * is still `retiring`. Neither disposition shortens the egress fence: the node leaves the protected
+ * authority only behind its `data.IRuntimeNetworkEgressRetirement`.
  * Every refusal is one of `data.nodeRuntimeRetirementRefusals` and takes nothing away.
  */
 export interface IReq_Any_Cloudly_RetireClusterNode extends plugins.typedrequestInterfaces.implementsTR<
@@ -243,6 +250,7 @@ export interface IReq_Any_Cloudly_RetireClusterNode extends plugins.typedrequest
     identity: IIdentity;
     nodeId: string;
     expectedGeneration: number;
+    disposition?: TNodeRuntimeRetirementDisposition;
   };
   response: {
     retirement: INodeRuntimeRetirement;