Module: LambdaSharp.App.EventBus

Version: 0.8.2.4

Overview

The LambdaSharp.App.EventBus module is used by the App declaration to create an API Gateway WebSocket proxy for CloudWatch EventBridge. The proxy is only created if the app has at least one event source. When created, the proxy manages event pattern subscriptions to forwarded events. The proxy uses the same notation as CloudWatch EventBridge to describe event patterns. This design promotes a unified way to work with CloudWatch events both in the backend and frontend. Access to the EventBus API is secured by an API key that is computed from the CloudFormation stack identifier and the app version identifier. Using the DevMode parameter, the EventBus API can be configured for more lenient access and a simplified API key, which allows for accessing it from localhost.

Resource Types

This module defines no resource types.

Parameters

AppVersionId

The AppVersionId parameter specifies the app version identifier. This value is used to construct the complete API key.

Required: Yes

Type: String

DevMode

The DevMode parameter specifies if the app EventBus API should run with relaxed API key constraints and enables debug logging. The value must be one of Enabled or Disabled. Default value is Disabled.

Required: No

Type: String

The DevMode parameter must have one of the following values:

Disabled: The API key is based on teh CloudFormation stack identifier and the app version identifier. Debug logging is disabled in the app.

Enabled

The API key is solely based on the CloudFormation stack identifer. Debug logging is enabled in the app.

Output Values

ApiKey

The ApiKey output contains the CloudFormation stack identifier portion of the API key.

Type: String

EventTopicArn

The EventTopicArn output contains the SNS topic ARN for broadcasting events to the app event bus.

Type: AWS::SNS::Topic

Url

The Url output contains the URL of the api endpoint used by the LambdaSharpEventBusClient.

Type: String

WebSocketApiId

The WebSocketApiId output contains the ID of the WebSocket API.

Type: AWS::ApiGatewayV2::Api

WebSocket API

The WebSocket API endpoint can be found in the Url output value of the nested stack. The WebSocket API manages the broadcasting of subscribed EventBridge events to clients. Each client can have an arbitrary number of subscription rules using the EventBridge pattern notation.

Note that events must first be published to WebSocket SNS topic before they can be subscribed to. The ARN of the SNS topic can be found in the EventTopicArn output value of the nested stack.

Authentication

The WebSocket API expects a header query parameter in the request to validate access to the API. The value of the header query parameter is a base64 encoded JSON document.

Header Document

{
    "Host": "string",
    "ApiKey": "string",
    "Id": "guid"
}

Header Properties

Host

The WebSocket domain name.

Required: Yes

Type: String

ApiKey

The API key to authorize access to the WebSocket. The API key is computed by concatenating AppVersionId with the colon character (i.e. ':') and the CloudFormation stack identifier, and then applying a base 64 encoding to the result. When DevMode is enabled, the API key only uses the CloudFormation stack identifier.

Required: Yes

Type: String

Id

The app instance ID or session ID. Must be a unique GUID.

Required: Yes

Type: GUID

Sample Header Encoding

The following example illustrates how to encode the JSON header into a query parameter.

Original header document:

{
    "Host": "acme.execute-api.us-west-2.amazonaws.com",
    "ApiKey": "ZWU4OTc0MjAtODgzNi0xMWViLWFmMmMtMDIxZTQ5Njc5YTBi",
    "Id": "4a114560-fa5b-4f94-a462-69fbaf432b86"
}

Encoded header value:

wss://acme.execute-api.us-west-2.amazonaws.com/LATEST/?header=ewogICAgIkhvc3QiOiAiYWNtZS5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbSIsCiAgICAiQXBpS2V5IjogIlpXVTRPVGMwTWpBdE9EZ3pOaTB4TVdWaUxXRm1NbU10TURJeFpUUTVOamM1WVRCaSIsCiAgICAiSWQiOiAiNGExMTQ1NjAtZmE1Yi00Zjk0LWE0NjItNjlmYmFmNDMyYjg2Igp9Cg==

Protocol

The WebSocket protocol has two types of interactions: actions and notifications. Actions are similar to requests in that each action has exactly one response, called acknowledgements. Acknowledgements are correlated to actions by the RequestId property. Notifications can occur at any time and are commonly triggered by a subscription rule.

Action Syntax

