queue

type Consumer interface {
	// Identifier returns a stable name for this consumer (typically the queue URL).
	Identifier() string
	// Poll fetches up to maxMessages messages.
	//
	// Every returned QueuedMessage.BrokerMessageID MUST be STABLE across
	// redeliveries of the same message: the router's duplicate filter takes a
	// changed broker id under a known app message id to mean a *different* copy
	// — an external process requeued work the pipeline still owns — and ACKs
	// (deletes) the arrival. A per-delivery id therefore makes the broker
	// destroy its own copy on every redelivery, leaving the in-memory copy as
	// the only one and turning at-least-once into at-most-once. Use the
	// broker's per-message identity (SQS MessageId, the queue row id, the
	// JetStream *stream* sequence), never a per-delivery counter.
	Poll(ctx context.Context, maxMessages uint32) ([]common.QueuedMessage, error)
	// Ack deletes the message from the queue. brokerMessageID is the broker's
	// own id for the message (common.QueuedMessage.BrokerMessageID), passed
	// explicitly because a receipt handle alone can't identify the message
	// across a redelivery: SQS needs the broker id to remember that it deleted
	// this message, and deriving it from the receipt requires state that may
	// have been evicted by then. Empty when the caller genuinely has no id.
	Ack(ctx context.Context, receipt string, brokerMessageID string) error
	// Nack marks the message visible again after delay. Counts as a failure.
	Nack(ctx context.Context, receipt string, delaySeconds *uint32) error
	// Defer marks the message visible again without counting as a failure.
	// Use for backpressure / rate-limiting; default falls back to Nack.
	Defer(ctx context.Context, receipt string, delaySeconds *uint32) error
	// HonoursDelayedReturn reports whether a Nack's delay is actually
	// enforced by this backend before it redelivers — R5 (owner ruling
	// 2026-09-17, docs/spec/router-deferral-handback.md, second unit).
	//
	// SQS and Postgres answer true: a Nack genuinely holds the message
	// invisible for the requested delay (Postgres additionally blocks a
	// nacked-with-delay group head's successors from claiming ahead of it —
	// see its Poll doc comment). NATS answers false: its stream is one
	// durable WorkQueue consumer with no per-group subject, so a Nack never
	// blocks a group's successors the way Postgres's claim does, and each
	// redelivery spends one of the stream's limited MaxDeliver attempts —
	// treating a deferral as a hand-back there would turn a bounded number
	// of in-memory retries into the same number of deliveries and then
	// silent, permanent redelivery loss.
	//
	// Deliberately no default: every backend answers explicitly (Go has no
	// default interface methods to omit it from), which is what the router
	// relies on to decide, per delay-bearing deferral, whether to hand the
	// message back to the broker (R1) or keep retrying it in memory (R5).
	HonoursDelayedReturn() bool
	// Healthy reports liveness.
	Healthy() bool
	// Stop signals the consumer to wind down.
	Stop()
	// Metrics returns the broker-side metrics. May call the broker; nil if unavailable.
	Metrics(ctx context.Context) (*Metrics, error)
	// Counters returns process-local counters (atomic reads). Nil if unsupported.
	Counters() *Metrics
}

type ConsumerFactory func(ctx context.Context, cfg common.QueueConfig) (Consumer, error)

type Embedded interface {
	Consumer
	Publisher
	// InitSchema creates the broker's required tables / topics.
	InitSchema(ctx context.Context) error
}

type Metrics struct {
	QueueIdentifier  string
	PendingMessages  uint64
	InFlightMessages uint64
	TotalPolled      uint64
	TotalAcked       uint64
	TotalNacked      uint64
	TotalDeferred    uint64
}

type Publisher interface {
	Identifier() string
	Publish(ctx context.Context, m common.Message) (string, error)
	PublishBatch(ctx context.Context, msgs []common.Message) ([]string, error)
}

type PublisherFactory func(ctx context.Context, cfg common.QueueConfig) (Publisher, error)