@serve.zone/interfaces 14.0.0 → 16.0.0

package/ts/data/deploymentadoption.ts

@@ -0,0 +1,445 @@
+import type {
+  IDeploymentPreflightRuntimeTask,
+  IOciPlatformDescriptorSummary,
+} from './deploymentpreflight.js';
+import type {
+  IImmutableImageDeploymentPlan,
+  IImmutableImageTargetScope,
+  TOciManifestMediaType,
+  TSha256Digest,
+} from './immutableimage.js';
+import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
+import type { IRegistryTarget } from './registry.js';
+
+export type TServiceDeploymentAdoptionDecision = 'GO' | 'NO-GO';
+
+/**
+ * Canonical sha256 hash of the complete adoption preflight snapshot. It is a
+ * state/TOCTOU fence and must never be substituted with the OCI image digest.
+ */
+export type TServiceDeploymentAdoptionDigest = TSha256Digest & {
+  readonly __serviceDeploymentAdoptionDigest: unique symbol;
+};
+
+export type TServiceDeploymentAdoptionBlockerCode =
+  | 'INVALID_REQUEST'
+  | 'AUTHORIZATION_MISSING'
+  | 'SERVICE_NOT_FOUND'
+  | 'SERVICE_OWNERSHIP_MISMATCH'
+  | 'SERVICE_ALREADY_IMMUTABLE'
+  | 'SERVICE_STATE_CONFLICT'
+  | 'REGISTRY_TARGET_MISSING'
+  | 'REGISTRY_REFERENCE_INVALID'
+  | 'REGISTRY_DIGEST_MISSING'
+  | 'OCI_INDEX_REQUIRED'
+  | 'OCI_PLATFORM_MISSING'
+  | 'RELEASE_NOT_FOUND'
+  | 'RELEASE_TAG_AMBIGUOUS'
+  | 'TARGET_SCOPE_UNAVAILABLE'
+  | 'RUNTIME_ATTESTATION_INCOMPLETE'
+  | 'RUNTIME_DIGEST_MISMATCH';
+
+export interface IServiceDeploymentAdoptionBlocker {
+  code: TServiceDeploymentAdoptionBlockerCode;
+  message: string;
+}
+
+export interface IServiceDeploymentAdoptionPreflightInput {
+  requestId: string;
+  organizationId: string;
+  serviceId: string;
+}
+
+export interface IServiceDeploymentAdoptionInput
+extends IServiceDeploymentAdoptionPreflightInput {
+  idempotencyKey: string;
+  expectedAdoptionDigest: TServiceDeploymentAdoptionDigest;
+}
+
+interface IServiceDeploymentAdoptionReportBase {
+  schemaVersion: 1;
+  mutationPerformed: false;
+  requestId: string;
+  generatedAt: number;
+  runtimeAttestation: {
+    requiredReplicaCount: number;
+    observedReplicaCount: number;
+    healthyReplicaCount: number;
+    observedDigestReplicaCount: number;
+    observedDigestConsistent: boolean;
+  };
+}
+
+interface IServiceDeploymentAdoptionServiceSnapshot {
+  organizationId: string;
+  serviceId: string;
+  serviceName: string;
+  imageId: string;
+  deployOnPush: boolean;
+  immutableImageRequired: boolean;
+  configuredReference: string;
+  registryTarget: IRegistryTarget;
+}
+
+interface IServiceDeploymentAdoptionRegistrySnapshot {
+  tag?: string;
+  digest?: TSha256Digest;
+  mediaType?: TOciManifestMediaType;
+  platforms: IOciPlatformDescriptorSummary[];
+  releaseId?: string;
+  releaseTag?: string;
+}
+
+export interface IServiceDeploymentAdoptionGoReport
+extends IServiceDeploymentAdoptionReportBase {
+  decision: 'GO';
+  service: IServiceDeploymentAdoptionServiceSnapshot & {
+    deployOnPush: true;
+    immutableImageRequired: false;
+  };
+  registry: IServiceDeploymentAdoptionRegistrySnapshot & {
+    tag: string;
+    digest: TSha256Digest;
+    mediaType:
+      | 'application/vnd.oci.image.index.v1+json'
+      | 'application/vnd.docker.distribution.manifest.list.v2+json';
+    platforms: [IOciPlatformDescriptorSummary, ...IOciPlatformDescriptorSummary[]];
+    releaseId: string;
+    releaseTag: string;
+  };
+  runtimeTasks: [IDeploymentPreflightRuntimeTask, ...IDeploymentPreflightRuntimeTask[]];
+  targetScope: IImmutableImageTargetScope;
+  adoptionDigest: TServiceDeploymentAdoptionDigest;
+  blockers: [];
+}
+
+export interface IServiceDeploymentAdoptionNoGoReport
+extends IServiceDeploymentAdoptionReportBase {
+  decision: 'NO-GO';
+  service?: IServiceDeploymentAdoptionServiceSnapshot;
+  registry: IServiceDeploymentAdoptionRegistrySnapshot;
+  runtimeTasks: IDeploymentPreflightRuntimeTask[];
+  targetScope?: IImmutableImageTargetScope;
+  adoptionDigest?: never;
+  blockers: [IServiceDeploymentAdoptionBlocker, ...IServiceDeploymentAdoptionBlocker[]];
+}
+
+export type IServiceDeploymentAdoptionReport =
+  | IServiceDeploymentAdoptionGoReport
+  | IServiceDeploymentAdoptionNoGoReport;
+
+export interface IServiceDeploymentAdoptionResult {
+  adoptionId: string;
+  adoptionDigest: TServiceDeploymentAdoptionDigest;
+  idempotentReplay: boolean;
+  plan: IImmutableImageDeploymentPlan;
+}
+
+const boundaryIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const indexMediaTypes = new Set<TOciManifestMediaType>([
+  'application/vnd.oci.image.index.v1+json',
+  'application/vnd.docker.distribution.manifest.list.v2+json',
+]);
+const adoptionBlockerCodes = new Set<TServiceDeploymentAdoptionBlockerCode>([
+  'INVALID_REQUEST',
+  'AUTHORIZATION_MISSING',
+  'SERVICE_NOT_FOUND',
+  'SERVICE_OWNERSHIP_MISMATCH',
+  'SERVICE_ALREADY_IMMUTABLE',
+  'SERVICE_STATE_CONFLICT',
+  'REGISTRY_TARGET_MISSING',
+  'REGISTRY_REFERENCE_INVALID',
+  'REGISTRY_DIGEST_MISSING',
+  'OCI_INDEX_REQUIRED',
+  'OCI_PLATFORM_MISSING',
+  'RELEASE_NOT_FOUND',
+  'RELEASE_TAG_AMBIGUOUS',
+  'TARGET_SCOPE_UNAVAILABLE',
+  'RUNTIME_ATTESTATION_INCOMPLETE',
+  'RUNTIME_DIGEST_MISMATCH',
+]);
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg);
+
+const isBoundedIdentifier = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && boundaryIdentifierRegex.test(valueArg);
+
+const isCanonicalDigest = (valueArg: unknown): valueArg is TSha256Digest =>
+  Boolean(normalizeSha256Digest(valueArg)) && normalizeSha256Digest(valueArg) === valueArg;
+
+const isNonNegativeInteger = (valueArg: unknown): valueArg is number =>
+  Number.isSafeInteger(valueArg) && (valueArg as number) >= 0;
+
+export const validateServiceDeploymentAdoptionPreflightInput = (
+  inputArg: unknown,
+): string[] => {
+  if (!isRecord(inputArg)) return ['adoption preflight input must be an object'];
+  const errors: string[] = [];
+  if (!isBoundedIdentifier(inputArg.requestId)) {
+    errors.push('requestId must be a bounded canonical identifier');
+  }
+  for (const key of ['organizationId', 'serviceId'] as const) {
+    if (!isBoundedIdentifier(inputArg[key])) {
+      errors.push(`${key} must be a bounded canonical identifier`);
+    }
+  }
+  return errors;
+};
+
+export const validateServiceDeploymentAdoptionInput = (inputArg: unknown): string[] => {
+  const errors = validateServiceDeploymentAdoptionPreflightInput(inputArg);
+  if (!isRecord(inputArg)) return errors;
+  if (!isBoundedIdentifier(inputArg.idempotencyKey)) {
+    errors.push('idempotencyKey must be a bounded canonical identifier');
+  }
+  if (!isCanonicalDigest(inputArg.expectedAdoptionDigest)) {
+    errors.push('expectedAdoptionDigest must be a canonical sha256 digest');
+  }
+  return errors;
+};
+
+export const validateServiceDeploymentAdoptionReport = (reportArg: unknown): string[] => {
+  if (!isRecord(reportArg)) return ['adoption report must be an object'];
+  const errors: string[] = [];
+  if (reportArg.schemaVersion !== 1) errors.push('schemaVersion must be 1');
+  if (reportArg.mutationPerformed !== false) {
+    errors.push('adoption preflight must be mutation-free');
+  }
+  if (!isBoundedIdentifier(reportArg.requestId)) {
+    errors.push('requestId must be a bounded canonical identifier');
+  }
+  if (!isNonNegativeInteger(reportArg.generatedAt)) {
+    errors.push('generatedAt must be a non-negative integer');
+  }
+  if (reportArg.decision !== 'GO' && reportArg.decision !== 'NO-GO') {
+    errors.push('decision must be GO or NO-GO');
+  }
+
+  const attestation = reportArg.runtimeAttestation;
+  if (!isRecord(attestation)) {
+    errors.push('runtimeAttestation must be an object');
+  } else {
+    for (const key of [
+      'requiredReplicaCount',
+      'observedReplicaCount',
+      'healthyReplicaCount',
+      'observedDigestReplicaCount',
+    ] as const) {
+      if (!isNonNegativeInteger(attestation[key])) {
+        errors.push(`runtimeAttestation.${key} must be a non-negative integer`);
+      }
+    }
+    if (typeof attestation.observedDigestConsistent !== 'boolean') {
+      errors.push('runtimeAttestation.observedDigestConsistent must be boolean');
+    }
+  }
+
+  const blockers = reportArg.blockers;
+  if (!Array.isArray(blockers)) {
+    errors.push('blockers must be an array');
+  } else {
+    for (const blocker of blockers) {
+      if (!isRecord(blocker)
+        || !adoptionBlockerCodes.has(blocker.code as TServiceDeploymentAdoptionBlockerCode)
+        || typeof blocker.message !== 'string'
+        || !blocker.message.trim()) {
+        errors.push('each blocker must contain a supported code and non-empty message');
+        break;
+      }
+    }
+  }
+
+  if (reportArg.decision === 'NO-GO') {
+    if (Array.isArray(blockers) && blockers.length === 0) {
+      errors.push('a NO-GO report must contain at least one blocker');
+    }
+    if (reportArg.adoptionDigest !== undefined) {
+      errors.push('a NO-GO report must not contain an adoption digest');
+    }
+    return errors;
+  }
+  if (reportArg.decision !== 'GO') return errors;
+
+  if (Array.isArray(blockers) && blockers.length !== 0) {
+    errors.push('a GO report must not contain blockers');
+  }
+  if (!isCanonicalDigest(reportArg.adoptionDigest)) {
+    errors.push('a GO report requires a canonical adoption digest');
+  }
+
+  const service = reportArg.service;
+  const registry = reportArg.registry;
+  const targetScope = reportArg.targetScope;
+  const runtimeTasks = reportArg.runtimeTasks;
+  if (!isRecord(service)) {
+    errors.push('a GO report requires a service snapshot');
+  } else {
+    for (const key of ['organizationId', 'serviceId', 'serviceName', 'imageId'] as const) {
+      if (!isBoundedIdentifier(service[key])) errors.push(`service.${key} is invalid`);
+    }
+    if (service.deployOnPush !== true || service.immutableImageRequired !== false) {
+      errors.push('a GO report requires the legacy mutable service state');
+    }
+    if (typeof service.configuredReference !== 'string' || !service.configuredReference.trim()) {
+      errors.push('service.configuredReference must be non-empty');
+    }
+    if (!isRecord(service.registryTarget)) {
+      errors.push('service.registryTarget must be present');
+    }
+  }
+
+  let registryDigest: TSha256Digest | undefined;
+  if (!isRecord(registry)) {
+    errors.push('a GO report requires a registry snapshot');
+  } else {
+    if (!normalizeImmutableReleaseTag(registry.tag) || registry.tag !== registry.releaseTag) {
+      errors.push('registry tag and releaseTag must be the same immutable tag');
+    }
+    if (!isCanonicalDigest(registry.digest)) {
+      errors.push('registry.digest must be a canonical sha256 digest');
+    } else {
+      registryDigest = registry.digest;
+      if (reportArg.adoptionDigest === registry.digest) {
+        errors.push('adoption digest must be a distinct full-state fence, not the image digest');
+      }
+    }
+    if (!indexMediaTypes.has(registry.mediaType as TOciManifestMediaType)) {
+      errors.push('registry.mediaType must identify an OCI image index');
+    }
+    if (!isBoundedIdentifier(registry.releaseId)) {
+      errors.push('registry.releaseId must be a bounded canonical identifier');
+    }
+    if (!Array.isArray(registry.platforms) || registry.platforms.length === 0) {
+      errors.push('registry.platforms must contain OCI platform evidence');
+    } else {
+      for (const architecture of ['amd64', 'arm64']) {
+        if (!registry.platforms.some((platformArg) => isRecord(platformArg)
+          && platformArg.os === 'linux'
+          && platformArg.architecture === architecture
+          && platformArg.runnable === true
+          && platformArg.manifestPresent === true
+          && isCanonicalDigest(platformArg.digest))) {
+          errors.push(`registry.platforms must contain runnable linux/${architecture} evidence`);
+        }
+      }
+    }
+  }
+
+  let requiredReplicaCount: number | undefined;
+  let targetNodeNames: string[] = [];
+  let replicasPerNode: number | undefined;
+  if (!isRecord(targetScope)) {
+    errors.push('a GO report requires an immutable target scope');
+  } else {
+    const clusterIds = targetScope.targetClusterIds;
+    const nodeNames = targetScope.targetNodeNames;
+    replicasPerNode = targetScope.replicasPerNode as number;
+    requiredReplicaCount = targetScope.requiredReplicaCount as number;
+    if (!Array.isArray(clusterIds) || clusterIds.length !== 1
+      || clusterIds.some((valueArg) => !isBoundedIdentifier(valueArg))
+      || new Set(clusterIds).size !== clusterIds.length) {
+      errors.push('targetScope.targetClusterIds must identify exactly one attested cluster');
+    }
+    if (!Array.isArray(nodeNames) || nodeNames.length === 0
+      || nodeNames.some((valueArg) => !isBoundedIdentifier(valueArg))
+      || new Set(nodeNames).size !== nodeNames.length) {
+      errors.push('targetScope.targetNodeNames must be non-empty and unique');
+    } else {
+      targetNodeNames = nodeNames as string[];
+    }
+    if (!Number.isSafeInteger(replicasPerNode) || replicasPerNode < 1) {
+      errors.push('targetScope.replicasPerNode must be a positive integer');
+    }
+    if (!Number.isSafeInteger(requiredReplicaCount) || requiredReplicaCount < 1
+      || requiredReplicaCount !== targetNodeNames.length * (replicasPerNode || 0)) {
+      errors.push('targetScope.requiredReplicaCount must match nodes times replicas');
+    }
+  }
+
+  if (!Array.isArray(runtimeTasks) || runtimeTasks.length === 0) {
+    errors.push('a GO report requires runtime task evidence');
+  } else {
+    if (requiredReplicaCount !== undefined && runtimeTasks.length !== requiredReplicaCount) {
+      errors.push('runtime task count must equal the required replica count');
+    }
+    const deploymentIds = new Set<string>();
+    const taskCountsByNode = new Map<string, number>();
+    for (const task of runtimeTasks) {
+      if (!isRecord(task)
+        || !isBoundedIdentifier(task.deploymentId)
+        || deploymentIds.has(task.deploymentId as string)) {
+        errors.push('runtime task deployment IDs must be valid and unique');
+        continue;
+      }
+      deploymentIds.add(task.deploymentId as string);
+      if (!isBoundedIdentifier(task.nodeName) || !targetNodeNames.includes(task.nodeName)) {
+        errors.push('every runtime task must belong to the exact target node scope');
+      } else {
+        taskCountsByNode.set(task.nodeName, (taskCountsByNode.get(task.nodeName) || 0) + 1);
+      }
+      if (task.status !== 'running' || task.healthStatus !== 'healthy') {
+        errors.push('every runtime task must be running and healthy');
+      }
+      if (!registryDigest || task.observedDigest !== registryDigest) {
+        errors.push('every runtime task must attest the exact registry digest');
+      }
+      if (typeof task.imageReference !== 'string' || !task.imageReference.trim()) {
+        errors.push('every runtime task must identify its image reference');
+      }
+    }
+    if (replicasPerNode !== undefined
+      && targetNodeNames.some((nodeNameArg) => taskCountsByNode.get(nodeNameArg) !== replicasPerNode)) {
+      errors.push('runtime task evidence must cover every target node and replica');
+    }
+  }
+
+  if (isRecord(attestation) && requiredReplicaCount !== undefined) {
+    if (attestation.requiredReplicaCount !== requiredReplicaCount
+      || attestation.observedReplicaCount !== requiredReplicaCount
+      || attestation.healthyReplicaCount !== requiredReplicaCount
+      || attestation.observedDigestReplicaCount !== requiredReplicaCount
+      || attestation.observedDigestConsistent !== true) {
+      errors.push('runtime attestation must consistently cover every required replica');
+    }
+  }
+
+  if (isRecord(service) && isRecord(service.registryTarget) && isRecord(registry)) {
+    const target = service.registryTarget;
+    if (target.protocol !== 'oci'
+      || target.tag !== registry.tag
+      || target.serviceId !== service.serviceId
+      || target.imageId !== service.imageId
+      || typeof target.registryHost !== 'string'
+      || !target.registryHost
+      || typeof target.repository !== 'string'
+      || !target.repository
+      || target.imageUrl !== `${target.registryHost}/${target.repository}:${target.tag}`) {
+      errors.push('service registry target must exactly bind the adopted service, image, and tag');
+    }
+    if (registryDigest) {
+      const digestPinnedReference = `${target.registryHost}/${target.repository}@${registryDigest}`;
+      const tagAndDigestReference = `${target.imageUrl}@${registryDigest}`;
+      const configuredReferences = new Set([
+        target.tag,
+        target.imageUrl,
+        digestPinnedReference,
+        tagAndDigestReference,
+      ]);
+      if (!configuredReferences.has(service.configuredReference as string)) {
+        errors.push('service configured reference must exactly bind the adopted registry target');
+      }
+      const runtimeReferences = new Set([
+        target.imageUrl,
+        digestPinnedReference,
+        tagAndDigestReference,
+      ]);
+      if (Array.isArray(runtimeTasks)
+        && runtimeTasks.some((taskArg) => !isRecord(taskArg)
+          || !runtimeReferences.has(taskArg.imageReference as string))) {
+        errors.push('every runtime task image reference must exactly bind the adopted registry target');
+      }
+    }
+  }
+  return errors;
+};