messagequeue

type DLQConfig struct {
	// Enabled enables dead letter queue.
	Enabled bool

	// TopicSuffix is appended to the original topic name to create the DLQ topic.
	// For example, if original topic is "orders" and suffix is "_dlq", DLQ topic will be "orders_dlq".
	TopicSuffix string
}

type Delivery interface {
	// Message returns the delivered message.
	Message() entityqueue.Message

	// Ack acknowledges successful processing of the message.
	// The message will be removed from the queue and not redelivered.
	Ack(ctx context.Context) error

	// Nack negatively acknowledges the message, indicating processing failure.
	// The message will be requeued for redelivery after requeueAfterMillis.
	// If requeueAfterMillis is 0, the message is requeued immediately.
	Nack(ctx context.Context, requeueAfterMillis int64) error

	// Reject moves the message to the dead letter entityqueue.
	// Use for poison pill messages that should never be retried.
	// reason is stored as last_error in the DLQ for debugging.
	// If DLQ is not configured, the message is acked (removed from queue).
	Reject(ctx context.Context, reason string) error

	// ExtendVisibilityTimeout extends the time before this message becomes
	// visible to other consumers. Use when processing takes longer than expected.
	ExtendVisibilityTimeout(ctx context.Context, durationMillis int64) error

	// DeliveryID returns a backend-specific identifier for this delivery.
	DeliveryID() string

	// Attempt returns how many times this message has been delivered.
	// Starts at 1 for first delivery.
	Attempt() int

	// ReceivedAt returns when this delivery was received (Unix milliseconds).
	ReceivedAt() int64

	// Metadata returns backend-specific delivery metadata.
	Metadata() map[string]string
}

type Publisher interface {
	// Publish sends a message to the specified topic.
	Publish(ctx context.Context, topic string, message entityqueue.Message) error

	// PublishAfter sends a message that becomes visible to subscribers only
	// after delayMs from now. It is a fresh publish — not a redelivery — so
	// it does not consume a delivery_state retry slot. delayMs <= 0 is
	// equivalent to Publish.
	//
	// Use for "postpone this work" semantics (e.g. spacing out repeated
	// poll cycles for a single key). Use Nack with a delay for "this
	// delivery failed, try again" — the two signals stay separate so
	// retry_count and DLQ behaviour remain meaningful.
	PublishAfter(ctx context.Context, topic string, message entityqueue.Message, delayMs int64) error

	// Close gracefully shuts down the publisher, flushing pending messages.
	Close() error
}

type Queue interface {
	// Publisher returns a Publisher instance.
	// May return a singleton or new instance depending on implementation.
	Publisher() Publisher

	// Subscriber returns a Subscriber instance.
	// May return a singleton or new instance depending on implementation.
	Subscriber() Subscriber

	// Close shuts down the queue and all associated resources.
	Close() error
}

type RetryConfig struct {
	// MaxAttempts is the maximum number of processing attempts.
	// After this many attempts, the message is moved to DLQ (if enabled).
	MaxAttempts int

	// InitialBackoffMs is the initial backoff duration for retries (in milliseconds).
	InitialBackoffMs int64

	// MaxBackoffMs is the maximum backoff duration (in milliseconds).
	MaxBackoffMs int64

	// BackoffMultiplier is the multiplier for exponential backoff.
	BackoffMultiplier float64
}

type Subscriber interface {
	// Subscribe starts consuming messages from the specified topic with the given config.
	// Returns a channel of Delivery instances and an error if subscription fails.
	//
	// Each subscription can have its own configuration for polling, batching,
	// retries, and dead letter queue behavior.
	//
	// The channel is closed when the subscriber is closed or context is cancelled.
	// Implementations should handle infrastructure errors internally (e.g., reconnect).
	//
	// Each Delivery provides the message and methods to acknowledge or reject it.
	// Consumers should call delivery.Ack() or delivery.Nack() for each delivery.
	Subscribe(ctx context.Context, topic string, config SubscriptionConfig) (<-chan Delivery, error)

	// Close gracefully shuts down the subscriber.
	// All delivery channels will be closed.
	// Idempotent - safe to call multiple times.
	Close() error
}

type SubscriptionConfig struct {
	// SubscriberName uniquely identifies this subscriber instance for partition leases.
	// Different workers should use different names (e.g., hostname, pod name, UUID).
	// Combined with ConsumerGroup, this determines which worker owns a partition lease.
	SubscriberName string

	// ConsumerGroup identifies this consumer for offset tracking.
	// Different consumer groups maintain independent offsets.
	ConsumerGroup string

	// PollIntervalMs is how often to poll for new messages (in milliseconds).
	PollIntervalMs int64

	// BatchSize is the maximum number of messages to fetch per poll.
	BatchSize int

	// VisibilityTimeoutMs is how long a message is invisible after being fetched (in milliseconds).
	// If the worker crashes or doesn't ack/nack in time, the message becomes
	// visible again after this duration.
	VisibilityTimeoutMs int64

	// LeaseRenewalIntervalMs is how often to renew partition leases (in milliseconds).
	LeaseRenewalIntervalMs int64

	// LeaseDurationMs is how long a lease is valid without renewal (in milliseconds).
	// Stale leases (not renewed within this duration) can be stolen by other workers.
	LeaseDurationMs int64

	// Retry configures message retry behavior.
	Retry RetryConfig

	// DLQ configures dead letter queue behavior.
	DLQ DLQConfig
}