A serverless offline plugin that enables aws eventBridge events. As of version 1.4.0 this plugin also supports non javascript handlers.
Install the plugin
npm install serverless-offline-aws-eventbridge --save
Note: if you are running Serverless-(offline) < 10 you need the a version < 2.0.0 of this package since the SLS offline and this eventbridge package were converted to a pure esm module that utilizes the exports functionality. See #60
Let serverless know about the plugin, also note the order when combined with serverless webpack and offline
plugins:
- serverless-offline
- serverless-offline-aws-eventbridge
Configuring the plugin
optional options shown with defaults
custom:
serverless-offline-aws-eventbridge:
port: 4010 # port to run the eventBridge mock server on
mockEventBridgeServer: true # Set to false if EventBridge is already mocked by another stack
hostname: 127.0.0.1 # IP or hostname of existing EventBridge if mocked by another stack
pubSubPort: 4011 # Port to run the MQ server (or just listen if using an EventBridge Mock server from another stack)
debug: false # flag to show debug messages
account: '' # account id that gets passed to the event
maximumRetryAttempts: 10 # maximumRetryAttempts to retry lambda
retryDelayMs: 500 # retry delay
throwRetryExhausted: false # default true
payloadSizeLimit: "10mb" # Controls the maximum payload size being passed to https://www.npmjs.com/package/bytes (Note: this payload size might not be the same size as your AWS Eventbridge receive)
Checkout the documentation for AWS eventbridge in serverless framework and the AWS SDK for publishing and subscribing to events.
Scheduled events are also supported. When a cron fires the event object that is sent along is an empty object.
A simple example configuration in serverless with a Lambda function that publishes an event and a Lambda that subscribes to the event.
functions:
publishEvent:
handler: events.publish
events:
- http:
path: publish
method: get
consumeEvent:
handler: events.consume
events:
- eventBridge:
eventBus: marketing
pattern:
source:
- acme.newsletter.campaign
scheduledEvent:
handler: events.scheduled
events:
- eventBridge:
eventBus: marketing
# run every 5 minutes
schedule: "cron(0/5 * * * ? *)"
The events handler with two functions (publish and consume)
import AWS from 'aws-sdk';
export const publish = async () => {
try {
const eventBridge = new AWS.EventBridge({
endpoint: 'http://127.0.0.1:4010',
accessKeyId: "YOURKEY",
secretAccessKey: "YOURSECRET",
region: "eu-west-1"
});
await eventBridge.putEvents({
Entries: [
{
EventBusName: 'marketing',
Source: 'acme.newsletter.campaign',
DetailType: 'UserSignUp',
Detail: `{ "E-Mail": "[email protected]" }`,
},
]
}).promise();
return { statusCode: 200, body: 'published' };
} catch (e) {
console.error(e);
return { statusCode: 400, body: 'could not publish' };
}
}
export const consume = async (event, context) => {
console.log(event);
/*
{
EventBusName: 'marketing',
Source: 'acme.newsletter.campaign',
DetailType: 'UserSignUp',
Detail: `{ "E-Mail": "[email protected]" }`,
}
*/
return { statusCode: 200, body: JSON.stringify(event) };
}
export const scheduled = async (event, context) => {
console.log('scheduled event');
return { statusCode: 200, body: 'scheduled event' };
}
EventBridge natively allows a few content-based filters defined here: https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns-content-based-filtering.html
This plugin supports the most common patterns:
prefix
anything-but
exists
functions:
consumeEvent:
handler: events.consume
events:
- eventBridge:
eventBus: marketing
pattern:
source:
- user
detail-type:
- { "anything-but": "deleted" }
detail:
firstname: [ { "prefix": "John" } ]
age: [ { "exists": true } ]
The cidr
filter is yet to be implemented.
At some point you might want to use an existing event bus. This plugin needs to somehow resolve intrinsic CloudFormation function calls to event bus names/arns.
An event bus created by the same template, will be referenced using the !GetAtt
function:
functions:
consumeEvent:
handler: events.consume
events:
- eventBridge:
eventBus: !GetAtt EventBus.Arn
This plugin will look for an EventBus
resource of type AWS::Events::EventBus
when deciding whether a function must be triggered.
Or you might use !ImportValue
to reference an event bus created by another stack.
functions:
consumeEvent:
handler: events.consume
events:
- eventBridge:
eventBus: !ImportValue EventBusNameFromOtherStack
In this case, you won't define the resource directly in your template. To overcome this limitation, you can define a custom object in serverless.yml
that indicates the mapping between imported keys and the actual event bus name/arn:
custom:
serverless-offline-aws-eventbridge:
port: 4010 # port to run the eventBridge mock server on
mockEventBridgeServer: true # Set to false if EventBridge is already mocked by another stack
hostname: 127.0.0.1 # IP or hostname of existing EventBridge if mocked by another stack
pubSubPort: 4011 # Port to run the MQ server (or just listen if using an EventBridge mock server from another stack)
debug: false # flag to show debug messages
account: '' # account id that gets passed to the event
imported-event-buses:
EventBusNameFromOtherStack: event-bus-name-or-arn
If your existing EventBridge is mocked on a different host/IP (e.g. When stacks are hosted in Docker containers), then you will also need to specify a hostname
. If using Docker, you should use the name of the container that mocks the EventBridge (assuming both containers are on the same Docker network).
Plugin is capable of working against locally running docker container of localstack. For example look in sns-sqs-lambda
IMPORTANT Right now you can run this plugin in "mock server" mode or in localstack mode. By configuring localstack section in your config mock server will not be running.
To configure localstack add configuration:
custom:
serverless-offline-aws-eventbridge:
localStackConfig:
localStackEndpoint: http://localhost:4566
Or in TypeScript
'serverless-offline-aws-eventbridge': {
localStackConfig: {
localStackEndpoint: 'http://localhost:4566',
},
}
For complete guide look in to TypeScript Localstack example.
Two stacks are provided as example:
same-stack-publisher-subscriber
runs a mock of Eventbridge. It also has a local (same stack) subscriberremote-subscriber
is a completely independent microservice listening to the eventBridge mock created by thesame-stack-publisher-subscriber
stack
- Run the first stack in a terminal
cd examples/same-stack-publisher-subscriber
npm i
serverless offline start
- Run the second stack in a different terminal
cd examples/remote-subscriber
npm i
serverless offline start
- Publish a test message
Simply hit the exposed API gateway endpoint: http://localhost:3016/dev/publish
You should see the message received on both stacks in the terminal output. You will also notice that the socket connection is resilient to crashes: everything works smoothly as soon as both offline stacks are up and running, regardless of which stack has been restarted last.
This plugin was inspired by the serverless-offline-sns plugin. Also thanks to @sndpl, @guavajellyaaron, @rloomans, @JamesKyburz, @plumsirawit, @damien-thiesson, @carrickkv2, @dnalborczyk and @MichalOleszczuk for their work and PR's.