Skip to content

Topology and naming

The shape

Publish("orders.created")
        |
        v
SNS topic  orders_created        (FIFO: orders_created.fifo)
        |   raw subscription, one per consumer
        +-----------------> SQS queue  billing        (FIFO: billing.fifo)  --redrive--> dead-letter queue
        +-----------------> SQS queue  shipping       ...

A subject has one SNS topic. Each durable subscription has one SQS queue, subscribed to the topic of each subject it consumes. Publishing is one SNS Publish to the topic; SNS fans it out to every subscribed queue. A nil Publish error means SNS accepted the message for delivery to every subscribed queue. It does not mean a queue has it: a queue subscribed after the publish never sees it.

Names

What Derived from Standard FIFO
topic the subject each . replaced by _ the same, plus .fifo
queue, AtLeastOnce DurableName as is plus .fifo
queue, AtMostOnce and Competing Group not available plus .fifo
queue, AtMostOnce and Fanout none: created not available ephemeral- plus 16 hex digits, plus .fifo
  • The mapping from subject to topic is one-way. orders.created and orders_created are the same topic. A subject is tokens of A-Z a-z 0-9 _ . -, and a topic name is A-Z a-z 0-9 _ -, which is why only the dot is translated.
  • A queue name, suffix included, over 80 characters is refused at Subscribe: messaging-sqs: queue name "…" is longer than SQS's 80 characters. Topic names are not length-checked.
  • Which of FIFO and Standard you use is not a setting on the queue. It is in the name: a FIFO backend looks for billing.fifo, a Standard one for billing.

What the default lookup does

ByName is the default Topology.

  • A queue: GetQueueUrl on the derived name. Any failure is sqs.ErrNoQueue wrapping the queue name and the SDK's message.
  • A topic: SNS has no lookup by name, so it pages ListTopics and takes the first ARN ending in : plus the derived name. It does this once per subject and remembers the answer for the life of the session. A listing failure is wrapped as messaging-sqs: listing topics for "…". No match is sqs.ErrNoTopic. With many topics, supply a Topology that knows its ARNs.

What Subscribe checks, in order

  1. the subscription is admissible: an exact subject; a mode the backend declares; a MaxProcessingTime of no more than twelve hours unless MaxHeadroom;
  2. the subject's topic exists;
  3. the queue exists, and its name is no more than 80 characters;
  4. the queue's VisibilityTimeout and RedrivePolicy can be read;
  5. under AtLeastOnce, the redrive policy exists and its maxReceiveCount equals MaxDeliver;
  6. the lease can be derived from AckWait or the queue's VisibilityTimeout.

It does not check that the queue is subscribed to the topic, that the subscription is raw, or that the dead-letter queue exists. A failure at any step after the queue is made discards an ephemeral queue it created.

What Publish sends

Part Sent as
the event, written by Settings.Format the SNS message body and its message attributes
FIFO only: the message group ID the subject, or the SHA-256 hex of the subject when it is over 128 characters, SNS's limit
FIFO only: the deduplication ID the SHA-256 hex of the event's Source, a NUL byte, and its ID. The pair is what CloudEvents defines uniqueness by

The format, the ten-attribute cap and the byte cap are in Wire format and SNS limits.

The queue the adapter creates

For AtMostOnce fan-out on FIFO only, the adapter calls CreateQueue with FifoQueue=true and ContentBasedDeduplication=false, sets an access policy admitting sns.amazonaws.com to sqs:SendMessage on the queue under the condition aws:SourceArn equals the subject's topic, and subscribes it to the topic with RawMessageDelivery=true. It unsubscribes and deletes it at Retire. It sets no redrive policy: a message there is deleted before hand-off. See Why it binds and never creates.