feat(core): stack synthesizers can be shared between stacks (#23571)

Currently, `StackSynthesizer` instances must be created fresh for each `Stack`. This makes it impossible to do things like specify the stack synthesizer once at the root of the construct tree (`App`), for example.

Lift that restriction: instances of default stack synthesizers can now be shared between multiple Stacks. User-written stack synthesizers can not magically be shared, but they can be made shareable by implementing `IReusableStackSynthesizer`.

Immediately add the feature of specyfing a single Stack Synthesizer at the top level.


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

packages/@aws-cdk/core/lib/app.ts

@@ -1,7 +1,9 @@
 import * as cxapi from '@aws-cdk/cx-api';
 import { Construct } from 'constructs';
 import * as fs from 'fs-extra';
+import { PRIVATE_CONTEXT_DEFAULT_STACK_SYNTHESIZER } from './private/private-context';
 import { addCustomSynthesis, ICustomSynthesis } from './private/synthesis';
+import { IReusableStackSynthesizer } from './stack-synthesizers';
 import { Stage } from './stage';
 
 const APP_SYMBOL = Symbol.for('@aws-cdk/core.App');
@@ -105,6 +107,17 @@ export interface AppProps {
    * @default true
    */
   readonly treeMetadata?: boolean;
+
+  /**
+   * The stack synthesizer to use by default for all Stacks in the App
+   *
+   * The Stack Synthesizer controls aspects of synthesis and deployment,
+   * like how assets are referenced and what IAM roles to use. For more
+   * information, see the README of the main CDK package.
+   *
+   * @default - A `DefaultStackSynthesizer` with default settings
+   */
+  readonly defaultStackSynthesizer?: IReusableStackSynthesizer;
 }
 
 /**
@@ -156,6 +169,10 @@ export class App extends Stage {
       this.node.setContext(cxapi.DISABLE_METADATA_STACK_TRACE, true);
     }
 
+    if (props.defaultStackSynthesizer) {
+      this.node.setContext(PRIVATE_CONTEXT_DEFAULT_STACK_SYNTHESIZER, props.defaultStackSynthesizer);
+    }
+
     const analyticsReporting = props.analyticsReporting ?? props.runtimeInfo;
 
     if (analyticsReporting !== undefined) {

packages/@aws-cdk/core/lib/private/private-context.ts

@@ -0,0 +1,10 @@
+/**
+ * Some construct-tree wide config we pass via context, because it's convenient.
+ *
+ * Users shouldn't touch these, and to make sure they don't we make sure the
+ * context keys have an unguessable prefix that is different on each execution.
+ */
+
+const PREFIX = `aws-cdk-private:${Math.random()}:`;
+
+export const PRIVATE_CONTEXT_DEFAULT_STACK_SYNTHESIZER = `${PREFIX}core/defaultStackSynthesizer`;

packages/@aws-cdk/core/lib/stack-synthesizers/bootstrapless-synthesizer.ts

@@ -33,6 +33,9 @@ export interface BootstraplessSynthesizerProps {
  * However, it will not assume asset buckets or repositories have been created,
  * and therefore does not support assets.
  *
+ * The name is poorly chosen -- it does still require bootstrapping, it just
+ * does not support assets.
+ *
  * Used by the CodePipeline construct for the support stacks needed for
  * cross-region replication S3 buckets. App builders do not need to use this
  * synthesizer directly.

packages/@aws-cdk/core/lib/stack-synthesizers/cli-credentials-synthesizer.ts

@@ -6,7 +6,7 @@ import { assertBound, StringSpecializer } from './_shared';
 import { AssetManifestBuilder } from './asset-manifest-builder';
 import { BOOTSTRAP_QUALIFIER_CONTEXT, DefaultStackSynthesizer } from './default-synthesizer';
 import { StackSynthesizer } from './stack-synthesizer';
-import { ISynthesisSession } from './types';
+import { ISynthesisSession, IReusableStackSynthesizer, IBoundStackSynthesizer } from './types';
 
 /**
  * Properties for the CliCredentialsStackSynthesizer
@@ -86,7 +86,7 @@ export interface CliCredentialsStackSynthesizerProps {
  * of the Bootstrap Stack V2 (also known as "modern bootstrap stack"). You can override
  * the default names using the synthesizer's construction properties.
  */
-export class CliCredentialsStackSynthesizer extends StackSynthesizer {
+export class CliCredentialsStackSynthesizer extends StackSynthesizer implements IReusableStackSynthesizer, IBoundStackSynthesizer {
   private qualifier?: string;
   private bucketName?: string;
   private repositoryName?: string;
@@ -140,6 +140,18 @@ export class CliCredentialsStackSynthesizer extends StackSynthesizer {
     /* eslint-enable max-len */
   }
 
+  /**
+   * Produce a bound Stack Synthesizer for the given stack.
+   *
+   * This method may be called more than once on the same object.
+   */
+  public reusableBind(stack: Stack): IBoundStackSynthesizer {
+    // Create a copy of the current object and bind that
+    const copy = Object.create(this);
+    copy.bind(stack);
+    return copy;
+  }
+
   public addFileAsset(asset: FileAssetSource): FileAssetLocation {
     assertBound(this.bucketName);
 

packages/@aws-cdk/core/lib/stack-synthesizers/default-synthesizer.ts

@@ -5,7 +5,7 @@ import { Token } from '../token';
 import { assertBound, StringSpecializer } from './_shared';
 import { AssetManifestBuilder } from './asset-manifest-builder';
 import { StackSynthesizer } from './stack-synthesizer';
-import { ISynthesisSession } from './types';
+import { ISynthesisSession, IReusableStackSynthesizer, IBoundStackSynthesizer } from './types';
 
 export const BOOTSTRAP_QUALIFIER_CONTEXT = '@aws-cdk/core:bootstrapQualifier';
 
@@ -227,7 +227,7 @@ export interface DefaultStackSynthesizerProps {
  * check to the template, to make sure the bootstrap stack is recent enough
  * to support all features expected by this synthesizer.
  */
-export class DefaultStackSynthesizer extends StackSynthesizer {
+export class DefaultStackSynthesizer extends StackSynthesizer implements IReusableStackSynthesizer, IBoundStackSynthesizer {
   /**
    * Default ARN qualifier
    */
@@ -324,6 +324,18 @@ export class DefaultStackSynthesizer extends StackSynthesizer {
     }
   }
 
+  /**
+   * Produce a bound Stack Synthesizer for the given stack.
+   *
+   * This method may be called more than once on the same object.
+   */
+  public reusableBind(stack: Stack): IBoundStackSynthesizer {
+    // Create a copy of the current object and bind that
+    const copy = Object.create(this);
+    copy.bind(stack);
+    return copy;
+  }
+
   /**
    * The qualifier used to bootstrap this stack
    */

packages/@aws-cdk/core/lib/stack-synthesizers/legacy.ts

@@ -4,9 +4,10 @@ import { Construct } from 'constructs';
 import { DockerImageAssetLocation, DockerImageAssetSource, FileAssetLocation, FileAssetSource } from '../assets';
 import { Fn } from '../cfn-fn';
 import { FileAssetParameters } from '../private/asset-parameters';
+import { Stack } from '../stack';
 import { assertBound } from './_shared';
 import { StackSynthesizer } from './stack-synthesizer';
-import { ISynthesisSession } from './types';
+import { ISynthesisSession, IReusableStackSynthesizer, IBoundStackSynthesizer } from './types';
 
 /**
  * The well-known name for the docker image asset ECR repository. All docker
@@ -44,7 +45,7 @@ const ASSETS_ECR_REPOSITORY_NAME_OVERRIDE_CONTEXT_KEY = 'assets-ecr-repository-n
  * This is the only StackSynthesizer that supports customizing asset behavior
  * by overriding `Stack.addFileAsset()` and `Stack.addDockerImageAsset()`.
  */
-export class LegacyStackSynthesizer extends StackSynthesizer {
+export class LegacyStackSynthesizer extends StackSynthesizer implements IReusableStackSynthesizer, IBoundStackSynthesizer {
   private cycle = false;
 
   /**
@@ -109,6 +110,18 @@ export class LegacyStackSynthesizer extends StackSynthesizer {
     this.emitArtifact(session);
   }
 
+  /**
+   * Produce a bound Stack Synthesizer for the given stack.
+   *
+   * This method may be called more than once on the same object.
+   */
+  public reusableBind(stack: Stack): IBoundStackSynthesizer {
+    // Create a copy of the current object and bind that
+    const copy = Object.create(this);
+    copy.bind(stack);
+    return copy;
+  }
+
   private doAddDockerImageAsset(asset: DockerImageAssetSource): DockerImageAssetLocation {
     // check if we have an override from context
     const repositoryNameOverride = this.boundStack.node.tryGetContext(ASSETS_ECR_REPOSITORY_NAME_OVERRIDE_CONTEXT_KEY);

packages/@aws-cdk/core/lib/stack-synthesizers/types.ts

@@ -16,7 +16,7 @@ export interface IStackSynthesizer {
   /**
    * Bind to the stack this environment is going to be used on
    *
-   * Must be called before any of the other methods are called.
+   * Must be called before any of the other methods are called, and can only be called once.
    */
   bind(stack: Stack): void;
 
@@ -40,6 +40,33 @@ export interface IStackSynthesizer {
   synthesize(session: ISynthesisSession): void;
 }
 
+/**
+ * Interface for Stack Synthesizers that can be used for more than one stack.
+ *
+ * Regular `IStackSynthesizer` instances can only be bound to a Stack once.
+ * `IReusableStackSynthesizer` instances.
+ *
+ * For backwards compatibility reasons, this class inherits from
+ * `IStackSynthesizer`, but if an object implements `IReusableStackSynthesizer`,
+ * no other methods than `reusableBind()` will be called.
+ */
+export interface IReusableStackSynthesizer extends IStackSynthesizer {
+  /**
+   * Produce a bound Stack Synthesizer for the given stack.
+   *
+   * This method may be called more than once on the same object.
+   */
+  reusableBind(stack: Stack): IBoundStackSynthesizer;
+}
+
+/**
+ * A Stack Synthesizer, obtained from `IReusableStackSynthesizer.`
+ *
+ * Just a type alias with a very concrete contract.
+ */
+export interface IBoundStackSynthesizer extends IStackSynthesizer {
+}
+
 /**
  * Represents a single session of synthesis. Passed into `Construct.synthesize()` methods.
  */
@@ -61,3 +88,10 @@ export interface ISynthesisSession {
   */
   validateOnSynth?: boolean;
 }
+
+/**
+ * Whether the given Stack Synthesizer is reusable or not
+ */
+export function isReusableStackSynthesizer(x: IStackSynthesizer): x is IReusableStackSynthesizer {
+  return !!(x as any).reusableBind;
+}

packages/@aws-cdk/core/lib/stack.ts

@@ -123,8 +123,17 @@ export interface StackProps {
   /**
    * Synthesis method to use while deploying this stack
    *
-   * @default - `DefaultStackSynthesizer` if the `@aws-cdk/core:newStyleStackSynthesis` feature flag
-   * is set, `LegacyStackSynthesizer` otherwise.
+   * The Stack Synthesizer controls aspects of synthesis and deployment,
+   * like how assets are referenced and what IAM roles to use. For more
+   * information, see the README of the main CDK package.
+   *
+   * If not specified, the `defaultStackSynthesizer` from `App` will be used.
+   * If that is not specified, `DefaultStackSynthesizer` is used if
+   * `@aws-cdk/core:newStyleStackSynthesis` is set to `true` or the CDK major
+   * version is v2. In CDK v1 `LegacyStackSynthesizer` is the default if no
+   * other synthesizer is specified.
+   *
+   * @default - The synthesizer specified on `App`, or `DefaultStackSynthesizer` otherwise.
    */
   readonly synthesizer?: IStackSynthesizer;
 
@@ -427,10 +436,18 @@ export class Stack extends Construct implements ITaggable {
     this._versionReportingEnabled = (props.analyticsReporting ?? this.node.tryGetContext(cxapi.ANALYTICS_REPORTING_ENABLED_CONTEXT))
       && !this.nestedStackParent;
 
-    this.synthesizer = props.synthesizer ?? (newStyleSynthesisContext
-      ? new DefaultStackSynthesizer()
-      : new LegacyStackSynthesizer());
-    this.synthesizer.bind(this);
+    const synthesizer = (props.synthesizer
+      ?? this.node.tryGetContext(PRIVATE_CONTEXT_DEFAULT_STACK_SYNTHESIZER)
+      ?? (newStyleSynthesisContext ? new DefaultStackSynthesizer() : new LegacyStackSynthesizer()));
+
+    if (isReusableStackSynthesizer(synthesizer)) {
+      // Produce a fresh instance for each stack (should have been the default behavior)
+      this.synthesizer = synthesizer.reusableBind(this);
+    } else {
+      // Bind the single instance in-place to the current stack (backwards compat)
+      this.synthesizer = synthesizer;
+      this.synthesizer.bind(this);
+    }
 
     props.permissionsBoundary?._bind(this);
 
@@ -1691,12 +1708,13 @@ import { FileSystem } from './fs';
 import { Names } from './names';
 import { Reference } from './reference';
 import { IResolvable } from './resolvable';
-import { DefaultStackSynthesizer, IStackSynthesizer, ISynthesisSession, LegacyStackSynthesizer, BOOTSTRAP_QUALIFIER_CONTEXT } from './stack-synthesizers';
+import { DefaultStackSynthesizer, IStackSynthesizer, ISynthesisSession, LegacyStackSynthesizer, BOOTSTRAP_QUALIFIER_CONTEXT, isReusableStackSynthesizer } from './stack-synthesizers';
 import { StringSpecializer } from './stack-synthesizers/_shared';
 import { Stage } from './stage';
 import { ITaggable, TagManager } from './tag-manager';
 import { Token, Tokenization } from './token';
 import { getExportable } from './private/refs';
 import { Fact, RegionInfo } from '@aws-cdk/region-info';
 import { deployTimeLookup } from './private/region-lookup';
-import { makeUniqueResourceName } from './private/unique-resource-name';
+import { makeUniqueResourceName } from './private/unique-resource-name';import { PRIVATE_CONTEXT_DEFAULT_STACK_SYNTHESIZER } from './private/private-context';
+

packages/@aws-cdk/core/package.json

@@ -126,6 +126,8 @@
       "construct-interface-extends-iconstruct:@aws-cdk/core.ICustomResourceProvider",
       "props-physical-name:@aws-cdk/core.CustomResourceProps",
       "integ-return-type:@aws-cdk/core.IStackSynthesizer.bind",
+      "integ-return-type:@aws-cdk/core.IBoundStackSynthesizer.bind",
+      "integ-return-type:@aws-cdk/core.IReusableStackSynthesizer.bind",
       "props-no-any:@aws-cdk/core.CfnJsonProps.value"
     ]
   },

packages/@aws-cdk/core/test/stack-synthesis/clicreds-synthesis.test.ts

@@ -207,16 +207,15 @@ describe('CLI creds synthesis', () => {
     expect(imageTag).toEqual('test-prefix-docker-asset-hash');
   });
 
-  test('cannot use same synthesizer for multiple stacks', () => {
+  test('can use same synthesizer for multiple stacks', () => {
     // GIVEN
     const synthesizer = new CliCredentialsStackSynthesizer();
 
     // WHEN
     new Stack(app, 'Stack2', { synthesizer });
-    expect(() => {
-      new Stack(app, 'Stack3', { synthesizer });
-    }).toThrow(/A StackSynthesizer can only be used for one Stack/);
+    new Stack(app, 'Stack3', { synthesizer });
 
+    app.synth();
   });
 });