@serve.zone/interfaces 31.5.0 → 31.7.0

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';