@serve.zone/interfaces 31.4.0 → 31.6.0

package/ts/data/clusternode.ts

@@ -1010,5 +1010,98 @@ export interface IClusterNode {
      * Debian packages installed on this node
      */
     requiredDebianPackages: string[];
+
+    /**
+     * Where this node's Corestore answers its control API.
+     *
+     * Cloudly owns it and the relay reads it. Absent means this node runs no
+     * Corestore the relay may reach, which is a fact to report rather than a
+     * reason to guess a hostname: the cluster-local alias every component used
+     * while Docker Swarm resolved it is exactly what stops resolving.
+     */
+    corestore?: IClusterNodeCorestore;
   };
 }
+
+/**
+ * How the cluster relay reaches one node's Corestore.
+ *
+ * Corestore is node-local: the database and the bucket of a workload live on
+ * the node the workload runs on, so one relay serving a whole cluster must be
+ * told, per node, where that node's control API listens. This is control-plane
+ * state, owned by Cloudly and stored in its database like every other field of
+ * the cluster document — never a file, an alias or an environment variable on
+ * the relay.
+ */
+export interface IClusterNodeCorestore {
+  /**
+   * The canonical origin of the control API, for example
+   * `http://10.20.0.15:3000`.
+   *
+   * `http:` is admitted because Corestore terminates no TLS today — it binds a
+   * plain control port and advertises no transport-encryption guarantee — and
+   * the hop is cluster-private by construction, reachable only from inside the
+   * cluster. `https:` is admitted too, so a deployment that puts TLS in front
+   * of Corestore needs no contract change.
+   *
+   * The endpoint says where, never with what: the bearer control token that
+   * authorizes every call is obtained from Cloudly through
+   * `getCorestoreControlCredentialMaterial`, sealed to the X25519 recipient the
+   * relay enrolled with `beginSecretRecipientEnrollment` and
+   * `completeSecretRecipientEnrollment`. No credential ever travels in this
+   * document, and none is read from the relay's environment.
+   */
+  endpoint: string;
+}
+
+const maximumClusterNodeCorestoreEndpointLength = 2048;
+
+/**
+ * Validates one node's Corestore endpoint and names every reason it is refused.
+ *
+ * A relay that dialled a wrong or ambiguous endpoint would provision a
+ * workload's database on a node that is not the workload's, so the origin must
+ * be exact: a scheme this contract admits, a host, an optional port, and
+ * nothing else — no path, no query, no fragment, no userinfo, no trailing
+ * slash.
+ */
+export const validateClusterNodeCorestore = (
+  valueArg: unknown,
+  pathArg = 'cluster node corestore',
+): string[] => {
+  if (!valueArg
+    || typeof valueArg !== 'object'
+    || Array.isArray(valueArg)
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype
+      && Object.getPrototypeOf(valueArg) !== null)
+    || Object.keys(valueArg as Record<string, unknown>).join(',') !== 'endpoint') {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const endpoint = (valueArg as { endpoint: unknown }).endpoint;
+  if (typeof endpoint !== 'string'
+    || endpoint.length === 0
+    || endpoint.length > maximumClusterNodeCorestoreEndpointLength) {
+    return [`${pathArg} endpoint must be a string of 1 to `
+      + `${maximumClusterNodeCorestoreEndpointLength} characters`];
+  }
+  let parsedEndpoint: URL;
+  try {
+    parsedEndpoint = new URL(endpoint);
+  } catch {
+    return [`${pathArg} endpoint must be a parsable URL`];
+  }
+  const errors: string[] = [];
+  if (parsedEndpoint.protocol !== 'http:' && parsedEndpoint.protocol !== 'https:') {
+    errors.push(`${pathArg} endpoint must use the http or https scheme`);
+  }
+  if (parsedEndpoint.username || parsedEndpoint.password) {
+    errors.push(`${pathArg} endpoint must not carry userinfo`);
+  }
+  if (parsedEndpoint.origin !== endpoint) {
+    errors.push(
+      `${pathArg} endpoint must be the canonical origin ${parsedEndpoint.origin}, `
+        + 'without a path, query, fragment, trailing slash or default port',
+    );
+  }
+  return errors;
+};

package/ts/data/corestore.ts

