messagequeue

type Consumer interface {
	Consume(ctx context.Context, errs chan<- error)
}

type ConsumerFunc func(context.Context, []byte) error

type ConsumerProvider interface {
	Close()
	NewConsumer(ctx context.Context, topic string, handlerFunc ConsumerFunc) (Consumer, error)
}

type PublishOption func(*PublishOptions)

type PublishOptions struct {
	// OrderingKey names the sequence this message belongs to. Messages
	// published with the same key are delivered in the order they were
	// published; messages with different keys have no order relative to
	// each other, which is what lets a broker spread the topic over
	// partitions, groups or shards and still keep each entity's history
	// intact. The usual key is the ID of whatever the message is about — an
	// account, an order, a device.
	//
	// The empty string means "no ordering requirement" and is the default.
	// It is not a key: every backend that honors ordering treats it as
	// "spread this one freely", not as a group that all unkeyed messages
	// share, because one shared group would serialize the whole topic.
	//
	// What each backend does with it:
	//
	//   - kafka sets it as the message key and partitions on a murmur2 hash
	//     of it, so one key is one partition and Kafka's per-partition order
	//     is the guarantee.
	//   - sqs sets it as MessageGroupId, which a FIFO queue requires on
	//     every message. See DeduplicationKey, which a FIFO queue also
	//     needs unless the queue deduplicates on content.
	//   - pubsub sets it as the message's OrderingKey.
	//   - redis ignores it. Redis pub/sub has no ordering concept to map it
	//     onto: there are no partitions, no groups, and no ordering
	//     guarantee beyond what one connection happens to deliver. A key
	//     given to a redis publisher changes nothing and is not an error.
	//
	// Ordering is a joint property of publisher and subscriber, and only the
	// publishing half is this package's to set. Kafka delivers a partition
	// in order to whichever consumer owns it; SQS FIFO and Pub/Sub both need
	// the queue or subscription provisioned for ordered delivery, which
	// happens outside this package.
	OrderingKey string

	// DeduplicationKey names this message's identity for provider-side
	// deduplication: a broker that sees the key twice within its
	// deduplication window delivers the message once.
	//
	// Only sqs honors it, as MessageDeduplicationId. A FIFO queue requires
	// either this or ContentBasedDeduplication enabled on the queue itself —
	// with neither, SendMessage fails rather than publishing — so a caller
	// publishing to a FIFO queue that hashes its own bodies can leave this
	// empty, and one publishing to a FIFO queue that does not must set it.
	//
	// kafka, pubsub and redis ignore it. None of them deduplicate on a
	// caller-supplied key: Kafka's idempotent producer deduplicates on its
	// own sequence numbers, and Pub/Sub and Redis do not deduplicate at all.
	// Handlers on those backends must be idempotent regardless; see the
	// idempotency package.
	DeduplicationKey string
}

type Publisher interface {
	// Stop halts all publishing.
	Stop()
	// Publish writes a message onto a message queue.
	Publish(ctx context.Context, data any, opts ...PublishOption) error
	// PublishAsync writes a message onto a message queue, logging any error
	// instead of returning it.
	//
	// "Async" names the error handling, not the delivery: it publishes on the
	// calling goroutine and returns when the publish has finished, exactly as
	// Publish does. A caller that wants the publish off its own goroutine has
	// to arrange that itself.
	PublishAsync(ctx context.Context, data any, opts ...PublishOption)
}

type PublisherProvider interface {
	Close()
	Ping(ctx context.Context) error
	NewPublisher(ctx context.Context, topic string) (Publisher, error)
}