Each request must have a Action property with a known value. The Action property indicates the shape of the request. In addition, must have a RequestId property to correlate responses from the WebSocket with their requests.

{
    "Action": "string",
    "RequestId": "guid"
}

Properties

The following properties are required for all requests.

Action

The name of the action to invoke.

Required: Yes

Type: String

RequestId

The unique identifier for the request.

Required: Yes

Type: GUID

Acknowledge: Success

A response to an action has Ack as its Action value. The RequestId must be used to correlate a response to an earlier request. The order in which responses are sent back is non-deterministic and the client must be able to associate responses correctly to pending requests.

A successful acknowledge response has Ok as its Status value.

{
    "Action": "Ack",
    "RequestId": "guid",
    "Status": "Ok"
}

Action

The value is always Ack.

Type: String

RequestId

The unique identifier for the request correlating it to a matching Action.

Type: GUID

Status

The value is always Ok.

Type: String

Acknowledge: Error

A failed acknowledge response has Error as its Status value. In addition, the Message property contains a description of the error.

{
    "Action": "Ack",
    "RequestId": "guid",
    "Status": "Error",
    "Message": "string"
}

Action

The value is always Ack.

Type: String

Message

A description of the error that occurred.

Type: String

RequestId

The unique identifier for the request correlating it to a matching Action.

Type: GUID

Status

The value is always Error.

Type: String

Action: Hello

The Hello action must be sent by the client as soon as the connection is opened. Failure to send the Hello action will cause the connection to be automatically closed by the WebSocket API.

{
    "Action": "Hello",
    "RequestId": "guid"
}

The Subscribe action is used to create or update a subscription rule. The subscription rule has an EventBridge pattern to describe which events should be sent to the client.

Note that only events published to the EventTopicArn SNS topic can be subscribed to.

{
    "Action": "Subscribe",
    "RequestId": "guid",
    "Rule": "string",
    "Pattern": "pattern"
}

Properties

The following properties are in addition to the default request properties.

Rule

The name of the subscription rule to create or update.

Required: Yes

Type: String

Pattern

The EventBridge pattern describing the events to subscribe to.

Note that only events published to the EventTopicArn SNS topic can be subscribed to.

Required: Yes

Type: EventBridge pattern as a JSON string

Action: Unsubscribe

The Unsubscribe action is used to delete a subscription rule.

{
    "Action": "Unsubscribe",
    "RequestId": "guid",
    "Rule": "string"
}

Properties

The following properties are in addition to the default request properties.

Rule

The name of the subscription rule to delete.

Required: Yes

Type: String

Notification: Event

An event notification has Event as its Action value. The WebSocket API sends this notification when an EventBridge event published to EventTopicArn matches one or more subscription rules.

{
  "Action": "Event",
  "Rules": [ "string" ],
  "Source": "string",
  "Type": "string",
  "Event": "json",
  "RequestId": "guid"
}

Properties

Action

The value is always Event.

Type: String

Event

The EventBridge event payload that matched the subscription rule.

Type: EventBridge event as a JSON string

RequestId

The unique identifier for the request.

Type: GUID

Rules

A list of subscription rules that were matched by the event.

Type: List of String

Source

The value of the source property from the EventBridge event.

Type: String

Type

The value of the detail-type property from the EventBridge event.

Type: String

Sample EventBridge event:

{
  "version": "0",
  "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "111122223333",
  "time": "2017-12-22T18:43:48Z",
  "region": "us-west-1",
  "resources": [
    "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0"
  ],
  "detail": {
    "instance-id": "i-1234567890abcdef0",
    "state": "terminated"
  }
}

Notification: KeepAlive

A keep-alive notification has KeepAlive as its Action value. The WebSocket API sends this notification periodically to keep the WebSocket connection alive.

{
  "Action": "KeepAlive",
  "RequestId": "guid"
}

Action

The value is always KeepAlive.

Type: String

RequestId

The unique identifier for the request.

Type: GUID

Module: LambdaSharp.App.EventBus

Overview

Resource Types

Parameters

Output Values

WebSocket API

Authentication

Header Document

Header Properties

Sample Header Encoding

Protocol

Action Syntax

Properties

Acknowledge: Success

Acknowledge: Error

Action: Hello

Action: Subscribe

Properties

Action: Unsubscribe

Properties

Notification: Event

Properties

Notification: KeepAlive