SNS

SNS is a custom Python reimplementation. 36 of the 42 SNS operations are implemented in LocalEmu's own code: standard and FIFO topics, nine subscription protocols (HTTP, HTTPS, email, email-json, SMS, SQS, application, Lambda, Firehose), filter policies on message attributes or message body, per-subscription DLQs, FIFO content-based deduplication with a 5-minute window, subscription confirmation tokens, application platform endpoints for mobile push, phone-number opt-out, and three CloudFormation resource types.

SMS and mobile push (the sms and application subscription protocols) do not reach a real carrier or push service. Messages are stored in LocalEmu and can be inspected over HTTP at /_aws/sns/sms-messages and /_aws/sns/platform-endpoint-messages. The other seven protocols deliver to the corresponding LocalEmu service.

Operation-level coverage: see the SNS coverage matrix.

Quick start

Create a topic, subscribe an SQS queue, publish a message, read it from the queue.

$ awsemu sns create-topic --name orders
{
  "TopicArn": "arn:aws:sns:us-east-1:000000000000:orders"
}

$ awsemu sqs create-queue --queue-name order-events
$ QURL=http://sqs.us-east-1.localhost:4566/000000000000/order-events
$ QARN=$(awsemu sqs get-queue-attributes --queue-url $QURL \
    --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)

$ awsemu sns subscribe \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders \
    --protocol sqs \
    --notification-endpoint $QARN

$ awsemu sns publish \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders \
    --message '{"order_id":"o-42","total":99}'

$ awsemu sqs receive-message --queue-url $QURL --query 'Messages[0].Body' --output text
{"Type":"Notification","MessageId":"...","TopicArn":"arn:aws:sns:us-east-1:000000000000:orders","Message":"{\"order_id\":\"o-42\",\"total\":99}", ...}

Architecture

SNS lives at services/sns/. The provider class SnsProvider (provider.py:156) handles the API surface and routes published messages through the PublishDispatcher:

• •
  Publish dispatch at publisher.py:1248: looks up every subscription on the topic, applies each subscription's filter policy, and forwards the message to the protocol-specific publisher.
• •
  Per-topic ordering at publisher.py:1332-1335: FIFO topics use a partitioned thread-pool executor keyed by MessageGroupId, so messages within the same group are processed serially; standard topics use a shared executor.
• •
  Filter policy evaluator at filter.py: parses and applies filter policies against either the message attributes (default) or the message body. Up to 5 keys per policy, up to 150 value combinations.
• •
  FIFO dedup cache at models.py:218-219: per-topic map of dedup-id to (message-id, sequence-number, timestamp). Entries older than the 5-minute window are pruned on each publish. Mutation is protected by a threading lock.
• •
  Confirmation tokens at provider.py:469-492: 288-hex-character tokens minted on Subscribe for HTTP/HTTPS subscribers and posted to the subscriber endpoint inside a SubscriptionConfirmation envelope. Non-HTTP subscribers (SQS, Lambda, Firehose, application, SMS) are auto-confirmed.

State lives in SnsStore (models.py:182): topics, subscriptions, FIFO dedup cache, platform applications, platform endpoint messages, SMS messages, opted-out phone numbers, and subscription confirmation tokens. When PERSISTENCE=1 is set, the store is serialised and restored across restarts.

Subscription protocols

Nine protocols are accepted by Subscribe (services/sns/constants.py:7-17). Each has its own publisher class in services/sns/publisher.py.

Configuration

Features supported

FIFO topics

FIFO topics preserve publish order within a MessageGroupId and deduplicate messages within a 5-minute window. The dispatch executor partitions work by group ID, so messages in the same group run serially while different groups run in parallel.

• •
  Required on publish: MessageGroupId. Either MessageDeduplicationId must be set, or the topic must have ContentBasedDeduplication=true.
• •
  Dedup window: 5 minutes. Re-publishing the same dedup ID inside the window returns the original MessageId and silently drops the duplicate.
• •
  Sequence numbers: the response includes SequenceNumber, monotonic across all FIFO topics in the account.
• •
  Subscriber constraint: a FIFO topic can only subscribe a FIFO SQS queue. The validation runs at provider.py:396-400.

$ awsemu sns create-topic --name orders.fifo \
    --attributes FifoTopic=true,ContentBasedDeduplication=true

$ awsemu sqs create-queue --queue-name order-events.fifo \
    --attributes FifoQueue=true,ContentBasedDeduplication=true

$ QARN=arn:aws:sqs:us-east-1:000000000000:order-events.fifo
$ awsemu sns subscribe \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders.fifo \
    --protocol sqs \
    --notification-endpoint $QARN

