projection

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

type DispatcherConfig struct {
	// Logger is an optional logger for observability.
	Logger es.Logger

	// PollInterval controls how often the dispatcher checks for a new latest global position.
	// Default is 100ms.
	PollInterval time.Duration
}

type HashPartitionStrategy struct{}

type PartitionStrategy interface {
	// ShouldProcess returns true if this projection instance should process the given event.
	// aggregateID is the aggregate ID of the event.
	// partitionKey identifies this projection instance (e.g., "0" for first of 4 workers).
	// totalPartitions is the total number of projection instances.
	ShouldProcess(aggregateID string, partitionKey int, totalPartitions int) bool
}

type ProcessorConfig struct {
	// PartitionStrategy determines which events this processor handles
	PartitionStrategy PartitionStrategy

	// Logger is an optional logger for observability.
	// If nil, logging is disabled (zero overhead).
	Logger es.Logger

	// WakeupSource is an optional best-effort signal source.
	// If nil, processors rely purely on PollInterval fallback polling.
	WakeupSource WakeupSource

	// PollBackoffFactor controls exponential backoff growth for idle fallback polling.
	// Values <= 1 disable growth (constant PollInterval fallback).
	// Default is 2.0.
	PollBackoffFactor float64

	// PollInterval is the duration to wait when no events are available.
	// This prevents tight polling loops that consume excessive CPU.
	// A value of 0 means no delay (busy polling - not recommended).
	// Default is 100ms, which provides a good balance between latency and CPU usage.
	PollInterval time.Duration

	// MaxPollInterval is the upper bound for idle fallback polling when backoff is enabled.
	// Default is 5s.
	MaxPollInterval time.Duration

	// WakeupJitter is the random delay applied after receiving a wake signal.
	// This helps smooth spikes when many projections wake at once.
	// Default is 25ms.
	WakeupJitter time.Duration

	// BatchSize is the number of events to read per batch
	BatchSize int

	// PartitionKey identifies this processor instance (0-indexed)
	PartitionKey int

	// TotalPartitions is the total number of processor instances
	TotalPartitions int

	// RunMode determines processing behavior.
	// Default: RunModeContinuous
	RunMode RunMode
}

type ProcessorRunner interface {
	// Run processes events for the given projection until the context is canceled.
	// Returns an error if the projection handler fails.
	Run(ctx context.Context, projection Projection) error
}

type Projection interface {
	// Name returns the unique name of this projection.
	// This name is used for checkpoint tracking.
	Name() string

	// Handle processes a single event.
	// Return an error to stop projection processing.
	//
	// The tx parameter is the processor's transaction used for checkpoint management.
	// SQL projections can use this transaction to ensure atomic updates of both
	// the read model and the checkpoint. This eliminates inconsistencies where
	// a projection succeeds but the checkpoint update fails (or vice versa).
	//
	// The transaction will be committed by the processor after Handle returns successfully.
	// Projections should NEVER call Commit() or Rollback() on the provided transaction.
	//
	// For non-SQL projections (Elasticsearch, Redis, message brokers), the tx parameter
	// should be ignored and projections should manage their own connections as before.
	//
	// Event is passed by value to enforce immutability (events are value objects).
	// Large data (Payload, Metadata byte slices) share references to their backing arrays,
	// so the actual payload/metadata data is not deep-copied.
	//
	//nolint:gocritic // hugeParam: Intentionally pass by value to enforce immutability
	Handle(ctx context.Context, tx *sql.Tx, event es.PersistedEvent) error
}

type RunMode int

type ScopedProjection interface {
	Projection
	// AggregateTypes returns the list of aggregate types this projection cares about.
	// If empty, the projection receives events from all aggregate types (still filtered by BoundedContexts if specified).
	// If non-empty, only events matching one of these aggregate types are passed to Handle.
	AggregateTypes() []string

	// BoundedContexts returns the list of bounded contexts this projection cares about.
	// If empty, the projection receives events from all bounded contexts (still filtered by AggregateTypes if specified).
	// If non-empty, only events matching one of these bounded contexts are passed to Handle.
	BoundedContexts() []string
}

type WakeupSource interface {
	// Subscribe registers a projection processor for wake signals.
	// Returns a receive-only signal channel and an unsubscribe function.
	Subscribe() (signals <-chan struct{}, unsubscribe func())
}