hopper

type AppendOpts struct {
	// Key orders the event's deliveries with others of the same key: a
	// consumer handles them one at a time, in order.
	Key string
	// Headers travel with the event and are available on Message.
	Headers map[string]string
}

type AttemptError = driver.AttemptError

type Batch[TTx any] struct {
	// contains filtered or unexported fields
}

type BatchOpts struct {
	OnSuccess  JobArgs
	OnFailure  JobArgs
	OnComplete JobArgs
	// CallbackOpts applies to every callback job.
	CallbackOpts *InsertOpts
	// Metadata is stored with the batch.
	Metadata []byte
}

type BatchResult struct {
	ID   JobID
	Jobs []*InsertResult
}

type BatchRow = driver.BatchRow

type CancelError struct {
	Err error
}

type Client[TTx any] struct {
	// contains filtered or unexported fields
}

type ClientRow = driver.ClientRow

type Codec interface {
	Marshal(v any) ([]byte, error)
	Unmarshal(data []byte, v any) error
}

type Config struct {
	// Queues lists the queues this client works, with per-queue settings. A
	// client with no queues only inserts jobs.
	Queues map[string]QueueConfig
	// Workers is the registry of workers. Required when Queues is set.
	Workers *Workers
	// Periodic lists jobs inserted on a schedule by the leader. See Cron
	// and Every.
	Periodic []PeriodicJob
	// Middleware wraps job execution and inserts, outermost first.
	Middleware []Middleware
	// Logger defaults to slog.Default().
	Logger *slog.Logger
	// Codec encodes args and outputs. Defaults to JSONCodec.
	Codec Codec
	// JobTimeout is how long a job may run before its context is canceled,
	// unless its worker's Timeout says otherwise. Defaults to one minute.
	JobTimeout time.Duration
	// MaxAttempts is the default number of attempts before a job is
	// discarded. Defaults to 25.
	MaxAttempts int
	// StopTimeout bounds how long Run waits for running jobs after its
	// context is canceled, before canceling them. Defaults to 30 seconds.
	StopTimeout time.Duration
	// PollInterval is how often an idle producer checks its queue for work
	// that arrived without a wake-up. Defaults to one second.
	PollInterval time.Duration
	// StrictKinds rejects inserts whose kind has no worker on this client.
	// By default any kind can be inserted, since another service may work it.
	StrictKinds bool
	// Hostname identifies this process in the clients table. Defaults to
	// os.Hostname().
	Hostname string
	// CompletedRetention is how long completed jobs stay in history.
	// Defaults to 24 hours; negative keeps them forever. Retention is
	// enforced by the leader, so the leader's setting applies cluster-wide.
	CompletedRetention time.Duration
	// FailedRetention is how long canceled and discarded jobs stay in
	// history, which is the dead-letter queue. Defaults to 7 days; negative
	// keeps them forever.
	FailedRetention time.Duration
	// StreamRetention is how long stream events stay in the log, for
	// consumers that start from the earliest event or are moved back.
	// Defaults to 7 days; negative keeps them forever.
	StreamRetention time.Duration
	// NeverLead keeps this client out of leader elections. It still claims
	// and works jobs, but never runs the leader's duties: rescuing jobs from
	// lost clients, retention, maintenance, periodic jobs and stream
	// delivery. Use it for clients that share an install but must not run it,
	// such as a developer's process against a shared environment. At least
	// one client of every install must be able to lead.
	NeverLead bool
	// LeaseTTL is how long this client's lease lasts without a renewal. It
	// is renewed three times per TTL; when it lapses, the client's running
	// jobs are rescued and the client cancels them. A longer lease rides
	// out a longer database outage before interrupting jobs, and delays the
	// rescue of a crashed client's jobs by as much. Defaults to 15 seconds.
	LeaseTTL time.Duration
	// RescueStuckAfter, if set, rescues jobs that have been running longer
	// than this even though their client's lease is live, for workers that
	// ignore their context. Off by default; timeouts cover most cases.
	RescueStuckAfter time.Duration
}

type Consumer struct {
	// Name identifies the consumer; the delivery job kind is derived from
	// it.
	Name    string
	Pattern string
	// Queue is where deliveries go. Defaults to QueueDefault.
	Queue string
	// Start applies when the consumer is created. Defaults to
	// StreamStartLatest.
	Start StreamStart
	// MaxAttempts is the retry budget of deliveries. Zero means 25, or 10
	// for events with a key, whose retries block their key.
	MaxAttempts int
	// Metadata is merged into every delivery's metadata.
	Metadata json.RawMessage
}

type ConsumerRow = driver.StreamConsumerRow

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

type DependencyFailure = driver.DependencyFailure

type Event struct {
	Kind EventKind
	At   time.Time
	// Job is set for job events: the row as claimed, before the outcome.
	Job *JobRow
	// Error is the attempt's error text for failed, discarded and
	// canceled jobs, and the snooze reason, if any, for snoozed jobs.
	Error string
	// ClientID is the client the event happened on.
	ClientID int64
}

type EventKind string

