@serve.zone/interfaces 11.2.0 → 11.4.0

package/ts/data/immutableimage.ts

@@ -0,0 +1,373 @@
+/** Canonical lower-case OCI sha256 digest. */
+export type TSha256Digest = `sha256:${string}`;
+
+export type TImageDeploymentPolicy = 'legacy-tag' | 'immutable-digest';
+
+export type TOciManifestMediaType =
+  | 'application/vnd.oci.image.index.v1+json'
+  | 'application/vnd.oci.image.manifest.v1+json'
+  | 'application/vnd.docker.distribution.manifest.list.v2+json'
+  | 'application/vnd.docker.distribution.manifest.v2+json';
+
+export type TImmutableImageRolloutMode = 'promotion' | 'automatic' | 'rollback';
+
+export type TImmutableImageMismatchReason =
+  | 'immutable-plan-missing'
+  | 'requested-digest-missing'
+  | 'requested-digest-malformed'
+  | 'registry-digest-inconsistent'
+  | 'runtime-capability-missing'
+  | 'pull-failed'
+  | 'pulled-digest-missing'
+  | 'pulled-digest-mismatch'
+  | 'service-image-not-digest-pinned'
+  | 'service-image-digest-mismatch'
+  | 'task-image-not-digest-pinned'
+  | 'task-image-digest-mismatch'
+  | 'container-inspection-unavailable'
+  | 'container-image-id-missing'
+  | 'container-repodigest-missing'
+  | 'container-repodigest-mismatch'
+  | 'runtime-attestation-missing'
+  | 'required-replica-missing'
+  | 'replica-unhealthy'
+  | 'replica-failed'
+  | 'stale-rollout-report'
+  | 'rollback-target-not-accepted';
+
+export type TRuntimeImageVerificationStatus =
+  | 'not-required'
+  | 'pending'
+  | 'verified'
+  | 'missing'
+  | 'mismatched';
+
+export type TImmutableImageRolloutStatus =
+  | 'pending'
+  | 'deploying'
+  | 'verifying'
+  | 'succeeded'
+  | 'failed'
+  | 'mismatched'
+  | 'rolling-back'
+  | 'rolled-back';
+
+export interface ICoreflowRuntimeCapabilities {
+  immutableImageDeploymentVersion: 1;
+}
+
+/**
+ * A registry manifest observed by Cloudly. Observation alone does not make the
+ * release deployable: acceptedAt is set only by an explicit promotion or a
+ * configured automatic promotion.
+ */
+export interface IImageRelease {
+  id: string;
+  data: {
+    serviceId: string;
+    imageId: string;
+    registryHost: string;
+    repository: string;
+    /** Digest of the registry root descriptor, preserving an index/list when submitted. */
+    registryRootDigest: TSha256Digest;
+    digestPinnedImageReference: string;
+    manifestMediaType: TOciManifestMediaType;
+    observedTags: string[];
+    firstObservedAt: number;
+    lastObservedAt: number;
+    observationCount: number;
+    acceptedAt?: number;
+    lastPromotedAt?: number;
+    promotionCount?: number;
+  };
+}
+
+export interface IImmutableImageTargetScope {
+  targetClusterIds: string[];
+  targetNodeNames: string[];
+  replicasPerNode: number;
+  requiredReplicaCount: number;
+}
+
+/** Immutable desired state issued by Cloudly and consumed by Coreflow. */
+export interface IImmutableImageDeploymentPlan {
+  policy: 'immutable-digest';
+  rolloutId: string;
+  rolloutGeneration: number;
+  releaseId: string;
+  registryHost: string;
+  repository: string;
+  requestedDigest: TSha256Digest;
+  digestPinnedImageReference: string;
+  manifestMediaType: TOciManifestMediaType;
+  createdAt: number;
+  mode: TImmutableImageRolloutMode;
+  rollbackOfRolloutId?: string;
+  targetScope: IImmutableImageTargetScope;
+}
+
+/** Runtime evidence collected from Docker service, task, container and image state. */
+interface IRuntimeImageEvidenceBase {
+  rolloutId?: string;
+  rolloutGeneration?: number;
+  expectedDigest?: TSha256Digest;
+  serviceImageReference?: string;
+  taskImageReference?: string;
+  taskReportedDigest?: TSha256Digest;
+  containerImageId?: string;
+  containerConfigImageReference?: string;
+  resolvedDigest?: TSha256Digest;
+  platformManifestDigest?: TSha256Digest;
+  repoDigests?: string[];
+  evidenceSource?: 'task-spec' | 'local-container-inspect';
+  observedAt: number;
+}
+
+export interface IVerifiedRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+  verificationStatus: 'verified';
+  rolloutId: string;
+  rolloutGeneration: number;
+  expectedDigest: TSha256Digest;
+  serviceImageReference: string;
+  taskImageReference: string;
+  taskReportedDigest: TSha256Digest;
+  containerImageId: string;
+  containerConfigImageReference: string;
+  resolvedDigest: TSha256Digest;
+  repoDigests: string[];
+  evidenceSource: 'local-container-inspect';
+  mismatchReason?: never;
+}
+
+export interface IUnverifiedRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+  verificationStatus: 'missing' | 'mismatched';
+  mismatchReason: TImmutableImageMismatchReason;
+}
+
+export interface IPendingRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+  verificationStatus: 'pending' | 'not-required';
+  mismatchReason?: never;
+}
+
+export type IRuntimeImageEvidence =
+  | IVerifiedRuntimeImageEvidence
+  | IUnverifiedRuntimeImageEvidence
+  | IPendingRuntimeImageEvidence;
+
+/** Mandatory security envelope when reporting an immutable rollout. */
+export interface IImmutableRolloutReportEnvelope {
+  rolloutId: string;
+  rolloutGeneration: number;
+  reporterSessionId: string;
+  reportSequence: number;
+  reporterCapabilities: ICoreflowRuntimeCapabilities;
+  reporterNodeIds: string[];
+  reporterNodeNames: string[];
+}
+
+export interface IImageRolloutReporterStatus {
+  reporterId: string;
+  reporterSessionId: string;
+  clusterId: string;
+  reporterNodeNames: string[];
+  rolloutId: string;
+  rolloutGeneration: number;
+  reportSequence: number;
+  reportedAt: number;
+  requiredReplicaCount: number;
+  observedReplicaCount: number;
+  healthyReplicaCount: number;
+  verifiedReplicaCount: number;
+  failedReplicaCount: number;
+  mismatchReason?: TImmutableImageMismatchReason;
+}
+
+export interface IImageRolloutStatus {
+  rolloutId: string;
+  rolloutGeneration: number;
+  expectedDigest: TSha256Digest;
+  status: TImmutableImageRolloutStatus;
+  requiredReplicaCount: number;
+  observedReplicaCount: number;
+  healthyReplicaCount: number;
+  verifiedReplicaCount: number;
+  failedReplicaCount: number;
+  mismatchReason?: TImmutableImageMismatchReason;
+  updatedAt: number;
+  reporters: IImageRolloutReporterStatus[];
+}
+
+const sha256DigestRegex = /^sha256:[a-f0-9]{64}$/;
+
+export const normalizeSha256Digest = (digest: string): TSha256Digest | undefined => {
+  const normalizedDigest = digest.trim().toLowerCase();
+  return sha256DigestRegex.test(normalizedDigest)
+    ? (normalizedDigest as TSha256Digest)
+    : undefined;
+};
+
+export const isSha256Digest = (digest: string): digest is TSha256Digest =>
+  sha256DigestRegex.test(digest);
+
+const registryHostRegex = /^(?:localhost|[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)(?::[1-9][0-9]{0,4})?$/;
+const repositoryRegex = /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$/;
+
+export const buildDigestPinnedImageReference = (
+  registryHost: string,
+  repository: string,
+  digest: TSha256Digest
+): string => {
+  if (!registryHostRegex.test(registryHost) || !repositoryRegex.test(repository)) {
+    throw new Error('registry host and repository must be canonical OCI names');
+  }
+  if (!isSha256Digest(digest)) {
+    throw new Error('digest must be a canonical sha256 digest');
+  }
+  return `${registryHost}/${repository}@${digest}`;
+};
+
+export const getDigestFromPinnedImageReference = (
+  imageReference: string
+): TSha256Digest | undefined => {
+  const separatorIndex = imageReference.lastIndexOf('@');
+  if (separatorIndex < 0) {
+    return undefined;
+  }
+  return normalizeSha256Digest(imageReference.slice(separatorIndex + 1));
+};
+
+export const validateImmutableImageDeploymentPlan = (
+  planArg: IImmutableImageDeploymentPlan
+): string[] => {
+  const errors: string[] = [];
+  if (!Number.isSafeInteger(planArg.rolloutGeneration) || planArg.rolloutGeneration < 1) {
+    errors.push('rolloutGeneration must be a positive safe integer');
+  }
+  if (!Number.isSafeInteger(planArg.createdAt) || planArg.createdAt < 1) {
+    errors.push('createdAt must be a positive safe integer');
+  }
+  let expectedReference: string | undefined;
+  try {
+    expectedReference = buildDigestPinnedImageReference(
+      planArg.registryHost,
+      planArg.repository,
+      planArg.requestedDigest
+    );
+  } catch (error) {
+    errors.push((error as Error).message);
+  }
+  if (expectedReference && planArg.digestPinnedImageReference !== expectedReference) {
+    errors.push('digestPinnedImageReference does not match registry, repository and digest');
+  }
+  const scope = planArg.targetScope;
+  if (!Number.isSafeInteger(scope.replicasPerNode) || scope.replicasPerNode < 1) {
+    errors.push('replicasPerNode must be a positive safe integer');
+  }
+  if (scope.targetClusterIds.length < 1 || scope.targetNodeNames.length < 1) {
+    errors.push('immutable rollout target scope must contain clusters and nodes');
+  }
+  if (new Set(scope.targetClusterIds).size !== scope.targetClusterIds.length
+    || new Set(scope.targetNodeNames).size !== scope.targetNodeNames.length) {
+    errors.push('immutable rollout target scope must not contain duplicates');
+  }
+  if (scope.requiredReplicaCount !== scope.targetNodeNames.length * scope.replicasPerNode) {
+    errors.push('requiredReplicaCount does not match target nodes and replicasPerNode');
+  }
+  if (planArg.mode === 'rollback' && !planArg.rollbackOfRolloutId) {
+    errors.push('rollback rollout must identify the rollout it replaces');
+  }
+  if (planArg.mode !== 'rollback' && planArg.rollbackOfRolloutId) {
+    errors.push('only rollback rollouts may set rollbackOfRolloutId');
+  }
+  return errors;
+};
+
+export const validateImageRolloutStatus = (statusArg: IImageRolloutStatus): string[] => {
+  const errors: string[] = [];
+  const counts = [
+    statusArg.requiredReplicaCount,
+    statusArg.observedReplicaCount,
+    statusArg.healthyReplicaCount,
+    statusArg.verifiedReplicaCount,
+    statusArg.failedReplicaCount,
+  ];
+  if (counts.some((countArg) => !Number.isSafeInteger(countArg) || countArg < 0)) {
+    errors.push('rollout replica counts must be non-negative safe integers');
+  }
+  const reporterIds = statusArg.reporters.map((reporterArg) => reporterArg.reporterId);
+  const reporterSessionIds = statusArg.reporters.map((reporterArg) => reporterArg.reporterSessionId);
+  const reporterNodeNames = statusArg.reporters.flatMap(
+    (reporterArg) => reporterArg.reporterNodeNames
+  );
+  if (new Set(reporterIds).size !== reporterIds.length
+    || new Set(reporterSessionIds).size !== reporterSessionIds.length) {
+    errors.push('rollout status must contain one latest report per reporter and session');
+  }
+  for (const reporter of statusArg.reporters) {
+    const reporterCounts = [
+      reporter.requiredReplicaCount,
+      reporter.observedReplicaCount,
+      reporter.healthyReplicaCount,
+      reporter.verifiedReplicaCount,
+      reporter.failedReplicaCount,
+    ];
+    if (reporterCounts.some((countArg) => !Number.isSafeInteger(countArg) || countArg < 0)) {
+      errors.push('reporter replica counts must be non-negative safe integers');
+    }
+    if (reporter.rolloutId !== statusArg.rolloutId
+      || reporter.rolloutGeneration !== statusArg.rolloutGeneration) {
+      errors.push('reporter rollout identity does not match aggregate rollout identity');
+    }
+    if (
+      reporter.observedReplicaCount > reporter.requiredReplicaCount
+      || reporter.healthyReplicaCount > reporter.observedReplicaCount
+      || reporter.verifiedReplicaCount > reporter.observedReplicaCount
+    ) {
+      errors.push('reporter replica counts are contradictory');
+    }
+  }
+  if (statusArg.status === 'succeeded' || statusArg.status === 'rolled-back') {
+    if (
+      statusArg.requiredReplicaCount < 1
+      || statusArg.observedReplicaCount !== statusArg.requiredReplicaCount
+      || statusArg.healthyReplicaCount !== statusArg.requiredReplicaCount
+      || statusArg.verifiedReplicaCount !== statusArg.requiredReplicaCount
+      || statusArg.failedReplicaCount !== 0
+    ) {
+      errors.push('successful rollout status requires every replica to be observed, healthy and verified');
+    }
+    if (statusArg.mismatchReason || statusArg.reporters.length < 1) {
+      errors.push('successful rollout status requires reporters without mismatch reasons');
+    }
+    if (new Set(reporterNodeNames).size !== reporterNodeNames.length) {
+      errors.push('successful rollout status must not count a node in multiple reporters');
+    }
+    if (statusArg.reporters.some((reporterArg) => (
+      reporterArg.requiredReplicaCount < 1
+      || reporterArg.observedReplicaCount !== reporterArg.requiredReplicaCount
+      || reporterArg.healthyReplicaCount !== reporterArg.requiredReplicaCount
+      || reporterArg.verifiedReplicaCount !== reporterArg.requiredReplicaCount
+      || reporterArg.failedReplicaCount !== 0
+      || Boolean(reporterArg.mismatchReason)
+    ))) {
+      errors.push('successful rollout requires every reporter replica to be healthy and verified');
+    }
+    const reporterTotals = statusArg.reporters.reduce((totalsArg, reporterArg) => ({
+      required: totalsArg.required + reporterArg.requiredReplicaCount,
+      observed: totalsArg.observed + reporterArg.observedReplicaCount,
+      healthy: totalsArg.healthy + reporterArg.healthyReplicaCount,
+      verified: totalsArg.verified + reporterArg.verifiedReplicaCount,
+      failed: totalsArg.failed + reporterArg.failedReplicaCount,
+    }), { required: 0, observed: 0, healthy: 0, verified: 0, failed: 0 });
+    if (
+      reporterTotals.required !== statusArg.requiredReplicaCount
+      || reporterTotals.observed !== statusArg.observedReplicaCount
+      || reporterTotals.healthy !== statusArg.healthyReplicaCount
+      || reporterTotals.verified !== statusArg.verifiedReplicaCount
+      || reporterTotals.failed !== statusArg.failedReplicaCount
+    ) {
+      errors.push('successful rollout aggregate must exactly match successful reporter evidence');
+    }
+  }
+  return errors;
+};

package/ts/data/index.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './deploymentpreflight.js';
 export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';
@@ -11,6 +12,7 @@ export * from './externalregistry.js';
 export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './immutableimage.js';
 export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';

package/ts/data/registry.ts

@@ -1,5 +1,10 @@
 export type TRegistryProtocol = 'oci';
 
+import type {
+  TOciManifestMediaType,
+  TSha256Digest,
+} from './immutableimage.js';
+
 export interface IRegistryTarget {
   protocol: TRegistryProtocol;
   registryHost: string;
@@ -11,6 +16,8 @@ export interface IRegistryTarget {
 }
 
 export interface IRegistryPushEvent {
+  eventId?: string;
+  releaseId?: string;
   protocol: TRegistryProtocol;
   registryHost: string;
   repository: string;
@@ -18,8 +25,28 @@ export interface IRegistryPushEvent {
   digest: string;
   imageUrl: string;
   pushedAt: number;
+  observedAt?: number;
   serviceId?: string;
   imageId?: string;
   actorUserId?: string;
   manifestMediaType?: string;
 }
+
+/** Fully verified registry observation used by immutable release processing. */
+export interface IImmutableRegistryPushEvent {
+  deploymentPolicy: 'immutable-digest';
+  eventId: string;
+  releaseId: string;
+  protocol: TRegistryProtocol;
+  registryHost: string;
+  repository: string;
+  tag: string;
+  registryRootDigest: TSha256Digest;
+  digestPinnedImageReference: string;
+  imageUrl: string;
+  observedAt: number;
+  serviceId: string;
+  imageId: string;
+  manifestMediaType: TOciManifestMediaType;
+  actorUserId?: string;
+}

package/ts/data/service.ts

@@ -3,6 +3,10 @@ import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig } from './mail.js';
+import type {
+  IImageRolloutStatus,
+  IImmutableImageDeploymentPlan,
+} from './immutableimage.js';
 import type {
   IServiceDomainRoute,
   IServicePublicPortMapping,
@@ -70,6 +74,12 @@ export interface IService {
     imageVersion: string;
     registryTarget?: IRegistryTarget;
     deployOnPush?: boolean;
+    /** Fail closed unless Cloudly supplies and Coreflow verifies a digest-pinned rollout. */
+    immutableImageRequired?: boolean;
+    /** Server-managed immutable desired state. Use the promotion/rollback APIs to change it. */
+    imageDeployment?: IImmutableImageDeploymentPlan;
+    /** Server-managed aggregate of task-derived runtime evidence. */
+    imageRolloutStatus?: IImageRolloutStatus;
 
     /**
      * When true the service tolerates overlapping deployments during
@@ -151,3 +161,9 @@ export interface IService {
     deploymentIds: string[];
   };
 }
+
+/** Caller-writable service data. Immutable policy and rollout fields are server-managed. */
+export type TServiceWritableData = Omit<
+  IService['data'],
+  'immutableImageRequired' | 'imageDeployment' | 'imageRolloutStatus'
+>;

package/ts/data/user.ts

@@ -4,6 +4,22 @@ export interface IToken {
   assignedRoles: string[];
 }
 
+export type TServiceDeploymentCapability =
+  | 'deployment:preflight'
+  | 'deployment:create-greenfield'
+  | 'deployment:promote-route'
+  | 'deployment:rollback-route';
+
+/**
+ * Server-persisted authority for one logical service. These grants are never
+ * accepted from the identity payload supplied by a caller; Cloudly reloads
+ * the owning user from the verified JWT before evaluating them.
+ */
+export interface IServiceDeploymentGrant {
+  serviceId: string;
+  capabilities: TServiceDeploymentCapability[];
+}
+
 export interface IIdentityCredential {
   jwt: string;
 }
@@ -28,5 +44,6 @@ export interface IUser {
     username?: string;
     password?: string;
     tokens?: IToken[];
+    serviceDeploymentGrants?: IServiceDeploymentGrant[];
   }
 }

package/ts/requests/deployment.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity } from '../data/user.js';
+import type { IImmutableRolloutReportEnvelope } from '../data/immutableimage.js';
 
 export interface IDeploymentWorkspaceFileEntry {
   type: 'file' | 'directory';
@@ -452,6 +453,8 @@ extends plugins.typedrequestInterfaces.implementsTR<
      * When absent, the snapshot replaces all persisted deployments of the service.
      */
     reporterNodeNames?: string[];
+    /** Mandatory when the referenced service requires immutable deployment. */
+    immutableReport?: IImmutableRolloutReportEnvelope;
     reportedAt: number;
   };
   response: Record<string, never>;

package/ts/requests/service.ts

@@ -1,8 +1,28 @@
 import * as plugins from '../plugins.js';
 import type { IService } from '../data/service.js';
+import type { TServiceWritableData } from '../data/service.js';
 import type { IRegistryTarget } from '../data/registry.js';
 import type { IIdentity } from '../data/user.js';
 import type { IServiceRessources } from '../data/docker.js';
+import type { IImageRelease } from '../data/immutableimage.js';
+import type {
+  IDeploymentPreflightReport,
+  IDeploymentPreflightRequestData,
+} from '../data/deploymentpreflight.js';
+
+export interface IRequest_Any_Cloudly_GetDeploymentPreflight
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetDeploymentPreflight
+> {
+  method: 'getDeploymentPreflight';
+  request: IDeploymentPreflightRequestData & {
+    identity: IIdentity;
+  };
+  response: {
+    report: IDeploymentPreflightReport;
+  };
+}
 
 export interface IRequest_Any_Cloudly_GetServiceById 
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -49,6 +69,61 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+export interface IRequest_Any_Cloudly_GetServiceImageReleases
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceImageReleases
+> {
+  method: 'getServiceImageReleases';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+  };
+  response: {
+    releases: IImageRelease[];
+  };
+}
+
+export interface IRequest_Any_Cloudly_PromoteServiceImageRelease
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_PromoteServiceImageRelease
+> {
+  method: 'promoteServiceImageRelease';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    releaseId: string;
+    idempotencyKey: string;
+    expectedRolloutGeneration: number;
+    expectedCurrentRolloutId?: string;
+    /** Explicitly opts the service into fail-closed immutable deployment. */
+    enableImmutableImage: true;
+  };
+  response: {
+    service: IService;
+  };
+}
+
+export interface IRequest_Any_Cloudly_RollbackServiceImageRelease
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_RollbackServiceImageRelease
+> {
+  method: 'rollbackServiceImageRelease';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    releaseId: string;
+    idempotencyKey: string;
+    expectedCurrentRolloutId: string;
+    expectedRolloutGeneration: number;
+  };
+  response: {
+    service: IService;
+  };
+}
+
 export interface IRequest_Any_Cloudly_CreateService
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -57,7 +132,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
   method: 'createService';
   request: {
     identity: IIdentity;
-    serviceData: IService['data'];
+    serviceData: TServiceWritableData;
   };
   response: {
     service: IService;
@@ -73,7 +148,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
   request: {
     identity: IIdentity;
     serviceId: string;
-    serviceData: IService['data'];
+    serviceData: TServiceWritableData;
   };
   response: {
     service: IService;