Documentation
¶
Index ¶
- Constants
- Variables
- func Enqueue(ctx context.Context, tx pgx.Tx, job Job) error
- func Migrations() []migrate.Source
- type FailedJob
- type Handler
- type HandlerFunc
- type Job
- type Registry
- type Repository
- func (r *Repository) CountFailed(ctx context.Context) (int64, error)
- func (r *Repository) DiscardFailed(ctx context.Context, id string) error
- func (r *Repository) GetFailed(ctx context.Context, id string) (FailedJob, error)
- func (r *Repository) ListFailed(ctx context.Context, limit int) ([]FailedJob, error)
- func (r *Repository) RequeueFailed(ctx context.Context, id string, runAt time.Time) error
- type Worker
- type WorkerConfig
Constants ¶
const Schema = `` /* 430-byte string literal not displayed */
Schema bootstraps the jobs table for ephemeral tests only. Production deployments must apply jobs.Migrations() for upgrade-safe evolution.
Variables ¶
var ( ErrInvalidRegistration = errors.New("jobs: invalid handler registration") ErrHandlerRegistered = errors.New("jobs: handler already registered") ErrHandlerNotFound = errors.New("jobs: handler not found") )
var ErrFailedJobNotFound = errors.New("jobs: permanently failed job not found")
ErrFailedJobNotFound indicates that no permanently failed job matched the requested operation.
Functions ¶
func Enqueue ¶
Enqueue inserts a job into the devengine_jobs table. It must be called within a transaction.
func Migrations ¶
Migrations returns the migrations required by the persistent delayed jobs queue. It does not install Outbox infrastructure.
Types ¶
type FailedJob ¶
type FailedJob struct {
ID string
Name string
Payload json.RawMessage
RunAt time.Time
Attempt int
MaxAttempts int
LastError string
CreatedAt time.Time
}
FailedJob is a permanently failed job available for operational inspection.
type HandlerFunc ¶
HandlerFunc allows using a function as a Handler.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores the handlers for different job types.
func (*Registry) HandlerFor ¶
HandlerFor returns the handler registered for the given name.
type Repository ¶
Repository provides PostgreSQL-native administrative operations for jobs.
func NewRepository ¶
func NewRepository(pool *pgxpool.Pool) *Repository
func (*Repository) CountFailed ¶
func (r *Repository) CountFailed(ctx context.Context) (int64, error)
CountFailed returns the number of permanently failed jobs.
func (*Repository) DiscardFailed ¶
func (r *Repository) DiscardFailed(ctx context.Context, id string) error
DiscardFailed permanently deletes a failed job.
func (*Repository) ListFailed ¶
ListFailed returns permanently failed jobs ordered from oldest to newest. A non-positive limit defaults to 100.
func (*Repository) RequeueFailed ¶
RequeueFailed makes a permanently failed job eligible for delivery again. It resets its attempt history and schedules it at runAt; a zero runAt means now.
type Worker ¶
type Worker struct {
Pool *pgxpool.Pool
Registry *Registry
Logger *slog.Logger
Config WorkerConfig
Tracer telemetry.Tracer
Meter telemetry.Meter
}
Worker is a background worker that polls the jobs table. Jobs use leased claims: active handlers renew their lease, and only the holder of the current claim token can renew or persist an outcome. Handlers must remain idempotent because delivery remains at-least-once (for example after a process crash or a lost lease).
type WorkerConfig ¶
type WorkerConfig struct {
BatchSize int
PollInterval time.Duration
InitialBackoff time.Duration
// LeaseDuration is the maximum time a worker owns a claimed job.
LeaseDuration time.Duration
// LeaseRenewalInterval controls how often an active handler renews its
// lease. Zero renews at half LeaseDuration. Values at or above the lease
// duration are clamped to half the lease to prevent expiry before renewal.
LeaseRenewalInterval time.Duration
}
WorkerConfig configures the jobs Worker.
Source Files