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.createdandorders_createdare the same topic. A subject is tokens ofA-Z a-z 0-9 _ . -, and a topic name isA-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
FIFOandStandardyou use is not a setting on the queue. It is in the name: aFIFObackend looks forbilling.fifo, aStandardone forbilling.
What the default lookup does¶
ByName is the default Topology.
- A queue:
GetQueueUrlon the derived name. Any failure issqs.ErrNoQueuewrapping the queue name and the SDK's message. - A topic: SNS has no lookup by name, so it pages
ListTopicsand 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 asmessaging-sqs: listing topics for "…". No match issqs.ErrNoTopic. With many topics, supply aTopologythat knows its ARNs.
What Subscribe checks, in order¶
- the subscription is admissible: an exact subject; a mode the backend declares; a
MaxProcessingTimeof no more than twelve hours unlessMaxHeadroom; - the subject's topic exists;
- the queue exists, and its name is no more than 80 characters;
- the queue's
VisibilityTimeoutandRedrivePolicycan be read; - under
AtLeastOnce, the redrive policy exists and itsmaxReceiveCountequalsMaxDeliver; - the lease can be derived from
AckWaitor the queue'sVisibilityTimeout.
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.