@serve.zone/interfaces 31.5.0 → 31.7.0

package/ts/requests/backup.ts

@@ -13,6 +13,7 @@ import type {
 } from '../data/backup.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity, IIdentityCredential } from '../data/user.js';
+import type { ICorestoreDatabaseClosureDescriptor } from '../runtime.corestore.relay.js';
 
 export interface IReq_Any_Cloudly_CreateServiceBackup
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -80,6 +81,15 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Superseded by `backupClusterService`, which names the node.
+ *
+ * This method was dispatched at the coreflow that had tagged itself with the
+ * node's hostname; a cluster relay authors no tags and serves every node of its
+ * cluster, so the node it should act on can no longer be inferred from which
+ * connection answered. It is retired together with the tag in the coordinated
+ * major.
+ */
 export interface IReq_Cloudly_Coreflow_ExecuteServiceBackup
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -100,6 +110,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/** Superseded by `restoreClusterService`; see `executeServiceBackup`. */
 export interface IReq_Cloudly_Coreflow_ExecuteServiceRestore
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -137,6 +148,14 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Retiring: `contentsBase64` carries a whole archive object inside one JSON
+ * envelope, which costs a third of the payload in encoding and bounds a backup
+ * by the message ceiling rather than by the transport. `backupServiceDatabaseClosure`
+ * streams the same bytes as a VirtualStream. Removal is the coordinated major,
+ * once every relay and every Cloudly speak the streamed contract; Corestore
+ * already documents its repository-wide archive object routes as legacy.
+ */
 export interface IReq_Coreflow_Cloudly_UploadBackupArchiveObject
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -185,6 +204,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/** Retiring with `uploadBackupArchiveObject`; `restoreServiceDatabaseClosure` replaces it. */
 export interface IReq_Coreflow_Cloudly_DownloadBackupArchiveObject
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -202,6 +222,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/** Superseded by `pruneClusterNodeArchive`; see `executeServiceBackup`. */
 export interface IReq_Cloudly_Coreflow_PruneNodeArchive
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -218,6 +239,152 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Backs up one service on one exact node of this cluster.
+ *
+ * The cluster relay serves every node of its cluster over one session, so the
+ * node is a request field: the connection that answers proves which cluster is
+ * speaking, never which node is meant. Everything else is what
+ * `executeServiceBackup` carried, so a caller moving to this method changes its
+ * routing and nothing about its backup.
+ */
+export interface IReq_Cloudly_Relay_BackupClusterService
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_BackupClusterService
+> {
+  method: 'backupClusterService';
+  request: {
+    /** The cluster node whose Corestore holds this service's data. */
+    nodeId: string;
+    backupId: string;
+    service: IService;
+    tags?: Record<string, string>;
+    replication?: {
+      enabled: boolean;
+    };
+  };
+  response: {
+    snapshots: TBackupSnapshot[];
+    replication?: IBackupReplicationResult;
+  };
+}
+
+/** Restores one service on one exact node of this cluster; see `backupClusterService`. */
+export interface IReq_Cloudly_Relay_RestoreClusterService
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_RestoreClusterService
+> {
+  method: 'restoreClusterService';
+  request: {
+    /** The cluster node whose Corestore receives the restore. */
+    nodeId: string;
+    backupId: string;
+    service: IService;
+    snapshots: TBackupSnapshot[];
+    clear?: boolean;
+    resourceTypes?: Array<TBackupSnapshot['type']>;
+    replication?: {
+      enabled: boolean;
+    };
+  };
+  response: {
+    restored: TBackupSnapshot[];
+  };
+}
+
+/**
+ * Prunes the archive of one exact node of this cluster.
+ *
+ * `found` stays false when that node has no archive to prune, which is a fact
+ * about the node rather than a failure of the relay.
+ */
+export interface IReq_Cloudly_Relay_PruneClusterNodeArchive
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_PruneClusterNodeArchive
+> {
+  method: 'pruneClusterNodeArchive';
+  request: {
+    /** The cluster node whose archive is pruned. */
+    nodeId: string;
+    retention: IArchiveRetentionPolicy;
+    dryRun?: boolean;
+  };
+  response: {
+    found: boolean;
+    result?: IArchivePruneResult;
+  };
+}
+
+/**
+ * The relay carries one service database closure to Cloudly.
+ *
+ * Relay-initiated, like every other byte a cluster sends: a cluster is
+ * outbound-only, so Cloudly cannot pull from it. The relay exports the closure
+ * from its node's Corestore and sends those exact bytes on its own session.
+ *
+ * `accepted` permits sending; it never confirms storage. The stream's own
+ * acceptance receipt, observed through `completion`, is what confirms that
+ * Cloudly durably holds the closure — exactly as `pushImageVersion` works.
+ *
+ * No identity field: the cluster is the one the verified machine identity on
+ * the relay's own session names, exactly as `getClusterRouteTable` and
+ * `getClusterPlatformDesiredState` work. A request-level identity would be a
+ * second authority for the same fact, and the weaker of the two.
+ */
+export interface IReq_Relay_Cloudly_BackupServiceDatabaseClosure
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Cloudly_BackupServiceDatabaseClosure
+> {
+  method: 'backupServiceDatabaseClosure';
+  request: {
+    backupId: string;
+    serviceId: string;
+    /** The cluster node this closure was exported from. */
+    nodeId: string;
+    /** Exact bytes and Corestore's receipt for them; validated before any byte moves. */
+    descriptor: ICorestoreDatabaseClosureDescriptor;
+    /** Requester sends closure bytes; the TypedHandler receives the opposite endpoint. */
+    closure: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
+  };
+  response: {
+    accepted: boolean;
+  };
+}
+
+/**
+ * The relay fetches one service database closure back from Cloudly.
+ *
+ * The descriptor arrives with the stream rather than after it, because
+ * Corestore's restore needs the exact byte length and receipt before the first
+ * byte is written: the relay opens its Corestore request from this descriptor
+ * and only then drains the stream into it.
+ *
+ * No identity field, for the same reason as `backupServiceDatabaseClosure`: the
+ * relay's own session names the cluster.
+ */
+export interface IReq_Relay_Cloudly_RestoreServiceDatabaseClosure
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Cloudly_RestoreServiceDatabaseClosure
+> {
+  method: 'restoreServiceDatabaseClosure';
+  request: {
+    backupId: string;
+    serviceId: string;
+    /** The cluster node the closure is restored onto. */
+    nodeId: string;
+  };
+  response: {
+    descriptor: ICorestoreDatabaseClosureDescriptor;
+    /** Requester receives closure bytes; the TypedHandler returns a sender endpoint. */
+    closure: plugins.typedrequestInterfaces.TVirtualStream<'receive'>;
+  };
+}
+
 /**
  * Creates a restore in a new non-runnable data-plane scratch namespace.
  * Cloudly derives clusterId and sourceServiceId from the authoritative backup,
@@ -316,6 +483,18 @@ extends plugins.typedrequestInterfaces.implementsTR<
 > {
   method: 'coreflowPrepareIsolatedRestore';
   request: {
+    /**
+     * The compact RS256 restore grant Cloudly signed for exactly this
+     * operation, carried untouched to Corestore.
+     *
+     * Corestore accepts no other authority on an isolated-restore route: the
+     * grant names the operation, expires within minutes, and binds the cluster,
+     * the node, the canonical resource mappings and the archive manifest, so a
+     * relay can carry it but can neither widen it nor mint one. Sensitive
+     * ephemeral input: exclude the complete request from hooks, logs and
+     * journals on every hop.
+     */
+    restoreGrant: string;
     clusterId: string;
     targetNodeName: string;
     restoreId: string;
