@serve.zone/interfaces 32.67.0 → 32.69.0

package/ts/data/deploymentreleaseredeploy.ts

@@ -0,0 +1,182 @@
+import { readDataProperties } from '../private/dataproperties.js';
+
+/**
+ * Release redeploy: an existing service deploys one of its own releases again, from Cloudly's
+ * registry, without a build or a push.
+ *
+ * An administrator (or a deployment machine user granted `deployment:redeploy-release` on the
+ * service) starts it with `startServiceReleaseDeployment`, naming the release and the service's
+ * current rollout fence. Cloudly then runs the whole deployment itself: it creates an
+ * existing-service operation whose origin is `releaseRedeploy`, tags the release's root under the
+ * operation's own tag in the service's repository (the tag is the operation id, which starts with
+ * {@link releaseRedeployContract.tagPrefix} and so can never be a version string), records
+ * `cloudly-release-redeploy` evidence naming the source release, promotes the release and drives
+ * the operation through rollout, route promotion and public verification to `succeeded` or
+ * `failed`. The operation's status is the only statement that the deploy happened.
+ *
+ * What the redeploy declares is the declaration in force now: the routes, public domains and
+ * proposed configuration of the operation that owns the service's current rollout plan, never the
+ * declaration the source release was first deployed with.
+ *
+ * Only a release that was accepted (promoted successfully before), is still retained by the
+ * registry's retention policy and is still whole (every manifest and blob present) can be
+ * redeployed. A release accepted before the current one is rolled back to (plan mode `rollback`);
+ * the current release, or one accepted after it, is promoted again (plan mode `promotion`).
+ */
+
+/** Where a release redeploy's image comes from: one release of the service itself. */
+export interface IReleaseRedeployReference {
+  /** The release whose registry root the redeploy deploys again. */
+  sourceReleaseId: string;
+}
+
+export const releaseRedeployContract = Object.freeze({
+  /**
+   * Every release redeploy's operation id, and therefore its release tag, starts with this. A
+   * semantic version never does, so a redeploy tag never collides with a version tag.
+   */
+  tagPrefix: 'redeploy-',
+  /** Operations one history read answers when it names no limit. */
+  historyDefaultLimit: 20,
+  /** Operations one history read answers at most. */
+  historyMaximumLimit: 50,
+});
+
+/**
+ * The named refusals `startServiceReleaseDeployment` answers in its error's `code`, beside the
+ * shared deployment codes it reuses (`DEPLOYMENT_CAPABILITY_FORBIDDEN`, `DEPLOYMENT_IDENTITY_INVALID`,
+ * `DEPLOY_ON_PUSH_MUST_BE_DISABLED`, `DEPLOYMENT_ROLLOUT_FENCE_CONFLICT`,
+ * `DEPLOYMENT_IDEMPOTENCY_CONFLICT`, `DEPLOYMENT_PREFLIGHT_UNAVAILABLE`).
+ *
+ * - `DEPLOYMENT_REDEPLOY_INVALID`: the request is malformed.
+ * - `DEPLOYMENT_SERVICE_NOT_FOUND`: no such service.
+ * - `DEPLOYMENT_REDEPLOY_NO_CURRENT_PLAN`: the service has no current rollout plan to redeploy over.
+ * - `DEPLOYMENT_REDEPLOY_DECLARATION_UNAVAILABLE`: the plan is not owned by a deployment operation
+ *   whose declaration Cloudly can state again (an adoption, or an operation that is gone).
+ * - `DEPLOYMENT_OPERATION_IN_FLIGHT`: another deployment operation of the service is not finished.
+ * - `DEPLOYMENT_RELEASE_NOT_FOUND`: no such release of this service.
+ * - `DEPLOYMENT_RELEASE_NOT_ACCEPTED`: the release was never promoted successfully.
+ * - `DEPLOYMENT_RELEASE_NOT_RETAINED`: retention no longer keeps the release.
+ * - `DEPLOYMENT_RELEASE_INCOMPLETE`: a manifest or blob of the release is missing from the registry.
+ * - `DEPLOYMENT_TARGET_SWARM_PHASE`: the service's rollout targets a cluster still in its Swarm
+ *   phase, which a Cloudly-run deployment does not drive.
+ * - `DEPLOYMENT_TARGET_UNAVAILABLE`: the service's rollout target cannot be resolved.
+ */
+export const serviceReleaseDeploymentRefusalCodes = [
+  'DEPLOYMENT_REDEPLOY_INVALID',
+  'DEPLOYMENT_SERVICE_NOT_FOUND',
+  'DEPLOYMENT_REDEPLOY_NO_CURRENT_PLAN',
+  'DEPLOYMENT_REDEPLOY_DECLARATION_UNAVAILABLE',
+  'DEPLOYMENT_OPERATION_IN_FLIGHT',
+  'DEPLOYMENT_RELEASE_NOT_FOUND',
+  'DEPLOYMENT_RELEASE_NOT_ACCEPTED',
+  'DEPLOYMENT_RELEASE_NOT_RETAINED',
+  'DEPLOYMENT_RELEASE_INCOMPLETE',
+  'DEPLOYMENT_TARGET_SWARM_PHASE',
+  'DEPLOYMENT_TARGET_UNAVAILABLE',
+] as const;
+
+export type TServiceReleaseDeploymentRefusalCode = typeof serviceReleaseDeploymentRefusalCodes[number];
+
+/** What `startServiceReleaseDeployment` states besides the caller's identity. */
+export interface IServiceReleaseDeploymentStartInput {
+  serviceId: string;
+  releaseId: string;
+  /** Binds one start; the same key with the same request answers the operation it started. */
+  idempotencyKey: string;
+  /** The service's current rollout generation: at least 1, since a redeploy needs a current plan. */
+  expectedRolloutGeneration: number;
+  /** The service's current rollout id. */
+  expectedCurrentRolloutId: string;
+}
+
+/** What `getServiceDeploymentOperations` states besides the caller's identity. */
+export interface IServiceDeploymentOperationHistoryQuery {
+  serviceId: string;
+  /** 1 to `releaseRedeployContract.historyMaximumLimit`; `historyDefaultLimit` when omitted. */
+  limit?: number;
+  /** An operation id the previous page answered as `nextBefore`: the page starts after it. */
+  before?: string;
+}
+
+const redeployIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+
+const isRedeployIdentifier = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && redeployIdentifierRegex.test(valueArg)
+);
+
+const startInputKeys = [
+  'serviceId',
+  'releaseId',
+  'idempotencyKey',
+  'expectedRolloutGeneration',
+  'expectedCurrentRolloutId',
+] as const;
+
+/** Every error of a start input; empty when it is exactly one valid input. */
+export const validateServiceReleaseDeploymentStartInput = (inputArg: unknown): string[] => {
+  const input = readDataProperties(inputArg);
+  if (input === null) return ['release deployment start input must be a plain object'];
+  const errors: string[] = [];
+  const keys = Object.keys(input);
+  if (keys.length !== startInputKeys.length
+    || !startInputKeys.every((keyArg) => keys.includes(keyArg))) {
+    errors.push(`release deployment start input must carry exactly ${startInputKeys.join(', ')}`);
+  }
+  for (const field of ['serviceId', 'releaseId', 'idempotencyKey', 'expectedCurrentRolloutId'] as const) {
+    if (!isRedeployIdentifier(input[field])) {
+      errors.push(`${field} must be a bounded canonical identifier`);
+    }
+  }
+  if (!Number.isSafeInteger(input.expectedRolloutGeneration)
+    || (input.expectedRolloutGeneration as number) < 1) {
+    errors.push('expectedRolloutGeneration must be the current generation, at least 1');
+  }
+  return errors;
+};
+
+/** Every error of a release redeploy reference; empty when it is exactly one valid reference. */
+export const validateReleaseRedeployReference = (referenceArg: unknown): string[] => {
+  const reference = readDataProperties(referenceArg);
+  if (reference === null) return ['releaseRedeploy must be a plain object'];
+  const keys = Object.keys(reference);
+  const errors: string[] = [];
+  if (keys.length !== 1 || keys[0] !== 'sourceReleaseId') {
+    errors.push('releaseRedeploy must carry exactly sourceReleaseId');
+  }
+  if (!isRedeployIdentifier(reference.sourceReleaseId)) {
+    errors.push('releaseRedeploy.sourceReleaseId must be a bounded canonical identifier');
+  }
+  return errors;
+};
+
+/** Every error of a history query; empty when it is exactly one valid query. */
+export const validateServiceDeploymentOperationHistoryQuery = (queryArg: unknown): string[] => {
+  const query = readDataProperties(queryArg);
+  if (query === null) return ['deployment operation history query must be a plain object'];
+  const errors: string[] = [];
+  if (Object.keys(query).some((keyArg) => !['serviceId', 'limit', 'before'].includes(keyArg))) {
+    errors.push('deployment operation history query carries only serviceId, limit and before');
+  }
+  if (!isRedeployIdentifier(query.serviceId)) {
+    errors.push('serviceId must be a bounded canonical identifier');
+  }
+  if (query.limit !== undefined
+    && (!Number.isSafeInteger(query.limit)
+      || (query.limit as number) < 1
+      || (query.limit as number) > releaseRedeployContract.historyMaximumLimit)) {
+    errors.push(`limit must be an integer from 1 to ${releaseRedeployContract.historyMaximumLimit}`);
+  }
+  if (query.before !== undefined && !isRedeployIdentifier(query.before)) {
+    errors.push('before must be a bounded canonical operation id');
+  }
+  return errors;
+};
+
+/** Whether a release tag is a release redeploy's own tag. */
+export const isReleaseRedeployTag = (tagArg: unknown): boolean => (
+  typeof tagArg === 'string'
+  && tagArg.startsWith(releaseRedeployContract.tagPrefix)
+  && tagArg.length > releaseRedeployContract.tagPrefix.length
+  && /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/.test(tagArg)
+);

