@serve.zone/interfaces 32.57.0 → 32.58.0

package/ts/appstore/versionconfig.ts

@@ -15,8 +15,8 @@
  * `platform.normalizeStorageRequest`), reporting through this module's rejection. What this module
  * adds are the rules a request can only break inside a version config: its class is declared and of
  * its kind, the class backs a declared limit or protection, ids and destinations are used once, the
- * legacy names stay reserved, a backup exclusion names an object-storage request, and the storage
- * feature ids are named.
+ * legacy names stay reserved, a backup exclusion names an object-storage request, a database backup
+ * exclusion names a provisioned database, and the storage feature ids are named.
  */
 import { normalizeServiceAbsolutePath, validateServiceContainerArgs } from '../data/service.js';
 import { normalizeServicePortConfig } from '../data/serviceports.js';
@@ -34,13 +34,16 @@ import { createStorageContractReaders } from '../private/storagecontract.js';
 import type { TObjectStorageDelivery } from '../platform/storage.js';
 import {
   appStoreBackupExclusionLimits,
+  appStoreDatabaseBackupExclusionLimits,
   appStoreStorageFeatureIds,
   validateAppStoreEnvironmentDeclarations,
   validateAppStoreVersionPlatformOidc,
 } from './types.js';
 import type {
   IAppStoreBackupExclusion,
+  IAppStoreDatabaseBackupExclusion,
   IAppStoreVersionConfig,
+  TAppStoreBackupExclusionDatabase,
   TAppStoreStorageRequest,
 } from './types.js';
 
