(iotevents): add aws-iotevents DetectorModel L2 Construct

[yamatatsu]

Description

Now, @aws-cdk/aws-iotevents has no L2 Construct. I will implements L2 Constructs.

Use Case

When users create IoT Events DetectorModel, This Cunstruct will support it.

Proposed Solution

We can create L2 constructs for aws-iotevents.

Other information

I'm starting to design.

And in first PR, I'm going to commit DetectorModel and State with only required properties.

Acknowledge

• I may be able to implement this feature request
• This feature might incur a breaking change

Design

ref: CloudFormation

usage:

const timer = new iotevents.Timer("heartbeatTimer", 60);

// Define nodes of the state machine
const onlineState = new iotevents.State({
  stateName: "online",
  onEnterEvents: [
    {
      eventName: "setTimer",
      actions: [timer.set()], // `timer.set()` return `SetTimerAction`
    },
  ],
  onInputEvents: [
    {
      eventName: "resetTimer",
      condition: 'currentInput("HeartbeatInputData")',
      actions: [timer.reset()], // `timer.reset()` return `ResetTimerAction`
    },
  ],
});
const offlineState = new iotevents.State({
  stateName: "offline",
});

// Define edges of the state machine
onlineState.transitionTo({
  eventName: "to_offline",
  condition: timer.timeout(), // `timer.timeout()` return just string
  nextState: offlineState,
});
offlineState.transitionTo({
  eventName: "to_online",
  condition: 'currentInput("HeartbeatInputData")',
  nextState: onlineState,
});

// Define the state machine
new iotevents.DetectorModel(this, "DetectorModel", {
  initialState: onlineState,
});

DetectorModel:

class DetectorModel {
  constructor(private readonly initialState: State) {}

  private getDefinition() {
    const stateSet = this.initialState.getGraphStates();

    return {
      initialState: this.initialState.stateName,
      states: Array.from(stateSet).map((state) => state.toCfn()),
    };
  }
}

State:

class State {
  constructor(private readonly props: StateProps) {}

  /**
   * get states recursively
   */
  getGraphStates(stateSet: Set<State> = new Set<State>()): Set<State> {
    if (stateSet.has(this)) {
      return stateSet;
    }
    stateSet.add(this);

    const nextStates = initialState.transitionEvents.forEach((te) => {
      te.nextState.getGraphStates(stateSet);
    });

    return stateSet;
  }
}

graph:

Roadmap

1. implement DetectorModel and State with only required properties
   • It will not be able to have multiple states yet.
2. implement state.transitionTo()
   • It will be able to have multiple states and to transit.
   • It will not be able to have events that is without transition.
   • It will not be able to perform actions.
3. implement IAction
4. create new repository aws-iotevents-actions
   • Note: AWS IoT Events has many actions like AWS IoT TopicRule. https://docs.aws.amazon.com/iotevents/latest/apireference/API_Action.html
5. implement onInput and onExit
6. implement rest Expressions
7. implement some actions (separate PRs for each actions)
   • It will be able to perform actions.

[yamatatsu]

I will contribute!

[peterwoodworth]

Thanks for the feature request for an l2 @yamatatsu! Excited to see what comes from this :)

@skinny85 will you be able to help review the design here?

[yamatatsu]

@skinny85
Sorry. above diagram is yet draft, so I'll ask for a review after a more thorough examination.

[yamatatsu]

@skinny85
I've edited above description!
I've written a lot, but it might be better to just agree on USAGE this issue and discuss the others in PR😉

[skinny85]

Thanks @yamatatsu. My comments:

1. Why the double array here (array of events with an array of actions)?

     onEnterEvents: [{
     eventName: 'setTimer',
     actions: [timer.set()], // `timer.set()` return `SetTimerAction`
   }],

2. I don't know what Timer is - it's not created with the iotevents module prefix...

3. I don't understand what condition is timer.timeout() here:

   onlineState.addTransition({
     eventName: 'to_offline',
     condition: timer.timeout(), // `timer.timeout()` return just string
     nextState: offlineState,
   });

4. I don't like the name State.addTransition(). I would prefer something like State.transitionTo(otherState, options).

