feat(toolkit-lib): hotswap messages and structured data

.projenrc.ts

@@ -702,6 +702,7 @@ const tmpToolkitHelpers = configureProject(
       'fast-check',
     ],
     deps: [
+      cloudAssemblySchema.name,
       'archiver',
       'glob',
       'semver',

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/hotswap.ts

@@ -0,0 +1,151 @@
+import type { PropertyDifference, Resource } from '@aws-cdk/cloudformation-diff';
+import type * as cxapi from '@aws-cdk/cx-api';
+import type { ResourceMetadata } from '../../resource-metadata/resource-metadata';
+
+/**
+ * A resource affected by a change
+ */
+export interface AffectedResource {
+  /**
+   * The logical ID of the affected resource in the template
+   */
+  readonly logicalId: string;
+  /**
+   * The CloudFormation type of the resource
+   * This could be a custom type.
+   */
+  readonly resourceType: string;
+  /**
+   * The display name of the resource type
+   * Usually a more user friendly variation of the resource type.
+   */
+  readonly displayType?: string;
+  /**
+   * The physical name of the resource when deployed.
+   *
+   * A physical name is not always available, e.g. new resources will not have one until after the deployment
+   */
+  readonly physicalName?: string;
+  /**
+   * Resource metadata attached to the logical id from the cloud assembly
+   *
+   * This is only present if the resource is present in the current Cloud Assembly,
+   * i.e. resource deletions will not have metadata.
+   */
+  readonly metadata?: ResourceMetadata;
+}
+
+/**
+ * Represents a change in a resource
+ */
+export interface ResourceChange {
+  /**
+   * The logical ID of the resource which is being changed
+   */
+  readonly logicalId: string;
+  /**
+   * The value the resource is being updated from
+   */
+  readonly oldValue: Resource;
+  /**
+   * The value the resource is being updated to
+   */
+  readonly newValue: Resource;
+  /**
+   * The changes made to the resource properties
+   */
+  readonly propertyUpdates: Record<string, PropertyDifference<unknown>>;
+  /**
+   * Resource metadata for the change from the cloud assembly
+   *
+   * This is only present if the resource is present in the current Cloud Assembly,
+   * i.e. resource deletions will not have metadata.
+   */
+  readonly metadata?: ResourceMetadata;
+}
+
+export interface HotswappableChange {
+  /**
+   * The resource change that is causing the hotswap.
+   */
+  readonly cause: ResourceChange;
+  /**
+   * A list of resources that are being hotswapped as part of the change
+   */
+  readonly resources: AffectedResource[];
+}
+
+export enum NonHotswappableReason {
+  /**
+   * Tags are not hotswappable
+   */
+  TAGS = 'tags',
+  /**
+   * Changed resource properties are not hotswappable on this resource type
+   */
+  PROPERTIES = 'properties',
+  /**
+   * A stack output has changed
+   */
+  OUTPUT = 'output',
+  /**
+   * A dependant resource is not hotswappable
+   */
+  DEPENDENCY_UNSUPPORTED = 'dependency-unsupported',
+  /**
+   * The resource type is not hotswappable
+   */
+  RESOURCE_UNSUPPORTED = 'resource-unsupported',
+  /**
+   * The resource is created in the deployment
+   */
+  RESOURCE_CREATION = 'resource-creation',
+  /**
+   * The resource is removed in the deployment
+   */
+  RESOURCE_DELETION = 'resource-deletion',
+  /**
+   * The resource identified by the logical id has its type changed
+   */
+  RESOURCE_TYPE_CHANGED = 'resource-type-changed',
+  /**
+   * The nested stack is created in the deployment
+   */
+  NESTED_STACK_CREATION = 'nested-stack-creation',
+}
+
+////////////////////////////////
+
+/**
+ * The result of an attempted hotswap deployment
+ */
+export interface HotswapResult {
+  /**
+   * The stack that was hotswapped
+   */
+  readonly stack: cxapi.CloudFormationStackArtifact;
+  /**
+   * Whether hotswapping happened or not.
+   *
+   * `false` indicates that the deployment could not be hotswapped and full deployment may be attempted as fallback.
+   */
+  readonly hotswapped: boolean;
+
+  /**
+   * The changes that were deemed hotswappable
+   */
+  readonly hotswappableChanges: any[];
+
+  /**
+   * The changes that were deemed not hotswappable
+   */
+  readonly nonHotswappableChanges: any[];
+}
+
+export interface HotswapDeployment {
+  readonly stack: cxapi.CloudFormationStackArtifact;
+}
+
+export interface HotswapChange {
+  readonly displayName: string;
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/index.ts

@@ -13,3 +13,4 @@ export * from './watch';
 export * from './stack-details';
 export * from './diff';
 export * from './logs-monitor';
+export * from './hotswap';

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/stack-activity.ts

@@ -1,7 +1,7 @@
-import type { MetadataEntry } from '@aws-cdk/cloud-assembly-schema';
 import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
 import type { StackEvent } from '@aws-sdk/client-cloudformation';
 import type { StackProgress } from './progress';
+import type { ResourceMetadata } from '../../resource-metadata/resource-metadata';
 
 /**
  * Payload when stack monitoring is starting or stopping for a given stack deployment.
@@ -48,6 +48,9 @@ export interface StackActivity {
 
   /**
    * Additional resource metadata
+   *
+   * This information is only available if the information is available in the current cloud assembly.
+   * I.e. no `metadata` will not be available for resource deletion events.
    */
   readonly metadata?: ResourceMetadata;
 
@@ -56,8 +59,3 @@ export interface StackActivity {
    */
   readonly progress: StackProgress;
 }
-
-export interface ResourceMetadata {
-  entry: MetadataEntry;
-  constructPath: string;
-}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/messages.ts

@@ -5,6 +5,7 @@ import type { BootstrapEnvironmentProgress } from '../payloads/bootstrap-environ
 import type { MissingContext, UpdatedContext } from '../payloads/context';
 import type { BuildAsset, DeployConfirmationRequest, PublishAsset, StackDeployProgress, SuccessfulDeployStackResult } from '../payloads/deploy';
 import type { StackDestroy, StackDestroyProgress } from '../payloads/destroy';
+import type { AffectedResource, HotswapDeployment, HotswappableChange } from '../payloads/hotswap';
 import type { StackDetailsPayload } from '../payloads/list';
 import type { CloudWatchLogEvent, CloudWatchLogMonitorControlEvent } from '../payloads/logs-monitor';
 import type { StackRollbackProgress } from '../payloads/rollback';
@@ -21,7 +22,7 @@ import type { FileWatchEvent, WatchSettings } from '../payloads/watch';
  * - X900-X999 are reserved for results
  */
 export const IO = {
-  // Defaults
+  // Defaults (0000)
   DEFAULT_TOOLKIT_INFO: make.info({
     code: 'CDK_TOOLKIT_I0000',
     description: 'Default info messages emitted from the Toolkit',
@@ -35,7 +36,7 @@ export const IO = {
     description: 'Default warning messages emitted from the Toolkit',
   }),
 
-  // 1: Synth
+  // 1: Synth (1xxx)
   CDK_TOOLKIT_I1000: make.info<Duration>({
     code: 'CDK_TOOLKIT_I1000',
     description: 'Provides synthesis times.',
@@ -57,7 +58,7 @@ export const IO = {
     interface: 'AssemblyData',
   }),
 
-  // 2: List
+  // 2: List (2xxx)
   CDK_TOOLKIT_I2901: make.result<StackDetailsPayload>({
     code: 'CDK_TOOLKIT_I2901',
     description: 'Provides details on the selected stacks and their dependencies',
@@ -70,9 +71,9 @@ export const IO = {
     description: 'Resource import failed',
   }),
 
-  // 4: Diff
+  // 4: Diff (4xxx)
 
-  // 5: Deploy & Watch
+  // 5: Deploy & Watch (5xxx)
   CDK_TOOLKIT_I5000: make.info<Duration>({
     code: 'CDK_TOOLKIT_I5000',
     description: 'Provides deployment times',
@@ -129,14 +130,13 @@ export const IO = {
     description: 'Confirm deploy security sensitive changes',
     interface: 'DeployConfirmationRequest',
   }),
-
   CDK_TOOLKIT_I5100: make.info<StackDeployProgress>({
     code: 'CDK_TOOLKIT_I5100',
     description: 'Stack deploy progress',
     interface: 'StackDeployProgress',
   }),
 
-  // Assets
+  // Assets (52xx)
   CDK_TOOLKIT_I5210: make.trace<BuildAsset>({
     code: 'CDK_TOOLKIT_I5210',
     description: 'Started building a specific asset',
@@ -147,7 +147,6 @@ export const IO = {
     description: 'Building the asset has completed',
     interface: 'Duration',
   }),
-
   CDK_TOOLKIT_I5220: make.trace<PublishAsset>({
     code: 'CDK_TOOLKIT_I5220',
     description: 'Started publishing a specific asset',
@@ -159,7 +158,7 @@ export const IO = {
     interface: 'Duration',
   }),
 
-  // Watch
+  // Watch (53xx)
   CDK_TOOLKIT_I5310: make.debug<WatchSettings>({
     code: 'CDK_TOOLKIT_I5310',
     description: 'The computed settings used for file watching',
@@ -189,7 +188,39 @@ export const IO = {
     description: 'Queued watch deployment started',
   }),
 
-  // Stack Monitor
+  // Hotswap (54xx)
+  CDK_TOOLKIT_I5400: make.trace<HotswapDeployment>({
+    code: 'CDK_TOOLKIT_I5400',
+    description: 'Starting hotswap deployment',
+    interface: 'HotswapDeployment',
+  }),
+  CDK_TOOLKIT_I5401: make.trace<HotswappableChange>({
+    code: 'CDK_TOOLKIT_I5401',
+    description: 'A hotswappable change is processed as part of a hotswap deployment',
+    interface: 'HotswappableChange',
+  }),
+  CDK_TOOLKIT_I5402: make.trace<HotswappableChange>({
+    code: 'CDK_TOOLKIT_I5402',
+    description: 'The hotswappable change has completed',
+    interface: 'HotswappableChange',
+  }),
+  CDK_TOOLKIT_I5403: make.info<AffectedResource>({
+    code: 'CDK_TOOLKIT_I5403',
+    description: 'Resource affected by the current hotswap operation',
+    interface: 'AffectedResource',
+  }),
+  CDK_TOOLKIT_I5404: make.info<AffectedResource>({
+    code: 'CDK_TOOLKIT_I5404',
+    description: 'Resource affected by the current hotswap operation has finished changing',
+    interface: 'HotswapChange',
+  }),
+  CDK_TOOLKIT_I5410: make.info<Duration>({
+    code: 'CDK_TOOLKIT_I5410',
+    description: 'Hotswap deployment end, a full deployment might still follow if needed',
+    interface: 'Duration',
+  }),
+
+  // Stack Monitor (55xx)
   CDK_TOOLKIT_I5501: make.info<StackMonitoringControlEvent>({
     code: 'CDK_TOOLKIT_I5501',
     description: 'Stack Monitoring: Start monitoring of a single stack',
@@ -206,7 +237,7 @@ export const IO = {
     interface: 'StackMonitoringControlEvent',
   }),
 
-  // Success
+  // Success (59xx)
   CDK_TOOLKIT_I5900: make.result<SuccessfulDeployStackResult>({
     code: 'CDK_TOOLKIT_I5900',
     description: 'Deployment results on success',
@@ -232,7 +263,7 @@ export const IO = {
     interface: 'ErrorPayload',
   }),
 
-  // 6: Rollback
+  // 6: Rollback (6xxx)
   CDK_TOOLKIT_I6000: make.info<Duration>({
     code: 'CDK_TOOLKIT_I6000',
     description: 'Provides rollback times',
@@ -254,7 +285,7 @@ export const IO = {
     interface: 'ErrorPayload',
   }),
 
-  // 7: Destroy
+  // 7: Destroy (7xxx)
   CDK_TOOLKIT_I7000: make.info<Duration>({
     code: 'CDK_TOOLKIT_I7000',
     description: 'Provides destroy times',
@@ -297,7 +328,7 @@ export const IO = {
     interface: 'ErrorPayload',
   }),
 
-  // 9: Bootstrap
+  // 9: Bootstrap (9xxx)
   CDK_TOOLKIT_I9000: make.info<Duration>({
     code: 'CDK_TOOLKIT_I9000',
     description: 'Provides bootstrap times',
@@ -443,4 +474,9 @@ export const SPAN = {
     start: IO.CDK_TOOLKIT_I5220,
     end: IO.CDK_TOOLKIT_I5221,
   },
+  HOTSWAP: {
+    name: 'hotswap-deployment',
+    start: IO.CDK_TOOLKIT_I5400,
+    end: IO.CDK_TOOLKIT_I5410,
+  },
 } satisfies Record<string, SpanDefinition<any, any>>;