feat(cdk): construct.uniqueId and relax construct id constraints

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

@@ -47,7 +47,7 @@ export class App extends Root {
                 throw new Error(`The child ${child.toString()} of Program must be a Stack`);
             }
 
-            out[child.name] = child as Stack;
+            out[child.id] = child as Stack;
         }
         return out;
     }
@@ -113,7 +113,7 @@ export class App extends Root {
         }
 
         return {
-            name: stack.name,
+            name: stack.id,
             environment,
             missing: Object.keys(stack.missingContext).length ? stack.missingContext : undefined,
             template: stack.toCloudFormation(),

packages/@aws-cdk/cdk/lib/cloudformation/logical-id.ts

@@ -1,11 +1,7 @@
+import { makeUniqueId } from '../util/uniqueid';
 import { StackElement } from "./stack";
 
-// tslint:disable-next-line:no-var-requires
-const md5 = require('../util/md5');
-
 const PATH_SEP = '/';
-const HASH_LEN = 8;
-const MAX_HUMAN_LEN = 240; // max ID len is 255
 
 /**
  * Interface for classes that implementation logical ID assignment strategies
@@ -55,42 +51,10 @@ export interface IAddressingScheme {
  */
 export class HashedAddressingScheme implements IAddressingScheme {
     public allocateAddress(addressComponents: string[]): string {
-        addressComponents = addressComponents.filter(x => x !== HIDDEN_ID);
-
-        if (addressComponents.length === 0) {
-            throw new Error('Construct has empty Logical ID');
-        }
-
-        // top-level resources will simply use the `name` as-is in order to support
-        // transparent migration of cloudformation templates to the CDK without the
-        // need to rename all resources.
-        if (addressComponents.length === 1) {
-            return addressComponents[0];
-        }
-
-        const hash = pathHash(addressComponents);
-        const human = removeDupes(addressComponents)
-            .filter(x => x !== HIDDEN_FROM_HUMAN_ID)
-            .join('')
-            .slice(0, MAX_HUMAN_LEN);
-
-        return human + hash;
+        return makeUniqueId(addressComponents);
     }
 }
 
-/**
- * Resources with this ID are hidden from humans
- *
- * They do not appear in the human-readable part of the logical ID,
- * but they are included in the hash calculation.
- */
-const HIDDEN_FROM_HUMAN_ID = 'Resource';
-
-/**
- * Resources with this ID are complete hidden from the logical ID calculation.
- */
-const HIDDEN_ID = 'Default';
-
 /**
  * Class that keeps track of the logical IDs that are assigned to resources
  *
@@ -176,15 +140,6 @@ export class LogicalIDs {
     }
 }
 
-/**
- * Take a hash of the given path.
- *
- * The hash is limited in size.
- */
-function pathHash(path: string[]): string {
-    return md5(path.join(PATH_SEP)).slice(0, HASH_LEN).toUpperCase();
-}
-
 const VALID_LOGICALID_REGEX = /^[A-Za-z][A-Za-z0-9]{1,254}$/;
 
 /**
@@ -195,21 +150,3 @@ function validateLogicalId(logicalId: string) {
         throw new Error(`Logical ID must adhere to the regular expression: ${VALID_LOGICALID_REGEX.toString()}, got '${logicalId}'`);
     }
 }
-
-/**
- * Remove duplicate "terms" from the path list
- *
- * If a component name is completely the same as the suffix of
- * the previous component name, we get rid of it.
- */
-function removeDupes(path: string[]): string[] {
-    const ret = new Array<string>();
-
-    for (const component of path) {
-        if (ret.length === 0 || !ret[ret.length - 1].endsWith(component)) {
-            ret.push(component);
-        }
-    }
-
-    return ret;
-}

packages/@aws-cdk/cdk/lib/cloudformation/output.ts

@@ -91,7 +91,7 @@ export class Output extends StackElement {
             this.export = props.export;
         } else if (!props.disableExport) {
             // prefix export name with stack name since exports are global within account + region.
-            const stackName = Stack.find(this).name;
+            const stackName = Stack.find(this).id;
             this.export = stackName ? stackName + ':' : '';
             this.export += this.logicalId;
         }

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

@@ -332,7 +332,7 @@ export abstract class StackElement extends Construct implements IDependable {
      * Return the path with respect to the stack
      */
     public get stackPath(): string {
-        return this.ancestors(this.stack).map(c => c.name).join(PATH_SEP);
+        return this.ancestors(this.stack).map(c => c.id).join(PATH_SEP);
     }
 
     public get dependencyElements(): IDependable[] {

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

@@ -1,23 +1,40 @@
 import cxapi = require('@aws-cdk/cx-api');
+import { makeUniqueId } from '../util/uniqueid';
 export const PATH_SEP = '/';
 
 /**
  * Represents the building block of the construct graph.
  * When a construct is created, it is always added as a child
  */
 export class Construct {
-    private static readonly VALID_NAME_REGEX = /^[A-Za-z][A-Za-z0-9]*$/;
-
     /**
      * Returns the parent of this node or undefined if this is a root node.
      */
     public readonly parent?: Construct;
 
     /**
-     * The name of this construct
+     * @deprecated use `id`
      */
     public readonly name: string;
 
+    /**
+     * The subtree-local id of the construct.
+     * This id is unique within the subtree. To obtain a tree-unique id, use `uniqueId`.
+     */
+    public readonly id: string;
+
+    /**
+     * The full path of this construct in the tree.
+     * Components are separated by '/'.
+     */
+    public readonly path: string;
+
+    /**
+     * A tree-unique alpha-numeric identifier for this construct.
+     * Includes all components of the tree.
+     */
+    public readonly uniqueId: string;
+
     /**
      * List of children and their names
      */
@@ -37,28 +54,33 @@ export class Construct {
      * @param parent The parent construct
      * @param props  Properties for this construct
      */
-    constructor(parent: Construct, name: string) {
-        this.name = name;
+    constructor(parent: Construct, id: string) {
+        this.id = id;
+        this.name = id; // legacy
         this.parent = parent;
 
         // We say that parent is required, but some root constructs bypass the type checks and
         // actually pass in 'undefined'.
         if (parent != null) {
-            if (name === '') {
+            if (id === '') {
                 throw new Error('Only root constructs may have an empty name');
             }
 
             // Has side effect so must be very last thing in constructor
-            parent.addChild(this, this.name);
+            parent.addChild(this, this.id);
         } else {
             // This is a root construct.
-            this.name = name;
+            this.id = id;
         }
 
         // Validate the name we ended up with
-        if (this.name !== '') {
-            this._validateName(this.name);
+        if (this.id !== '') {
+            this._validateName(this.id);
         }
+
+        const components = this.rootPath().map(c => c.id);
+        this.path = components.join(PATH_SEP);
+        this.uniqueId = components.length > 0 ? makeUniqueId(components) : '';
     }
 
     /**
@@ -77,7 +99,7 @@ export class Construct {
         for (let i = 0; i < depth; ++i) {
             out += '  ';
         }
-        const name = this.name || '';
+        const name = this.id || '';
         out += `${this.typename}${name.length > 0 ? ' [' + name + ']' : ''}\n`;
         for (const child of this.children) {
             out += child.toTreeString(depth + 1);
@@ -137,7 +159,7 @@ export class Construct {
      */
     public setContext(key: string, value: any) {
         if (this.children.length > 0) {
-            const names = this.children.map(c => c.name);
+            const names = this.children.map(c => c.id);
             throw new Error('Cannot set context after children have been added: ' + names.join(','));
         }
         this.context[key] = value;
@@ -173,15 +195,6 @@ export class Construct {
         return value;
     }
 
-    /**
-     * Returns the path of all constructs from root to this construct, in string form.
-     *
-     * @returns /-separated path of this Construct.
-     */
-    public get path(): string {
-        return this.rootPath().map(c => c.name).join(PATH_SEP);
-    }
-
     /**
      * An array of metadata objects associated with this construct.
      * This can be used, for example, to implement support for deprecation notices, source mapping, etc.
@@ -281,17 +294,12 @@ export class Construct {
     }
 
     /**
-     * Validate that the name of the construct is a legal identifier
-     *
-     * At the moment, we restrict these to valid CloudFormation identifiers.
-     *
-     * Protected so it can be overridden by subclasses. Starts with _ to hide the virtual function from JSII,
-     * because we don't want this validation to involve asynchrony. This restricts it to only
-     * be overridable in (Type|Java)Script, but that suffices for now.
+     * Validate that the name of the construct is a legal identifier.
+     * Construct names can be any characters besides the path separator.
      */
     protected _validateName(name: string) {
-        if (!Construct.VALID_NAME_REGEX.test(name)) {
-            throw new Error(`Name must adhere to the regular expression: ${Construct.VALID_NAME_REGEX.toString()}, got '${name}'`);
+        if (name.indexOf(PATH_SEP) !== -1) {
+            throw new Error(`Construct names cannot include '${PATH_SEP}': ${name}`);
         }
     }
 

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

@@ -37,16 +37,16 @@ export namespace jsx {
      * @returns A Construct object
      */
     export function construct(tree: any, parent?: Construct): Construct {
-        const name = (tree.props && tree.props.name) || '';
-        const root = new tree.type(parent, name, tree.props); // create root
+        const id = (tree.props && tree.props.id) || '';
+        const root = new tree.type(parent, id, tree.props); // create root
         createChildren(root, tree.children);
         return root;
     }
 
     function createChildren(parent: Construct, children: any[]) {
         for (const child of children) {
-            const name = (child.props && child.props.name) || '';
-            const childObj = new child.type(parent, name, child.props);
+            const id = (child.props && child.props.id) || '';
+            const childObj = new child.type(parent, id, child.props);
             createChildren(childObj, child.children);
         }
     }

packages/@aws-cdk/cdk/lib/util/uniqueid.ts

@@ -0,0 +1,85 @@
+// tslint:disable-next-line:no-var-requires
+const md5 = require('./md5');
+
+/**
+ * Resources with this ID are hidden from humans
+ *
+ * They do not appear in the human-readable part of the logical ID,
+ * but they are included in the hash calculation.
+ */
+const HIDDEN_FROM_HUMAN_ID = 'Resource';
+
+/**
+ * Resources with this ID are complete hidden from the logical ID calculation.
+ */
+const HIDDEN_ID = 'Default';
+
+const PATH_SEP = '/';
+
+const HASH_LEN = 8;
+const MAX_HUMAN_LEN = 240; // max ID len is 255
+
+/**
+ * Given a set of named path components, returns a unique alpha-numeric identifier
+ * with a maximum length of 255. This is done by calculating a hash on the full path
+ * and using it as a suffix of a length-limited "human" rendition of the path components.
+ *
+ * @param components The path components
+ */
+export function makeUniqueId(components: string[]) {
+    components = components.filter(x => x !== HIDDEN_ID);
+
+    if (components.length === 0) {
+        throw new Error('Unable to calculate a unique ID for an empty path');
+    }
+
+    // top-level resources will simply use the `name` as-is in order to support
+    // transparent migration of cloudformation templates to the CDK without the
+    // need to rename all resources.
+    if (components.length === 1) {
+        return components[0];
+    }
+
+    const hash = pathHash(components);
+    const human = removeDupes(components)
+        .map(removeNonAlpha)
+        .filter(x => x !== HIDDEN_FROM_HUMAN_ID)
+        .join('')
+        .slice(0, MAX_HUMAN_LEN);
+
+    return human + hash;
+}
+
+/**
+ * Take a hash of the given path.
+ *
+ * The hash is limited in size.
+ */
+function pathHash(path: string[]): string {
+    return md5(path.join(PATH_SEP)).slice(0, HASH_LEN).toUpperCase();
+}
+
+/**
+ * Removes all non-alphanumeric characters in a string.
+ */
+function removeNonAlpha(s: string) {
+    return s.replace(/[^A-Za-z0-9]/g, '');
+}
+
+/**
+ * Remove duplicate "terms" from the path list
+ *
+ * If a component name is completely the same as the suffix of
+ * the previous component name, we get rid of it.
+ */
+function removeDupes(path: string[]): string[] {
+    const ret = new Array<string>();
+
+    for (const component of path) {
+        if (ret.length === 0 || !ret[ret.length - 1].endsWith(component)) {
+            ret.push(component);
+        }
+    }
+
+    return ret;
+}

packages/@aws-cdk/cdk/test/cloudformation/test.logical-id.ts

@@ -131,6 +131,17 @@ const uniqueTests = {
         // THEN: same ID, same object
         test.equal(theId1, theId2);
 
+        test.done();
+    },
+
+    'non-alphanumeric characters are removed from the human part of the logical ID'(test: Test) {
+        const scheme = new HashedAddressingScheme();
+        const val1 = scheme.allocateAddress([ 'Foo-bar', 'B00m', 'Hello_World', '&&Horray Horray.' ]);
+        const val2 = scheme.allocateAddress([ 'Foobar', 'B00m', 'HelloWorld', 'HorrayHorray' ]);
+
+        // same human part, different hash
+        test.deepEqual(val1, 'FoobarB00mHelloWorldHorrayHorray640E99FB');
+        test.deepEqual(val2, 'FoobarB00mHelloWorldHorrayHorray744334FD');
         test.done();
     }
 };