queue

type Handler func(ctx context.Context, msg *Message) error

type Message struct {
	// ID uniquely identifies the message within its backend. Format is
	// backend-specific; consumers should treat it as opaque.
	ID string

	// Topic is the name of the topic this message was published to.
	Topic string

	// Body is the raw payload.
	Body []byte

	// Attempts is 1 on first delivery, incremented on redelivery.
	Attempts int

	// EnqueuedAt is the time the message was accepted by Publish.
	EnqueuedAt time.Time

	// DeliverAt is set when the message was scheduled with PublishOptions.
	// Delay. Zero means "immediate".
	DeliverAt time.Time

	// Metadata holds backend-specific fields (SQS ReceiptHandle, Kafka
	// partition/offset, etc.). Opaque to callers who target the interface;
	// backend-typed helpers may expose it.
	Metadata map[string]string
}

type PublishOptions struct {
	// Delay defers delivery for at least this duration. Zero means
	// immediate. Backends without native delay support may error or
	// approximate (documented per backend).
	Delay time.Duration

	// DedupKey requests the backend deduplicate messages that carry the
	// same key within a backend-defined window. Empty means no
	// deduplication. Backends that do not support it silently ignore the
	// key.
	DedupKey string

	// Metadata is attached to the Message for consumers that need
	// contextual routing hints. Backend-specific keys pass through.
	Metadata map[string]string
}

type Queue interface {
	// Publish adds body to topic. Returns the assigned message ID.
	Publish(ctx context.Context, topic string, body []byte, opts ...PublishOptions) (id string, err error)

	// Subscribe starts a consumer that dispatches messages on topic to
	// handler. It returns immediately; the consumer runs in the
	// background until the returned Subscription is closed or the Queue
	// is closed. Multiple subscribers to the same topic share the
	// message stream (competing consumers) — each message is delivered
	// to exactly one subscriber (modulo redelivery).
	Subscribe(ctx context.Context, topic string, handler Handler) (Subscription, error)

	// Close stops all subscriptions and releases resources.
	Close(ctx context.Context) error
}

type Subscription interface {
	// Close stops the consumer. Returns after the current in-flight
	// handler (if any) finishes or ctx expires.
	Close(ctx context.Context) error

	// Topic returns the topic this subscription is bound to.
	Topic() string
}