fix: update all 'onXxx' methods to be CloudWatch Events (#2609)

Make all CloudWatch events methods consistent. All methods called
'onXxx()' are now guaranteed to be CloudWatch Events triggers, all
non-CWE methods that started with 'on' are now called differently.

Introduce the 'onCloudTrailEvent' convention, to clearly signal
that the indicated event depend on the presence of a CloudTrail
Trail to capture it (as opposed to being intrinsically supported
by the service itself).

Introduce awslint rules to enforce these conventions.

Fixes #2278.

BREAKING CHANGES

* All `onXxx()` CloudWatch Event methods now have the signature:

```ts
resource.onEvent('SomeId', {
    target: new SomeTarget(...),
    // options
});
```

* CloudWatch: rename `onAlarm()` => `addAlarmAction()`, `onOk` =>
  `addOkAction`, `onInsufficientData` => `addInsufficientDataAction`.
* AutoScaling: rename `onLifecycleTransition` => `addLifecycleHook()`.
* LambdaDeploymentGroup: rename `onPreHook` => `addPreHook`,
  `onPostHook` => `addPostHook`.
* UserPool: rename all `onXxx` methods => `addXxxTrigger`.
* Repository: rename `onImagePushed` => `onCloudTrailImagePushed`.
* Bucket: rename `onEvent` => `addEventNotification`, `onObjectCreated`
  => `addObjectCreatedNotification`, `onObjectRemoved` =>
  `addObjectRemovedNotification`, `onPutObject` =>
  `onCloudTrailPutObject`.

packages/@aws-cdk/aws-applicationautoscaling/lib/step-scaling-policy.ts

@@ -108,7 +108,7 @@ export class StepScalingPolicy extends cdk.Construct {
  evaluationPeriods: 1,
  threshold,
  });
- this.lowerAlarm.onAlarm(this.lowerAction);
+ this.lowerAlarm.addAlarmAction(this.lowerAction);
  }
 
  if (alarms.upperAlarmIntervalIndex !== undefined) {
@@ -138,7 +138,7 @@ export class StepScalingPolicy extends cdk.Construct {
  evaluationPeriods: 1,
  threshold,
  });
- this.upperAlarm.onAlarm(this.upperAction);
+ this.upperAlarm.addAlarmAction(this.upperAction);
  }
  }
 }

packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts

@@ -193,7 +193,7 @@ abstract class AutoScalingGroupBase extends Resource implements IAutoScalingGrou
  /**
  * Send a message to either an SQS queue or SNS topic when instances launch or terminate
  */
