serverless-offline-sns

# serverless-offline-sns A serverless plugin to listen to offline SNS and call lambda fns with events. [![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com) [![Build Status](https://travis-ci.org/mj1618/serverless-offline-sns.svg?branch=master)](https://travis-ci.org/mj1618/serverless-offline-sns) [![npm version](https://badge.fury.io/js/serverless-offline-sns.svg)](https://badge.fury.io/js/serverless-offline-sns) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![All Contributors](https://img.shields.io/badge/all_contributors-30-orange.svg?style=flat-square)](#contributors) ## Docs - [Prerequisites](#prerequisites) - [Installation](#installation) - [Configure](#configure) - [Usage](#usage) - [Contributors](#contributors) For an example of a working application please see [serverless-offline-sns-example](https://github.com/mj1618/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](https://github.com/localstack/localstack) SNS server endpoint, you can put it in the custom config. See below for details. ## Installation Install the plugin ```bash npm install serverless-offline-sns --save ``` Let serverless know about the plugin ```YAML 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. ```YAML 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](https://github.com/dherault/serverless-offline) plugin serverless-offline-sns will start automatically. If you are not using this plugin you can run the following command instead: ```bash serverless offline-sns start ``` ## Configure Configure your function handlers with events as described in the [Serverless SNS Documentation](https://serverless.com/framework/docs/providers/aws/events/sns/) 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. ```YAML functions: pong: handler: handler.pong events: - sns: test-topic ``` Or you can use the exact ARN of the topic, in 2 ways: ```YAML functions: pong: handler: handler.pong events: - sns: arn: "arn:aws:sns:us-east-1:123456789012:test-topic" # 1st way - sns: "arn:aws:sns:us-east-1:123456789012:test-topic-two" # 2nd way ``` Here's a demo of some code that will trigger this handler: ```javascript 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: ```YAML 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. ## Hosted AWS SNS configuration In order to listen to a hosted SNS on AWS, you need the following: ```YAML custom: serverless-offline-sns: localPort: ${env:LOCAL_PORT} remotePort: ${env:SNS_SUBSCRIBE_REMOTE_PORT} host: 0.0.0.0 sns-subscribe-endpoint: ${env:SNS_SUBSCRIBE_ENDPOINT} sns-endpoint: ${env:SNS_ENDPOINT}``` ``` If you want to unsubscribe when you stop your server, then call `sls offline-sns cleanup` when the script exits. ## Usage If you use [serverless-offline](https://github.com/dherault/serverless-offline) this plugin will start automatically. However if you don't use serverless-offline you can start this plugin manually with - ```bash 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`: ```javascript // 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](https://github.com/mj1618/serverless-offline-sns/issues) and [issues](https://github.com/mj1618/serverless-offline-sns/issues). Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):  | [<img src="https://avatars0.githubusercontent.com/u/6138817?v=4" width="100px;"/> 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") | [<img src="https://avatars0.githubusercontent.com/u/517620?v=4" width="100px;"/> 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") | [<img src="https://avatars2.githubusercontent.com/u/5116271?v=4" width="100px;"/> 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") | [<img src="https://avatars3.githubusercontent.com/u/32281536?v=4" width="100px;"/> Jade Hwang](https://github.com/jadehwangsonos) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Ajadehwangsonos "Bug reports") | [<img src="https://avatars1.githubusercontent.com/u/933251?v=4" width="100px;"/> 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") | [<img src="https://avatars2.githubusercontent.com/u/9253219?v=4" width="100px;"/> 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") | [<img src="https://avatars1.githubusercontent.com/u/29059474?v=4" width="100px;"/> 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") | | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | [<img src="https://avatars2.githubusercontent.com/u/33498?v=4" width="100px;"/> Jamie Learmonth](http://www.boxlightmedia.com) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Ajamiel "Bug reports") | [<img src="https://avatars2.githubusercontent.com/u/2598355?v=4" width="100px;"/> 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") | [<img src="https://avatars3.githubusercontent.com/u/412382?v=4" width="100px;"/> 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") | [<img src="https://avatars0.githubusercontent.com/u/205515?v=4" width="100px;"/> Matt Ledom](https://github.com/mledom) [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=mledom "Code") [🎨](#design-mledom "Design") | [<img src="https://avatars3.githubusercontent.com/u/2430033?v=4" width="100px;"/> Keith Kirk](http://kmfk.io) [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=kmfk "Code") [🎨](#design-kmfk "Design") | [<img src="https://avatars1.githubusercontent.com/u/679761?v=4" width="100px;"/> Kobi Meirson](https://github.com/kobim) [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=kobim "Code") | [<img src="https://avatars2.githubusercontent.com/u/2048655?v=4" width="100px;"/> Steve Green](https://github.com/lagnat) [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=lagnat "Code") | | [<img src="https://avatars1.githubusercontent.com/u/334487?v=4" width="100px;"/> 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") | [<img src="https://avatars2.githubusercontent.com/u/592682?v=4" width="100px;"/> Zdenek Farana](https://zdenekfarana.com/) [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=byF "Code") | [<img src="https://avatars3.githubusercontent.com/u/80440?v=4" width="100px;"/> Daniel Maricic](https://woss.io) [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=woss "Code") | [<img src="https://avatars1.githubusercontent.com/u/542245?v=4" width="100px;"/> Brandon Evans](http://www.brandonmevans.com) [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=BrandonE "Code") | [<img src="https://avatars0.githubusercontent.com/u/1598537?v=4" width="100px;"/> 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") | [<img src="https://avatars1.githubusercontent.com/u/16331726?v=4" width="100px;"/> 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") | [<img src="https://avatars2.githubusercontent.com/u/6473775?v=4" width="100px;"/> Clement134](https://github.com/Clement134) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3AClement134 "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=Clement134 "Code") | | [<img src="https://avatars3.githubusercontent.com/u/33069039?v=4" width="100px;"/> PJ Cavanaugh](https://github.com/pjcav) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Apjcav "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=pjcav "Code") | [<img src="https://avatars3.githubusercontent.com/u/25830138?v=4" width="100px;"/> Victor Ferreira](https://github.com/victorsferreira) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Avictorsferreira "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=victorsferreira "Code") | [<img src="https://avatars2.githubusercontent.com/u/12129589?v=4" width="100px;"/> Theo](https://github.com/shierro) [📖](https://github.com/mj1618/serverless-offline-sns/commits?author=shierro "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/47985584?v=4" width="100px;"/> Matt Telesky](https://github.com/mteleskycmp) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Amteleskycmp "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=mteleskycmp "Code") | [<img src="https://avatars3.githubusercontent.com/u/4624648?v=4" width="100px;"/> Garrett Scott](https://github.com/perkyguy) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Aperkyguy "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=perkyguy "Code") | [<img src="https://avatars3.githubusercontent.com/u/428113?v=4" width="100px;"/> Patrice Gargiolo](https://github.com/Pat-rice) [📖](https://github.com/mj1618/serverless-offline-sns/commits?author=Pat-rice "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/5074290?v=4" width="100px;"/> Michael W. Martin](https://games.crossfit.com/athlete/110515) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Aanaerobic "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=anaerobic "Code") | | [<img src="https://avatars0.githubusercontent.com/u/18377620?v=4" width="100px;"/> mr-black-8](https://github.com/mr-black-8) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Amr-black-8 "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=mr-black-8 "Code") | [<img src="https://avatars1.githubusercontent.com/u/314629?v=4" width="100px;"/> Matthew Miller](https://github.com/brocksamson) [🐛](https://github.com/mj1618/serverless-offline-sns/issues?q=author%3Abrocksamson "Bug reports") [💻](https://github.com/mj1618/serverless-offline-sns/commits?author=brocksamson "Code") |  This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!