5. I don't see what's the point of Definition here:

   new iotevents.DetectorModel(this, 'DetectorModel', {
     definition: new iotevents.Definition(onlineState),
   });

   Seems purely like boilerplate that DetectorModel can do for you.
   I would change to:

   new iotevents.DetectorModel(this, 'DetectorModel', {
     initialState: onlineState,
   });

Just my quick thoughts based on the first reading of the proposal 🙂.

[yamatatsu]

@skinny85

1. Why the double array here (array of events with an array of actions)?

My sample code is too simple. 😅 An event can be specified a condition which the event to be triggerd or not.
For example, following case:

• (A) On every enter the state, set timer.
• (B) On every enter the state, increment count of enter the state.
• (C) On enter the state at first time, notify something.

The code will be written as following:

onEnterEvents: [
  {
    eventName: 'setTimer',
    actions: [
      timer.set(), // (A)
      { // (B)
        variableName: 'countOfEnterThisState',
        value: 'isUndefined($variable.countOfEnterThisState) && 1 || $variable.countOfEnterThisState + 1',
      },
    ],
  },
  {
    eventName: 'firstEnter',
    condition: '$variable.countOfEnterThisState == 1',
    actions: [
      { // (C)
        lambda: { // CFn page: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iotevents-detectormodel-lambda.html
          functionArn: 'notification-lambda-arn',
        },
      }
    ],
  },
],

2. I don't know what Timer is - it's not created with the iotevents module prefix...

Oh.. sorry!

const timer = new iotevents.Timer('heartbeatTimer', 60);

And I've fix also above description code.

3. I don't understand what condition is timer.timeout() here:

I intend to implement Timer as just generater for SetTimer, ResetTimer, ClearTimer and timeout() Function. It will generate these from same timerName.

const timer = new iotevents.Timer('heartbeatTimer', 60);
timer.set()
// => {
//   SetTimer: {
//     TimerName: "heartbeatTimer",
//     Seconds: 60,
//   }
// }
timer.reset()
// => {
//   ResetTimer: {
//     TimerName: "heartbeatTimer",
//   }
// }
timer.clear()
// => {
//   ClearTimer: {
//     TimerName: "heartbeatTimer",
//   }
// }
timer.timeout()
// => 'timeout("heartbeatTimer")'

4. I don't like the name State.addTransition(). I would prefer something like State.transitionTo(otherState, options).

Sounds good! Thank you!

5. I don't see what's the point of Definition here:

Sounds good! 👍

[skinny85]

OK, makes sense 🙂. Looks good to me, feel free to start working on the implementation based on that design.

[yamatatsu]

I've craete an PR that I implemented Inputin, before creating an PR that I implement DetectorModel.
Because CloudFormation threw an error on deploying DetectorModel:

Detector Model Definition must use at least one Input in a condition.

Following refference that refer to Input is needed:

const input = new iotevents.Input(this, 'input', {
  attributeJsonPaths: ['payload.temperature'],
});

const onlineState = new iotevents.State({
  stateName: 'online',
  onEnterEvents: [{
    eventName: 'test-event',
    condition: `currentInput("${input.inputName}")`, // this reference is needed for deploying
  }],
});

new iotevents.DetectorModel(this, 'MyDetectorModel', {
  initialState: onlineState,
});

[skinny85]

@yamatatsu I believe this was done in #18049 - can we close this issue?

[yamatatsu]

@skinny85 This issue have the roadmap and we have rest works.
But if it is better that this issue is splited to some small issues, I will close this issue and create small issues 👍🏻 WDYT?

[yamatatsu]

The Roadmap is here, and I've reach to No.2 implement state.transitionTo() with #18768 .

Roadmap

1. implement DetectorModel and State with only required properties
   • It will not be able to have multiple states yet.
2. implement state.transitionTo()
   • It will be able to have multiple states and to transit.
   • It will not be able to have events that is without transition.
   • It will not be able to perform actions.
3. implement IAction
4. create new repository aws-iotevents-actions
   • Note: AWS IoT Events has many actions like AWS IoT TopicRule. https://docs.aws.amazon.com/iotevents/latest/apireference/API_Action.html
5. implement some actions (separate PRs for each actions)
   • It will be able to perform actions.

[skinny85]

Nah, let's just keep this open then, no need to create new issues for this 🙂.

[github-actions]

This issue has not received any attention in 1 year. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.