refactor: readonly struct properties and hide internals (#2106)

This change upgrades the repo to jsii 0.8.0 which requires that all struct types (data interfaces like our "Props" interfaces) will be marked readonly in order to ensure they can be passed by-value.

The new jsii version also hides all members marked as @internal which means that those APIs will not be available from outside the framework.

Fixes awslabs/cdk-ops#321

BREAKING CHANGE: stack._toCloudFormation method is now unavailable and is replaced by @aws-cdk/assert.SynthUtils.toCloudFormation(stack).

packages/@aws-cdk/alexa-ask/lib/pipeline-actions.ts

@@ -8,32 +8,32 @@ export interface AlexaSkillDeployActionProps extends codepipeline.CommonActionPr
   /**
    * The client id of the developer console token
    */
-  clientId: cdk.Secret;
+  readonly clientId: cdk.Secret;
 
   /**
    * The client secret of the developer console token
    */
-  clientSecret: cdk.Secret;
+  readonly clientSecret: cdk.Secret;
 
   /**
    * The refresh token of the developer console token
    */
-  refreshToken: cdk.Secret;
+  readonly refreshToken: cdk.Secret;
 
   /**
    * The Alexa skill id
    */
-  skillId: string;
+  readonly skillId: string;
 
   /**
    * The source artifact containing the voice model and skill manifest
    */
-  inputArtifact: codepipeline.Artifact;
+  readonly inputArtifact: codepipeline.Artifact;
 
   /**
    * An optional artifact containing overrides for the skill manifest
    */
-  parameterOverridesArtifact?: codepipeline.Artifact;
+  readonly parameterOverridesArtifact?: codepipeline.Artifact;
 }
 
 /**

packages/@aws-cdk/app-delivery/lib/pipeline-deploy-stack-action.ts

@@ -8,39 +8,39 @@ export interface PipelineDeployStackActionProps {
   /**
    * The CDK stack to be deployed.
    */
-  stack: cdk.Stack;
+  readonly stack: cdk.Stack;
 
   /**
    * The CodePipeline stage in which to perform the deployment.
    */
-  stage: codepipeline.IStage;
+  readonly stage: codepipeline.IStage;
 
   /**
    * The CodePipeline artifact that holds the synthesized app, which is the
    * contents of the ``<directory>`` when running ``cdk synth -o <directory>``.
    */
-  inputArtifact: codepipeline.Artifact;
+  readonly inputArtifact: codepipeline.Artifact;
 
   /**
    * The name to use when creating a ChangeSet for the stack.
    *
    * @default CDK-CodePipeline-ChangeSet
    */
-  changeSetName?: string;
+  readonly changeSetName?: string;
 
   /**
    * The runOrder for the CodePipeline action creating the ChangeSet.
    *
    * @default 1
    */
-  createChangeSetRunOrder?: number;
+  readonly createChangeSetRunOrder?: number;
 
   /**
    * The runOrder for the CodePipeline action executing the ChangeSet.
    *
    * @default ``createChangeSetRunOrder + 1``
    */
-  executeChangeSetRunOrder?: number;
+  readonly executeChangeSetRunOrder?: number;
 
   /**
    * IAM role to assume when deploying changes.
@@ -51,7 +51,7 @@ export interface PipelineDeployStackActionProps {
    *
    * @default A fresh role with admin or no permissions (depending on the value of `adminPermissions`).
    */
-  role?: iam.IRole;
+  readonly role?: iam.IRole;
 
   /**
    * Acknowledge certain changes made as part of deployment
@@ -64,7 +64,7 @@ export interface PipelineDeployStackActionProps {
    * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#using-iam-capabilities
    * @default AnonymousIAM, unless `adminPermissions` is true
    */
-  capabilities?: cfn.CloudFormationCapabilities;
+  readonly capabilities?: cfn.CloudFormationCapabilities;
 
   /**
    * Whether to grant admin permissions to CloudFormation while deploying this template.
@@ -81,7 +81,7 @@ export interface PipelineDeployStackActionProps {
    * use `addToRolePolicy` and `capabilities` to control what the CloudFormation
    * deployment is allowed to do.
    */