@@ -0,0 +1,28 @@
+/**
+ * The Corestore shapes the control plane exchanges outside the Node-only
+ * `/runtime` export.
+ *
+ * Only what a browser-visible contract has to name lives here. Everything that
+ * needs Corestore's canonical JSON, digests or receipts stays in
+ * `runtime.corestore.*`, which imports this declaration rather than repeating
+ * it: one structure, one rule set, two entry points.
+ */
+
+/**
+ * The safe reference to an allocation-managed Corestore database.
+ *
+ * Corestore returns it when a database is allocated and requires the exact same
+ * value back on every later operation against that database. It intentionally
+ * excludes the NoSQLDB principal, the publication capability, the database URI,
+ * the password and every provider-private evidence field, so it can travel
+ * through a control plane, be persisted as authority and be quoted in a
+ * validation reason without disclosing a credential.
+ */
+export interface ICorestoreDatabaseAllocationReference {
+  purpose: 'scratch-rehearsal';
+  rehearsalId: string;
+  allocationId: string;
+  generation: number;
+  bindingSha256: string;
+  receiptSha256: string;
+}

package/ts/data/index.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './clusteringress.js';
 export * from './config.js';
+export * from './corestore.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';
 export * from './deployment.js';

package/ts/data/isolatedrestore.ts

@@ -3,6 +3,7 @@ import type {
   IBackupArchiveObject,
   TIsolatedRestoreResourceMapping,
 } from './backup.js';
+import type { ICorestoreDatabaseAllocationReference } from './corestore.js';
 import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
@@ -614,6 +615,44 @@ const readSafeInteger = (
   return valueArg;
 };
 
+/**
+ * Corestore's safe reference to an allocation-managed database, exactly as it
+ * issued it.
+ *
+ * Every field is read here rather than trusted, because this value is bound
+ * into the restore grant: a reference the coordinator mistyped would be signed
+ * authority for a database nobody meant to replace.
+ */
+const readDatabaseAllocationReference = (
+  valueArg: unknown,
+  fieldNameArg: string,
+): ICorestoreDatabaseAllocationReference => {
+  const value = readRecord(valueArg, fieldNameArg);
+  assertExactKeys(
+    value,
+    [
+      'purpose',
+      'rehearsalId',
+      'allocationId',
+      'generation',
+      'bindingSha256',
+      'receiptSha256',
+    ],
+    fieldNameArg,
+  );
+  if (value.purpose !== 'scratch-rehearsal') {
+    return fail(`${fieldNameArg}.purpose must be scratch-rehearsal`);
+  }
+  return {
+    purpose: 'scratch-rehearsal',
+    rehearsalId: readScopedId(value.rehearsalId, `${fieldNameArg}.rehearsalId`),
+    allocationId: readSha256(value.allocationId, `${fieldNameArg}.allocationId`),
+    generation: readSafeInteger(value.generation, `${fieldNameArg}.generation`, 1),
+    bindingSha256: readSha256(value.bindingSha256, `${fieldNameArg}.bindingSha256`),
+    receiptSha256: readSha256(value.receiptSha256, `${fieldNameArg}.receiptSha256`),
+  };
+};
+
 const readMountPath = (valueArg: unknown, fieldNameArg: string): string => {
   const value = readString(
     valueArg,
@@ -871,7 +910,9 @@ const normalizeMapping = (
     );
     assertExactKeys(
       target,
-      ['resourceName', 'databaseName'],
+      Object.hasOwn(target, 'databaseAllocation')
+        ? ['resourceName', 'databaseName', 'databaseAllocation']
+        : ['resourceName', 'databaseName'],
       `${fieldName}.target`,
     );
     const sourceResourceName = readResourceName(
@@ -910,6 +951,17 @@ const normalizeMapping = (
       target: {
         resourceName: targetResourceName,
         databaseName: targetDatabaseName,
+        // Present exactly when the target is allocation-managed, and therefore
+        // part of what the mapping digest binds: Corestore refuses an allocated
+        // target whose exact reference the authority did not cover.
+        ...(Object.hasOwn(target, 'databaseAllocation')
+          ? {
+              databaseAllocation: readDatabaseAllocationReference(
+                target.databaseAllocation,
+                `${fieldName}.target.databaseAllocation`,
+              ),
+            }
+          : {}),
       },
     };
   }

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/cluster.ts

@@ -109,6 +109,27 @@ export interface IReq_Any_Cloudly_DisableClusterRelayV1 extends plugins.typedreq
   };
 }
 
+/**
+ * The relay registrations an administrator asks Cloudly about.
+ *
+ * Read-only: it answers with what Cloudly accepted, plus whether a verified socket carries each
+ * relay at this instant. `clusterIds` narrows the answer to the named clusters; omitting it asks
+ * for every cluster whose relay ever registered.
+ */
+export interface IReq_Any_Cloudly_GetClusterRelayRegistrations extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetClusterRelayRegistrations
+> {
+  method: 'getClusterRelayRegistrations';
+  request: {
+    identity: userInterfaces.IIdentity;
+    clusterIds?: string[];
+  };
+  response: {
+    registrations: clusterInterfaces.IClusterRelayRegistration[];
+  };
+}
+
 /**
  * The cluster relay tells Cloudly where it listens, over its own authenticated socket.
  *