Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including serverless-offline-sns with all npm packages installed. Try it out:

var serverlessOfflineSns = require("serverless-offline-sns")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

serverless-offline-sns v0.53.0

Serverless plugin to run a local SNS server and call lambdas with events notifications.

serverless-offline-sns

A serverless plugin to listen to offline SNS and call lambda fns with events.

serverless Build Status npm version PRs Welcome License: MIT All Contributors

Docs

For an example of a working application please see serverless-offline-sns-example

Prerequisites

This plugin provides an SNS server configured automatically without you specifying an endpoint.

If you'd rather use your own endpoint, e.g. from your AWS account or a localstack SNS server endpoint, you can put it in the custom config. See below for details.

Installation

Install the plugin

npm install serverless-offline-sns --save

Let serverless know about the plugin

plugins:
  - serverless-offline-sns

Note that ordering matters when used with serverless-offline and serverless-webpack. serverless-webpack must be specified at the start of the list of plugins.

Configure the plugin with your offline SNS endpoint, host to listen on, and a free port the plugin can use.

custom:
  serverless-offline-sns:
    port: 4002 # a free port for the sns server to run on
    debug: false
    # host: 0.0.0.0 # Optional, defaults to 127.0.0.1 if not provided to serverless-offline
    # sns-endpoint: http://127.0.0.1:4567 # Optional. Only if you want to use a custom endpoint
    # accountId: 123456789012 # Optional

In normal operation, the plugin will use the same --host option as provided to serverless-offline. The host parameter as shown above overrides this setting.

If you are using the serverless-offline plugin serverless-offline-sns will start automatically. If you are not using this plugin you can run the following command instead:

serverless offline-sns start

Configure

Configure your function handlers with events as described in the Serverless SNS Documentation

Here's an example serverless.yml config which calls a function on an SNS notifcation. Note that the offline-sns plugin will automatically pick up this config, subscribe to the topic and call the handler on an SNS notification.

functions:
  pong:
    handler: handler.pong
    events:
      - sns: test-topic

Or you can use the exact ARN of the topic:

functions:
  pong:
    handler: handler.pong
    events:
      - sns:
         arn: "arn:aws:sns:us-east-1:123456789012:test-topic"

Here's a demo of some code that will trigger this handler:

var AWS = require("aws-sdk"); // must be npm installed to use
var sns = new AWS.SNS({
  endpoint: "http://127.0.0.1:4002",
  region: "us-east-1",
});
sns.publish({
  Message: "hello!",
  MessageStructure: "json",
  TopicArn: "arn:aws:sns:us-east-1:123456789012:test-topic",
}, () => {
  console.log("ping");
});

Note the region that offline-sns will listen on is what is configured in your serverless.yml provider.

Localstack docker configuration

In order to listen to localstack SNS event, if localstack is started with docker, you need the following:

custom:
  serverless-offline-sns:
    host: 0.0.0.0 # Enable plugin to listen on every local address
    sns-subscribe-endpoint: 192.168.1.225 #Host ip address
    sns-endpoint: http://localhost:4575 # Default localstack sns endpoint

What happens is that the container running localstack will execute a POST request to the plugin, but to reach outside the container, it needs to use the host ip address.

Usage

If you use serverless-offline this plugin will start automatically.

However if you don't use serverless-offline you can start this plugin manually with -

serverless offline-sns start

Subscribing

serverless-offline-sns supports http, https, and sqs subscriptions. email, email-json, sms, application, and lambda protocols are not supported at this time.

When using sqs the Endpoint for the subscription must be the full QueueUrl returned from the SQS service when creating the queue or listing with ListQueues:

// async
const queue = await sqs.createQueue({ QueueName: 'my-queue' }).promise();
const subscription = await sns.subscribe({
    TopicArn: myTopicArn,
    Protocol: 'sqs',
    Endpoint: queue.QueueUrl,
}).promise();

Contributors

Happy to accept contributions, feature requests and issues.

Thanks goes to these wonderful people (emoji key):

| [Matthew James
Matthew James](https://github.com/mj1618)
[💬](#question-mj1618 "Answering Questions") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=mj1618 "Code") [🎨](#design-mj1618 "Design") [📖](https://github.com/mj1618/serverless-offline-sns/commits?author=mj1618 "Documentation") [💡](#example-mj1618 "Examples") | [darbio
darbio](https://github.com/darbio)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Adarbio "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=darbio "Code") | [TiVoMaker
TiVoMaker](https://github.com/TiVoMaker)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3ATiVoMaker "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=TiVoMaker "Code") [🎨](#design-TiVoMaker "Design") [📖](https://github.com/mj1618/serverless-offline-sns/commits?author=TiVoMaker "Documentation") | [Jade Hwang
Jade Hwang](https://github.com/jadehwangsonos)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Ajadehwangsonos "Bug reports") | [Bennett Rogers
Bennett Rogers](https://github.com/bennettrogers)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Abennettrogers "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=bennettrogers "Code") | [Julius Breckel
Julius Breckel](https://github.com/jbreckel)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=jbreckel "Code") [💡](#example-jbreckel "Examples") [⚠️](https://github.com/mj1618/serverless-offline-sns/commits?author=jbreckel "Tests") | [RainaWLK
RainaWLK](https://github.com/RainaWLK)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3ARainaWLK "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=RainaWLK "Code") | | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | [Jamie Learmonth
Jamie Learmonth](http://www.boxlightmedia.com)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Ajamiel "Bug reports") | [Gevorg A. Galstyan
Gevorg A. Galstyan](https://github.com/gevorggalstyan)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Agevorggalstyan "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=gevorggalstyan "Code") | [Ivan Montiel
Ivan Montiel](https://idmontie.github.io)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Aidmontie "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=idmontie "Code") [⚠️](https://github.com/mj1618/serverless-offline-sns/commits?author=idmontie "Tests") | [Matt Ledom
Matt Ledom](https://github.com/mledom)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=mledom "Code") [🎨](#design-mledom "Design") | [Keith Kirk
Keith Kirk](http://kmfk.io)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=kmfk "Code") [🎨](#design-kmfk "Design") | [Kobi Meirson
Kobi Meirson](https://github.com/kobim)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=kobim "Code") | [Steve Green
Steve Green](https://github.com/lagnat)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=lagnat "Code") | | [Daniel
Daniel](http://dandoes.net)
[🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3ADanielSchaffer "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=DanielSchaffer "Code") [🎨](#design-DanielSchaffer "Design") | [Zdenek Farana
Zdenek Farana](https://zdenekfarana.com/)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=byF "Code") | [Daniel Maricic
Daniel Maricic](https://woss.io)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=woss "Code") | [Brandon Evans
Brandon Evans](http://www.brandonmevans.com)
[💻](https://github.com/mj1618/serverless-offline-sns/commits?author=BrandonE "Code") | [AJ Stuyvenberg
AJ Stuyvenberg](https://aaronstuyvenberg.com)
[💬](#question-astuyve "Answering Questions") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=astuyve "Code") [⚠️](https://github.com/mj1618/serverless-offline-sns/commits?author=astuyve "Tests") | [justin.kruse
justin.kruse](https://github.com/jkruse14)
[⚠️](https://github.com/mj1618/serverless-offline-sns/commits?author=jkruse14 "Tests") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=jkruse14 "Code") |

This project follows the all-contributors specification. Contributions of any kind welcome!

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free