feat(iot): add the TopicRule L2 construct

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

@@ -9,8 +9,47 @@
 >
 > [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.
+AWS IoT Core lets you connect billions of IoT devices and route trillions of
+messages to AWS services without managing infrastructure.
+
+## 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';
+```
+
+## `TopicRule`
+
+The `TopicRule` construct defined Rules that give your devices the ability to
+interact with AWS services.
+
+For example, to define a rule:
+
+```ts
+new iot.TopicRule(stack, 'MyTopicRule', {
+ topicRuleName: 'MyRuleName', // optional property
+ sql: iot.IotSql.fromStringAsVer20160323(
+ "SELECT topic(2) as device_id, temperature FROM 'device/+/data'",
+ ),
+});
+```

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

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

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

@@ -0,0 +1,75 @@
+import { Construct } from 'constructs';
+
+/**
+ * The type returned from the `bind()` method in {@link IotSql}.
+ */
+export interface IotSqlConfig {
+ /**
+ * The version of the SQL rules engine to use when evaluating the rule.
+ */
+ readonly awsIotSqlVersion: string;
+
+ /**
+ * The SQL statement used to query the topic.
+ */
+ readonly sql: string;
+}
+
+/**
+ * Defines AWS IoT SQL.
+ */
+export abstract class IotSql {
+ /**
+ * Uses the original SQL version built on 2015-10-08.
+ *
+ * @param sql The actual SQL-like syntax query
+ * @returns Instance of IotSql
+ */
+ public static fromStringAsVer20151008(sql: string): IotSql {
+ return new IotSqlImpl('2015-10-08', sql);
+ }
+
+ /**
+ * Uses the SQL version built on 2016-03-23.
+ *
+ * @param sql The actual SQL-like syntax query
+ * @returns Instance of IotSql
+ */
+ public static fromStringAsVer20160323(sql: string): IotSql {
+ return new IotSqlImpl('2016-03-23', sql);
+ }
+
+ /**
+ * Uses the most recent beta SQL version. If you use this version, it might
+ * introduce breaking changes to your rules.
+ *
+ * @param sql The actual SQL-like syntax query
+ * @returns Instance of IotSql
+ */
+ public static fromStringAsVerNewestUnstable(sql: string): IotSql {
+ return new IotSqlImpl('beta', sql);
+ }
+
+ /**
+ * Returns the IoT SQL configuration.
+ */
+ public abstract bind(scope: Construct): IotSqlConfig;
+}
+
+
+class IotSqlImpl extends IotSql {
+ constructor(private readonly version: string, private readonly sql: string) {
+ super();
+
+ if (sql === '') {
+ throw new Error('IoT SQL string cannot be empty');
+ }
+ }
+
+ bind(_scope: Construct): IotSqlConfig {
+ return {
+ awsIotSqlVersion: this.version,
+ sql: this.sql,
+ };
+ }
+}

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

@@ -0,0 +1,106 @@
+import { ArnFormat, Resource, Stack, IResource } from '@aws-cdk/core';
+import { Construct } from 'constructs';
+import { IotSql } from './iot-sql';
+import { CfnTopicRule } from './iot.generated';
+
+/**
+ * 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;
+}
+
+/**
+ * Properties for defining an AWS IoT Rule
+ */
+export interface TopicRuleProps {
+ /**
+ * The name of the rule.
+ * @default None
+ */
+ readonly topicRuleName?: string;
+
+ /**
+ * 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: IotSql;
+}
+
+/**
+ * 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(`Missing topic rule name in ARN: '${topicRuleArn}'`);
+ }
+ const resourceName = parts.resourceName;
+
+ class Import extends Resource implements ITopicRule {
+ public readonly topicRuleArn = topicRuleArn;
+ public readonly topicRuleName = resourceName;
+ }
+ return new Import(scope, id, {
+ environmentFromArn: topicRuleArn,
+ });
+ }
+
+ /**
+ * Arn of this rule
+ * @attribute
+ */
+ public readonly topicRuleArn: string;
+
+ /**
+ * Name of this rule
+ * @attribute
+ */
+ public readonly topicRuleName: string;
+
+ constructor(scope: Construct, id: string, props: TopicRuleProps) {
+ super(scope, id, {
+ physicalName: props.topicRuleName,
+ });
+
+ const sqlConfig = props.sql.bind(this);
+
+ const resource = new CfnTopicRule(this, 'Resource', {
+ ruleName: this.physicalName,
+ topicRulePayload: {
+ actions: [],
+ awsIotSqlVersion: sqlConfig.awsIotSqlVersion,
+ sql: sqlConfig.sql,
+ },
+ });
+
+ this.topicRuleArn = this.getResourceArnAttribute(resource.attrArn, {
+ service: 'iot',
+ resource: 'rule',
+ resourceName: this.physicalName,
+ });
+ this.topicRuleName = this.getResourceNameAttribute(resource.ref);
+ }
+}

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,14 @@
+{
+ "Resources": {
+ "TopicRule40A4EA44": {
+ "Type": "AWS::IoT::TopicRule",
+ "Properties": {
+ "TopicRulePayload": {
+ "Actions": [],
+ "AwsIotSqlVersion": "2015-10-08",
+ "Sql": "SELECT topic(2) as device_id FROM 'device/+/data'"
+ }
+ }
+ }
+ }
+}

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

@@ -0,0 +1,18 @@
+/// !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);
+
+ new iot.TopicRule(this, 'TopicRule', {
+ sql: iot.IotSql.fromStringAsVer20151008("SELECT topic(2) as device_id FROM 'device/+/data'"),
+ });
+ }
+}
+
+new TestStack(app, 'test-stack');
+app.synth();