@@ -56,6 +59,7 @@ const versionConfigMemberList = [
   'storageClasses',
   'storageRequests',
   'backupExclusions',
+  'databaseBackupExclusions',
   'publishedPorts',
   'platformRequirements',
   'platformOidc',
@@ -101,6 +105,12 @@ const legacyObjectStorageRequestId = 'legacy-s3';
 const knownStorageFeatureIds: readonly string[] = Object.values(appStoreStorageFeatureIds);
 const platformRequirementKeys = ['mongodb', 's3', 'clickhouse', 'valkey', 'mariadb', 'mail'] as const;
 const controlCharacterPattern = /[\u0000-\u001f\u007f]/;
+/** The C0 and C1 controls and DEL: what the database engine refuses in a namespace component. */
+const collectionNameControlPattern = /[\u0000-\u001f\u007f-\u009f]/;
+/** Each database a version can declare exclusions for, with the platform requirement provisioning it. */
+const backupExclusionDatabaseRequirements: Readonly<Record<TAppStoreBackupExclusionDatabase, 'mongodb'>> = {
+  mongodb: 'mongodb',
+};
 const utf8Encoder = new TextEncoder();
 
 /** Thrown inside this module only; every exported validator answers it as its result. */
@@ -612,6 +622,7 @@ function checkFeatureDeclaration(
   requiresFeaturesArg: unknown,
   explicitRequestsArg: readonly TAppStoreStorageRequest[],
   backupExclusionsArg: readonly IAppStoreBackupExclusion[],
+  databaseBackupExclusionsArg: readonly IAppStoreDatabaseBackupExclusion[],
   labelArg: string,
 ): void {
   const derivedFeatures = new Set<string>();
@@ -628,6 +639,9 @@ function checkFeatureDeclaration(
   if (backupExclusionsArg.length > 0) {
     derivedFeatures.add(appStoreStorageFeatureIds.objectStorageBackupExclusions);
   }
+  if (databaseBackupExclusionsArg.length > 0) {
+    derivedFeatures.add(appStoreStorageFeatureIds.databaseBackupExclusions);
+  }
 
   const declaredEntries = requiresFeaturesArg === undefined
     ? []
@@ -669,6 +683,19 @@ const hasUnpairedSurrogate = (valueArg: string): boolean => {
   return false;
 };
 
+/** An exclusion's `reason`: one trimmed line an operator reads. */
+function checkBackupExclusionReason(valueArg: unknown, maximumLengthArg: number, entryLabelArg: string): string {
+  if (typeof valueArg !== 'string'
+    || valueArg.length === 0
+    || valueArg.length > maximumLengthArg
+    || valueArg.trim() !== valueArg
+    || controlCharacterPattern.test(valueArg)
+    || hasUnpairedSurrogate(valueArg)) {
+    return reject(`Invalid ${entryLabelArg}.reason: must be one trimmed line of 1 to ${maximumLengthArg} characters`);
+  }
+  return valueArg;
+}
+
 /** One object key prefix: a relative key path that names a whole subtree. */
 function checkBackupExclusionKeyPrefix(valueArg: unknown, labelArg: string): string {
   if (typeof valueArg !== 'string') return reject(`Invalid ${labelArg}: expected a string`);
@@ -741,16 +768,99 @@ function checkBackupExclusions(valueArg: unknown, labelArg: string): IAppStoreBa
     previousRequest = storageRequest;
 
     const keyPrefixes = checkBackupExclusionKeyPrefixes(entry.keyPrefixes, `${entryLabel}.keyPrefixes`);
+    return { storageRequest, keyPrefixes, reason: checkBackupExclusionReason(reason, maximumReasonLength, entryLabel) };
+  });
+}
+
+/**
+ * One collection name a database backup exclusion carries: a name the database engine stores
+ * (`database` resources run on NoSQLDB, a MongoDB-compatible engine) that is not a system collection.
+ */
+function checkDatabaseBackupExclusionCollection(valueArg: unknown, labelArg: string): string {
+  const { maximumCollectionNameBytes } = appStoreDatabaseBackupExclusionLimits;
+  if (typeof valueArg !== 'string') return reject(`Invalid ${labelArg}: expected a string`);
+  if (collectionNameControlPattern.test(valueArg) || hasUnpairedSurrogate(valueArg)) {
+    reject(`Invalid ${labelArg}: must not contain a control character or an unpaired surrogate`);
+  }
+  const byteLength = utf8Encoder.encode(valueArg).byteLength;
+  if (byteLength < 1 || byteLength > maximumCollectionNameBytes) {
+    reject(`Invalid ${labelArg}: must be 1 to ${maximumCollectionNameBytes} UTF-8 bytes`);
+  }
+  if (valueArg.startsWith('.')) reject(`Invalid ${labelArg}: must not start with '.'`);
+  if (valueArg.startsWith('system.')) reject(`Invalid ${labelArg}: must not name a 'system.' collection`);
+  if (/[/\\$]/.test(valueArg)) reject(`Invalid ${labelArg}: must not contain '/', '\\' or '$'`);
+  return valueArg;
+}
+
+/**
+ * One exclusion's collection list: 1 to 64 names, strictly increasing.
+ * `validateAppStoreDatabaseBackupExclusionCollections` exports it, so every reader of a collection
+ * list judges it by this one rule.
+ */
+function checkDatabaseBackupExclusionCollections(valueArg: unknown, labelArg: string): string[] {
+  const { maximumCollections } = appStoreDatabaseBackupExclusionLimits;
+  const collectionEntries = readDataElements(valueArg, maximumCollections);
+  if (collectionEntries === null || collectionEntries.length === 0) {
+    return reject(`Invalid ${labelArg}: expected an array of 1 to ${maximumCollections} collection names`);
+  }
+  const collections: string[] = [];
+  collectionEntries.forEach((collectionArg, indexArg) => {
+    const collection = checkDatabaseBackupExclusionCollection(collectionArg, `${labelArg}[${indexArg}]`);
+    const previousCollection = collections[collections.length - 1];
+    if (previousCollection !== undefined && compareWireTokens(previousCollection, collection) >= 0) {
+      reject(`Invalid ${labelArg}: must be strictly increasing`);
+    }
+    collections.push(collection);
+  });
+  return collections;
+}
 
-    if (typeof reason !== 'string'
-      || reason.length === 0
-      || reason.length > maximumReasonLength
-      || reason.trim() !== reason
-      || controlCharacterPattern.test(reason)
-      || hasUnpairedSurrogate(reason)) {
-      reject(`Invalid ${entryLabel}.reason: must be one trimmed line of 1 to ${maximumReasonLength} characters`);
+/**
+ * The members of each database backup exclusion, its collections and the entry order. Whether the
+ * version provisions the database an entry names is judged with its platform requirements
+ * (`checkDatabaseBackupExclusionTargets`).
+ */
+function checkDatabaseBackupExclusions(valueArg: unknown, labelArg: string): IAppStoreDatabaseBackupExclusion[] {
+  if (valueArg === undefined) return [];
+  const { maximumEntries, maximumReasonLength } = appStoreDatabaseBackupExclusionLimits;
+  const entries = readDataElements(valueArg, maximumEntries);
+  if (entries === null || entries.length === 0) {
+    return reject(`Invalid ${labelArg}: databaseBackupExclusions must contain between 1 and ${maximumEntries} entries`);
+  }
+  let previousDatabase: string | null = null;
+  return entries.map((entryArg, indexArg): IAppStoreDatabaseBackupExclusion => {
+    const entryLabel = `${labelArg} databaseBackupExclusions[${indexArg}]`;
+    const entry = readRecord(entryArg, entryLabel);
+    assertExactKeys(entry, ['database', 'collections', 'reason'], entryLabel);
+    const { database } = entry;
+    if (typeof database !== 'string' || !Object.hasOwn(backupExclusionDatabaseRequirements, database)) {
+      return reject(`Invalid ${entryLabel}.database: expected one of ${Object.keys(backupExclusionDatabaseRequirements).join(', ')}`);
+    }
+    if (previousDatabase !== null && compareWireTokens(previousDatabase, database) >= 0) {
+      reject(previousDatabase === database
+        ? `Invalid ${labelArg}: databaseBackupExclusions name database '${database}' more than once`
+        : `Invalid ${labelArg}: databaseBackupExclusions must be in strictly increasing database order`);
+    }
+    previousDatabase = database;
+    return {
+      database: database as TAppStoreBackupExclusionDatabase,
+      collections: checkDatabaseBackupExclusionCollections(entry.collections, `${entryLabel}.collections`),
+      reason: checkBackupExclusionReason(entry.reason, maximumReasonLength, entryLabel),
+    };
+  });
+}
+
+/** Each database backup exclusion names a database the version provisions. */
+function checkDatabaseBackupExclusionTargets(
+  exclusionsArg: readonly IAppStoreDatabaseBackupExclusion[],
+  platformRequirementsArg: Record<string, unknown>,
+  labelArg: string,
+): void {
+  exclusionsArg.forEach((exclusionArg, indexArg) => {
+    const requirement = backupExclusionDatabaseRequirements[exclusionArg.database];
+    if (platformRequirementsArg[requirement] !== true) {
+      reject(`Invalid ${labelArg} databaseBackupExclusions[${indexArg}].database: '${exclusionArg.database}' requires platformRequirements.${requirement}`);
     }
-    return { storageRequest, keyPrefixes, reason };
   });
 }
 
@@ -842,7 +952,15 @@ function checkStorage(configArg: Record<string, unknown>, labelArg: string): voi
     labelArg,
   );
   const backupExclusions = checkBackupExclusions(configArg.backupExclusions, labelArg);
-  checkFeatureDeclaration(configArg.requiresFeatures, explicitRequests, backupExclusions, labelArg);
+  const databaseBackupExclusions = checkDatabaseBackupExclusions(configArg.databaseBackupExclusions, labelArg);
+  checkFeatureDeclaration(
+    configArg.requiresFeatures,
+    explicitRequests,
+    backupExclusions,
+    databaseBackupExclusions,
+    labelArg,
+  );
+  checkDatabaseBackupExclusionTargets(databaseBackupExclusions, platformRequirements, labelArg);
   const legacyS3 = platformRequirements.s3 === true;
   if (legacyS3 && explicitRequests.some((requestArg) => requestArg.kind === 'objectStorage')) {
     reject(`Invalid ${labelArg}: platformRequirements.s3 cannot coexist with explicit objectStorage requests`);
@@ -923,8 +1041,9 @@ export const validateAppStorePublishedPorts = (publishedPortsArg: unknown, label
 
 /**
  * The config's member set and its storage: legacy `volumes`, `storageClasses`, `storageRequests`,
- * `platformRequirements`, `backupExclusions`, the storage feature ids `requiresFeatures` must name,
- * and every environment, secret-file and mount destination being used once.
+ * `platformRequirements`, `backupExclusions`, `databaseBackupExclusions`, the storage feature ids
+ * `requiresFeatures` must name, and every environment, secret-file and mount destination being used
+ * once.
  */
 export const validateAppStoreVersionStorage = (configArg: unknown, labelArg = defaultLabel): string[] =>
   firstRejection(() => checkStorage(readConfig(configArg, labelArg), labelArg));
@@ -941,6 +1060,18 @@ export const validateAppStoreBackupExclusionKeyPrefixes = (
   labelArg = 'keyPrefixes',
 ): string[] => firstRejection(() => checkBackupExclusionKeyPrefixes(valueArg, labelArg));
 
+/**
+ * One database backup exclusion's `collections`, the rule `validateAppStoreVersionStorage` applies
+ * to each `IAppStoreDatabaseBackupExclusion`: 1 to 64 names in strictly increasing UTF-16
+ * code-unit order, each 1 to 128 UTF-8 bytes, not starting with `.` or `system.`, without `/`,
+ * `\`, `$`, a control character or an unpaired surrogate. A reader of a list that carries such
+ * names elsewhere, such as Corestore's export request or a backup's provenance, judges it here.
+ */
+export const validateAppStoreDatabaseBackupExclusionCollections = (
+  valueArg: unknown,
+  labelArg = 'collections',
+): string[] => firstRejection(() => checkDatabaseBackupExclusionCollections(valueArg, labelArg));
+
 /**
  * Every member rule of a version config, in the order a host applies them: image, port model,
  * container arguments, environment declarations, storage, platform OIDC, published ports.