serverless-offline-aws-eventbridge

A serverless offline plugin that enables aws eventBridge events. As of version 1.4.0 this plugin also supports non javascript handlers.

Docs

• Installation
• Configure
• Usage
• Versions
• Thanks

Installation

Install the plugin

1npm 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 https://github.com/rubenkaiser/serverless-offline-eventBridge/issues/60

Let serverless know about the plugin, also note the order when combined with serverless webpack and offline

1plugins:
2  - serverless-offline
3  - serverless-offline-aws-eventbridge

Configuring the plugin

optional options shown with defaults

1custom:
2  serverless-offline-aws-eventbridge:
3    port: 4010 # port to run the eventBridge mock server on
4    mockEventBridgeServer: true # Set to false if EventBridge is already mocked by another stack
5    hostname: 127.0.0.1 # IP or hostname of existing EventBridge if mocked by another stack
6    pubSubPort: 4011 # Port to run the MQ server (or just listen if using an EventBridge Mock server from another stack)
7    debug: false # flag to show debug messages
8    account: '' # account id that gets passed to the event
9    maximumRetryAttempts: 10 # maximumRetryAttempts to retry lambda
10    retryDelayMs: 500 # retry delay
11    throwRetryExhausted: false # default true
12    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)

Publishing and subscribing

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.

1functions:
2  publishEvent:
3    handler: events.publish
4    events:
5      - http:
6          path: publish
7          method: get
8
9  consumeEvent:
10    handler: events.consume
11    events:
12      - eventBridge:
13          eventBus: marketing
14          pattern:
15            source:
16              - acme.newsletter.campaign
17
18  scheduledEvent:
19    handler: events.scheduled
20    events:
21      - eventBridge:
22          eventBus: marketing
23          # run every 5 minutes
24          schedule: "cron(0/5 * * * ? *)"

The events handler with two functions (publish and consume)

1  import AWS from 'aws-sdk';
2
3  export const publish = async () => {
4    try {
5      const eventBridge = new AWS.EventBridge({
6        endpoint: 'http://127.0.0.1:4010',
7        accessKeyId: "YOURKEY",
8        secretAccessKey: "YOURSECRET",
9        region: "eu-west-1"
10      });
11
12      await eventBridge.putEvents({
13        Entries: [
14          {
15            EventBusName: 'marketing',
16            Source: 'acme.newsletter.campaign',
17            DetailType: 'UserSignUp',
18            Detail: `{ "E-Mail": "some@someemail.some" }`,
19          },
20        ]
21      }).promise();
22      return { statusCode: 200, body: 'published' };
23    } catch (e) {
24      console.error(e);
25      return { statusCode: 400, body: 'could not publish' };
26    }
27  }
28
29  export const consume = async (event, context) => {
30    console.log(event);
31    /*
32      {
33        EventBusName: 'marketing',
34        Source: 'acme.newsletter.campaign',
35        DetailType: 'UserSignUp',
36        Detail: `{ "E-Mail": "some@someemail.some" }`,
37      }
38    */
39    return { statusCode: 200, body: JSON.stringify(event) };
40  }
41
42  export const scheduled = async (event, context) => {
43    console.log('scheduled event');
44    return { statusCode: 200, body: 'scheduled event' };
45  }

Support of EventBridge patterns

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
• suffix
• anything-but
• exists

1functions:
2  consumeEvent:
3    handler: events.consume
4    events:
5      - eventBridge:
6          eventBus: marketing
7          pattern:
8            source:
9              - user
10            detail-type:
11              - { "anything-but": "deleted" }
12            detail:
13              firstname: [ { "prefix": "John" } ]
14              occupation: [ { "suffix": "man" } ]
15              age: [ { "exists": true } ]

The cidr filter is yet to be implemented.

Using CloudFormation intrinsic functions

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:

1functions:
2
3  consumeEvent:
4    handler: events.consume
5    events:
6      - eventBridge:
7          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.

1functions:
2
3  consumeEvent:
4    handler: events.consume
5    events:
6      - eventBridge:
7          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:

1custom:
2  serverless-offline-aws-eventbridge:
3    port: 4010 # port to run the eventBridge mock server on
4    mockEventBridgeServer: true # Set to false if EventBridge is already mocked by another stack
5    hostname: 127.0.0.1 # IP or hostname of existing EventBridge if mocked by another stack
6    pubSubPort: 4011 # Port to run the MQ server (or just listen if using an EventBridge mock server from another stack)
7    debug: false # flag to show debug messages
8    account: '' # account id that gets passed to the event
9    imported-event-buses:
10      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).

Localstack

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:

1custom:
2  serverless-offline-aws-eventbridge:
3    localStackConfig:
4      localStackEndpoint: http://localhost:4566

Or in TypeScript

1'serverless-offline-aws-eventbridge': {
2      localStackConfig: {
3        localStackEndpoint: 'http://localhost:4566',
4      },
5    }

For complete guide look in to TypeScript Localstack example.

Currently supported targets

• SNS

Examples

Two stacks are provided as example:

• same-stack-publisher-subscriber runs a mock of Eventbridge. It also has a local (same stack) subscriber
• remote-subscriber is a completely independent microservice listening to the eventBridge mock created by the same-stack-publisher-subscriber stack

1. Run the first stack in a terminal

1cd examples/same-stack-publisher-subscriber
2npm i
3serverless offline start

2. Run the second stack in a different terminal

1cd examples/remote-subscriber
2npm i
3serverless offline start

3. 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.

Thanks

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.