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:/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();