queue

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

type HookFunc func(ctx context.Context, q IQueue, queueName string, m *Message) error

type IQueue interface {
	// Publish data.
	//
	// NOTE: Use `prm.Any` to set implementation-specific parameters.
	Publish(ctx context.Context, queueName string, msg *Message, prm *PublishParams, options ...OptionsFunc) error

	// Subscribe to channel.
	//
	// NOTE: Use `prm.Any` to set implementation-specific parameters.
	Subscribe(ctx context.Context, queueName string, cb CallbackFunc, prm *SubscribeParams, options ...OptionsFunc) error

	// GetType returns its type.
	GetType() string

	// GetClient returns the queue client. Use that to interact with the
	// underlying queue client.
	GetClient() any

	// GetLogger returns the logger.
	GetLogger() sypl.ISypl

	// GetName returns the queue name.
	GetName() string

	// GetCounterPublished returns the metric.
	GetCounterPublished() *expvar.Int

	// GetCounterPublishedFailed returns the metric.
	GetCounterPublishedFailed() *expvar.Int

	// GetCounterReceived returns the metric.
	GetCounterReceived() *expvar.Int

	// GetCounterReceivedFailed returns the metric.
	GetCounterReceivedFailed() *expvar.Int

	// GetCounterSubscribed returns the metric.
	GetCounterSubscribed() *expvar.Int

	// GetCounterSubscribedFailed returns the metric.
	GetCounterSubscribedFailed() *expvar.Int
}

type Map map[string]IQueue

type Message struct {
	// Body is the raw message payload in bytes.
	Body []byte

	// MessageID uniquely identifies the message across a queue system.
	// Example: Message ID in SQS, Delivery Tag in RabbitMQ, Offset in Kafka, etc.
	MessageID string

	// Metadata holds specific attributes that don't fit into standard fields.
	Metadata map[string]interface{}

	// Timestamp indicates when the message was published to the queue.
	Timestamp time.Time
}

type Mock struct {

	// Publish data.
	MockPublish func(ctx context.Context, queueName string, msg *Message, prm *PublishParams, options ...OptionsFunc) error

	// Subscribe to channel.
	MockSubscribe func(ctx context.Context, queueName string, cb CallbackFunc, prm *SubscribeParams, options ...OptionsFunc) error

	// GetType returns its type.
	MockGetType func() string

	// GetClient returns the queue client. Use that to interact with the underlying queue client.
	MockGetClient func() any

	// GetLogger returns the logger.
	MockGetLogger func() sypl.ISypl

	// GetName returns the queue name.
	MockGetName func() string

	// GetCounterPublished returns the metric.
	MockGetCounterPublished func() *expvar.Int

	// GetCounterPublishedFailed returns the metric.
	MockGetCounterPublishedFailed func() *expvar.Int

	// GetCounterReceived returns the metric.
	MockGetCounterReceived func() *expvar.Int

	// GetCounterReceivedFailed returns the metric.
	MockGetCounterReceivedFailed func() *expvar.Int

	// GetCounterSubscribed returns the metric.
	MockGetCounterSubscribed func() *expvar.Int

	// GetCounterSubscribedFailed returns the metric.
	MockGetCounterSubscribedFailed func() *expvar.Int
}

type Operation string

type Options struct {
	// QueueName name.
	QueueName string `json:"queueName"`

	// PreHookFunc is the function which runs before the operation.
	PreHookFunc HookFunc `json:"-"`

	// PostHookFunc is the function which runs after the operation.
	PostHookFunc HookFunc `json:"-"`
}

type OptionsFunc func(o *Options) error

type PublishParams struct {
	// Any is a placeholder for Queue-specific implementation specific fields.
	Any any `json:"-"`

	// Tags attach categorization metadata to the message.
	// Example: Message Tags in SQS, Message Properties in RabbitMQ, Record Headers in Kafka, etc.
	Tags []string

	// Route specifies where to publish the message.
	// Example: Routing Key in RabbitMQ, Topic in Kafka, unused in standard SQS, etc.
	Route string

	// DelaySeconds postpones message delivery by specified seconds.
	// Example: Message Timer in SQS, Delayed Exchange in RabbitMQ, etc.
	DelaySeconds int

	// MessageGroupID ensures ordering for related messages.
	// Example: Group ID in FIFO queues (SQS), Partition Key in Kafka, etc.
	MessageGroupID string

	// Priority influences message delivery order where supported.
	// Example: Message Priority in RabbitMQ, custom implementation in other queues, etc.
	Priority int

	// Metadata holds queue-specific attributes for publishing.
	// Example: System Attributes in SQS, Headers in RabbitMQ/Kafka, etc.
	Metadata map[string]interface{}
}

type Queue struct {
	// Logger.
	Logger sypl.ISypl `json:"-" validate:"required"`

	// Name of the queue type.
	Name string `json:"name" validate:"required,lowercase,gte=1"`
	// contains filtered or unexported fields
}

type SubscribeParams struct {
	// Any is a placeholder for Queue-specific implementation specific fields.
	Any any `json:"-"`

	// GroupID identifies a group of consumers that work as one unit.
	// Example: Consumer Group in Kafka/SQS, Consumer Tag prefix in RabbitMQ, etc.
	GroupID string

	// Tags filter which messages this subscriber receives.
	// Example: Message Filtering in SQS, Binding Keys in RabbitMQ, Topic Subscriptions in Kafka, etc.
	Tags []string

	// Route specifies which route/topic to subscribe to.
	// Example: Binding Pattern in RabbitMQ, Topic in Kafka, unused in standard SQS, etc.
	Route string

	// BatchSize defines how many messages to process in a single batch.
	// This helps optimize throughput vs. latency across all queue systems.
	BatchSize int

	// MaxMessages sets the maximum number of messages to receive in total.
	// Useful for controlling message flow and preventing overwhelming consumers.
	MaxMessages int

	// WaitTimeout specifies how long to wait for messages when none are immediately available.
	// Example: Long Polling in SQS, Consumer Timeout in Kafka, etc.
	WaitTimeout time.Duration

	// Metadata holds queue-specific attributes that don't fit into standard fields.
	// Example: Message Attributes in SQS, Headers in RabbitMQ/Kafka, etc.
	Metadata map[string]interface{}

	// ContextTimeout specifies how long to wait for the callback to finish.
	ContextTimeout time.Duration
}