@serve.zone/interfaces 32.66.0 → 32.68.0

package/ts/data/hostedapp.ts

@@ -5,6 +5,23 @@ export const hostedAppOidcAppInstanceIdClaim = 'servezone_app_instance_id' as co
 export const hostedAppMachineServiceIdClaim = 'servezone_service_id' as const;
 export const hostedAppMachineAudience = 'serve.zone/hosted-app-lifecycle' as const;
 
+/**
+ * The environment variable names under which a host (Onebox, Cloudly) hands a hosted app its
+ * runtime identity. `appInstanceId`, `hostType` and `runtimeUrl` travel in the public environment;
+ * `controlToken` is a secret and carries the host's machine JWT (`IHostedAppMachineClaims`,
+ * audience `hostedAppMachineAudience`). The app sends that JWT verbatim as `identity.jwt` of the
+ * hosted lifecycle requests and never logs, stores or decodes it. The host rotates it only by
+ * replacing the workload and accepts only the token it issued last.
+ *
+ * These are shipped values that running workloads read: never rename them.
+ */
+export const hostedAppRuntimeIdentityKeys = {
+  appInstanceId: 'SERVEZONE_APP_INSTANCE_ID',
+  hostType: 'SERVEZONE_APP_HOST_TYPE',
+  runtimeUrl: 'SERVEZONE_RUNTIME_URL',
+  controlToken: 'SERVEZONE_APP_CONTROL_TOKEN',
+} as const;
+
 export interface IHostedAppMachineClaims {
   sub: string;
   aud: typeof hostedAppMachineAudience;

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';

package/ts/data/user.ts

@@ -22,7 +22,13 @@ export type TServiceDeploymentCapability =
   | 'deployment:rollback-image'
   | 'deployment:rollback-route'
   | 'deployment:retry'
-  | 'deployment:cleanup';
+  | 'deployment:cleanup'
+  /**
+   * Start a release redeploy of the service (`startServiceReleaseDeployment`): Cloudly deploys one
+   * of the service's own accepted, retained releases again and runs the operation itself. Granted
+   * on an existing-service grant only; administrators hold it implicitly.
+   */
+  | 'deployment:redeploy-release';
 
 /**
  * Server-persisted authority for one logical service. These grants are never
@@ -64,6 +70,7 @@ const serviceDeploymentCapabilities = new Set<TServiceDeploymentCapability>([
   'deployment:rollback-route',
   'deployment:retry',
   'deployment:cleanup',
+  'deployment:redeploy-release',
 ]);
 
 const deploymentBoundaryIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
@@ -112,6 +119,10 @@ export const validateServiceDeploymentGrant = (
     && capabilities.includes('deployment:adopt-existing')) {
     errors.push('deployment:adopt-existing requires an existing-service grant');
   }
+  if (capabilities && grant.scope !== 'service'
+    && capabilities.includes('deployment:redeploy-release')) {
+    errors.push('deployment:redeploy-release requires an existing-service grant');
+  }
   if (capabilities && grant.scope !== 'organization-service-slot'
     && capabilities.includes('deployment:import-legacy')) {
     errors.push('deployment:import-legacy requires an organization-service-slot grant');

package/ts/requests/deployment.ts

@@ -75,6 +75,11 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * @deprecated Stores a deployment record and deploys nothing; no runtime writes these records.
+ * A deployment is a release redeploy (`startServiceReleaseDeployment`) or a tsdeploy deployment.
+ * It is removed in the next Cloudly major.
+ */
 export interface IReq_Any_Cloudly_CreateDeployment
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,

package/ts/requests/service.ts

@@ -17,6 +17,10 @@ import type {
   IServiceDeploymentStatus,
 } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
+import type {
+  IServiceDeploymentOperationHistoryQuery,
+  IServiceReleaseDeploymentStartInput,
+} from '../data/deploymentreleaseredeploy.js';
 import type {
   ILegacyServiceHostObservation,
   ILegacyServiceRuntimeAttestation,
@@ -214,6 +218,11 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * @deprecated Rolls back by re-opening an earlier operation; nothing calls it and it is not
+ * maintained. A rollback is a release redeploy (`startServiceReleaseDeployment`) of the earlier
+ * release. It is removed in the next Cloudly major.
+ */
 export interface IRequest_Any_Cloudly_RollbackServiceImageRelease
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -262,6 +271,52 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Starts a release redeploy: Cloudly deploys one of the service's own accepted, retained and whole
+ * releases again (`data.deploymentreleaseredeploy`) and runs the operation itself to `succeeded` or
+ * `failed`. The answer is the operation as it stands once it was started; its state, failure and
+ * evidence are read with `readServiceDeploymentStatus`, never assumed from the answer.
+ *
+ * An administrator or a deployment machine user holding `deployment:redeploy-release` on the
+ * service may start one; the operation's actor is the caller. A refusal carries one of
+ * `data.serviceReleaseDeploymentRefusalCodes` or a shared deployment code in its `code`. The same
+ * `idempotencyKey` with the same request answers the operation it started.
+ */
+export interface IRequest_Any_Cloudly_StartServiceReleaseDeployment
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_StartServiceReleaseDeployment
+> {
+  method: 'startServiceReleaseDeployment';
+  request: {
+    identity: IIdentityCredential;
+  } & IServiceReleaseDeploymentStartInput;
+  response: {
+    operation: IServiceDeploymentOperation;
+  };
+}
+
+/**
+ * One page of a service's deployment operations, newest first: every operation of every origin
+ * (tsdeploy's and Cloudly's own). `nextBefore` names the operation the next page starts after and
+ * is absent on the last page. Administrators, or a deployment machine user holding
+ * `deployment:status` on the service.
+ */
+export interface IRequest_Any_Cloudly_GetServiceDeploymentOperations
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceDeploymentOperations
+> {
+  method: 'getServiceDeploymentOperations';
+  request: {
+    identity: IIdentityCredential;
+  } & IServiceDeploymentOperationHistoryQuery;
+  response: {
+    operations: IServiceDeploymentOperation[];
+    nextBefore?: string;
+  };
+}
+
 /**
  * Answers one deployment operation's status and advances it: a rolling-out operation whose runtime
  * evidence proves success or failure is transitioned before the answer. A deployment that polls