feat: idiomize cloudformation intrinsics and pseudo parameters #1428

eladb · 2018-12-25T12:46:32Z

Refactor CloudFormation intrinsic functions so that they will have a more idiomatic shape. They have been converted from classes (e.g. new FnJoin(...)) to static methods (e.g. Fn.join(...)). Condition functions are mapped to Fn.conditionXxx and return an FnCondition object.

Furthermore, return type of these static methods are now tokens represented as the resolved type (i.e. string or string[]) instead of CloudFormationToken objects. This allows using these functions and pseudo parameters naturally (instead of requiring the use of .toString() or .toList()).

Fixes #202

BREAKING CHANGE: CloudFormation intrinsic functions are now represented as static methods under the Fn class (e.g. Fn.join(...) instead of new FnJoin(...).toString()).

Pull Request Checklist

Testing
- Unit test added
- CLI change?: manually run integration tests and paste output as a PR comment
- cdk-init template change?: coordinated update of integration tests with team
Docs
- jsdocs: All public APIs documented
- README: README and/or documentation topic updated
Title and Description
- Change type: title prefixed with fix, feat will appear in changelog
- Title: use lower-case and doesn't end with a period
- Breaking?: last paragraph: "BREAKING CHANGE: <describe what changed + link for details>"
- Issues: Indicate issues fixed via: "Fixes #xxx" or "Closes #xxx"
Sensitive Modules (requires 2 PR approvers)
- IAM Policy Document (in @aws-cdk/aws-iam)
- EC2 Security Groups and ACLs (in @aws-cdk/aws-ec2)
- Grant APIs (only if not based on official documentation with a reference)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.

RomainMuller

Mostly goodness! A couple of comments though... Nothing too bad.

As discussed, it may be wise to revert the Aws changes as they'll unfortunately collide with #1436 in ways that might result in hardcore merge conflict pain.

RomainMuller · 2018-12-27T09:00:38Z

package.json