@@ -332,6 +511,44 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Cloudly stages one archive object of an isolated restore on the relay's node.
+ *
+ * Cloudly holds the source backup, so these bytes travel Cloudly → relay and
+ * the requester is the sender. One object per call, as the archive manifest
+ * lists it: Corestore writes staged objects under a `write-object` grant, one
+ * bounded chunk at a time, and the relay is what turns this stream into those
+ * chunks. The object descriptor is the manifest entry itself — path, exact size
+ * and digest — so the relay can prove the complete object before it counts as
+ * written, and so a replayed stage settles on the same bytes.
+ */
+export interface IReq_Cloudly_Relay_StageIsolatedRestoreArchive
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_StageIsolatedRestoreArchive
+> {
+  method: 'stageIsolatedRestoreArchive';
+  request: {
+    /**
+     * The compact RS256 restore grant for the `write-object` operation, carried
+     * untouched to Corestore. Sensitive ephemeral input, like every other
+     * grant on these routes.
+     */
+    restoreGrant: string;
+    clusterId: string;
+    targetNodeName: string;
+    restoreId: string;
+    expectedRevision: number;
+    /** The manifest entry these bytes complete: `path`, `size`, `sha256`. */
+    object: IBackupArchiveObject;
+    /** Requester sends the object bytes; the TypedHandler receives them. */
+    archive: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
+  };
+  response: {
+    state: IIsolatedRestoreNodeState;
+  };
+}
+
 /** Read-only status for one exact cluster/node/restore routing key. */
 export interface IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -340,6 +557,18 @@ extends plugins.typedrequestInterfaces.implementsTR<
 > {
   method: 'coreflowGetIsolatedRestoreStatus';
   request: {
+    /**
+     * The compact RS256 restore grant Cloudly signed for exactly this
+     * operation, carried untouched to Corestore.
+     *
+     * Corestore accepts no other authority on an isolated-restore route: the
+     * grant names the operation, expires within minutes, and binds the cluster,
+     * the node, the canonical resource mappings and the archive manifest, so a
+     * relay can carry it but can neither widen it nor mint one. Sensitive
+     * ephemeral input: exclude the complete request from hooks, logs and
+     * journals on every hop.
+     */
+    restoreGrant: string;
     clusterId: string;
     targetNodeName: string;
     restoreId: string;
@@ -357,6 +586,18 @@ extends plugins.typedrequestInterfaces.implementsTR<
 > {
   method: 'coreflowExecuteIsolatedRestore';
   request: {
+    /**
+     * The compact RS256 restore grant Cloudly signed for exactly this
+     * operation, carried untouched to Corestore.
+     *
+     * Corestore accepts no other authority on an isolated-restore route: the
+     * grant names the operation, expires within minutes, and binds the cluster,
+     * the node, the canonical resource mappings and the archive manifest, so a
+     * relay can carry it but can neither widen it nor mint one. Sensitive
+     * ephemeral input: exclude the complete request from hooks, logs and
+     * journals on every hop.
+     */
+    restoreGrant: string;
     clusterId: string;
     targetNodeName: string;
     restoreId: string;
@@ -378,6 +619,18 @@ extends plugins.typedrequestInterfaces.implementsTR<
 > {
   method: 'coreflowCleanupIsolatedRestore';
   request: {
+    /**
+     * The compact RS256 restore grant Cloudly signed for exactly this
+     * operation, carried untouched to Corestore.
+     *
+     * Corestore accepts no other authority on an isolated-restore route: the
+     * grant names the operation, expires within minutes, and binds the cluster,
+     * the node, the canonical resource mappings and the archive manifest, so a
+     * relay can carry it but can neither widen it nor mint one. Sensitive
+     * ephemeral input: exclude the complete request from hooks, logs and
+     * journals on every hop.
+     */
+    restoreGrant: string;
     clusterId: string;
     targetNodeName: string;
     restoreId: string;

package/ts/requests/corestore.ts

@@ -22,6 +22,10 @@ export interface ICorestoreServiceResources {
 /**
  * Corestore inventory of one node (each coreflow node runs its own corestore;
  * the data is node-local, which is what makes node placement matter).
+ *
+ * Superseded by `IClusterCorestoreInventory`, which names the node by its
+ * cluster-document id instead of by the Swarm hostnames a connection tagged
+ * itself with.
  */
 export interface ICorestoreNodeInventory {
   /** Swarm node hostnames of the reporting coreflow. */
@@ -83,6 +87,156 @@ export interface ICoreflowInventoryRegistration {
   registeredAt: number;
 }
 
+/**
+ * What one node's Corestore holds, as the cluster relay read it.
+ *
+ * Node identity is the cluster document's node id: one relay serves every node
+ * of its cluster, so which node an inventory describes is stated, never derived
+ * from which connection answered. An unreachable node names why — `errorCode`
+ * is required whenever `reachable` is false and refused whenever it is true —
+ * because a node whose Corestore cannot be reached is a fact the control plane
+ * needs, and a silent empty inventory would read as "nothing provisioned",
+ * which is the opposite.
+ */
+export interface IClusterCorestoreInventory {
+  nodeId: string;
+  checkedAt: number;
+  reachable: boolean;
+  errorCode?: 'CORESTORE_ENDPOINT_UNKNOWN' | 'CORESTORE_UNREACHABLE';
+  services: ICorestoreServiceResources[];
+}
+
+const clusterCorestoreInventoryIdentifierPattern = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+
+const isClusterCorestoreRecord = (
+  valueArg: unknown,
+): valueArg is Record<string, unknown> => (
+  Boolean(valueArg)
+  && typeof valueArg === 'object'
+  && !Array.isArray(valueArg)
+  && (Object.getPrototypeOf(valueArg) === Object.prototype
+    || Object.getPrototypeOf(valueArg) === null)
+);
+
+const hasClusterCorestoreKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
+): boolean => {
+  const actualKeys = Object.keys(valueArg);
+  return keysArg.every((keyArg) => actualKeys.includes(keyArg))
+    && actualKeys.every((keyArg) => keysArg.includes(keyArg) || optionalKeysArg.includes(keyArg));
+};
+
+const validateClusterCorestoreServiceResources = (
+  valueArg: unknown,
+  pathArg: string,
+): string[] => {
+  if (!isClusterCorestoreRecord(valueArg)
+    || !hasClusterCorestoreKeys(
+      valueArg,
+      ['serviceId', 'resources', 'updatedAt'],
+      ['serviceName'],
+    )) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (typeof valueArg.serviceId !== 'string'
+    || !clusterCorestoreInventoryIdentifierPattern.test(valueArg.serviceId)) {
+    errors.push(`${pathArg} serviceId must be a bounded identifier`);
+  }
+  if (!Number.isSafeInteger(valueArg.updatedAt) || (valueArg.updatedAt as number) < 0) {
+    errors.push(`${pathArg} updatedAt must be a non-negative safe integer`);
+  }
+  if (!Array.isArray(valueArg.resources)) {
+    errors.push(`${pathArg} resources must be an array`);
+    return errors;
+  }
+  for (const [index, resource] of valueArg.resources.entries()) {
+    const resourcePath = `${pathArg} resources[${index}]`;
+    if (!isClusterCorestoreRecord(resource)
+      || !hasClusterCorestoreKeys(
+        resource,
+        ['capability', 'provider', 'resourceName', 'createdAt'],
+      )) {
+      errors.push(`${resourcePath} must use its exact schema`);
+      continue;
+    }
+    if (resource.capability !== 'database' && resource.capability !== 'objectstorage') {
+      errors.push(`${resourcePath} capability must be database or objectstorage`);
+    }
+    if (typeof resource.provider !== 'string' || resource.provider.length === 0) {
+      errors.push(`${resourcePath} provider must be a non-empty string`);
+    }
+    if (typeof resource.resourceName !== 'string' || resource.resourceName.length === 0) {
+      errors.push(`${resourcePath} resourceName must be a non-empty string`);
+    }
+    if (!Number.isSafeInteger(resource.createdAt) || (resource.createdAt as number) < 0) {
+      errors.push(`${resourcePath} createdAt must be a non-negative safe integer`);
+    }
+  }
+  return errors;
+};
+
+/**
+ * Validates one cluster Corestore inventory and names every reason it is
+ * refused.
+ *
+ * Shape only. Whether that node belongs to the cluster, and whether a resource
+ * should exist, are decisions for the control plane that asked; an inventory
+ * that passes here has claimed neither. A reachable inventory that names an
+ * error, and an unreachable one that lists resources, are both refused: an
+ * answer has to be one of the two things it can be.
+ */
+export const validateClusterCorestoreInventory = (
+  valueArg: unknown,
+  pathArg = 'cluster corestore inventory',
+): string[] => {
+  if (!isClusterCorestoreRecord(valueArg)
+    || !hasClusterCorestoreKeys(
+      valueArg,
+      ['nodeId', 'checkedAt', 'reachable', 'services'],
+      ['errorCode'],
+    )) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (typeof valueArg.nodeId !== 'string'
+    || !clusterCorestoreInventoryIdentifierPattern.test(valueArg.nodeId)) {
+    errors.push(`${pathArg} nodeId must be a bounded identifier`);
+  }
+  if (!Number.isSafeInteger(valueArg.checkedAt) || (valueArg.checkedAt as number) < 0) {
+    errors.push(`${pathArg} checkedAt must be a non-negative safe integer`);
+  }
+  if (typeof valueArg.reachable !== 'boolean') {
+    errors.push(`${pathArg} reachable must be a boolean`);
+  }
+  if (valueArg.errorCode !== undefined
+    && valueArg.errorCode !== 'CORESTORE_ENDPOINT_UNKNOWN'
+    && valueArg.errorCode !== 'CORESTORE_UNREACHABLE') {
+    errors.push(`${pathArg} errorCode must name why the node could not be read`);
+  }
+  if (valueArg.reachable === true && valueArg.errorCode !== undefined) {
+    errors.push(`${pathArg} must not carry an errorCode while it reports the node reachable`);
+  }
+  if (valueArg.reachable === false && valueArg.errorCode === undefined) {
+    // An unreachable node with no reason reads like a node holding nothing,
+    // which is the one confusion this shape exists to prevent.
+    errors.push(`${pathArg} must name why the node could not be read while it reports it unreachable`);
+  }
+  if (!Array.isArray(valueArg.services)) {
+    errors.push(`${pathArg} services must be an array`);
+    return errors;
+  }
+  if (valueArg.reachable === false && valueArg.services.length > 0) {
+    errors.push(`${pathArg} must list no services while it reports the node unreachable`);
+  }
+  for (const [index, service] of valueArg.services.entries()) {
+    errors.push(...validateClusterCorestoreServiceResources(service, `${pathArg} services[${index}]`));
+  }
+  return errors;
+};
+
 export interface IReq_Any_Cloudly_GetCorestoreInventory
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -95,6 +249,35 @@ extends plugins.typedrequestInterfaces.implementsTR<
   response: ICorestoreInventoryReport;
 }
 
+/**
+ * Cloudly asks the relay what one exact node of its cluster holds.
+ *
+ * The node is a request field because one relay serves them all: the connection
+ * that answers proves the cluster, never the node. A greenfield cluster answers
+ * with an empty `services` list and `reachable: true`, which is the proof that
+ * a namespace is blank — distinct from `reachable: false`, which proves
+ * nothing at all.
+ *
+ * Named apart from `getCorestoreInventory` on purpose: that method is Cloudly's
+ * own operator-facing read and lives on the other end of this socket. One name
+ * on both ends would leave direction as the only thing telling two different
+ * bodies apart.
+ */
+export interface IReq_Cloudly_Relay_GetClusterCorestoreInventory
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_GetClusterCorestoreInventory
+> {
+  method: 'getClusterCorestoreInventory';
+  request: {
+    nodeId: string;
+  };
+  response: {
+    inventory: IClusterCorestoreInventory;
+  };
+}
+
+/** Superseded by `getClusterCorestoreInventory`, which names the node. */
 export interface IReq_Cloudly_Coreflow_GetCorestoreInventory
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,

package/ts/requests/node.ts

@@ -203,6 +203,41 @@ export interface IReq_Any_Cloudly_DeleteNodeById extends plugins.typedrequestInt
   };
 }
 
+/**
+ * An administrator states where one node's Corestore control API answers.
+ *
+ * Corestore is node-local, so one relay serving a whole cluster must be told per node where to
+ * dial; the cluster-local alias every component used while Docker Swarm resolved it is exactly
+ * what stops resolving. The endpoint is control-plane state Cloudly owns and the relay reads,
+ * so an administrator sets it here rather than a relay discovering it.
+ *
+ * Cloudly validates the endpoint with `validateClusterNodeCorestore` before it writes, takes the
+ * node's own real-write fence inside the writing transaction so a concurrent deletion conflicts
+ * instead of leaving an endpoint behind for a node that is gone, and pushes the cluster
+ * configuration afterwards so every connected relay learns the change without reconnecting.
+ *
+ * `endpoint: null` clears it, which is the same fact as never having set one: the node runs no
+ * Corestore the relay may reach, and an inventory for it answers
+ * `errorCode: 'CORESTORE_ENDPOINT_UNKNOWN'` rather than guessing a hostname. The endpoint says
+ * where, never with what — no credential travels in this request or in the node document.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint
+> {
+  method: 'setClusterNodeCorestoreEndpoint';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    /** A canonical `http:` or `https:` origin, or `null` to state that this node has none. */
+    endpoint: string | null;
+  };
+  response: {
+    /** The node as it now stands, so a caller needs no second read to see what it set. */
+    node: IClusterNode;
+  };
+}
+
 export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IRequest_Spark_Cloudly_SendHeartbeat

package/ts/requests/platform.ts

@@ -23,6 +23,42 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * One platform binding and the node its Corestore resources live on.
+ *
+ * Corestore is node-local, so a binding without a node is a database nobody can
+ * place: while every cluster ran one coreflow per node, "this node" was whoever
+ * answered, and a cluster relay serving every node has no such implicit answer.
+ * The placement is Cloudly's, derived from where the service is assigned.
+ */
+export interface IClusterPlatformBindingPlacement {
+  nodeId: string;
+  binding: IPlatformBinding;
+}
+
+/**
+ * The desired platform state for the relay's own cluster, node by node.
+ *
+ * Its session decides which cluster it speaks for, so the request carries no
+ * cluster of its own. It replaces `getPlatformDesiredState` for a cluster
+ * relay: the same capabilities and provider configs, and bindings that state
+ * where they belong instead of leaving it to be inferred.
+ */
+export interface IReq_Relay_Cloudly_GetClusterPlatformDesiredState
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Cloudly_GetClusterPlatformDesiredState
+> {
+  method: 'getClusterPlatformDesiredState';
+  request: Record<string, never>;
+  response: {
+    capabilities: IPlatformCapability[];
+    providerConfigs: IPlatformProviderConfig[];
+    /** Sorted by node, then by binding id, so two reads compare directly. */
+    bindings: IClusterPlatformBindingPlacement[];
+  };
+}
+
 export interface IReq_Any_Cloudly_GetPlatformCapabilities
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,