Documentation
¶
Overview ¶
Package jobs is a typed job layer on top of hex/queue. It gives consumers Laravel/Sidekiq-style named jobs with retry, exponential backoff, dead-letter routing, and delayed dispatch — all built on any queue.Queue implementation.
A job is a struct that satisfies the Job interface: it has a Name and a Run method. Consumers register handlers on a Runner; Dispatch serialises a job into a queue.Message and publishes it. On the consumer side the Runner dispatches to the registered handler for the job's Name, applies retry policy, and moves permanently failing jobs to a dead-letter topic.
Envelope wire format:
{"name": "send-email", "payload": <json>, "attempt": 3, "dispatched_at": "..."}
The envelope is JSON so the wire is inspectable and portable across backends. Payload is the arbitrary Go value the consumer passes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DispatchOptions ¶
type DispatchOptions struct {
// Delay defers execution for at least this duration.
Delay time.Duration
// MaxAttempts overrides the runner default for this specific job.
MaxAttempts int
}
DispatchOptions customises a single Runner.Dispatch call.
type Envelope ¶
type Envelope struct {
Name string `json:"name"`
Payload json.RawMessage `json:"payload,omitempty"`
Attempt int `json:"attempt"`
MaxAttempts int `json:"max_attempts,omitempty"`
DispatchedAt time.Time `json:"dispatched_at"`
ID string `json:"id,omitempty"`
}
Envelope is the wire format for a queued job. It is exported so tools (dashboards, dead-letter inspectors) can decode messages without a dependency on hex/queue/jobs.
type Handler ¶
type Handler func(ctx context.Context, payload json.RawMessage) error
Handler is invoked when a matching job is received. The raw payload is passed as JSON bytes; handlers typically unmarshal into their own payload struct.
type Options ¶
type Options struct {
// Topic is the queue.Queue topic used for all jobs handled by this
// runner. Defaults to "jobs".
Topic string
// DeadLetterTopic is where jobs go after MaxAttempts. Empty disables
// dead-lettering; failing jobs are dropped instead.
DeadLetterTopic string
// MaxAttempts caps the total number of attempts per job (initial
// try + retries). Zero means 3. Set to a negative number to retry
// forever (not recommended).
MaxAttempts int
// BaseBackoff is the initial retry delay. Defaults to 1 second.
// Exponential: attempt n waits BaseBackoff * 2^(n-1), capped at
// MaxBackoff.
BaseBackoff time.Duration
// MaxBackoff caps the retry delay. Defaults to 5 minutes.
MaxBackoff time.Duration
}
Options tune a Runner and its dispatched jobs.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner registers job handlers and consumes them from the underlying queue.
func (*Runner) Dispatch ¶
func (r *Runner) Dispatch(ctx context.Context, name string, payload any, opts ...DispatchOptions) (string, error)
Dispatch publishes a job. Payload is any JSON-marshallable value. The returned string is the underlying message ID.
func (*Runner) Register ¶
Register installs a handler for the given job name. Registering the same name twice overwrites the previous handler.
Source Files