Documentation
¶
Overview ¶
Package sqs implements the backend contract of gitlab.com/phpboyscout/go/messaging over Amazon SQS and SNS, twice.
FIFO is the ordered backend: one FIFO topic in front of each subject, the subject as the message group, deduplication on publish by the event's identity, and at-most-once by deletion before hand-off. Standard is the throughput backend: at-least-once only, because a standard queue may deliver a message even after it has been deleted. Both survive a restart, both keep a lease with the visibility timeout in whole seconds, and neither matches a pattern, because a subscription there is a queue and a queue is a name.
Almost nothing is created: topics, queues, subscriptions and redrive policies are the operator's, resolved by name, failing naming whichever is missing. The one exception is at-most-once fan-out, which creates its own queue at Subscribe, subscribes it to the subject's topic under a policy admitting only that topic, and deletes it at Retire, because the queue exists only for the life of one source.
A subject supports about a hundred consumers at once. AWS caps subscriptions per FIFO topic at 100, and every durable queue consuming the subject holds one, as does every live fan-out subscriber. The README carries that quota and its two neighbours.
This module leans on gitlab.com/phpboyscout/go/awsclient for configuration and credentials and writes the receiving, publishing and settling against aws-sdk-go-v2's sqs and sns services, which appear nowhere else in the estate.
Settings.Format writes what the backend publishes, CloudEvents binary with the ce- prefix as SNS attributes when unset, and Settings.Reads is the chain it reads with, binary then structured when unset. Structured carries what binary cannot, more than ten attributes and a payload that is not UTF-8, at the cost of moving any filter policy on an attribute to the message body (messaging spec 0014).
Specified by https://gitlab.com/phpboyscout/go/messaging/-/wikis/specs/0007-the-sqs-backend
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.NewSentinel("messaging_sqs.closed", "messaging-sqs: the session is closed")
ErrClosed is returned by Publish and Subscribe after Close: the message went nowhere, or the source would outlive its session, and a caller must know.
var ErrNoQueue = errors.NewSentinel("messaging_sqs.no_queue",
"messaging-sqs: the queue this subscription consumes does not exist; a bus resolves a queue and never creates one")
ErrNoQueue is returned by Subscribe when the queue a subscription names does not exist. The bus binds, and never creates (0005 D9, 0007 D2).
var ErrNoTopic = errors.NewSentinel("messaging_sqs.no_topic",
"messaging-sqs: the topic in front of this subject does not exist; a bus resolves a topic and never creates one")
ErrNoTopic is returned by Subscribe and Publish when the topic in front of a subject does not exist.
Functions ¶
func FIFO ¶
func FIFO(s Settings, opts ...FIFOOption) messaging.Backend
FIFO is the ordered backend (0007 D1): one FIFO topic per subject with the subject as the message group, deduplication on publish by the event's identity, both delivery modes, and one message in flight per subject per queue, which is what strict ordering costs on SQS.
func Standard ¶ added in v0.2.0
Standard is the throughput backend (0007 D1): standard topics and queues, at-least-once only, because a standard queue may deliver a message even after it has been deleted, which is exactly the case at-most-once forbids. The suite holds it to the general rows in that mode (0005 D12, the cheapest declared mode).
Types ¶
type ByName ¶
type ByName struct{}
ByName is the default Topology: the derived names are the operator's names.
func (ByName) QueueURL ¶
func (ByName) QueueURL(ctx context.Context, c Clients, name string, _ messaging.SourceSpec) (string, error)
QueueURL resolves the queue by name.
type FIFOOption ¶ added in v0.5.0
type FIFOOption func(*backend)
FIFOOption configures the FIFO backend.
func MaxHeadroom ¶ added in v0.5.0
func MaxHeadroom() FIFOOption
MaxHeadroom lets a FIFO message stay hidden past twelve hours from its receive: a decline waits its whole delay, a lease extends by its full AckWait, and MaxProcessingTime may exceed twelve hours. SQS was measured enforcing only its per-call twelve hours on FIFO, against its own guide, so a refusal falls back to the default cut (messaging 0013 D10).
type Settings ¶
type Settings struct {
// AWS resolves the configuration the SQS and SNS clients are built from.
// Required.
AWS awsclient.Source
// Topology resolves the names this module derives into what the operator
// created. Nil means ByName: a queue by GetQueueUrl on its derived name,
// a topic by its derived name among the account's topics (0007 D2, D3).
Topology Topology
// Logger receives what the backend cannot return: a message on a queue no
// format could read, a heartbeat that failed. Nil discards.
Logger *slog.Logger
// Format writes every event this backend publishes. Unset, it is
// CloudEvents binary with the ce- prefix (0014 D4, D6). Structured moves
// every attribute into the body, which lifts SNS's ten-attribute cap and
// moves any filter policy on them to MessageBody scope.
Format envelope.Format
// Reads is the chain a received message is read with, strictly: one
// format must claim it. Unset, it is binary with the ce- prefix, then
// structured.
Reads []envelope.Format
}
Settings is what both backends are built from.
type Topology ¶
type Topology interface {
// QueueURL is the queue a subscription consumes. The spec is the
// subscription's, so an operator's tool can see what it asks for.
QueueURL(ctx context.Context, clients Clients, name string, spec messaging.SourceSpec) (string, error)
// TopicARN is the topic in front of a subject.
TopicARN(ctx context.Context, clients Clients, name string, subject string) (string, error)
}
Topology is the operator's answer to the names the module derives (0007 D3). The module creates nothing; a Topology that does is the operator's tool, and a test fixture is one.