engine

type Classifier func(error) Outcome

type Config struct {
	// Store is the persistence driver the engine fetches from and settles into.
	Store driver.Store
	// Source is the job partition this engine operates; it never touches jobs of
	// another source.
	Source driver.Source
	// Logger is the structured logger. Nil means slog.Default().
	Logger *slog.Logger
	// Settings are the resolved runtime knobs.
	Settings Settings
	// Acker settles a successful job, receiving the handler's result. Nil
	// means the default: Store.Ack with the result discarded (queue and event
	// handlers produce none). The workflow runtime injects AckTaskResult here
	// so a task's output is persisted atomically with its completion. Like
	// every settlement it is fenced: a not-found error is swallowed as the
	// expected lost-lease race.
	Acker func(ctx context.Context, id, leaseToken uuid.UUID, result json.RawMessage) error
}

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

type Kind struct {
	// Name is the fetch partition (job kind, or subscriber name for events).
	Name string
	// Concurrency caps concurrent handlers of this kind.
	Concurrency int
	// Timeout bounds one handler execution; 0 means unlimited.
	Timeout time.Duration
	// MaxAttempts is the retry budget dequeues resolve durably on a job's first
	// lease when MaxAttemptsSet is true (see driver.DequeueParams).
	MaxAttempts int
	// MaxAttemptsSet marks MaxAttempts as an explicit per-kind override.
	MaxAttemptsSet bool
	// Handler runs one leased job. Its result travels to the engine's acker on
	// success; runtimes without task results (queue, event) return nil.
	Handler func(ctx context.Context, job driver.Job) (json.RawMessage, error)
	// Classify maps a handler error to its outcome. Nil means plain retry.
	Classify Classifier
}

type Outcome struct {
	Kind OutcomeKind
	// Delay overrides the exponential backoff for a retry and is the snooze
	// duration for OutcomeSnooze; 0 means Backoff for a retry and an
	// immediate re-check for a snooze.
	Delay time.Duration
	// Reportable flags the error for loud logging when retries are exhausted.
	Reportable bool
}

type OutcomeError interface {
	error
	// AsyncOutcome returns the engine settlement the sentinel encodes.
	AsyncOutcome() Outcome
}

type OutcomeKind int

type Settings struct {
	// LeaseTTL is how long a claim is held; it also paces lease renewal
	// (LeaseTTL/2) and the reaper (one sweep per LeaseTTL).
	LeaseTTL time.Duration
	// ShutdownDrain is how long Start waits for in-flight handlers after ctx
	// ends before cancelling them.
	ShutdownDrain time.Duration
	// MaxConcurrency caps concurrent handlers across every kind.
	MaxConcurrency int
	// FetchBatchSize caps how many jobs one dequeue leases.
	FetchBatchSize int
	// FetchPollInterval is the minimum polling period while idle.
	FetchPollInterval time.Duration
	// FetchCooldown is the pause after a productive fetch, and the idle backoff
	// floor.
	FetchCooldown time.Duration
	// IdleBackoffMax caps the exponential idle backoff of a fetch loop.
	IdleBackoffMax time.Duration
	// MaxReaps is how many lease expirations a job survives before the reaper
	// kills it.
	MaxReaps int
	// StatsRetention bounds the daily stat counters; 0 retains forever.
	StatsRetention time.Duration
	// CompletedRetention bounds succeeded-job history; 0 retains forever.
	CompletedRetention time.Duration
	// DeadRetention bounds dead-job history; 0 retains forever (the default:
	// dead jobs are never automatically removed unless an operator opts in).
	DeadRetention time.Duration
	// PromoteInterval overrides the scheduled->pending promotion cadence.
	// Zero means the production default (1s).
	PromoteInterval time.Duration
	// VacuumInterval overrides the vacuum cadence. Zero means the production
	// default (1h).
	VacuumInterval time.Duration
}