@@ -7,7 +7,7 @@
    "pkglint": "tools/pkglint/bin/pkglint -f ."
  },
  "devDependencies": {
-    "@types/node": "^8.10.38",
+    "@types/node": "8.10.38",


Why the pinning?

For some reason it seems like npm keeps moving us to 10.x when we build in CI and then we get these unsolicited breakage of master. Other ideas?

packages/@aws-cdk/aws-cloudfront/lib/web_distribution.ts

packages/@aws-cdk/aws-codebuild/test/test.codebuild.ts

packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-target-group.ts

packages/@aws-cdk/aws-s3/lib/bucket.ts

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

RomainMuller · 2018-12-27T09:14:16Z

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

+   * @param value A string, such as "A", that you want to compare against a list of strings.
+   * @returns an FnCondition token
+   */
+  public static containsCondition(listOfStrings: string[], value: string): FnCondition {


I don't like the Condition suffix everywhere. It looks mighty redundant. In the case of containsConditions here, the name even would imply I'm checking if some array contains a FnCondition reference, which is not what it's doing.

I would at the very least remove the Condition suffix, and maybe ideally move this into a Condition class (Condition.equals(val, val), Condition.contains(arr, val), ...)

Some suffix/prefix is needed for two reasons:

Many of the condition functions use names that are reserved words (such as "if", "and", "or").

It should be possible for users to easily distinguish between condition functions and normal functions.

I agree about "containsCondition" implying the wrong thing.

Alternative options:

A prefix "condition": conditionContains, conditionAnd, etc

A postfix "cond": containsCond, andCond

A prefix "cond": condContains, condIf

Any other ideas?

I prefer going for a prefix (since we don't want to go full on namespace/class, that's what's closest), preferably condition (the short-hand doesn't improve much of anything).

RomainMuller · 2018-12-27T09:16:21Z

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

@@ -90,6 +100,8 @@ export class Parameter extends Referenceable {
    super(parent, name);
    this.properties = props;
    this.value = new Ref(this);
+    this.valueAsString = this.value.toString();
+    this.valueAsList = this.value.toList();


Am always somewhat annoyed that only one of those is valid for a given entity... And we allows both. But I guess we can't do better, can we?

I was thinking that we can also provide StringParameter and StringListParamater as sugar classes that will make this a bit more strongly-typed.

packages/@aws-cdk/cdk/test/cloudformation/test.fn.ts

RomainMuller · 2018-12-27T09:20:09Z

packages/@aws-cdk/cdk/test/cloudformation/test.rule.ts

-    rule.addAssertion(new FnEquals('lhs', 'rhs'), 'lhs equals rhs');
-    rule.addAssertion(new FnNot(new FnAnd(new FnContains([ 'hello', 'world' ], "world"))), 'some assertion');
+    rule.addAssertion(Fn.equalsCondition('lhs', 'rhs'), 'lhs equals rhs');
+    rule.addAssertion(Fn.notCondition(Fn.andCondition(Fn.containsCondition([ 'hello', 'world' ], "world"))), 'some assertion');


This... is where the helpers I mentioned previously come in handy... This Polish notation nonsense is a recipe for disaster. Also, it's so verbose!

See my note about not over indexing on the CFN conditions programming model. Especially not as part of this change.

This reverts commit 69da340.

eladb · 2018-12-27T10:22:17Z

Reverted the pseudo parameter change to avoid conflict with #1436

Fixes #742 Built on top of #1428 BREAKING CHANGE: AWS resource-related classes have been changed to conform to API guidelines: - `XxxRef` abstract classes are now `IXxx` interfaces - `XxxRefProps` are now `XxxImportProps` - `XxxRef.import(...)` are now `Xxx.import(...)` accept `XxxImportProps` and return `IXxx` - `export(): XxxImportProps` is now defined in `IXxx` and implemented by imported resources - Lambda's static "metric" methods moved from `lambda.FunctionRef` to `lambda.Function`. - Route53 record classes now require a `zone` when created (not assuming zone is the parent construct).

mergify · 2019-09-23T15:07:50Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

Elad Ben-Israel added 3 commits December 25, 2018 12:42

Convert FnXxx to Fn.xxx()

71b60e4

Pseudo parameters from new Aws.Xxx() to Aws.xxx

69da340

Finalize change

f2827d0

eladb requested review from Doug-AWS, RomainMuller, skinny85, SoManyHs and a team as code owners December 25, 2018 12:46

Move FnCondition to condition.ts

0424e80

eladb mentioned this pull request Dec 26, 2018

feat: aws resource api linting (breaking changes) #1434

Merged

4 tasks

RomainMuller approved these changes Dec 27, 2018

View reviewed changes

eladb mentioned this pull request Dec 27, 2018

FnSplit: consider improving the API #1437

Closed

Elad Ben-Israel added 4 commits December 27, 2018 11:46

CR fixes

cf839e0

Revert "Pseudo parameters from new Aws.Xxx() to Aws.xxx"

603a460

This reverts commit 69da340.

Do not use FnBase as an external base class

0130c76

Merge branch 'master' into benisrae/intrinsics-and-pseudo-refactor

b9fb939

Elad Ben-Israel added 2 commits December 27, 2018 13:41

Remove merge error

dbd80d9

Rename condition methods

e967937

eladb merged commit 04217a5 into master Dec 27, 2018

eladb deleted the benisrae/intrinsics-and-pseudo-refactor branch December 27, 2018 14:36

NGL321 added the contribution/core This is a PR that came from AWS. label Sep 23, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: idiomize cloudformation intrinsics and pseudo parameters #1428

feat: idiomize cloudformation intrinsics and pseudo parameters #1428

eladb commented Dec 25, 2018 •

edited

RomainMuller left a comment

RomainMuller Dec 27, 2018

eladb Dec 27, 2018

RomainMuller Dec 27, 2018

eladb Dec 27, 2018

RomainMuller Dec 27, 2018

RomainMuller Dec 27, 2018

eladb Dec 27, 2018

RomainMuller Dec 27, 2018

eladb Dec 27, 2018

eladb commented Dec 27, 2018

mergify bot commented Sep 23, 2019

feat: idiomize cloudformation intrinsics and pseudo parameters #1428

feat: idiomize cloudformation intrinsics and pseudo parameters #1428

Conversation

eladb commented Dec 25, 2018 • edited

Pull Request Checklist

RomainMuller left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eladb commented Dec 27, 2018

mergify bot commented Sep 23, 2019

eladb commented Dec 25, 2018 •

edited