chore(core): add Stage class

Stages synthesize to embedded Cloud Assemblies.

Ideally there should be CLI support for embedded Cloud Assemblies, but there isn't yet. It will be coming soon, I promise.

To implement this, had to grab the reins of synthesis back from the constructs library. I've taken the liberty to declare synthesis in constructs deprecated.

Took the opportunity where we're declaring a new type of construct in the construct hierarchy to clean up the default stack name generation (get rid of the hashes and add a prefix, which will make deploying multiple Stages in the same environment just naturally work out nicely in a non-ugly way).

Started to write a section in the README on Stacks and Stages, but I couldn't figure out how to write about the use for Stages without referencing unreleased things, so I gave up. For the same reason, made this a chore as there is no user value right now so why would this show up in
the CHANGELOG?

Also moved the "artifacts" classes in cx-api together to unclutter the file structure.

Primary author: @rix0rrr

allowed-breaking-changes.txt

@@ -1,5 +1,9 @@
+# Actually adding any artifact type will break the load() type signature  because I could have written
+# const x: A | B = Manifest.load();
+# and that won't typecheck if Manifest.load() adds a union arm and now returns A | B | C.
+change-return-type:@aws-cdk/cloud-assembly-schema.Manifest.load
+
 removed:@aws-cdk/core.BootstraplessSynthesizer.DEFAULT_ASSET_PUBLISHING_ROLE_ARN
 removed:@aws-cdk/core.DefaultStackSynthesizer.DEFAULT_ASSET_PUBLISHING_ROLE_ARN
 removed:@aws-cdk/core.DefaultStackSynthesizerProps.assetPublishingExternalId
 removed:@aws-cdk/core.DefaultStackSynthesizerProps.assetPublishingRoleArn
-

packages/@aws-cdk/cloud-assembly-schema/lib/artifact-schema.ts

@@ -84,7 +84,27 @@ export interface TreeArtifactProperties {
   readonly file: string;
 }
 
+/**
+ * Artifact properties for nested cloud assemblies
+ */
+export interface NestedCloudAssemblyProperties  {
+  /**
+   * Relative path to the nested cloud assembly
+   */
+  readonly directoryName: string;
+
+  /**
+   * Display name for the cloud assembly
+   *
+   * @default - The artifact ID
+   */
+  readonly displayName?: string;
+}
+
 /**
  * Properties for manifest artifacts
  */
-export type ArtifactProperties = AwsCloudFormationStackProperties | AssetManifestProperties | TreeArtifactProperties;
+export type ArtifactProperties = AwsCloudFormationStackProperties
+| AssetManifestProperties
+| TreeArtifactProperties
+| NestedCloudAssemblyProperties;

packages/@aws-cdk/cloud-assembly-schema/lib/schema.ts