type InsertOpts struct {
	// Queue defaults to QueueDefault.
	Queue string
	// Priority defaults to PriorityNormal.
	Priority Priority
	// MaxAttempts defaults to Config.MaxAttempts.
	MaxAttempts int
	// ScheduledAt delays the job until the given time. Zero runs it as soon
	// as possible.
	ScheduledAt time.Time
	// Metadata is a JSON object stored with the job, for trace context and
	// similar. It is not passed to the worker as args.
	Metadata json.RawMessage
	// Unique makes the job unique among live jobs of its kind. See
	// UniqueOpts.
	Unique *UniqueOpts
	// TTL bounds how long the job may wait to run, measured from its
	// insert: before its first attempt, between retries, and while snoozed.
	// A job still waiting when it passes is discarded without running again.
	// A running job is not interrupted. Zero means no limit.
	TTL time.Duration
	// Await announces the job's finalize, so that Await returns as soon as
	// it commits instead of on its next poll.
	Await bool
	// OrderingKey serializes the job with others of the same key in its
	// queue: at most one runs at a time, oldest first, and a failing job
	// blocks its key while it retries. See PublishOpts.OrderingKey.
	OrderingKey string
	// PartitionKey groups the job for the queue's PartitionLimit, for
	// example a customer ID.
	PartitionKey string
}

type InsertParams struct {
	Args JobArgs
	Opts *InsertOpts
	// contains filtered or unexported fields
}

type InsertResult struct {
	Job *JobRow
	// Duplicate reports that a live job with the same unique key already
	// existed. Job is then that existing job.
	Duplicate bool
}

type IntervalSchedule struct {
	Interval time.Duration
}

type JSONCodec struct{}

type Job[T JobArgs] struct {
	*JobRow
	Args T
}

type JobArgs interface {
	Kind() string
}

type JobArgsWithInsertOpts interface {
	JobArgs
	InsertOpts() InsertOpts
}

type JobFailedError struct {
	Job *JobRow
}

type JobFilter struct {
	Queue  string
	Kinds  []string
	States []JobState
	// OrderingKey lists one ordering key's jobs, its lane. Keys are scoped
	// to a queue, so it needs Queue; the listing fails without one.
	OrderingKey string
	// NewestFirst lists in descending ID order: the latest inserted jobs
	// first, though IDs from the same millisecond can sort either way.
	NewestFirst bool
	// After starts the listing after the given job, for paging: pass the
	// last ID of one page to get the next.
	After JobID
}

type JobID = driver.JobID

type JobRow = driver.JobRow

type JobState = driver.JobState

type Message[T any] struct {
	*JobRow
	Payload T
	Topic   string
	// ID identifies the published message; every subscription's delivery of
	// it shares the ID.
	ID          string
	Headers     map[string]string
	OrderingKey string
	// Stream and Position are set for a consumer's deliveries: the
	// consumer's name and the event's place in the log.
	Stream   string
	Position StreamPosition
}

type Middleware interface {
	// Work wraps one attempt of a job. next runs the worker (and any inner
	// middleware); its error is the worker's return value.
	Work(ctx context.Context, job *JobRow, next func(ctx context.Context) error) error
	// Insert wraps an insert batch. next performs the insert; middleware may
	// pass it a modified copy of params, for example with trace context in
	// Metadata.
	Insert(ctx context.Context, params []InsertParams, next func(ctx context.Context, params []InsertParams) ([]*InsertResult, error)) ([]*InsertResult, error)
}

type MiddlewareDefaults struct{}

type PanicError struct {
	Value any
	Stack string
}

type PeriodicJob struct {
	// Name identifies the job in the periodic table. It defaults to the
	// args' kind and must be unique among a client's periodic jobs.
	Name     string
	Schedule Schedule
	Args     JobArgs
	Opts     *PeriodicOpts
	// contains filtered or unexported fields
}

type PeriodicOpts struct {
	// Name overrides the periodic job's name.
	Name string
	// RunOnStart inserts a job as soon as a leader starts scheduling, in
	// addition to the regular slots.
	RunOnStart bool
	// CatchUp inserts up to this many slots missed while no leader was
	// running (for example during a full outage), oldest first. By default
	// missed slots are skipped, except a slot due in the last few seconds,
	// which covers a leader failover.
	CatchUp int
	// Location evaluates a cron expression in this zone when the
	// expression does not name one. Defaults to UTC.
	Location *time.Location
	// InsertOpts are applied to every inserted job.
	InsertOpts *InsertOpts
}

type Priority int

type PublishOpts struct {
	// OrderingKey makes delivery FIFO per key, per queue: at most one
	// delivery with the key runs at a time, oldest first, and a failing
	// delivery blocks its key while it retries. Keys are independent.
	OrderingKey string
	// DedupKey makes the publish idempotent: while a delivery with the key
	// is live, a repeated publish inserts nothing and reports Duplicate.
	DedupKey string
	// Headers travel with the message and are available on Message.
	Headers map[string]string
	// Delay defers delivery.
	Delay time.Duration
	// TTL bounds how long each delivery may wait to run, as
	// InsertOpts.TTL does: one still waiting when it passes, whether before
	// its first attempt, between retries or while snoozed, is discarded.
	TTL time.Duration
	// Priority defaults to PriorityNormal.
	Priority Priority
	// Await announces each delivery's finalize, for Await.
	Await bool
}

