@serve.zone/interfaces 31.4.0 → 31.6.0

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/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,

package/ts/runtime.corestore.relay.ts

@@ -0,0 +1,111 @@
+import type { ICorestoreDatabaseBackupReceipt } from './runtime.corestore.js';
+import {
+  corestoreDatabaseBackupRuntimeLimits,
+  normalizeCorestoreDatabaseBackupReceipt,
+} from './runtime.corestore.js';
+
+/**
+ * Carrying a Corestore database closure through the cluster relay.
+ *
+ * A cluster is outbound-only, so Cloudly never reads Corestore itself: the
+ * relay exports the closure from its cluster's Corestore and streams it to
+ * Cloudly, and streams it back for a restore. The bytes travel as a
+ * VirtualStream on the relay's own session; this descriptor is what the parent
+ * TypedRequest carries about them.
+ *
+ * No version suffix and no schema field: the protocol version is the installed
+ * `@serve.zone/interfaces` version.
+ */
+
+/**
+ * What a peer states about the closure it is about to send or serve.
+ *
+ * `size` is mandatory, and it is the reason this descriptor exists at all:
+ * Corestore's database backup restore requires one exact `Content-Length`,
+ * identity transfer encoding and no content encoding, and it refuses a body
+ * whose byte length differs from its receipt. A stream that only learned its
+ * length at EOF could therefore never be restored — the receiver has to open
+ * the Corestore request before the first byte arrives.
+ *
+ * `sha256` is the digest of those exact bytes, and `receipt` is Corestore's own
+ * closure receipt, which binds the backup, the source service, the snapshot and
+ * the closure's identity. The two are cross-checked here rather than trusted
+ * separately: a descriptor whose `size` or `sha256` disagrees with its receipt
+ * describes a closure nobody can restore.
+ */
+export interface ICorestoreDatabaseClosureDescriptor {
+  /** Exact byte length of the closure, as Corestore's `Content-Length` needs it. */
+  size: number;
+  /** Lowercase hex SHA-256 over those exact bytes. */
+  sha256: string;
+  /** Corestore's own receipt for this closure; its identity and integrity authority. */
+  receipt: ICorestoreDatabaseBackupReceipt;
+}
+
+const bareSha256Pattern = /^[a-f0-9]{64}$/;
+
+const isRecord = (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 hasExactKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+): boolean => {
+  const actualKeys = Object.keys(valueArg).sort();
+  const expectedKeys = [...keysArg].sort();
+  return actualKeys.length === expectedKeys.length
+    && actualKeys.every((keyArg, indexArg) => keyArg === expectedKeys[indexArg]);
+};
+
+/**
+ * Validates one closure descriptor and names every reason it is refused.
+ *
+ * Shape and self-consistency only: whether the closure exists, whether the
+ * backup is this cluster's and whether the target database may be replaced are
+ * decisions for the party that holds them. A descriptor that passes here has
+ * claimed none of them. No reason quotes closure bytes, because a reason
+ * travels into logs and the closure is tenant data.
+ */
+export const validateCorestoreDatabaseClosureDescriptor = (
+  valueArg: unknown,
+  pathArg = 'corestore database closure descriptor',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['size', 'sha256', 'receipt'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  const maximumBytes = corestoreDatabaseBackupRuntimeLimits.maximumClosureBytes;
+  if (!Number.isSafeInteger(valueArg.size)
+    || (valueArg.size as number) < 1
+    || (valueArg.size as number) > maximumBytes) {
+    errors.push(`${pathArg} size must be an integer from 1 to ${maximumBytes}`);
+  }
+  if (typeof valueArg.sha256 !== 'string' || !bareSha256Pattern.test(valueArg.sha256)) {
+    errors.push(`${pathArg} sha256 must be a lowercase hex SHA-256 digest`);
+  }
+  let receipt: ICorestoreDatabaseBackupReceipt | undefined;
+  try {
+    receipt = normalizeCorestoreDatabaseBackupReceipt(valueArg.receipt);
+  } catch (error) {
+    // Corestore's own normalizer names the field it refused and never the
+    // material behind it, so its reason is worth more than its class.
+    errors.push(`${pathArg} receipt is not canonical: ${(error as Error).message}`);
+  }
+  if (!receipt || errors.length > 0) {
+    return errors;
+  }
+  if (valueArg.size !== receipt.closure.archiveBytes) {
+    errors.push(
+      `${pathArg} size must equal the ${receipt.closure.archiveBytes} bytes its receipt states`,
+    );
+  }
+  if (valueArg.sha256 !== receipt.closure.sha256) {
+    errors.push(`${pathArg} sha256 must equal the digest its receipt states`);
+  }
+  return errors;
+};

package/ts/runtime.corestore.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import type {
   IActiveSecretRecipientMetadata,
+  ICorestoreDatabaseAllocationReference,
   IIdentityCredential,
   ISecretVersionReference,
 } from './data/index.js';
@@ -1281,14 +1282,12 @@ export const corestoreDatabaseBackupRuntimeLimits = Object.freeze({
   maximumServiceNameBytes: 1024,
 });
 
-export interface ICorestoreDatabaseAllocationReference {
-  purpose: 'scratch-rehearsal';
-  rehearsalId: string;
-  allocationId: string;
-  generation: number;
-  bindingSha256: string;
-  receiptSha256: string;
-}
+/**
+ * Declared in the data tree, because an isolated restore's canonical resource
+ * mappings bind the exact same reference and that tree carries no runtime
+ * import. Re-exported here so this module's readers keep one import site.
+ */
+export type { ICorestoreDatabaseAllocationReference };
 
 export interface ICorestoreDatabaseBackupSnapshotTags {
   corestore: 'resource';

package/ts/runtime.ts

@@ -42,6 +42,7 @@ export * from './runtime.workloadinit.js';
 export * from './runtime.networkprojection.js';
 export * from './runtime.corestore.js';
 export * from './runtime.corestore.databaseexportpackage.js';
+export * from './runtime.corestore.relay.js';
 export * from './runtime.cloudlylegacydeploymentsettlement.js';
 export * from './runtime.cloudlylegacydeploymentsettlement.offlineexport.js';