@@ -25,6 +25,11 @@ export enum ArtifactType {
    * Manifest for all assets in the Cloud Assembly
    */
   ASSET_MANIFEST = 'cdk:asset-manifest',
+
+  /**
+   * Nested Cloud Assembly
+   */
+  NESTED_CLOUD_ASSEMBLY = 'cdk:cloud-assembly',
 }
 
 /**

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -72,6 +72,9 @@
                         },
                         {
                             "$ref": "#/definitions/TreeArtifactProperties"
+                        },
+                        {
+                            "$ref": "#/definitions/NestedCloudAssemblyProperties"
                         }
                     ]
                 }
@@ -85,6 +88,7 @@
             "enum": [
                 "aws:cloudformation:stack",
                 "cdk:asset-manifest",
+                "cdk:cloud-assembly",
                 "cdk:tree",
                 "none"
             ],
@@ -331,6 +335,23 @@
                 "file"
             ]
         },
+        "NestedCloudAssemblyProperties": {
+            "description": "Artifact properties for nested cloud assemblies",
+            "type": "object",
+            "properties": {
+                "directoryName": {
+                    "description": "Relative path to the nested cloud assembly",
+                    "type": "string"
+                },
+                "displayName": {
+                    "description": "Display name for the cloud assembly (Default - The artifact ID)",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "directoryName"
+            ]
+        },
         "MissingContext": {
             "description": "Represents a missing piece of context.",
             "type": "object",

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.version.json

@@ -1 +1 @@
-{"version":"4.0.0"}
+{"version":"6.0.0"}

packages/@aws-cdk/cloud-assembly-schema/scripts/update-schema.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -euo pipefail
 scriptsdir=$(cd $(dirname $0) && pwd)
-packagedir=$(realpath ${scriptsdir}/..)
+packagedir=$(cd ${scriptsdir}/.. && pwd)
 
 # Output
 OUTPUT_DIR="${packagedir}/schema"

packages/@aws-cdk/core/README.md

@@ -17,6 +17,42 @@ Guide](https://docs.aws.amazon.com/cdk/latest/guide/home.html) for
 information of most of the capabilities of this library. The rest of this
 README will only cover topics not already covered in the Developer Guide.
 
+## Stacks and Stages
+
+A `Stack` is the smallest physical unit of deployment, and maps directly onto
+a CloudFormation Stack. You define a Stack by defining a subclass of `Stack`
+-- let's call it `MyStack` -- and instantiating the constructs that make up
+your application in `MyStack`'s constructor. You then instantiate this stack
+one or more times to define different instances of your application. For example,
+you can instantiate it once using few and cheap EC2 instances for testing,
+and once again using more and bigger EC2 instances for production.
+
+When your application grows, you may decide that it makes more sense to split it
+out across multiple `Stack` classes. This can happen for a number of reasons:
+
+- You could be starting to reach the maximum number of resources allowed in a single
+  stack (this is currently 200).
+- You could decide you want to separate out stateful resources and stateless resources
+  into separate stacks, so that it becomes easy to tear down and recreate the stacks
+  that don't have stateful resources.
+- There could be a single stack with resources (like a VPC) that are shared
+  between multiple instances of other stacks containing your applications.
+
+As soon as your conceptual application starts to encompass multiple stacks,
+it is convenient to wrap them in another construct that represents your
+logical application. You can then treat that new unit the same way you used
+to be able to treat a single stack: by instantiating it multiple times
+for different instances of your application.
+
+You can define a custom subclass of `Construct`, holding one or more
+`Stack`s, to represent a single logical instance of your application.
+
+As a final note: `Stack`s are not a unit of reuse. They describe physical
+deployment layouts, and as such are best left to application builders to
+organize their deployments with. If you want to vend a reusable construct,
+define it as a subclasses of `Construct`: the consumers of your construct
+will decide where to place it in their own stacks.
+
 ## Nested Stacks
 
 [Nested stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html) are stacks created as part of other stacks. You create a nested stack within another stack by using the `NestedStack` construct.
@@ -36,7 +72,7 @@ class MyNestedStack extends cfn.NestedStack {
   constructor(scope: Construct, id: string, props?: cfn.NestedStackProps) {
     super(scope, id, props);
 
-    new s3.Bucket(this, 'NestedBucket');  
+    new s3.Bucket(this, 'NestedBucket');
   }
 }
 
@@ -236,7 +272,7 @@ new CustomResource(this, 'MyMagicalResource', {
     Property2: 'bar'
   },
 
-  // the ARN of the provider (SNS/Lambda) which handles 
+  // the ARN of the provider (SNS/Lambda) which handles
   // CREATE, UPDATE or DELETE events for this resource type
   // see next section for details
   serviceToken: 'ARN'
@@ -292,7 +328,7 @@ function getOrCreate(scope: Construct): sns.Topic {
 Every time a resource event occurs (CREATE/UPDATE/DELETE), an SNS notification
 is sent to the SNS topic. Users must process these notifications (e.g. through a
 fleet of worker hosts) and submit success/failure responses to the
-CloudFormation service. 
+CloudFormation service.
 
 Set `serviceToken` to `topic.topicArn`  in order to use this provider:
 
@@ -311,7 +347,7 @@ new CustomResource(this, 'MyResource', {
 
 An AWS lambda function is called *directly* by CloudFormation for all resource
 events. The handler must take care of explicitly submitting a success/failure
-response to the CloudFormation service and handle various error cases. 
+response to the CloudFormation service and handle various error cases.
 
 Set `serviceToken` to `lambda.functionArn` to use this provider:
 
@@ -361,7 +397,7 @@ exports.handler = async function(event) {
   const id = event.PhysicalResourceId; // only for "Update" and "Delete"
   const props = event.ResourceProperties;
   const oldProps = event.OldResourceProperties; // only for "Update"s
-  
+
   switch (event.RequestType) {
     case "Create":
       // ...
@@ -371,7 +407,7 @@ exports.handler = async function(event) {
 
       // if an error is thrown, a FAILED response will be submitted to CFN
       throw new Error('Failed!');
-      
+
     case "Delete":
       // ...
   }
@@ -403,10 +439,10 @@ Here is an complete example of a custom resource that summarizes two numbers:
 
 ```js
 exports.handler = async e => {
-  return { 
-    Data: { 
+  return {
+    Data: {
       Result: e.ResourceProperties.lhs + e.ResourceProperties.rhs
-    } 
+    }
   };
 };
 ```
@@ -463,7 +499,7 @@ Handlers are implemented as AWS Lambda functions, which means that they can be
 implemented in any Lambda-supported runtime. Furthermore, this provider has an
 asynchronous mode, which means that users can provide an `isComplete` lambda
 function which is called periodically until the operation is complete. This
-allows implementing providers that can take up to two hours to stabilize. 
+allows implementing providers that can take up to two hours to stabilize.
 
 Set `serviceToken` to `provider.serviceToken` to use this type of provider:
 
@@ -487,7 +523,7 @@ See the [documentation](https://docs.aws.amazon.com/cdk/api/latest/docs/custom-r
 Every time a resource event occurs (CREATE/UPDATE/DELETE), an SNS notification
 is sent to the SNS topic. Users must process these notifications (e.g. through a
 fleet of worker hosts) and submit success/failure responses to the
-CloudFormation service. 
+CloudFormation service.
 
 Set `serviceToken` to `topic.topicArn`  in order to use this provider:
 
@@ -506,7 +542,7 @@ new CustomResource(this, 'MyResource', {
 
 An AWS lambda function is called *directly* by CloudFormation for all resource
 events. The handler must take care of explicitly submitting a success/failure
-response to the CloudFormation service and handle various error cases. 
+response to the CloudFormation service and handle various error cases.
 
 Set `serviceToken` to `lambda.functionArn` to use this provider:
 
@@ -532,7 +568,7 @@ Handlers are implemented as AWS Lambda functions, which means that they can be
 implemented in any Lambda-supported runtime. Furthermore, this provider has an
 asynchronous mode, which means that users can provide an `isComplete` lambda
 function which is called periodically until the operation is complete. This
-allows implementing providers that can take up to two hours to stabilize. 
+allows implementing providers that can take up to two hours to stabilize.
 
 Set `serviceToken` to `provider.serviceToken` to use this provider:
 
@@ -827,7 +863,7 @@ to use intrinsic functions in keys. Since JSON map keys must be strings, it is
 impossible to use intrinsics in keys and `CfnJson` can help.
 
 The following example defines an IAM role which can only be assumed by
-principals that are tagged with a specific tag. 
+principals that are tagged with a specific tag.
 
 ```ts
 const tagParam = new CfnParameter(this, 'TagName');

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

@@ -1,7 +1,5 @@
 import * as cxapi from '@aws-cdk/cx-api';
-import { Construct, ConstructNode } from './construct-compat';
-import { prepareApp } from './private/prepare-app';
-import { collectRuntimeInformation } from './private/runtime-info';
+import { Assembly } from './assembly';
 import { TreeMetadata } from './private/tree-metadata';
 
 const APP_SYMBOL = Symbol.for('@aws-cdk/core.App');
@@ -76,8 +74,7 @@ export interface AppProps {
  *
  * @see https://docs.aws.amazon.com/cdk/latest/guide/apps.html
  */
