A serverless plugin to listen to offline SNS and call lambda fns with events.
Originally created and maintained for nearly 10 years by Matthew James.
- Prerequisites
- Installation
- Configure
- HTTP delivery retry
- Subscription filter policies
- Usage
- Contributors
For an example of a working application please see serverless-offline-sns-example
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.
Install the plugin
npm install serverless-offline-sns --saveLet serverless know about the plugin
plugins:
- serverless-offline-snsNote 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 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:
serverless-offline-sns:
sns-endpoint: sns.${self:provider.region}.amazonaws.com
sns-subscribe-endpoint: <ngrok_url>
remotePort: 80
localPort: <ngrok_port>
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 plugin serverless-offline-sns will start automatically. If you are not using this plugin you can run the following command instead:
serverless offline-sns startConfigure 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-topicOr you can use the exact ARN of the topic, in 2 ways:
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 wayHere'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: "{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.
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 endpointWhat 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.
In order to listen to a hosted SNS on AWS, you need the following:
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.
If you have multiple serverless services, please specify a root directory:
custom:
serverless-offline-sns:
servicesDirectory: "/path/to/directory"The root directory must contain directories with serverless.yaml files inside.
By default, failed HTTP deliveries (connection errors or non-2xx responses) are not retried. You can configure retries to better simulate AWS SNS's delivery policy:
custom:
serverless-offline-sns:
port: 4002
retry: 3 # number of retry attempts after the initial failure (default: 0)
retry-interval: 1000 # delay in milliseconds between retries (default: 0)With retry: 3, a failing endpoint will be attempted up to 4 times in total (1 initial + 3 retries). Both network errors and HTTP error responses (4xx/5xx) trigger a retry.
Subscription filter policies are supported for both MessageAttributes (default) and MessageBody scopes, matching real AWS SNS behaviour.
functions:
myFunction:
handler: handler.myFunction
events:
- sns:
topicName: my-topic
filterPolicy:
eventType:
- order.created
- order.updatedOnly messages whose MessageAttributes include an eventType matching one of the listed values are delivered. Messages that do not satisfy all filter conditions are silently dropped.
Set filterPolicyScope: MessageBody to match filter policy keys against top-level fields in the JSON message body instead:
functions:
myFunction:
handler: handler.myFunction
events:
- sns:
topicName: my-topic
filterPolicyScope: MessageBody
filterPolicy:
eventType:
- order.created
- order.updatedThe message body must be valid JSON, and the filter policy keys must match top-level fields. If the message body is not valid JSON or a required key is absent, the message is dropped.
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 startserverless-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();Happy to accept contributions, feature requests and issues.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