package/ts/data/immutableimage.ts

@@ -206,9 +206,24 @@ export interface IImageReleaseLegacyImportEvidence extends IImageReleaseTrustedE
   sourceRootDigest: TSha256Digest;
 }
 
+/**
+ * Cloudly's own copy of one of the service's accepted releases under a release redeploy's tag.
+ *
+ * Nothing was built or pushed: the release's root was tagged again in the same repository, so
+ * `sourceRootDigest` equals `registryRootDigest`, and `sourceReleaseId` names the release row the
+ * root belongs to. `sourceTag` is the tag the release was accepted under before.
+ */
+export interface IImageReleaseRedeployEvidence extends IImageReleaseTrustedEvidenceBase {
+  source: 'cloudly-release-redeploy';
+  sourceReleaseId: string;
+  sourceTag: string;
+  sourceRootDigest: TSha256Digest;
+}
+
 export type IImageReleaseTrustedEvidence =
   | IImageReleaseRegistryPushEvidence
-  | IImageReleaseLegacyImportEvidence;
+  | IImageReleaseLegacyImportEvidence
+  | IImageReleaseRedeployEvidence;
 
 export const selectTrustedImageReleaseEvidence = (argsArg: {
   release: IImageRelease;
@@ -222,8 +237,9 @@ export const selectTrustedImageReleaseEvidence = (argsArg: {
   digest: TSha256Digest;
   /**
    * The one evidence source the operation's image may have come from: a legacy-import operation
-   * accepts only Cloudly's import, every other operation only its actor's registry push. Omitted,
-   * it is the registry push, the only source an operation without a legacy import has.
+   * accepts only Cloudly's import, a release-redeploy operation only Cloudly's redeploy copy, every
+   * other operation only its actor's registry push. Omitted, it is the registry push, the only
+   * source an operation without a legacy import or a release redeploy has.
    */
   evidenceSource?: IImageReleaseTrustedEvidence['source'];
 }): { evidence?: IImageReleaseTrustedEvidence; errors: string[] } => {
@@ -248,6 +264,13 @@ export const selectTrustedImageReleaseEvidence = (argsArg: {
         evidenceArg.sourceRootDigest,
       ]
       : []),
+    ...(evidenceArg.source === 'cloudly-release-redeploy'
+      ? [
+        evidenceArg.sourceReleaseId,
+        evidenceArg.sourceTag,
+        evidenceArg.sourceRootDigest,
+      ]
+      : []),
   ].join('\u0000');
   const uniqueEvidence = new Map<string, IImageReleaseTrustedEvidence>();
   const errors: string[] = [];
@@ -284,6 +307,16 @@ export const selectTrustedImageReleaseEvidence = (argsArg: {
     errors.push('trusted release evidence is ambiguous');
   }
   const evidence = evidenceMatches.length === 1 ? evidenceMatches[0] : undefined;
+  // A redeploy copies one root of this release row under a new tag; it never makes a new root,
+  // and only a row that was accepted before (promoted successfully) can be redeployed.
+  if (evidence?.source === 'cloudly-release-redeploy'
+    && (argsArg.release.data.acceptedAt === undefined
+      || evidence.sourceRootDigest !== argsArg.release.data.registryRootDigest
+      || evidence.sourceReleaseId !== argsArg.release.id
+      || evidence.sourceTag === evidence.tag
+      || !argsArg.release.data.observedTags.includes(evidence.sourceTag))) {
+    errors.push('release redeploy evidence must name this accepted release, its root and an earlier tag of it');
+  }
   if (evidence && evidence.manifestMediaType !== argsArg.release.data.manifestMediaType) {
     errors.push('trusted release and release root media types disagree');
   }

package/ts/data/index.ts

@@ -18,6 +18,7 @@ export * from './deploymentlegacyimport.js';
 export * from './deploymentmachineuser.js';
 export * from './deploymentoperation.js';
 export * from './deploymentpreflight.js';
+export * from './deploymentreleaseredeploy.js';
 export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';
@@ -80,6 +81,8 @@ export * from './clusternodehostname.js';
 export * from './settings.js';
 export * from './sparklegacyretirement.js';
 export * from './sparknodereport.js';
+export * from './nodeaction.js';
+export * from './sparkfleettarget.js';
 export * from './service.js';
 export * from './servicecredential.js';
 export * from './serviceplatformownership.js';