-export class App extends Construct {
-
+export class App extends Assembly {
   /**
    * Checks if an object is an instance of the `App` class.
    * @returns `true` if `obj` is an `App`.
@@ -87,16 +84,14 @@ export class App extends Construct {
     return APP_SYMBOL in obj;
   }
 
-  private _assembly?: cxapi.CloudAssembly;
-  private readonly runtimeInfo: boolean;
-  private readonly outdir?: string;
-
   /**
    * Initializes a CDK application.
    * @param props initialization properties
    */
   constructor(props: AppProps = {}) {
-    super(undefined as any, '');
+    super(undefined as any, '', {
+      outdir: props.outdir ?? process.env[cxapi.OUTDIR_ENV],
+    });
 
     Object.defineProperty(this, APP_SYMBOL, { value: true });
 
@@ -110,10 +105,6 @@ export class App extends Construct {
       this.node.setContext(cxapi.DISABLE_VERSION_REPORTING, true);
     }
 
-    // both are reverse logic
-    this.runtimeInfo = this.node.tryGetContext(cxapi.DISABLE_VERSION_REPORTING) ? false : true;
-    this.outdir = props.outdir || process.env[cxapi.OUTDIR_ENV];
-
     const autoSynth = props.autoSynth !== undefined ? props.autoSynth : cxapi.OUTDIR_ENV in process.env;
     if (autoSynth) {
       // synth() guarantuees it will only execute once, so a default of 'true'
@@ -126,33 +117,6 @@ export class App extends Construct {
     }
   }
 
-  /**
-   * Synthesizes a cloud assembly for this app. Emits it to the directory
-   * specified by `outdir`.
-   *
-   * @returns a `CloudAssembly` which can be used to inspect synthesized
-   * artifacts such as CloudFormation templates and assets.
-   */
-  public synth(): cxapi.CloudAssembly {
-    // we already have a cloud assembly, no-op for you
-    if (this._assembly) {
-      return this._assembly;
-    }
-
-    const assembly = ConstructNode.synth(this.node, {
-      outdir: this.outdir,
-      runtimeInfo: this.runtimeInfo ? collectRuntimeInformation() : undefined,
-    });
-
-    this._assembly = assembly;
-    return assembly;
-  }
-
-  protected prepare() {
-    super.prepare();
-    prepareApp(this);
-  }
-
   private loadContext(defaults: { [key: string]: string } = { }) {
     // prime with defaults passed through constructor
     for (const [ k, v ] of Object.entries(defaults)) {