-  adminPermissions: boolean;
+  readonly adminPermissions: boolean;
 }
 
 /**

packages/@aws-cdk/assert/lib/expect.ts

@@ -1,26 +1,22 @@
 import cdk = require('@aws-cdk/cdk');
+import { ConstructNode, ConstructOrder } from '@aws-cdk/cdk';
 import api = require('@aws-cdk/cx-api');
 import { StackInspector } from './inspector';
+import { SynthUtils } from './synth-utils';
 
 export function expect(stack: api.SynthesizedStack | cdk.Stack, skipValidation = false): StackInspector {
   // Can't use 'instanceof' here, that breaks if we have multiple copies
   // of this library.
   let sstack: api.SynthesizedStack;
 
-  if (isStackClassInstance(stack)) {
-    if (!skipValidation) {
-      // Do a prepare-and-validate run over the given stack
-      stack.node.prepareTree();
-
-      const errors = stack.node.validateTree();
-      if (errors.length > 0) {
-        throw new Error(`Stack validation failed:\n${errors.map(e => `${e.message} at: ${e.source.node.scope}`).join('\n')}`);
-      }
-    }
+  if (cdk.Stack.isStack(stack)) {
+    const session = SynthUtils.synthesize(stack, {
+      skipValidation
+    });
 
     sstack = {
       name: stack.name,
-      template: stack._toCloudFormation(),
+      template: SynthUtils.templateForStackName(session, stack.name),
       metadata: collectStackMetadata(stack.node),
       environment: {
         name: 'test',
@@ -35,13 +31,9 @@ export function expect(stack: api.SynthesizedStack | cdk.Stack, skipValidation =
   return new StackInspector(sstack);
 }
 
-function isStackClassInstance(x: api.SynthesizedStack | cdk.Stack): x is cdk.Stack {
-  return '_toCloudFormation' in x;
-}
-
-function collectStackMetadata(root: cdk.ConstructNode): api.StackMetadata {
+function collectStackMetadata(root: ConstructNode): api.StackMetadata {
   const result: api.StackMetadata = {};
-  for (const construct of root.findAll(cdk.ConstructOrder.PreOrder)) {
+  for (const construct of root.findAll(ConstructOrder.PreOrder)) {
     const path = `/${root.id}/${construct.node.path}`;
     for (const entry of construct.node.metadata) {
       result[path] = result[path] || [];

packages/@aws-cdk/assert/lib/index.ts

@@ -1,6 +1,7 @@
 export * from './assertion';
 export * from './expect';
 export * from './inspector';
+export * from './synth-utils';
 
 export * from './assertions/exist';
 export * from './assertions/have-resource';

packages/@aws-cdk/assert/lib/synth-utils.ts

@@ -0,0 +1,17 @@
+import { ISynthesisSession, Stack, SynthesisOptions, Synthesizer } from '@aws-cdk/cdk';
+
+export class SynthUtils {
+  public static toCloudFormation(stack: Stack, options: SynthesisOptions = { }): any {
+    const session = this.synthesize(stack, options);
+    return this.templateForStackName(session, stack.name);
+  }
+
+  public static templateForStackName(session: ISynthesisSession, stackName: string): any {
+    return session.store.readJson(session.getArtifact(stackName).properties!.templateFile);
+  }
+
+  public static synthesize(stack: Stack, options: SynthesisOptions): ISynthesisSession {
+    const synth = new Synthesizer();
+    return synth.synthesize(stack, options);
+  }
+}

packages/@aws-cdk/assets-docker/lib/image-asset.ts

@@ -9,7 +9,7 @@ export interface DockerImageAssetProps {
   /**
    * The directory where the Dockerfile is stored
    */
-  directory: string;
+  readonly directory: string;
 
   /**
    * ECR repository name
@@ -20,7 +20,7 @@ export interface DockerImageAssetProps {
    *
    * @default automatically derived from the asset's ID.
    */
