feat(iot): add the TopicRule L2 construct

packages/@aws-cdk/aws-iot/README.md

@@ -9,8 +9,84 @@
 >
 > [CFN Resources]: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib
 
+![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
+
+> The APIs of higher level constructs in this module are experimental and under active development.
+> They are subject to non-backward compatible changes or removal in any future version. These are
+> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
+> announced in the release notes. This means that while you may use them, you may need to update
+> your source code when upgrading to a newer version of this package.
+
 ---
 
 <!--END STABILITY BANNER-->
 
-This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
+The `TopicRule` construct defined Rules that give your devices the ability to interact with AWS services.
+Rules are analyzed and actions are performed based on the MQTT topic stream.
+The `TopicRule` construct can use actions like these:
+
+- Write data received from a device to an Amazon DynamoDB database.
+- Save a file to Amazon S3.
+- Send a push notification to all users using Amazon SNS.
+- Publish data to an Amazon SQS queue.
+- Invoke a Lambda function to extract data.
+- Process messages from a large number of devices using Amazon Kinesis. (*To be developed*)
+- Send data to the Amazon OpenSearch Service. (*To be developed*)
+- Capture a CloudWatch metric.
+- Change a CloudWatch alarm.
+- Send message data to an AWS IoT Analytics channel. (*To be developed*)
+- Start execution of a Step Functions state machine. (*To be developed*)
+- Send message data to an AWS IoT Events input. (*To be developed*)
+- Send message data an asset property in AWS IoT SiteWise. (*To be developed*)
+- Send message data to a web application or service. (*To be developed*)
+
+## Installation
+
+Install the module:
+
+```console
+$ npm i @aws-cdk/aws-iot
+```
+
+Import it into your code:
+
+```ts
+import * as iot from '@aws-cdk/aws-iot';
+```
+
+The `iot.Project` construct represents a build project resource. See the reference documentation for a comprehensive list of initialization properties, methods and attributes.
+
+## `TopicRule`
+
+For example, to define a rule that triggers to put to a S3 bucket:
+
+```ts
+new iot.TopicRule(stack, 'MyTopicRule', {
+  topicRuleName: 'MyRuleName', // optional property
+  sql: "SELECT topic(2) as device_id, temperature FROM 'device/+/data'",
+  acctions: [
+    {
+      configration: {
+        s3: {
+          bucketName: 'your-bucket-name',
+          key: 'your-bucket-key',
+          roleArn: 'your-role-arn',
+        }
+      }
+    }
+  ],
+});
+```
+
+Or you can add action after constructing instance as following:
+
+```ts
+const topicRule = new TopicRule(stack, 'MyTopicRule', {
+  sql: "SELECT topic(2) as device_id, temperature FROM 'device/+/data'",
+});
+topicRule.addAction({
+  configration: {
+    functionArn: 'your-lambda-function-arn',
+  }
+});
+```

packages/@aws-cdk/aws-iot/lib/action.ts

@@ -0,0 +1,24 @@
+import { CfnTopicRule } from './iot.generated';
+import { ITopicRule } from './topic-rule';
+
+/**
+ * An abstract action for TopicRule.
+ */
+export interface IAction {
+  /**
+   * Returns the topic rule action specification.
+   *
+   * @param rule The TopicRule that would trigger this action.
+   */
+  bind(rule: ITopicRule): ActionConfig;
+}
+
+/**
+ * Properties for an topic rule action
+ */
+export interface ActionConfig {
+  /**
+   * The configuration for this action.
+   */
+  readonly configuration: CfnTopicRule.ActionProperty;
+}

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

@@ -1,2 +1,5 @@
+export * from './action';
+export * from './topic-rule';
+
 // AWS::IoT CloudFormation Resources:
 export * from './iot.generated';

packages/@aws-cdk/aws-iot/lib/topic-rule.ts

@@ -0,0 +1,137 @@
+import { ArnFormat, Lazy, Resource, Stack, IResource } from '@aws-cdk/core';
+import { Construct } from 'constructs';
+import { IAction } from './action';
+import { CfnTopicRule } from './iot.generated';
+
+/**
+ * Properties for defining an AWS IoT Rule
+ */
+export interface TopicRuleProps {
+  /**
+   * The name of the rule.
+   * @default None
+   */
+  readonly topicRuleName?: string;
+
+  /**
+   * The actions associated with the rule.
+   *
+   * @default No actions will be perform
+   */
+  readonly actions?: Array<IAction>;
+
+  /**
+   * A simplified SQL syntax to filter messages received on an MQTT topic and push the data elsewhere.
+   *
+   * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-sql-reference.html
+   */
+  readonly sql: string;
+}
+
+/**
+ * Represents an AWS IoT Rule
+ */
+export interface ITopicRule extends IResource {
+  /**
+   * The value of the topic rule Amazon Resource Name (ARN), such as
+   * arn:aws:iot:us-east-2:123456789012:rule/rule_name
+   *
+   * @attribute
+   */
+  readonly topicRuleArn: string;
+
+  /**
+   * The name topic rule
+   *
+   * @attribute
+   */
+  readonly topicRuleName: string;
+}
+
+/**
+ * Defines an AWS IoT Rule in this stack.
+ */
+export class TopicRule extends Resource implements ITopicRule {
+  /**
+   * Import an existing AWS IoT Rule provided an ARN
+   *
+   * @param scope The parent creating construct (usually `this`).
+   * @param id The construct's name.
+   * @param topicRuleArn AWS IoT Rule ARN (i.e. arn:aws:iot:<region>:<account-id>:rule/MyRule).
+   */
+  public static fromTopicRuleArn(scope: Construct, id: string, topicRuleArn: string): ITopicRule {
+    const parts = Stack.of(scope).splitArn(topicRuleArn, ArnFormat.SLASH_RESOURCE_NAME);
+    if (!parts.resourceName) {
+      throw new Error('Invalid topic rule arn: topicRuleArn has no resource name.');
+    }
+    const resourceName = parts.resourceName;
+
+    class Import extends Resource implements ITopicRule {
+      public readonly topicRuleArn = topicRuleArn;
+      public readonly topicRuleName = resourceName;
+    }
+    return new Import(scope, id);
+  }
+
+  /**
+   * Arn of this rule
+   * @attribute
+   */
+  public readonly topicRuleArn: string;
+
+  /**
+   * Name of this rule
+   * @attribute
+   */
+  public readonly topicRuleName: string;
+
+  private readonly actions = new Array<CfnTopicRule.ActionProperty>();
+
+  constructor(scope: Construct, id: string, props: TopicRuleProps) {
+    super(scope, id, {
+      physicalName: props.topicRuleName,
+    });
+
+    if (props.sql === '') {
+      throw new Error('sql cannot be empty.');
+    }
+
+    const resource = new CfnTopicRule(this, 'Resource', {
+      ruleName: this.physicalName,
+      topicRulePayload: {
+        actions: Lazy.any({ produce: () => this.actions }),
+        sql: props.sql,
+      },
+    });
+
+    this.topicRuleArn = this.getResourceArnAttribute(resource.attrArn, {
+      service: 'iot',
+      resource: 'rule',
+      resourceName: this.physicalName,
+    });
+    this.topicRuleName = this.getResourceNameAttribute(resource.ref);
+
+    props.actions?.forEach(action => {
+      this.addAction(action);
+    });
+  }
+
+  /**
+   * Add a action to the rule.
+   *
+   * @param action the action to associate with the rule.
+   */
+  public addAction(action: IAction): void {
+    const { configuration } = action.bind(this);
+
+    const keys = Object.keys(configuration);
+    if (keys.length === 0) {
+      throw new Error('Empty actions are not allowed. Please define one type of action');
+    }
+    if (keys.length >= 2) {
+      throw new Error(`Each object in the actions list can only have one action defined. keys: ${keys}`);
+    }
+
+    this.actions.push(configuration);
+  }
+}

packages/@aws-cdk/aws-iot/package.json

@@ -74,9 +74,11 @@
   "devDependencies": {
     "@aws-cdk/assertions": "0.0.0",
     "@aws-cdk/cdk-build-tools": "0.0.0",
+    "@aws-cdk/cdk-integ-tools": "0.0.0",
     "@aws-cdk/cfn2ts": "0.0.0",
     "@aws-cdk/pkglint": "0.0.0",
-    "@types/jest": "^26.0.24"
+    "@types/jest": "^26.0.24",
+    "jest": "^26.6.3"
   },
   "dependencies": {
     "@aws-cdk/core": "0.0.0",
@@ -91,7 +93,7 @@
     "node": ">= 10.13.0 <13 || >=13.7.0"
   },
   "stability": "experimental",
-  "maturity": "cfn-only",
+  "maturity": "experimental",
   "awscdkio": {
     "announce": false
   },

packages/@aws-cdk/aws-iot/test/integ.topic-rule.expected.json

@@ -0,0 +1,19 @@
+{
+  "Resources": {
+    "TopicRule40A4EA44": {
+      "Type": "AWS::IoT::TopicRule",
+      "Properties": {
+        "TopicRulePayload": {
+          "Actions": [
+            {
+              "Lambda": {
+                "FunctionArn": "test-arn"
+              }
+            }
+          ],
+          "Sql": "SELECT topic(2) as device_id FROM 'device/+/data'"
+        }
+      }
+    }
+  }
+}

packages/@aws-cdk/aws-iot/test/integ.topic-rule.ts

@@ -0,0 +1,28 @@
+/// !cdk-integ pragma:ignore-assets
+import * as cdk from '@aws-cdk/core';
+import * as iot from '../lib';
+
+const app = new cdk.App();
+
+class TestStack extends cdk.Stack {
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    const topicRule = new iot.TopicRule(this, 'TopicRule', {
+      sql: "SELECT topic(2) as device_id FROM 'device/+/data'",
+    });
+
+    topicRule.addAction({
+      bind: () => ({
+        configuration: {
+          lambda: {
+            functionArn: 'test-arn',
+          },
+        },
+      }),
+    });
+  }
+}
+
+new TestStack(app, 'test-stack');
+app.synth();