type PublishResult struct {
	// MessageID identifies the message across its deliveries. It is empty
	// when no subscription matched.
	MessageID  string
	Deliveries []*InsertResult
}

type QueueConfig struct {
	// MaxWorkers is the number of jobs this client runs at once from the
	// queue. Required.
	MaxWorkers int
	// DeleteCompleted deletes completed jobs instead of archiving them to
	// history, for maximum throughput. Canceled and discarded jobs are
	// always archived, because history is the dead-letter queue.
	DeleteCompleted bool

	// GlobalLimit caps the queue's running jobs across all clients.
	GlobalLimit int
	// RateLimit caps claims per second across all clients, in a token
	// bucket of RateBurst tokens (defaulting to one second's worth).
	RateLimit float64
	RateBurst int
	// PartitionLimit caps running jobs per InsertOpts.PartitionKey.
	PartitionLimit int
	// PriorityAging raises a waiting job's priority by one level each time
	// it has waited this long, so low priorities cannot starve.
	PriorityAging time.Duration
}

type QueueControl[TTx any] struct {
	// contains filtered or unexported fields
}

type QueueLimits = driver.QueueLimits

type QueueRow = driver.QueueRow

type QueueStats = driver.QueueStats

type Raw = json.RawMessage

type Schedule interface {
	// Next returns the first slot strictly after t, or the zero time if
	// there is none within a reasonable horizon.
	Next(t time.Time) time.Time
}

type SeekOpts struct {
	// Position makes the event after it the next delivered.
	Position StreamPosition
	// Time replays from the first event appended at or after it.
	Time time.Time
	// Earliest replays every retained event.
	Earliest bool
	// Latest skips to the events appended from now on.
	Latest bool
}

type SnoozeError struct {
	Duration time.Duration
	// Reason is stored on the job while it waits, as JobRow.SnoozeReason,
	// for operators, and is the Error of the job.snoozed event. It is
	// cleared when the job runs again. A job that expires or is canceled
	// while it waits keeps the reason in the error it is finalized with.
	Reason string
}

type Stats = driver.Stats

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

type StepOpts struct {
	// After lists the steps this one waits for. It is inserted pending and
	// becomes available once they have all finished.
	After []Step
	// OnDependencyFailure defaults to DependencyCancel.
	OnDependencyFailure DependencyFailure
	// Insert holds the job's own options.
	Insert *InsertOpts
}

type StreamEvent = driver.StreamEvent

type StreamPosition = driver.StreamPosition

type StreamStart = driver.StreamStart

type Streams[TTx any] struct {
	// contains filtered or unexported fields
}

type Subscription struct {
	// Name identifies the subscription; the delivery job kind is derived
	// from it.
	Name    string
	Pattern string
	// Queue is where deliveries go. Defaults to QueueDefault.
	Queue string
	// MaxAttempts is the retry budget of deliveries. Zero means 25, or 10
	// for deliveries with an ordering key, whose retries block their key.
	MaxAttempts int
	// Metadata is merged into every delivery's metadata.
	Metadata json.RawMessage
}

type SubscriptionRow = driver.SubscriptionRow

type Topic interface {
	Topic() string
}

type UniqueConflict int

type UniqueOpts struct {
	// ByArgs includes the args in the key: the fields tagged
	// `hopper:"unique"`, or the whole args if no field is tagged.
	ByArgs bool
	// ByQueue includes the queue in the key.
	ByQueue bool
	// ByPeriod includes the current time, truncated to this period, so that
	// at most one job exists per period. For example 24 * time.Hour allows
	// one job per UTC day.
	ByPeriod time.Duration
	// OnConflict is what to do when the job exists.
	OnConflict UniqueConflict
}

type UnknownKindError struct {
	Kind string
}

type Worker[T JobArgs] interface {
	// Work runs the job. Returning nil completes it. Returning an error
	// schedules a retry with backoff, or discards the job when it is out of
	// attempts. Return Snooze(d) to run again later without using an attempt
	// and Cancel(err) to discard now.
	Work(ctx context.Context, job *Job[T]) error
	// Timeout returns how long the job may run before its context is
	// canceled: 0 for the client's default, or a negative duration for no
	// timeout.
	Timeout(job *Job[T]) time.Duration
	// NextRetry returns when a failed job runs again, or the zero time for
	// the default backoff.
	NextRetry(job *Job[T]) time.Time
}

type WorkerDefaults[T JobArgs] struct{}

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

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

type WorkflowOpts struct {
	OnSuccess  JobArgs
	OnFailure  JobArgs
	OnComplete JobArgs
	// CallbackOpts applies to every callback job.
	CallbackOpts *InsertOpts
	// Metadata is stored with the workflow.
	Metadata json.RawMessage
}

type WorkflowResult struct {
	ID JobID
	// Jobs are in step order.
	Jobs []*InsertResult
}

type WorkflowRow = driver.WorkflowRow