@serve.zone/interfaces 32.34.0 → 32.36.0

package/ts/data/deploymentlegacyimport.ts

@@ -0,0 +1,371 @@
+import type {
+  TImmutableContainerPlatform,
+  TOciManifestMediaType,
+  TSha256Digest,
+} from './immutableimage.js';
+import { normalizeSha256Digest } from './immutableimage.js';
+import { hasExactKeys, isPlainRecord } from '../private/dataproperties.js';
+
+/**
+ * Legacy image import: a greenfield deployment whose image is the one a legacy `deployOnPush`
+ * service already runs, instead of one built from a source revision.
+ *
+ * A legacy service without deployable source still has an image in Cloudly's registry and, until
+ * its runtime is frozen, healthy replicas running it. An administrator captures that fact once as
+ * a {@link ILegacyServiceRuntimeAttestation} while the replicas still run. A greenfield successor
+ * reservation names the attestation in `legacyImport` instead of a `sourceRevision`, and Cloudly
+ * then imports the attested image into the successor's own repository and release tag itself:
+ * the bytes never leave the registry and the release records that it was imported, not built.
+ *
+ * Deployment roots are indexes. An attested root that already is an index is imported as it is. A
+ * root that is one platform manifest is imported under an index whose only descriptor is that
+ * manifest, in the manifest's own family — a Docker manifest list around a Docker manifest, an OCI
+ * index around an OCI manifest — so the platform manifest stays byte-identical and its digest is
+ * still the one the legacy runtime ran. The attestation states everything that descriptor needs.
+ */
+
+/** The media types a legacy image's per-platform manifest can carry. */
+export type TLegacyImagePlatformManifestMediaType =
+  | 'application/vnd.oci.image.manifest.v1+json'
+  | 'application/vnd.docker.distribution.manifest.v2+json';
+
+/** The index media type of the family a platform manifest belongs to. */
+export type TLegacyImageImportIndexMediaType =
+  | 'application/vnd.oci.image.index.v1+json'
+  | 'application/vnd.docker.distribution.manifest.list.v2+json';
+
+/** One platform manifest of a legacy image, as Cloudly read it from its own registry. */
+export interface ILegacyImagePlatformManifest {
+  platform: TImmutableContainerPlatform;
+  manifestDigest: TSha256Digest;
+  manifestMediaType: TLegacyImagePlatformManifestMediaType;
+  /** Exact byte length of the platform manifest, which an index descriptor states. */
+  manifestSize: number;
+  imageConfigDigest: TSha256Digest;
+}
+
+/** The registry image a legacy service ran, under the mutable tag it was deployed from. */
+export interface ILegacyServiceImageSource {
+  registryHost: string;
+  repository: string;
+  /** The mutable tag the legacy service was deployed from, `latest` included. */
+  tag: string;
+  /** Digest of the root the tag named: a single platform manifest or an index. */
+  rootDigest: TSha256Digest;
+  rootMediaType: TOciManifestMediaType;
+  /**
+   * The runnable Linux platforms the root carries, sorted by platform. A single-manifest root
+   * carries exactly one, whose manifest is the root itself.
+   */
+  platforms: ILegacyImagePlatformManifest[];
+}
+
+/** One healthy replica of the legacy service, observed running the attested digest. */
+export interface ILegacyServiceRuntimeTaskAttestation {
+  deploymentId: string;
+  nodeName: string;
+  observedDigest: TSha256Digest;
+}
+
+/**
+ * Durable evidence, captured by an administrator while the legacy runtime still ran, that every
+ * required replica of a legacy service was healthy and ran exactly the registry root it names.
+ *
+ * Cloudly writes one and never changes it. A capture only succeeds on complete evidence, so a
+ * stored attestation is by construction one whose runtime digest is its source root digest.
+ */
+export interface ILegacyServiceRuntimeAttestation {
+  id: string;
+  data: {
+    legacyServiceId: string;
+    organizationId: string;
+    source: ILegacyServiceImageSource;
+    runtime: {
+      requiredReplicaCount: number;
+      healthyReplicaCount: number;
+      runtimeDigest: TSha256Digest;
+      /** Sorted by deploymentId, one per required replica. */
+      tasks: ILegacyServiceRuntimeTaskAttestation[];
+    };
+    capturedByUserId: string;
+    capturedAt: number;
+  };
+}
+
+/**
+ * What a legacy-import reservation names in place of a source revision: the legacy service, the
+ * attestation Cloudly holds for it, and the root digest the deployer asserts that attestation
+ * carries.
+ */
+export interface ILegacyImageImportReference {
+  legacyServiceId: string;
+  attestationId: string;
+  sourceRootDigest: TSha256Digest;
+}
+
+const identifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+/** An OCI tag, the mutable `latest` included: the source tag is whatever the legacy service ran. */
+const ociTagRegex = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
+const registryHostRegex = /^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?(?::[0-9]{1,5})?$/;
+const repositoryRegex = /^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*$/;
+const maximumManifestSize = 4 * 1024 * 1024;
+const maximumReplicaCount = 64;
+
+const legacyImagePlatformManifestMediaTypes: readonly TLegacyImagePlatformManifestMediaType[] = [
+  'application/vnd.oci.image.manifest.v1+json',
+  'application/vnd.docker.distribution.manifest.v2+json',
+];
+const legacyImageImportIndexMediaTypes: readonly TLegacyImageImportIndexMediaType[] = [
+  'application/vnd.oci.image.index.v1+json',
+  'application/vnd.docker.distribution.manifest.list.v2+json',
+];
+const legacyImagePlatforms: readonly TImmutableContainerPlatform[] = ['linux/amd64', 'linux/arm64'];
+
+const isIdentifier = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && identifierRegex.test(valueArg)
+);
+
+const isCanonicalDigest = (valueArg: unknown): valueArg is TSha256Digest => (
+  typeof valueArg === 'string' && normalizeSha256Digest(valueArg) === valueArg
+);
+
+const isPositiveSafeInteger = (valueArg: unknown, maximumArg: number): valueArg is number => (
+  typeof valueArg === 'number'
+  && Number.isSafeInteger(valueArg)
+  && valueArg >= 1
+  && valueArg <= maximumArg
+);
+
+/** True when a media type names a single platform manifest rather than an index. */
+export const isLegacyImagePlatformManifestMediaType = (
+  valueArg: unknown,
+): valueArg is TLegacyImagePlatformManifestMediaType => (
+  legacyImagePlatformManifestMediaTypes.some((mediaTypeArg) => mediaTypeArg === valueArg)
+);
+
+/** True when a media type names an index of either family. */
+export const isLegacyImageImportIndexMediaType = (
+  valueArg: unknown,
+): valueArg is TLegacyImageImportIndexMediaType => (
+  legacyImageImportIndexMediaTypes.some((mediaTypeArg) => mediaTypeArg === valueArg)
+);
+
+export const validateLegacyImageImportReference = (referenceArg: unknown): string[] => {
+  if (!isPlainRecord(referenceArg)) return ['legacyImport must be an object'];
+  const errors: string[] = [];
+  if (!hasExactKeys(referenceArg, ['legacyServiceId', 'attestationId', 'sourceRootDigest'])) {
+    errors.push('legacyImport must use its exact schema');
+  }
+  if (!isIdentifier(referenceArg.legacyServiceId)) {
+    errors.push('legacyImport.legacyServiceId must be a bounded canonical identifier');
+  }
+  if (!isIdentifier(referenceArg.attestationId)) {
+    errors.push('legacyImport.attestationId must be a bounded canonical identifier');
+  }
+  if (!isCanonicalDigest(referenceArg.sourceRootDigest)) {
+    errors.push('legacyImport.sourceRootDigest must be a canonical sha256 digest');
+  }
+  return errors;
+};
+
+const validatePlatformManifest = (
+  manifestArg: unknown,
+  indexArg: number,
+): string[] => {
+  const label = `source.platforms[${indexArg}]`;
+  if (!isPlainRecord(manifestArg)) return [`${label} must be an object`];
+  const errors: string[] = [];
+  if (!hasExactKeys(manifestArg, [
+    'platform',
+    'manifestDigest',
+    'manifestMediaType',
+    'manifestSize',
+    'imageConfigDigest',
+  ])) {
+    errors.push(`${label} must use its exact schema`);
+  }
+  if (!legacyImagePlatforms.some((platformArg) => platformArg === manifestArg.platform)) {
+    errors.push(`${label}.platform must be linux/amd64 or linux/arm64`);
+  }
+  if (!isCanonicalDigest(manifestArg.manifestDigest)) {
+    errors.push(`${label}.manifestDigest must be a canonical sha256 digest`);
+  }
+  if (!isLegacyImagePlatformManifestMediaType(manifestArg.manifestMediaType)) {
+    errors.push(`${label}.manifestMediaType must name an OCI or Docker image manifest`);
+  }
+  if (!isPositiveSafeInteger(manifestArg.manifestSize, maximumManifestSize)) {
+    errors.push(`${label}.manifestSize must be a positive bounded byte length`);
+  }
+  if (!isCanonicalDigest(manifestArg.imageConfigDigest)) {
+    errors.push(`${label}.imageConfigDigest must be a canonical sha256 digest`);
+  }
+  return errors;
+};
+
+const validateImageSource = (sourceArg: unknown): string[] => {
+  if (!isPlainRecord(sourceArg)) return ['source must be an object'];
+  const errors: string[] = [];
+  if (!hasExactKeys(sourceArg, [
+    'registryHost',
+    'repository',
+    'tag',
+    'rootDigest',
+    'rootMediaType',
+    'platforms',
+  ])) {
+    errors.push('source must use its exact schema');
+  }
+  if (typeof sourceArg.registryHost !== 'string' || !registryHostRegex.test(sourceArg.registryHost)) {
+    errors.push('source.registryHost must be a canonical registry host');
+  }
+  if (typeof sourceArg.repository !== 'string'
+    || sourceArg.repository.length > 255
+    || !repositoryRegex.test(sourceArg.repository)) {
+    errors.push('source.repository must be a canonical OCI repository name');
+  }
+  if (typeof sourceArg.tag !== 'string' || !ociTagRegex.test(sourceArg.tag)) {
+    errors.push('source.tag must be an OCI tag');
+  }
+  if (!isCanonicalDigest(sourceArg.rootDigest)) {
+    errors.push('source.rootDigest must be a canonical sha256 digest');
+  }
+  const rootIsManifest = isLegacyImagePlatformManifestMediaType(sourceArg.rootMediaType);
+  const rootIsIndex = isLegacyImageImportIndexMediaType(sourceArg.rootMediaType);
+  if (!rootIsManifest && !rootIsIndex) {
+    errors.push('source.rootMediaType must name an OCI or Docker manifest or index');
+  }
+  if (!Array.isArray(sourceArg.platforms)
+    || sourceArg.platforms.length < 1
+    || sourceArg.platforms.length > legacyImagePlatforms.length) {
+    errors.push('source.platforms must carry one or two runnable Linux platforms');
+    return errors;
+  }
+  const platforms = sourceArg.platforms as unknown[];
+  platforms.forEach((manifestArg, indexArg) => {
+    errors.push(...validatePlatformManifest(manifestArg, indexArg));
+  });
+  const platformNames = platforms.map((manifestArg) => (
+    isPlainRecord(manifestArg) ? manifestArg.platform : undefined
+  ));
+  const sortedPlatformNames = legacyImagePlatforms.filter((platformArg) => (
+    platformNames.includes(platformArg)
+  ));
+  if (JSON.stringify(platformNames) !== JSON.stringify(sortedPlatformNames)) {
+    errors.push('source.platforms must be unique and sorted by platform');
+  }
+  if (rootIsManifest) {
+    const onlyPlatform = platforms[0];
+    if (platforms.length !== 1
+      || !isPlainRecord(onlyPlatform)
+      || onlyPlatform.manifestDigest !== sourceArg.rootDigest
+      || onlyPlatform.manifestMediaType !== sourceArg.rootMediaType) {
+      errors.push('a single-manifest source root must be its own one platform manifest');
+    }
+  }
+  if (rootIsIndex && platforms.some((manifestArg) => (
+    isPlainRecord(manifestArg) && manifestArg.manifestDigest === sourceArg.rootDigest
+  ))) {
+    errors.push('an index source root cannot also be one of its platform manifests');
+  }
+  return errors;
+};
+
+const validateRuntime = (runtimeArg: unknown, rootDigestArg: unknown): string[] => {
+  if (!isPlainRecord(runtimeArg)) return ['runtime must be an object'];
+  const errors: string[] = [];
+  if (!hasExactKeys(runtimeArg, [
+    'requiredReplicaCount',
+    'healthyReplicaCount',
+    'runtimeDigest',
+    'tasks',
+  ])) {
+    errors.push('runtime must use its exact schema');
+  }
+  if (!isPositiveSafeInteger(runtimeArg.requiredReplicaCount, maximumReplicaCount)) {
+    errors.push('runtime.requiredReplicaCount must be a positive bounded replica count');
+  }
+  if (runtimeArg.healthyReplicaCount !== runtimeArg.requiredReplicaCount) {
+    errors.push('runtime.healthyReplicaCount must equal the required replica count');
+  }
+  if (!isCanonicalDigest(runtimeArg.runtimeDigest)) {
+    errors.push('runtime.runtimeDigest must be a canonical sha256 digest');
+  } else if (runtimeArg.runtimeDigest !== rootDigestArg) {
+    errors.push('runtime.runtimeDigest must be the attested source root digest');
+  }
+  if (!Array.isArray(runtimeArg.tasks) || runtimeArg.tasks.length !== runtimeArg.requiredReplicaCount) {
+    errors.push('runtime.tasks must hold exactly one task per required replica');
+    return errors;
+  }
+  const tasks = runtimeArg.tasks as unknown[];
+  tasks.forEach((taskArg, indexArg) => {
+    const label = `runtime.tasks[${indexArg}]`;
+    if (!isPlainRecord(taskArg)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+    if (!hasExactKeys(taskArg, ['deploymentId', 'nodeName', 'observedDigest'])) {
+      errors.push(`${label} must use its exact schema`);
+    }
+    if (!isIdentifier(taskArg.deploymentId)) {
+      errors.push(`${label}.deploymentId must be a bounded canonical identifier`);
+    }
+    if (typeof taskArg.nodeName !== 'string' || !taskArg.nodeName || taskArg.nodeName.length > 253) {
+      errors.push(`${label}.nodeName must be a bounded non-empty name`);
+    }
+    if (taskArg.observedDigest !== runtimeArg.runtimeDigest) {
+      errors.push(`${label}.observedDigest must be the attested runtime digest`);
+    }
+  });
+  const deploymentIds = tasks.map((taskArg) => (
+    isPlainRecord(taskArg) ? taskArg.deploymentId : undefined
+  ));
+  const sortedDeploymentIds = deploymentIds
+    .filter((idArg): idArg is string => typeof idArg === 'string')
+    .sort();
+  if (new Set(deploymentIds).size !== deploymentIds.length
+    || JSON.stringify(deploymentIds) !== JSON.stringify(sortedDeploymentIds)) {
+    errors.push('runtime.tasks must be unique and sorted by deploymentId');
+  }
+  return errors;
+};
+
+export const validateLegacyServiceRuntimeAttestation = (attestationArg: unknown): string[] => {
+  if (!isPlainRecord(attestationArg)) return ['attestation must be an object'];
+  const errors: string[] = [];
+  if (!hasExactKeys(attestationArg, ['id', 'data'])) {
+    errors.push('attestation must use its exact schema');
+  }
+  if (!isIdentifier(attestationArg.id)) {
+    errors.push('id must be a bounded canonical identifier');
+  }
+  const data = attestationArg.data;
+  if (!isPlainRecord(data)) return [...errors, 'data must be an object'];
+  if (!hasExactKeys(data, [
+    'legacyServiceId',
+    'organizationId',
+    'source',
+    'runtime',
+    'capturedByUserId',
+    'capturedAt',
+  ])) {
+    errors.push('data must use its exact schema');
+  }
+  if (!isIdentifier(data.legacyServiceId)) {
+    errors.push('legacyServiceId must be a bounded canonical identifier');
+  }
+  if (!isIdentifier(data.organizationId)) {
+    errors.push('organizationId must be a bounded canonical identifier');
+  }
+  if (!isIdentifier(data.capturedByUserId)) {
+    errors.push('capturedByUserId must be a bounded canonical identifier');
+  }
+  if (!isPositiveSafeInteger(data.capturedAt, Number.MAX_SAFE_INTEGER)) {
+    errors.push('capturedAt must be a positive timestamp');
+  }
+  errors.push(...validateImageSource(data.source));
+  errors.push(...validateRuntime(
+    data.runtime,
+    isPlainRecord(data.source) ? data.source.rootDigest : undefined,
+  ));
+  return errors;
+};

package/ts/data/deploymentoperation.ts

@@ -2,6 +2,8 @@ import type { IDeploymentPreflightProposedConfiguration, IDeploymentPreflightRun
 import type { IGatewayRouteDnsResult } from './gateway.js';
 import type { IImageRolloutStatus, IImmutableImageDeploymentPlan, TSha256Digest } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
+import type { ILegacyImageImportReference } from './deploymentlegacyimport.js';
+import { validateLegacyImageImportReference } from './deploymentlegacyimport.js';
 import type { IRegistryTarget } from './registry.js';
 import { hasExactKeys } from '../private/dataproperties.js';
 import { normalizeServiceAbsolutePath, validateServiceContainerArgs } from './service.js';
@@ -14,7 +16,6 @@ interface IDeploymentReservationInputBase {
   organizationId: string;
   serviceId: string;
   idempotencyKey: string;
-  sourceRevision: string;
   version: string;
   intentDigest: TSha256Digest;
   proposedConfiguration: IDeploymentPreflightProposedConfiguration;
@@ -22,15 +23,38 @@ interface IDeploymentReservationInputBase {
   routes: IDeploymentRouteRequest[];
 }
 
+/** A deployment whose image its deployer builds and pushes from one source revision. */
+interface ISourceDeploymentOrigin {
+  sourceRevision: string;
+  legacyImport?: never;
+}
+
+/**
+ * A greenfield deployment whose image Cloudly imports from an attested legacy service instead:
+ * there is no source revision, so none is stated.
+ */
+interface ILegacyImportDeploymentOrigin {
+  legacyImport: ILegacyImageImportReference;
+  sourceRevision?: never;
+}
+
 export interface IExistingServiceDeploymentReservationInput
-extends IDeploymentReservationInputBase {
+extends IDeploymentReservationInputBase, ISourceDeploymentOrigin {
   mode: 'existing-service';
   expectedRolloutGeneration: number;
   expectedCurrentRolloutId?: string;
 }
 
 export interface IGreenfieldServiceDeploymentReservationInput
-extends IDeploymentReservationInputBase {
+extends IDeploymentReservationInputBase, ISourceDeploymentOrigin {
+  mode: 'greenfield';
+  expectedRolloutGeneration?: never;
+  expectedCurrentRolloutId?: never;
+}
+
+/** A greenfield successor slot whose image is a legacy service's attested image. */
+export interface ILegacyImportServiceDeploymentReservationInput
+extends IDeploymentReservationInputBase, ILegacyImportDeploymentOrigin {
   mode: 'greenfield';
   expectedRolloutGeneration?: never;
   expectedCurrentRolloutId?: never;
@@ -38,7 +62,8 @@ extends IDeploymentReservationInputBase {
 
 export type IDeploymentReservationInput =
   | IExistingServiceDeploymentReservationInput
-  | IGreenfieldServiceDeploymentReservationInput;
+  | IGreenfieldServiceDeploymentReservationInput
+  | ILegacyImportServiceDeploymentReservationInput;
 
 export type TDeploymentOperationState =
   | 'reserving'
@@ -240,7 +265,15 @@ export const validateDeploymentReservationInput = (inputArg: unknown): string[]
       errors.push(`${field} must be a bounded canonical identifier`);
     }
   }
-  if (typeof inputArg.sourceRevision !== 'string'
+  if (inputArg.legacyImport !== undefined) {
+    errors.push(...validateLegacyImageImportReference(inputArg.legacyImport));
+    if (inputArg.mode !== 'greenfield') {
+      errors.push('a legacy import reserves a greenfield successor');
+    }
+    if (inputArg.sourceRevision !== undefined) {
+      errors.push('a legacy import has no source revision');
+    }
+  } else if (typeof inputArg.sourceRevision !== 'string'
     || !fullGitRevisionRegex.test(inputArg.sourceRevision)) {
     errors.push('sourceRevision must be a full lowercase git revision');
   }
@@ -394,40 +427,51 @@ export interface IDeploymentOperationFailure {
 export interface IServiceDeploymentOperation {
   id: string;
   revision: number;
-  data: {
-    mode: TDeploymentOperationMode;
-    organizationId: string;
-    serviceId: string;
-    actorUserId: string;
-    idempotencyKey: string;
-    requestDigest: TSha256Digest;
-    sourceRevision: string;
-    version: string;
-    intentDigest: TSha256Digest;
-    configurationDigest: TSha256Digest;
-    proposedConfiguration: IDeploymentPreflightProposedConfiguration;
-    namespace: string;
-    registryTarget: IRegistryTarget;
-    releaseTag: string;
-    routes: IDeploymentRouteRequest[];
-    claimKeys: string[];
-    state: TDeploymentOperationState;
-    releaseId?: string;
-    registryRootDigest?: TSha256Digest;
-    rolloutId?: string;
-    rolloutGeneration?: number;
-    routeGeneration?: number;
-    routeVerification?: IDeploymentRouteVerificationEvidence[];
-    /**
-     * Most recent failure record. Set when the operation fails and retained
-     * as audit history through 'cleaning' and 'cleaned'; cleared only by a
-     * forward transition such as a successful retry. A populated failure does
-     * therefore NOT imply state === 'failed'.
-     */
-    failure?: IDeploymentOperationFailure;
-    createdAt: number;
-    updatedAt: number;
-  };
+  data: IServiceDeploymentOperationData;
+}
+
+/**
+ * An operation's durable state. It states where its image comes from exactly as its reservation
+ * did: a `sourceRevision` for an image its deployer builds, or a `legacyImport` (greenfield only)
+ * for a legacy service's attested image Cloudly imports.
+ */
+export type IServiceDeploymentOperationData = IServiceDeploymentOperationStateData & (
+  | ISourceDeploymentOrigin
+  | ILegacyImportDeploymentOrigin
+);
+
+interface IServiceDeploymentOperationStateData {
+  mode: TDeploymentOperationMode;
+  organizationId: string;
+  serviceId: string;
+  actorUserId: string;
+  idempotencyKey: string;
+  requestDigest: TSha256Digest;
+  version: string;
+  intentDigest: TSha256Digest;
+  configurationDigest: TSha256Digest;
+  proposedConfiguration: IDeploymentPreflightProposedConfiguration;
+  namespace: string;
+  registryTarget: IRegistryTarget;
+  releaseTag: string;
+  routes: IDeploymentRouteRequest[];
+  claimKeys: string[];
+  state: TDeploymentOperationState;
+  releaseId?: string;
+  registryRootDigest?: TSha256Digest;
+  rolloutId?: string;
+  rolloutGeneration?: number;
+  routeGeneration?: number;
+  routeVerification?: IDeploymentRouteVerificationEvidence[];
+  /**
+   * Most recent failure record. Set when the operation fails and retained
+   * as audit history through 'cleaning' and 'cleaned'; cleared only by a
+   * forward transition such as a successful retry. A populated failure does
+   * therefore NOT imply state === 'failed'.
+   */
+  failure?: IDeploymentOperationFailure;
+  createdAt: number;
+  updatedAt: number;
 }
 
 export interface IServiceDeploymentStatus {