# serverless-offline-aws-eventbridge > Serverless plugin to run event bridge offline. Localstack support. Latest version **2.2.4** (published 2024-11-22) · MIT license · 0 weekly downloads ## Install ```sh npm install serverless-offline-aws-eventbridge pnpm add serverless-offline-aws-eventbridge yarn add serverless-offline-aws-eventbridge bun add serverless-offline-aws-eventbridge ``` ## Health **Score 25/100 (F)** — status: maintenance-mode. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; large bundle. Negative: stale; low maintenance score. ## Facts | | | |---|---| | Version | 2.2.4 | | Published | 2024-11-22 | | First published | 2020-05-28 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 8 | | Unpacked size | 164.7 MB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 57 | | Author | Ruben Kaiser | | Maintainers | rkaiser | | Keywords | serverless, serverless-offline, eventbridge, localstack | ## Links - npm: https://www.npmjs.com/package/serverless-offline-aws-eventbridge - Repository: https://github.com/rubenkaiser/serverless-offline-eventBridge - Homepage: https://github.com/rubenkaiser/serverless-offline-eventBridge#readme - Issues: https://github.com/rubenkaiser/serverless-offline-eventBridge/issues - npm.io page: https://npm.io/package/serverless-offline-aws-eventbridge ## Dependencies (8) - [cors](https://npm.io/package/cors.md) ^2.8.5 - [mqtt](https://npm.io/package/mqtt.md) ^4.3.7 - [aedes](https://npm.io/package/aedes.md) ^0.49.0 - [express](https://npm.io/package/express.md) ^4.21.0 - [jsonpath](https://npm.io/package/jsonpath.md) ^1.1.1 - [deepmerge](https://npm.io/package/deepmerge.md) ^4.3.1 - [node-cron](https://npm.io/package/node-cron.md) ^3.0.2 - [@aws-sdk/client-eventbridge](https://npm.io/package/@aws-sdk/client-eventbridge.md) ^3.315.0 ## Alternatives - [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads - [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads - [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads - [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads - [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads ## Recent versions - 2.2.4 (latest) — 2024-11-22 - 2.2.3-beta.1 (beta) — 2024-10-08 - 2.2.3-beta.0 — 2024-10-02 - 2.2.2 — 2024-09-17 - 2.2.1 — 2024-08-30 - 2.2.0 — 2024-08-19 - 2.2.0-beta.1 — 2023-10-01 - 2.2.0-beta.0 — 2023-10-01 - 2.1.0 — 2023-06-07 - 2.1.0-beta.0 — 2023-04-23 - 2.0.5 — 2023-02-03 - 2.0.4 — 2023-01-12 - 2.0.4-beta.1 — 2023-01-12 - 2.0.4-beta.0 — 2023-01-12 - 2.0.3 — 2022-10-03 - … 41 more at https://npm.io/package/serverless-offline-aws-eventbridge/versions ## README # 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. [![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com) [![npm version](https://badge.fury.io/js/serverless-offline-aws-eventbridge.svg)](https://badge.fury.io/js/serverless-offline-aws-eventbridge) [![npm package](https://img.shields.io/npm/dm/serverless-offline-aws-eventbridge.svg)](https://www.npmjs.com/package/serverless-offline-aws-eventbridge) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ## Docs - [Installation](#installation) - [Configure](#configure) - [Usage](#usage) - [Versions](#versions) - [Thanks](#thanks) ## Installation Install the plugin ```bash 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 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 ```YAML plugins: - serverless-offline - serverless-offline-aws-eventbridge ``` Configuring the plugin optional options shown with defaults ```YAML 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) ``` ## 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. ```YAML 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) ```javascript 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": "some@someemail.some" }`, }, ] }).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": "some@someemail.some" }`, } */ return { statusCode: 200, body: JSON.stringify(event) }; } export const scheduled = async (event, context) => { console.log('scheduled event'); return { statusCode: 200, body: 'scheduled event' }; } ``` ## 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` ```yaml functions: consumeEvent: handler: events.consume events: - eventBridge: eventBus: marketing pattern: source: - user detail-type: - { "anything-but": "deleted" } detail: firstname: [ { "prefix": "John" } ] occupation: [ { "suffix": "man" } ] 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: ```YAML 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. ```YAML 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: ```YAML 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). ## Localstack Plugin is capable of working against locally running docker container of localstack. For example look in [sns-sqs-lambda](examples/typescript//localstack//sns-sqs-lambda/README.md) **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: ```YAML custom: serverless-offline-aws-eventbridge: localStackConfig: localStackEndpoint: http://localhost:4566 ``` Or in TypeScript ```typescript 'serverless-offline-aws-eventbridge': { localStackConfig: { localStackEndpoint: 'http://localhost:4566', }, } ``` For complete guide look in to [TypeScript Localstack example](./examples//typescript//localstack/sns-sqs-lambda). ### Currently supported targets - [SNS](./examples//typescript//localstack//sns-sqs-lambda//README.md#L7) ## 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 ```bash cd examples/same-stack-publisher-subscriber npm i serverless offline start ``` 2) Run the second stack in a different terminal ```bash cd examples/remote-subscriber npm i serverless 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. --- _Source: https://npm.io/package/serverless-offline-aws-eventbridge · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._