feat(core): present reason for cyclic references

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';