- public onLifecycleTransition(id: string, props: BasicLifecycleHookProps): LifecycleHook {
+ public addLifecycleHook(id: string, props: BasicLifecycleHookProps): LifecycleHook {
  return new LifecycleHook(this, `LifecycleHook${id}`, {
  autoScalingGroup: this,
  ...props
@@ -701,7 +701,7 @@ export interface IAutoScalingGroup extends IResource {
  /**
  * Send a message to either an SQS queue or SNS topic when instances launch or terminate
  */
- onLifecycleTransition(id: string, props: BasicLifecycleHookProps): LifecycleHook;
+ addLifecycleHook(id: string, props: BasicLifecycleHookProps): LifecycleHook;
 
  /**
  * Scale out or in based on time

packages/@aws-cdk/aws-autoscaling/lib/step-scaling-policy.ts

@@ -109,7 +109,7 @@ export class StepScalingPolicy extends cdk.Construct {
  evaluationPeriods: 1,
  threshold,
  });
- this.lowerAlarm.onAlarm(this.lowerAction);
+ this.lowerAlarm.addAlarmAction(this.lowerAction);
  }
 
  if (alarms.upperAlarmIntervalIndex !== undefined) {
@@ -139,7 +139,7 @@ export class StepScalingPolicy extends cdk.Construct {
  evaluationPeriods: 1,
  threshold,
  });
- this.upperAlarm.onAlarm(this.upperAction);
+ this.upperAlarm.addAlarmAction(this.upperAction);
  }
  }
 }

packages/@aws-cdk/aws-autoscaling/test/test.lifecyclehooks.ts

@@ -18,7 +18,7 @@ export = {
  });
 
  // WHEN
- asg.onLifecycleTransition('Transition', {
+ asg.addLifecycleHook('Transition', {
  notificationTarget: new FakeNotificationTarget(),
  lifecycleTransition: autoscaling.LifecycleTransition.InstanceLaunching,
  defaultResult: autoscaling.DefaultResult.Abandon,

packages/@aws-cdk/aws-cloudtrail/SAMPLE-EVENTS.md

@@ -0,0 +1,68 @@
+# Some sample CloudTrail events
+
+For reference.
+
+
+## S3
+
+PutObject
+
+ {
+  "eventSource": "s3.amazonaws.com",
+  "resources": [
+  {
+  "ARN": "arn:aws:s3:::BUCKETNAME/OBJECTKEY",
+  "type": "AWS::S3::Object"
+  },
+  {
+  "accountId": "123456789012",
+  "ARN": "arn:aws:s3:::BUCKETNAME",
+  "type": "AWS::S3::Bucket"
+  }
+  ],
+  "eventTime": "2019-05-22T08:38:05Z",
+  "userAgent": "[aws-cli/1.16.96 Python/2.7.12 Linux/4.4.0-146-generic botocore/1.12.86]",
+  "readOnly": false,
+  "recipientAccountId": "123456789012",
+  "awsRegion": "eu-west-1",
+  "requestID": "CF9748DFDC5FB0A4",
+  "additionalEventData": {
+  "CipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
+  "bytesTransferredOut": 0,
+  "AuthenticationMethod": "AuthHeader",
+  "x-amz-id-2": "hRJMAs5p4ALZIabP4ATIL53npWU61+N6LYWj02gdQtR0ymKSySzVXUSZx7ydv7tRJwk+XMaPerM=",
+  "bytesTransferredIn": 197,
+  "SignatureVersion": "SigV4"
+  },
+  "eventType": "AwsApiCall",
+  "eventID": "3074546e-1bfa-4973-8502-b1bb4d0bda1a",
+  "eventVersion": "1.05",
+  "eventName": "PutObject",
+  "sourceIPAddress": "1.2.3.4",
+  "userIdentity": {
+  "accountId": "123456789012",
+  "type": "AssumedRole",
+  "principalId": "AROAJBNCAL3UTR5C42U4M:user-SomeRole",
+  "accessKeyId": "AZYCAIJERO6H7",
+  "sessionContext": {
+  "attributes": {
+  "mfaAuthenticated": "false",
+  "creationDate": "2019-05-22T08:10:21Z"
+  },
+  "sessionIssuer": {
+  "accountId": "123456789012",
+  "type": "Role",
+  "principalId": "AROAJBNCAL3UTR5C42U4M",
+  "userName": "SomeRole",
+  "arn": "arn:aws:iam::123456789012:role/SomeRole"
+  }
+  },
+  "arn": "arn:aws:sts::123456789012:assumed-role/SomeRole/user-SomeRole"
+  },
+  "responseElements": null,
+  "requestParameters": {
+  "bucketName": "BUCKETNAME",
+  "Host": "BUCKETNAME.s3.eu-west-1.amazonaws.com",
+  "key": "OBJECTKEY"
+  }
+ }

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

@@ -222,14 +222,16 @@ export class Trail extends Resource {
  }
 
  /**
- * Create an event rule for when an event is recorded by any trail.
+ * Create an event rule for when an event is recorded by any Trail in the account.
  *
- * Note that the event doesn't necessarily have to come from this
- * trail. Be sure to filter the event properly using an event pattern.
+ * Note that the event doesn't necessarily have to come from this Trail, it can
+ * be captured from any one.
+ *
+ * Be sure to filter the event further down using an event pattern.
  */
- public onEvent(name: string, target?: events.IRuleTarget, options?: events.RuleProps) {
- const rule = new events.Rule(this, name, options);
- rule.addTarget(target);
+ public onCloudTrailEvent(id: string, options: events.OnEventOptions): events.Rule {
+ const rule = new events.Rule(this, id, options);
+ rule.addTarget(options.target);
  rule.addEventPattern({
  detailType: ['AWS API Call via CloudTrail']
  });

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

@@ -197,11 +197,13 @@ export = {
  const trail = new Trail(stack, 'MyAmazingCloudTrail', { managementEvents: ReadWriteType.WriteOnly });
 
  // WHEN
- trail.onEvent('DoEvents', {
- bind: () => ({
- arn: 'arn',
- id: 'myid'
- })
+ trail.onCloudTrailEvent('DoEvents', {
+ target: {
+ bind: () => ({
+ arn: 'arn',
+ id: 'myid'
+ })
+ }
  });
 
  // THEN

packages/@aws-cdk/aws-cloudwatch/lib/alarm.ts

@@ -155,7 +155,7 @@ export class Alarm extends Resource implements IAlarm {
  *
  * Typically the ARN of an SNS topic or ARN of an AutoScaling policy.
  */
- public onAlarm(...actions: IAlarmAction[]) {
+ public addAlarmAction(...actions: IAlarmAction[]) {
  if (this.alarmActionArns === undefined) {
  this.alarmActionArns = [];
  }
@@ -168,7 +168,7 @@ export class Alarm extends Resource implements IAlarm {
  *
  * Typically the ARN of an SNS topic or ARN of an AutoScaling policy.
  */
- public onInsufficientData(...actions: IAlarmAction[]) {
+ public addInsufficientDataAction(...actions: IAlarmAction[]) {
  if (this.insufficientDataActionArns === undefined) {
  this.insufficientDataActionArns = [];
  }
@@ -181,7 +181,7 @@ export class Alarm extends Resource implements IAlarm {
  *
  * Typically the ARN of an SNS topic or ARN of an AutoScaling policy.
  */
- public onOk(...actions: IAlarmAction[]) {
+ public addOkAction(...actions: IAlarmAction[]) {
  if (this.okActionArns === undefined) {
  this.okActionArns = [];
  }

packages/@aws-cdk/aws-cloudwatch/test/test.alarm.ts

@@ -72,9 +72,9 @@ export = {
  evaluationPeriods: 2
  });
 
- alarm.onAlarm(new TestAlarmAction('A'));
- alarm.onInsufficientData(new TestAlarmAction('B'));
- alarm.onOk(new TestAlarmAction('C'));
+ alarm.addAlarmAction(new TestAlarmAction('A'));
+ alarm.addInsufficientDataAction(new TestAlarmAction('B'));
+ alarm.addOkAction(new TestAlarmAction('C'));
 
  // THEN
  expect(stack).to(haveResource('AWS::CloudWatch::Alarm', {

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

@@ -32,6 +32,13 @@ export interface IProject extends IResource, iam.IGrantable {
  /** The IAM service Role of this Project. Undefined for imported Projects. */
  readonly role?: iam.IRole;
 
+ /**
+ * Defines a CloudWatch event rule triggered when something happens with this project.
+ *
+ * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html
+ */
+ onEvent(id: string, options: events.OnEventOptions): events.Rule;
+
  /**
  * Defines a CloudWatch event rule triggered when the build project state
  * changes. You can filter specific build status events using an event
@@ -57,30 +64,30 @@ export interface IProject extends IResource, iam.IGrantable {
  *
  * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html
  */
- onStateChange(name: string, target?: events.IRuleTarget, options?: events.RuleProps): events.Rule;
+ onStateChange(id: string, options: events.OnEventOptions): events.Rule;
 
  /**
  * Defines a CloudWatch event rule that triggers upon phase change of this
  * build project.
  *
  * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html
  */
- onPhaseChange(name: string, target?: events.IRuleTarget, options?: events.RuleProps): events.Rule;
+ onPhaseChange(id: string, options: events.OnEventOptions): events.Rule;
 
  /**
  * Defines an event rule which triggers when a build starts.
  */
- onBuildStarted(name: string, target?: events.IRuleTarget, options?: events.RuleProps): events.Rule;
+ onBuildStarted(id: string, options: events.OnEventOptions): events.Rule;
 
  /**
  * Defines an event rule which triggers when a build fails.
  */
- onBuildFailed(name: string, target?: events.IRuleTarget, options?: events.RuleProps): events.Rule;
+ onBuildFailed(id: string, options: events.OnEventOptions): events.Rule;
 
  /**
  * Defines an event rule which triggers when a build completes successfully.
  */
- onBuildSucceeded(name: string, target?: events.IRuleTarget, options?: events.RuleProps): events.Rule;
+ onBuildSucceeded(id: string, options: events.OnEventOptions): events.Rule;
 
  /**
  * @returns a CloudWatch metric associated with this build project.
@@ -157,6 +164,23 @@ abstract class ProjectBase extends Resource implements IProject {
  /** The IAM service Role of this Project. */
  public abstract readonly role?: iam.IRole;
 
+ /**
+ * Defines a CloudWatch event rule triggered when something happens with this project.
+ *
+ * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html
+ */
+ public onEvent(id: string, options: events.OnEventOptions): events.Rule {
+ const rule = new events.Rule(this, id, options);
+ rule.addTarget(options.target);
+ rule.addEventPattern({
+ source: ['aws.codebuild'],
+ detail: {
+ 'project-name': [this.projectName]
+ }
+ });
+ return rule;
+ }
+
  /**
  * Defines a CloudWatch event rule triggered when the build project state
  * changes. You can filter specific build status events using an event
@@ -182,17 +206,10 @@ abstract class ProjectBase extends Resource implements IProject {
  *
  * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html
  */
- public onStateChange(name: string, target?: events.IRuleTarget, options?: events.RuleProps) {
- const rule = new events.Rule(this, name, options);
- rule.addTarget(target);
+ public onStateChange(id: string, options: events.OnEventOptions) {
+ const rule = this.onEvent(id, options);
  rule.addEventPattern({
- source: ['aws.codebuild'],
  detailType: ['CodeBuild Build State Change'],
- detail: {
- 'project-name': [
- this.projectName
- ]
- }
  });
  return rule;
  }
@@ -203,17 +220,10 @@ abstract class ProjectBase extends Resource implements IProject {
  *
  * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html
  */
- public onPhaseChange(name: string, target?: events.IRuleTarget, options?: events.RuleProps) {
- const rule = new events.Rule(this, name, options);
- rule.addTarget(target);
+ public onPhaseChange(id: string, options: events.OnEventOptions) {
+ const rule = this.onEvent(id, options);
  rule.addEventPattern({
- source: ['aws.codebuild'],
  detailType: ['CodeBuild Build Phase Change'],
- detail: {
- 'project-name': [
- this.projectName
- ]
- }
  });
  return rule;
  }
@@ -224,8 +234,8 @@ abstract class ProjectBase extends Resource implements IProject {
  * To access fields from the event in the event target input,
  * use the static fields on the `StateChangeEvent` class.
  */
- public onBuildStarted(name: string, target?: events.IRuleTarget, options?: events.RuleProps) {
- const rule = this.onStateChange(name, target, options);
+ public onBuildStarted(id: string, options: events.OnEventOptions) {
+ const rule = this.onStateChange(id, options);
  rule.addEventPattern({
  detail: {
  'build-status': ['IN_PROGRESS']
@@ -240,8 +250,8 @@ abstract class ProjectBase extends Resource implements IProject {
  * To access fields from the event in the event target input,
  * use the static fields on the `StateChangeEvent` class.
  */
- public onBuildFailed(name: string, target?: events.IRuleTarget, options?: events.RuleProps) {
- const rule = this.onStateChange(name, target, options);
+ public onBuildFailed(id: string, options: events.OnEventOptions) {
+ const rule = this.onStateChange(id, options);
  rule.addEventPattern({
  detail: {
  'build-status': ['FAILED']
@@ -256,8 +266,8 @@ abstract class ProjectBase extends Resource implements IProject {
  * To access fields from the event in the event target input,
  * use the static fields on the `StateChangeEvent` class.
  */
- public onBuildSucceeded(name: string, target?: events.IRuleTarget, options?: events.RuleProps) {
- const rule = this.onStateChange(name, target, options);
+ public onBuildSucceeded(id: string, options: events.OnEventOptions) {
+ const rule = this.onStateChange(id, options);
  rule.addEventPattern({
  detail: {
  'build-status': ['SUCCEEDED']

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

@@ -973,11 +973,11 @@ export = {
  source: new codebuild.CodePipelineSource()
  });
 
- project.onBuildFailed('OnBuildFailed');
- project.onBuildSucceeded('OnBuildSucceeded');
- project.onPhaseChange('OnPhaseChange');
- project.onStateChange('OnStateChange');
- project.onBuildStarted('OnBuildStarted');
+ project.onBuildFailed('OnBuildFailed', { target: { bind: () => ({ arn: 'ARN', id: 'ID' }) }});
+ project.onBuildSucceeded('OnBuildSucceeded', { target: { bind: () => ({ arn: 'ARN', id: 'ID' }) }});
+ project.onPhaseChange('OnPhaseChange', { target: { bind: () => ({ arn: 'ARN', id: 'ID' }) }});
+ project.onStateChange('OnStateChange', { target: { bind: () => ({ arn: 'ARN', id: 'ID' }) }});
+ project.onBuildStarted('OnBuildStarted', { target: { bind: () => ({ arn: 'ARN', id: 'ID' }) }});
 
  expect(stack).to(haveResource('AWS::Events::Rule', {
  "EventPattern": {