SNS fan-out

This guide covers the SNS surface: topic management, subscriptions and the confirmation flow, message filtering, raw vs enveloped delivery, PublishBatch, FIFO topics, and MessageStructure=json. SNS topics are virtual BoltDB registry entries (no native channel) that fan out, at publish time, to SQS subscriptions and HTTP/HTTPS webhooks. The SNS surface ships 17 actions (see Capabilities).

Topic management

• CreateTopic — idempotent on an existing name; a FIFO topic uses the .fifo suffix.
• DeleteTopic — cascades its subscriptions.
• ListTopics — ARN-sorted, 100 per page; not authorization-filtered.
• GetTopicAttributes / SetTopicAttributes — the only writable attributes are DisplayName and DeliveryPolicy.

Subscriptions

Subscribe accepts three protocols only:

The writable subscription attributes are RawMessageDelivery (bool), FilterPolicy (JSON, parsed and validated at set), FilterPolicyScope, RedrivePolicy (JSON), and DeliveryPolicy.

The http/https confirmation GET is SigV4-exempt so the SubscribeURL embedded in a SubscriptionConfirmation envelope is usable as-is — see Authentication.

Message filtering

A FilterPolicy filters which subscriptions receive a publish. All 8 AWS operators are supported: exact string/number/bool, prefix, suffix, anything-but, numeric comparison/range, exists true/false, and CIDR. Keys are ANDed, values within a key ORed; an empty policy matches everything. Write-time limits: ≤ 5 keys, ≤ 150 value combinations. Binary attributes match only exists:true.

Raw vs enveloped delivery

RawMessageDelivery controls the delivered shape:

• Enveloped (false, the default) — the body is the SNS Notification JSON: {Type:"Notification", MessageId, TopicArn, Subject?, Message, Timestamp, SignatureVersion:"1", Signature:"", SigningCertURL:"", UnsubscribeURL, MessageAttributes?}. Each MessageAttributes entry is {Type, Value} (Binary is base64).
• Raw (true) — for an SQS subscription, the bare message bytes plus the attribute tag codec and sns_topic_arn / sns_subject tags; for an HTTP subscription, the bare payload with attributes mapped to x-amz-sns-attr-{name} headers.

Fan-out semantics

Publish / PublishBatch fan out to every confirmed, filter-matching subscription:

• there is one MessageId per publish, shared across all deliveries;
• all sqs deliveries of one publish go out in a single SendQueueMessagesBatch;
• per-target failures (deleted queue, unauthorized, oversize, FIFO mismatch) are dropped with a metric and do not fail the publish;
• zero matching subscriptions → the publish succeeds and the message is dropped;
• a per-target Casbin write check applies on each sqs.{queue}.

MessageStructure=json is supported: pass a JSON object with a string default key plus optional per-protocol string overrides.

FIFO topics

A .fifo topic restricts Subscribe to the sqs protocol onto a .fifo queue (http / https are rejected). Publish / PublishBatch:

• require MessageGroupId (and reject it on a standard topic);
• treat MessageDeduplicationId as optional — topic-level content-based dedup is unsupported, so pass it explicitly.

Group and dedup ids propagate into the FIFO queue-message build. See Reliability for the full FIFO ordering and dedup detail.

Error quick reference

Related