Module: LambdaSharp.App.EventBus
Version: 0.8.3.5
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 ofEnabled
orDisabled
. Default value isDisabled
.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 theLambdaSharpEventBusClient
.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. WhenDevMode
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 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 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"
}
Action: Subscribe
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