relay

type Engine struct {
	// contains filtered or unexported fields
}

type EngineParams struct {
	RelayID                       string
	Interval                      time.Duration
	BatchSize                     int
	LeaseTimeout                  time.Duration
	ReapBatchSize                 int
	PublisherConnectRetryInterval time.Duration
	HealthCheckInterval           time.Duration
	RetryPolicy                   RetryPolicy
	EnableBatchPublish            bool
	EnableStats                   bool
}

type Event struct {
	// ID is the unique identifier for the event (UUID v4/v7 recommended).
	ID uuid.UUID `db:"event_id"      json:"id"`
	// Type defines the subject/topic the message should be published to.
	Type string `db:"event_type"    json:"type"`
	// PartitionKey is used for load balancing on the broker side if supported
	PartitionKey *string `db:"partition_key" json:"partition_key"`
	// Payload is the raw message body.
	Payload []byte `db:"payload"       json:"payload"`
	// Headers is a JSON blob containing custom message attributes/headers.
	Headers json.RawMessage `db:"headers"       json:"headers"`

	// Attempts tracks the number of times this event has been tried for delivery.
	Attempts int `db:"attempts" json:"attempts"`

	// CreatedAt is the timestamp when the event was first inserted into the database.
	CreatedAt time.Time `db:"created_at" json:"created_at"`
}

type EventStatus string

type ExponentialBackoff struct {
	// MaxAttempts is the hard limit for delivery attempts.
	MaxAttempts int
	// BaseDelay is the initial backoff duration (e.g., 1s).
	BaseDelay time.Duration
	// MaxDelay is the maximum duration any single backoff can reach.
	MaxDelay time.Duration
	// Jitter is a factor (0.0 to 1.0) used to randomize the backoff interval.
	Jitter float64
}

type FailedEvent struct {
	// ID of the event that failed.
	ID uuid.UUID `json:"id"           db:"id"`
	// NewStatus is the state the event should transition to (PENDING or DEAD).
	NewStatus EventStatus `json:"new_status"   db:"status"`
	// AvailableAt is the time when the event becomes eligible for retry.
	AvailableAt time.Time `json:"available_at" db:"available_at"`
	// Attempts is the incremented count of delivery tries.
	Attempts int `json:"attempts"     db:"attempts"`
	// LastError captures the error message from the publisher for diagnostics.
	LastError string `json:"last_error"   db:"last_error"`
}

type MockPublisher struct {
	mock.Mock
}

type MockStorage struct {
	mock.Mock
}

type PruneOptions struct {
	// DeliveredAge defines the duration threshold for DELIVERED events.
	// The string must follow the format "[number][unit]" where unit is:
	// 'd' for days, 'h' for hours, or 'm' for minutes (e.g., "7d", "24h", "60m").
	// An empty string or "0" indicates that no pruning should be performed
	// for this status.
	DeliveredAge string

	// DeadAge defines the duration threshold for DEAD events.
	// Follows the same format as DeliveredAge (e.g., "30d").
	// Use this to clear out "quarantined" events after a period of time.
	DeadAge string

	// DryRun, if true, instructs the storage implementation to calculate
	// and return the count of rows that meet the criteria without
	// actually performing the deletion.
	DryRun bool
}

type PruneResult struct {
	// DeliveredDeleted is the total number of events with status 'DELIVERED'
	// that were successfully removed from the storage.
	DeliveredDeleted int64

	// DeadDeleted is the total number of events with status 'DEAD'
	// that were successfully removed from the storage.
	DeadDeleted int64
}

type PublishError struct {
	// Err is the underlying error returned by the transport client.
	Err error
	// IsRetryable indicates if the failure is transient (e.g., network timeout)
	// or permanent (e.g., authentication failure, invalid subject).
	// This field determines whether the Engine will retry the event or move it to 'DEAD' status.
	IsRetryable bool
	// Code is a machine-readable string used for categorizing errors in metrics and logs.
	Code string // e.g., "BROKER_NACK", "AUTH_EXPIRED", "VALIDATION_ERROR"
}

type Publisher interface {

	// Connect establishes the initial connection to the message broker.
	// It should perform handshakes, authenticate, and initialize necessary
	// resources (like NATS JetStream contexts or Kafka writers).
	Connect(ctx context.Context) error

	// Publish sends a single event to the downstream system.
	// It should block until the broker provides a delivery acknowledgment
	// or the provided context is cancelled.
	Publish(ctx context.Context, event Event) error

	// Close performs a graceful shutdown of the publisher, ensuring any
	// buffered data is flushed and network resources are released.
	Close(ctx context.Context) error

	// Ping verifies the connectivity to the message broker (e.g., Kafka, NATS).
	// It ensures the publisher is authenticated and capable of sending messages.
	Ping(ctx context.Context) error
}

type RetryPolicy interface {
	// NextBackoff returns the duration to wait before the next attempt and
	// a boolean indicating whether the retry limit has been reached.
	NextBackoff(attempts int) (time.Duration, bool)
}

type Server struct {
	// contains filtered or unexported fields
}

type State int64

type Stats struct {
	// PendingCount is the total number of events currently in 'PENDING' status.
	PendingCount int64 `json:"pending_count"`
	// RetryingCount is the number of events in 'PENDING' status that have
	// failed at least once (attempts > 0).
	RetryingCount int64 `json:"retrying_count"`
	// OldestAgeSec is the age in seconds of the oldest event waiting to be processed.
	OldestAgeSec int64 `json:"oldest_age_sec"`
}

type Storage interface {
	// ClaimBatch identifies and locks a set of pending events for a specific relay instance.
	// It transitions events to the 'DELIVERING' status and associates them with the relayID.
	// The 'buffer' parameter allows for reusing a slice to minimize allocations.
	ClaimBatch(
		ctx context.Context,
		relayID string,
		batchSize int,
		buffer []Event,
	) ([]Event, error)

	// MarkDeliveredBatch moves events to the final 'DELIVERED' state.
	// It must verify that the events are still locked by the provided relayID
	// to prevent race conditions with the lease reaper.
	MarkDeliveredBatch(ctx context.Context, ids []uuid.UUID, relayID string) error

	// MarkFailedBatch handles events that encountered errors during publishing.
	// It updates event metadata (attempts, last_error) and determines if the event
	// should be retried (PENDING) or quarantined (DEAD).
	MarkFailedBatch(ctx context.Context, failures []FailedEvent, relayID string) error

	// ReapExpiredLeases identifies events stuck in the 'DELIVERING' state past their
	// lease duration and resets them to 'PENDING', allowing other instances to pick them up.
	ReapExpiredLeases(ctx context.Context, leaseTimeout time.Duration, limit int) (int64, error)

	// GetStats retrieves high-level operational metrics about the outbox table,
	// such as the current backlog size and the age of the oldest pending message.
	GetStats(ctx context.Context) (Stats, error)

	// Prune removes old DELIVERED and DEAD events from storage to maintain performance.
	// This is typically called by the CLI or a background maintenance job.
	Prune(ctx context.Context, opts PruneOptions) (PruneResult, error)

	// Close releases any resources held by the storage implementation, such as
	// database connection pools.
	Close(ctx context.Context) error

	// Ping verifies the connectivity to the underlying database. It should
	// return an error if the storage backend is unreachable or misconfigured.
	Ping(ctx context.Context) error
}