-  repositoryName?: string;
+  readonly repositoryName?: string;
 }
 
 /**

packages/@aws-cdk/assets-docker/test/test.image-asset.ts

@@ -1,4 +1,4 @@
-import { expect, haveResource } from '@aws-cdk/assert';
+import { expect, haveResource, SynthUtils } from '@aws-cdk/assert';
 import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 import { Test } from 'nodeunit';
@@ -18,7 +18,7 @@ export = {
     });
 
     // THEN
-    const template = stack._toCloudFormation();
+    const template = SynthUtils.toCloudFormation(stack);
 
     test.deepEqual(template.Parameters.ImageImageName5E684353, {
       Type: 'String',

packages/@aws-cdk/assets/lib/asset.ts

@@ -25,18 +25,18 @@ export interface GenericAssetProps {
   /**
    * The disk location of the asset.
    */
-  path: string;
+  readonly path: string;
 
   /**
    * The packaging type for this asset.
    */
-  packaging: AssetPackaging;
+  readonly packaging: AssetPackaging;
 
   /**
    * A list of principals that should be able to read this asset from S3.
    * You can use `asset.grantRead(principal)` to grant read permissions later.
    */
-  readers?: iam.IPrincipal[];
+  readonly readers?: iam.IPrincipal[];
 }
 
 /**
@@ -184,13 +184,13 @@ export interface FileAssetProps {
   /**
    * File path.
    */
-  path: string;
+  readonly path: string;
 
   /**
    * A list of principals that should be able to read this file asset from S3.
    * You can use `asset.grantRead(principal)` to grant read permissions later.
    */
-  readers?: iam.IPrincipal[];
+  readonly readers?: iam.IPrincipal[];
 }
 
 /**
@@ -206,13 +206,13 @@ export interface ZipDirectoryAssetProps {
   /**
    * Path of the directory.
    */
-  path: string;
+  readonly path: string;
 
   /**
    * A list of principals that should be able to read this ZIP file from S3.
    * You can use `asset.grantRead(principal)` to grant read permissions later.
    */
-  readers?: iam.IPrincipal[];
+  readonly readers?: iam.IPrincipal[];
 }
 
 /**

packages/@aws-cdk/assets/test/test.asset.ts

@@ -1,4 +1,4 @@
-import { expect, haveResource, ResourcePart } from '@aws-cdk/assert';
+import { expect, haveResource, ResourcePart, SynthUtils } from '@aws-cdk/assert';
 import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 import cxapi = require('@aws-cdk/cx-api');
@@ -30,7 +30,7 @@ export = {
     });
 
     // verify that now the template contains parameters for this asset
-    const template = stack._toCloudFormation();
+    const template = SynthUtils.toCloudFormation(stack);
     test.equal(template.Parameters.MyAssetS3Bucket68C9B344.Type, 'String');
     test.equal(template.Parameters.MyAssetS3VersionKey68E1A45D.Type, 'String');
 
@@ -74,7 +74,7 @@ export = {
     });
 
     // verify that now the template contains parameters for this asset
-    const template = stack._toCloudFormation();
+    const template = SynthUtils.toCloudFormation(stack);
     test.equal(template.Parameters.MyAssetS3Bucket68C9B344.Type, 'String');
     test.equal(template.Parameters.MyAssetS3VersionKey68E1A45D.Type, 'String');
 

packages/@aws-cdk/aws-apigateway/lib/deployment.ts

@@ -7,12 +7,12 @@ export interface DeploymentProps  {
   /**
    * The Rest API to deploy.
    */
-  api: IRestApi;
+  readonly api: IRestApi;
 
   /**
    * A description of the purpose of the API Gateway deployment.
    */
-  description?: string;
+  readonly description?: string;
 
   /**
    * When an API Gateway model is updated, a new deployment will automatically be created.
@@ -21,7 +21,7 @@ export interface DeploymentProps  {
    *
    * @default false
    */
-  retainDeployments?: boolean;
+  readonly retainDeployments?: boolean;
 }
 
 /**