# Three messages, same MessageGroupId => strict order downstream
$ for i in 1 2 3; do
    awsemu sns publish \
        --topic-arn arn:aws:sns:us-east-1:000000000000:orders.fifo \
        --message-group-id customer-42 \
        --message "{\"order\": $i}"
  done

$ awsemu sqs receive-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/order-events.fifo \
    --max-number-of-messages 10 --wait-time-seconds 2 \
    --query 'Messages[].Body' --output json | python3 -c "import sys,json; [print(json.loads(m)[\"Message\"]) for m in json.load(sys.stdin)]"
{"order": 1}
{"order": 2}
{"order": 3}

Filter policies

A subscription's FilterPolicy attribute decides which published messages reach that subscription. The policy is JSON; each key maps to a list of value matchers. The default FilterPolicyScope is MessageAttributes; set it to MessageBody to match against the message body instead.

Operators are exact-string, numeric ranges, prefix, suffix, anything-but, and exists. A policy can declare up to 5 keys and the cross-product of all value alternatives must not exceed 150 combinations (filter.py:290 and filter.py:298).

$ awsemu sns subscribe \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders \
    --protocol sqs \
    --notification-endpoint $QARN \
    --attributes '{
      "FilterPolicy": "{\"priority\":[\"high\"],\"total\":[{\"numeric\":[\">\",100]}]}",
      "FilterPolicyScope": "MessageAttributes"
    }'

# This message matches: priority=high AND total>100. It is delivered.
$ awsemu sns publish \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders \
    --message 'priority order' \
    --message-attributes '{
      "priority": {"DataType":"String","StringValue":"high"},
      "total":    {"DataType":"Number","StringValue":"500"}
    }'

# This message does NOT match (priority=low). It is dropped before reaching the queue.
$ awsemu sns publish \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders \
    --message 'noise' \
    --message-attributes '{
      "priority": {"DataType":"String","StringValue":"low"}
    }'

Wire a topic to Lambda

$ awsemu lambda create-function \
    --function-name on-order \
    --runtime python3.12 \
    --role arn:aws:iam::000000000000:role/lambda-role \
    --handler handler.handler \
    --zip-file fileb://handler.zip

$ FARN=arn:aws:lambda:us-east-1:000000000000:function:on-order
$ awsemu sns subscribe \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders \
    --protocol lambda \
    --notification-endpoint $FARN

$ awsemu sns publish \
    --topic-arn arn:aws:sns:us-east-1:000000000000:orders \
    --message '{"order_id":"o-99"}'

# The Lambda is invoked asynchronously with the SNS event envelope
$ awsemu logs tail /aws/lambda/on-order --follow

Inspecting stored protocols

SMS and mobile push do not leave LocalEmu. The published messages are kept in memory and four internal HTTP endpoints let you inspect them:

# Inspect the SMS publish history (sms protocol + direct phone-number publishes)
$ curl -s http://localhost:4566/_aws/sns/sms-messages

# Inspect mobile push history (application platform endpoints)
$ curl -s http://localhost:4566/_aws/sns/platform-endpoint-messages

# Look up subscription confirmation tokens
$ curl -s http://localhost:4566/_aws/sns/subscription-tokens

# Phone numbers that called OptOutPhoneNumber
$ curl -s http://localhost:4566/_aws/sns/phone-opt-outs

Subscription confirmation

When you call Subscribe, the behaviour depends on the protocol:

Tokens are 288 hex characters and encode the region. Token validation strips region back out so cross-region confirmations work without extra plumbing.

Limits and defaults

Known limitations

• •
  SMS does not reach a carrier. Messages published through the sms protocol or a direct phone-number publish are stored at /_aws/sns/sms-messages. No real SMS is sent.
• •
  Mobile push does not reach APNs, FCM, or any other push service. Messages routed to platform endpoints are stored at /_aws/sns/platform-endpoint-messages.
• •
  Email confirmation links are not delivered for you. Email subscriptions stay in PendingConfirmation. Either fetch the token from /_aws/sns/subscription-tokens and call ConfirmSubscription, or run an SES inbox-watcher to follow the link.
• •
  Server-side encryption (KmsMasterKeyId) is not implemented. Setting the attribute has no effect on the stored message bodies.
• •
  Topic policy is stored, not enforced. AddPermission and RemovePermission update the Policy attribute, but cross-account publishes and subscribes are accepted regardless of the policy contents.
• •
  Subscription-level tags are stored only partially. TagResource on a subscription ARN succeeds, but the tags do not round-trip through GetSubscriptionAttributes.
• •
  SMS Sandbox is not implemented. Six operations return NotImplementedException: CreateSMSSandboxPhoneNumber, DeleteSMSSandboxPhoneNumber, GetSMSSandboxAccountStatus, ListOriginationNumbers, ListSMSSandboxPhoneNumbers, VerifySMSSandboxPhoneNumber.