feat(core): present reason for cyclic references (#2061)

To help people debugging cyclic references, we now trace the "reason"
a cyclic reference got added, so that we can present the conflicting
references instead of just presenting an error. Fix the order of
the error message, which was the wrong way around.

Clean up references a little:

- Split out `Reference` and `CfnReference`, which got conflated in an
  undesirable way. `Reference` is now officially the base class for all
  references, and `CfnReference` is only one implementation of it for
  CloudFormation references.
- Make 'scope' required for references, the only place where it was
  potentially empty was for CFN Pseudo Parameters, refactored those to
  not use classes anymore (because there's no need to).
- Get rid of 'Ref', the class wasn't being very useful.
- Make a dependency Construct => Stack lazy (it was conflicting at
  load time with the Stack => Construct dependency which is more
  important).

Author: rix0rrr

packages/@aws-cdk/aws-codebuild/lib/project.ts

@@ -602,7 +602,7 @@ export class Project extends ProjectBase {
 
     let cache: CfnProject.ProjectCacheProperty | undefined;
     if (props.cacheBucket) {
-      const cacheDir = props.cacheDir != null ? props.cacheDir : new cdk.AwsNoValue().toString();
+      const cacheDir = props.cacheDir != null ? props.cacheDir : cdk.Aws.noValue;
       cache = {
         type: 'S3',
         location: cdk.Fn.join('/', [props.cacheBucket.bucketName, cacheDir]),

packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/imported.ts

@@ -24,7 +24,7 @@ export abstract class ImportedTargetGroupBase extends cdk.Construct implements I
     super(scope, id);
 
     this.targetGroupArn = props.targetGroupArn;
-    this.loadBalancerArns = props.loadBalancerArns || new cdk.AwsNoValue().toString();
+    this.loadBalancerArns = props.loadBalancerArns || cdk.Aws.noValue;
   }
 
   public export() {

packages/@aws-cdk/aws-ses/lib/receipt-rule-action.ts

@@ -280,7 +280,7 @@ export class ReceiptRuleLambdaAction implements IReceiptRuleAction {
       this.props.function.addPermission(permissionId, {
         action: 'lambda:InvokeFunction',
         principal: new iam.ServicePrincipal('ses.amazonaws.com'),
-        sourceAccount: new cdk.ScopedAws().accountId
+        sourceAccount: cdk.Aws.accountId
       });
     }
 
@@ -344,7 +344,7 @@ export class ReceiptRuleS3Action implements IReceiptRuleAction {
       .addServicePrincipal('ses.amazonaws.com')
       .addResource(this.props.bucket.arnForObjects(`${keyPattern}*`))
       .addCondition('StringEquals', {
-        'aws:Referer': new cdk.ScopedAws().accountId
+        'aws:Referer': cdk.Aws.accountId
       });
 
     this.props.bucket.addToResourcePolicy(s3Statement);
@@ -362,7 +362,7 @@ export class ReceiptRuleS3Action implements IReceiptRuleAction {
             'kms:EncryptionContext:aws:ses:message-id': 'false'
           },
           StringEquals: {
-            'kms:EncryptionContext:aws:ses:source-account': new cdk.ScopedAws().accountId
+            'kms:EncryptionContext:aws:ses:source-account': cdk.Aws.accountId
           }
         });
 

packages/@aws-cdk/cdk/lib/cfn-element.ts

@@ -126,17 +126,6 @@ export abstract class CfnElement extends Construct {
   }
 }
 
-import { Reference } from "./reference";
-
-/**
- * A generic, untyped reference to a Stack Element
- */
-export class Ref extends Reference {
-  constructor(element: CfnElement) {
-    super({ Ref: element.logicalId }, 'Ref', element);
-  }
-}
-
 /**
  * Base class for referenceable CloudFormation constructs which are not Resources
  *
@@ -152,8 +141,16 @@ export abstract class CfnRefElement extends CfnElement {
    * Returns a token to a CloudFormation { Ref } that references this entity based on it's logical ID.
    */
   public get ref(): string {
-    return new Ref(this).toString();
+    return this.referenceToken.toString();
+  }
+
+  /**
+   * Return a token that will CloudFormation { Ref } this stack element
+   */
+  protected get referenceToken(): Token {
+    return new CfnReference({ Ref: this.logicalId }, 'Ref', this);
   }
 }
 
-import { findTokens } from "./resolve";
+import { CfnReference } from "./cfn-reference";
+import { findTokens } from "./resolve";

packages/@aws-cdk/cdk/lib/cfn-parameter.ts

@@ -1,4 +1,4 @@
-import { CfnRefElement, Ref } from './cfn-element';
+import { CfnRefElement } from './cfn-element';
 import { Construct } from './construct';
 import { Token } from './token';
 
@@ -99,7 +99,7 @@ export class CfnParameter extends CfnRefElement {
   constructor(scope: Construct, id: string, props: CfnParameterProps) {
     super(scope, id);
     this.properties = props;
-    this.value = new Ref(this);
+    this.value = this.referenceToken;
     this.stringValue = this.value.toString();
     this.stringListValue = this.value.toList();
   }

packages/@aws-cdk/cdk/lib/cfn-reference.ts

@@ -0,0 +1,115 @@
+import { Reference } from "./reference";
+
+const CFN_REFERENCE_SYMBOL = Symbol('@aws-cdk/cdk.CfnReference');
+
+/**
+ * A Token that represents a CloudFormation reference to another resource
+ *
+ * If these references are used in a different stack from where they are
+ * defined, appropriate CloudFormation `Export`s and `Fn::ImportValue`s will be
+ * synthesized automatically instead of the regular CloudFormation references.
+ *
+ * Additionally, the dependency between the stacks will be recorded, and the toolkit
+ * will make sure to deploy producing stack before the consuming stack.
+ *
+ * This magic happens in the prepare() phase, where consuming stacks will call
+ * `consumeFromStack` on these Tokens and if they happen to be exported by a different
+ * Stack, we'll register the dependency.
+ */
+export class CfnReference extends Reference {
+  /**
+   * Check whether this is actually a Reference
+   */
+  public static isCfnReference(x: Token): x is CfnReference {
+    return (x as any)[CFN_REFERENCE_SYMBOL] === true;
+  }
+
+  /**
+   * What stack this Token is pointing to
+   */
+  private readonly producingStack?: Stack;
+
+  /**
+   * The Tokens that should be returned for each consuming stack (as decided by the producing Stack)
+   */
+  private readonly replacementTokens: Map<Stack, Token>;
+
+  private readonly originalDisplayName: string;
+
+  constructor(value: any, displayName: string, target: Construct) {
+    if (typeof(value) === 'function') {
+        throw new Error('Reference can only hold CloudFormation intrinsics (not a function)');
+    }
+    // prepend scope path to display name
+    super(value, `${target.node.id}.${displayName}`, target);
+    this.originalDisplayName = displayName;
+    this.replacementTokens = new Map<Stack, Token>();
+
+    this.producingStack = target.node.stack;
+    Object.defineProperty(this, CFN_REFERENCE_SYMBOL, { value: true });
+  }
+
+  public resolve(context: ResolveContext): any {
+    // If we have a special token for this consuming stack, resolve that. Otherwise resolve as if
+    // we are in the same stack.
+    const token = this.replacementTokens.get(context.scope.node.stack);
+    if (token) {
+      return token.resolve(context);
+    } else {
+      return super.resolve(context);
+    }
+  }
+
+  /**
+   * Register a stack this references is being consumed from.
+   */
+  public consumeFromStack(consumingStack: Stack, consumingConstruct: IConstruct) {
+    if (this.producingStack && this.producingStack !== consumingStack && !this.replacementTokens.has(consumingStack)) {
+      // We're trying to resolve a cross-stack reference
+      consumingStack.addDependency(this.producingStack, `${consumingConstruct.node.path} -> ${this.target.node.path}.${this.originalDisplayName}`);
+      this.replacementTokens.set(consumingStack, this.exportValue(this, consumingStack));
+    }
+  }
+
+  /**
+   * Export a Token value for use in another stack
+   *
+   * Works by mutating the producing stack in-place.
+   */
+  private exportValue(tokenValue: Token, consumingStack: Stack): Token {
+    const producingStack = this.producingStack!;
+
+    if (producingStack.env.account !== consumingStack.env.account || producingStack.env.region !== consumingStack.env.region) {
+      throw new Error('Can only reference cross stacks in the same region and account.');
+    }
+
+    // Ensure a singleton "Exports" scoping Construct
+    // This mostly exists to trigger LogicalID munging, which would be
+    // disabled if we parented constructs directly under Stack.
+    // Also it nicely prevents likely construct name clashes
+
+    const exportsName = 'Exports';
+    let stackExports = producingStack.node.tryFindChild(exportsName) as Construct;
+    if (stackExports === undefined) {
+      stackExports = new Construct(producingStack, exportsName);
+    }
+
+    // Ensure a singleton CfnOutput for this value
+    const resolved = producingStack.node.resolve(tokenValue);
+    const id = 'Output' + JSON.stringify(resolved);
+    let output = stackExports.node.tryFindChild(id) as CfnOutput;
+    if (!output) {
+      output = new CfnOutput(stackExports, id, { value: tokenValue });
+    }
+
+    // We want to return an actual FnImportValue Token here, but Fn.importValue() returns a 'string',
+    // so construct one in-place.
+    return new Token({ 'Fn::ImportValue': output.obtainExportName() });
+  }
+
+}
+
+import { CfnOutput } from "./cfn-output";
+import { Construct, IConstruct } from "./construct";
+import { Stack } from "./stack";
+import { ResolveContext, Token } from "./token";

packages/@aws-cdk/cdk/lib/cfn-resource.ts

@@ -1,13 +1,13 @@
 import cxapi = require('@aws-cdk/cx-api');
 import { CfnCondition } from './cfn-condition';
 import { Construct, IConstruct } from './construct';
-import { Reference } from './reference';
 import { CreationPolicy, DeletionPolicy, UpdatePolicy } from './resource-policy';
 import { TagManager } from './tag-manager';
 import { capitalizePropertyNames, ignoreEmpty, PostResolveToken } from './util';
 // import required to be here, otherwise causes a cycle when running the generated JavaScript
 // tslint:disable-next-line:ordered-imports
 import { CfnRefElement } from './cfn-element';
+import { CfnReference } from './cfn-reference';
 
 export interface CfnResourceProps {
   /**
@@ -133,7 +133,7 @@ export class CfnResource extends CfnRefElement {
    * @param attributeName The name of the attribute.
    */
   public getAtt(attributeName: string) {
-    return new Reference({ 'Fn::GetAtt': [this.logicalId, attributeName] }, attributeName, this);
+    return new CfnReference({ 'Fn::GetAtt': [this.logicalId, attributeName] }, attributeName, this);
   }
 
   /**

packages/@aws-cdk/cdk/lib/construct.ts

@@ -46,11 +46,11 @@ export class ConstructNode {
   private readonly _children: { [name: string]: IConstruct } = { };
   private readonly context: { [key: string]: any } = { };
   private readonly _metadata = new Array<MetadataEntry>();
-  private readonly references = new Set<Token>();
+  private readonly references = new Set<Reference>();
   private readonly dependencies = new Set<IDependable>();
 
   /** Will be used to cache the value of ``this.stack``. */
-  private _stack?: Stack;
+  private _stack?: import('./stack').Stack;
 
   /**
    * If this is set to 'true'. addChild() calls for this construct and any child
@@ -91,11 +91,13 @@ export class ConstructNode {
   /**
    * The stack the construct is a part of.
    */
-  public get stack(): Stack {
+  public get stack(): import('./stack').Stack {
+    // Lazy import to break cyclic import
+    const stack: typeof import('./stack') = require('./stack');
     return this._stack || (this._stack = _lookStackUp(this));
 
-    function _lookStackUp(_this: ConstructNode) {
-      if (Stack.isStack(_this.host)) {
+    function _lookStackUp(_this: ConstructNode): import('./stack').Stack  {
+      if (stack.Stack.isStack(_this.host)) {
         return _this.host;
       }
       if (!_this.scope) {
@@ -471,7 +473,7 @@ export class ConstructNode {
    */
   public recordReference(...refs: Token[]) {
     for (const ref of refs) {
-      if (ref.isReference) {
+      if (Reference.isReference(ref)) {
         this.references.add(ref);
       }
     }
@@ -480,12 +482,12 @@ export class ConstructNode {
   /**
    * Return all references of the given type originating from this node or any of its children
    */
-  public findReferences(): Token[] {
-    const ret = new Set<Token>();
+  public findReferences(): OutgoingReference[] {
+    const ret = new Set<OutgoingReference>();
 
     function recurse(node: ConstructNode) {
-      for (const ref of node.references) {
-        ret.add(ref);
+      for (const reference of node.references) {
+        ret.add({ source: node.host, reference });
       }
 
       for (const child of node.children) {
@@ -729,5 +731,10 @@ export interface Dependency {
   target: IConstruct;
 }
 
+export interface OutgoingReference {
+  source: IConstruct;
+  reference: Reference;
+}
+
 // Import this _after_ everything else to help node work the classes out in the correct order...
-import { Stack } from './stack';
+import { Reference } from './reference';

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

@@ -16,6 +16,7 @@ export * from './logical-id';
 export * from './cfn-mapping';
 export * from './cfn-output';
 export * from './cfn-parameter';
+export * from './cfn-reference';
 export * from './pseudo';
 export * from './cfn-resource';
 export * from './resource-policy';