Serverless Offline SNS
Serverless plugin to run a local SNS server and call serverless SNS handlers with events notifications.
Looking for a maintainer for this project, email me if you are interested.
# serverless-offline-sns
A serverless plugin to listen to offline SNS and call lambda fns with events.
[](http://www.serverless.com)
[](https://badge.fury.io/js/serverless-offline-sns)
[](#contributing)
[](https://github.com/prettier/prettier)
[](https://opensource.org/licenses/MIT)
[](#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 SNS provider endpoint
# sns-subscribe-endpoint: http://127.0.0.1:3000 # Optional. Only if you want to use a custom subscribe endpoint from SNS to send messages back to
# accountId: 123456789012 # Optional
# location: .build # Optional if the location of your handler.js is not in ./ (useful for typescript)
```
For example, if you would like to connect to AWS and have callbacks coming via ngrok, use:
```YAML
serverless-offline-sns:
sns-endpoint: sns.${self:provider.region}.amazonaws.com
sns-subscribe-endpoint:
remotePort: 80
localPort:
accountId: ${self:provider.accountId}
```
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: "{content: \"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.
## Multiple serverless services configuration
If you have multiple serverless services, please specify a root directory:
```YAML
custom:
serverless-offline-sns:
servicesDirectory: "/path/to/directory"
```
The root directory must contain directories with serverless.yaml files inside.
## 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)):
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!
