Jobs

Table of contents
  1. Jobs
    1. Generating jobs
    2. Class structure
      1. Models
    3. Job options
    4. Unique jobs
    5. Debounced jobs
    6. Encrypted jobs
    7. Interacting with the queue
    8. Interruptible jobs

Generating jobs

perago make:job ProcessPodcast            # app/jobs/process_podcast.go
perago make:job ProcessPodcast --batched  # checks for a cancelled batch
perago make:job SendSms --sync            # runs in the dispatching process

Class structure

A job is any type with Handle(ctx context.Context) error. Its exported fields are its payload: they are JSON-encoded when the job is dispatched and decoded into a fresh value before Handle runs. Embed perago.Queueable to get the queue methods (Release, Delete, Fail, Attempts, Batch, OnQueue, and the rest).

type ProcessPodcast struct {
	perago.Queueable
	PodcastID int
	Mailer    *mail.Client `json:"-"` // not part of the payload
}

func init() { perago.Register(&ProcessPodcast{}) }

func (j *ProcessPodcast) Handle(ctx context.Context) error { ... }

Workers rebuild jobs by name, so register every job in init() of a package your worker imports. The name defaults to package.Type. Declare JobName() string, or use perago.RegisterAs("podcasts.Process", &ProcessPodcast{}), to keep old payloads working after a rename.

To inject dependencies, as Laravel does through handle’s parameters, register a factory:

perago.RegisterFactory("jobs.ProcessPodcast", func() perago.Job {
	return &ProcessPodcast{Mailer: mailer}
})

Binary data goes into a []byte field, which JSON stores as base64.

Models

On a migro project, model.Of[T] and model.Many[T] put migro models in a job as their primary key and load them again, fresh, before Handle (Laravel’s SerializesModels). See Using with migro. Without migro, keep the key in the job and load the row in Handle, or give a field type a Restore method by implementing perago.Restorable.

Job options

Laravel’s attributes and properties are optional methods on the job:

Laravel perago
#[Tries(5)], $tries Tries() int (0 retries forever)
#[Backoff([10, 30])], backoff() Backoff() []time.Duration (the last value repeats)
#[Timeout(120)] Timeout() time.Duration
retryUntil() RetryUntil() time.Time (wins over Tries)
#[RetryFor(minutes: 10)] RetryFor() time.Duration
#[MaxExceptions(3)] MaxExceptions() int
#[FailOnTimeout] FailOnTimeout() bool or embed perago.FailsOnTimeout
#[CountCrashesAsExceptions] CountCrashesAsExceptions() bool or embed perago.CountsCrashes
#[DeleteWhenMissingModels] DeleteWhenMissingModels() bool or embed perago.DeletesMissingModels
failed(Throwable $e) Failed(ctx, err error)
middleware() Middleware() []perago.Middleware
displayName() DisplayName() string
messageGroup(), deduplicationId() MessageGroup() string, DeduplicationID() string

A job without Tries uses the worker’s --tries (1 by default). Attempts are counted the way Laravel counts them: each reservation is an attempt, whether it ends in an error, a release, a timeout or success.

Unique jobs

type UpdateSearchIndex struct {
	perago.Unique       // ShouldBeUnique
	ProductID int
}

func (j *UpdateSearchIndex) UniqueID() string         { return strconv.Itoa(j.ProductID) }
func (j *UpdateSearchIndex) UniqueFor() time.Duration { return time.Hour } // #[UniqueFor(3600)]
func (j *UpdateSearchIndex) UniqueVia() perago.Cache  { return redisCache } // optional

While a unique job is queued or running, dispatching another one with the same UniqueID does nothing: Send returns an empty id and a nil error. The lock is released when the job finishes or fails. With perago.UniqueUntilProcessing, it is released right before the job starts. Unique locks need an atomic Cache: memory (one process), database or Redis. They do not apply to jobs inside a batch.

Debounced jobs

func (j *ReindexDocument) DebounceFor() time.Duration     { return 30 * time.Second } // #[DebounceFor(30)]
func (j *ReindexDocument) DebounceMaxWait() time.Duration { return 2 * time.Minute }  // maxWait: 120
func (j *ReindexDocument) DebounceID() string             { return j.DocumentID }
func (j *ReindexDocument) DebounceVia() perago.Cache       { return redisCache }       // optional

Within the window, only the latest dispatch runs. The superseded jobs are deleted when they come up, and each fires JobDebounced. DebounceMaxWait caps how long a job can keep being pushed back. Debounce and unique are mutually exclusive.

Encrypted jobs

type ChargeCard struct {
	perago.Encrypted   // ShouldBeEncrypted
	Card string
}

The payload is sealed with AES-256-GCM using Config.Key (32 bytes) before it reaches the backend. To rotate the key, move the old one to Config.PreviousKeys.

Interacting with the queue

Inside Handle, through the embedded Queueable:

j.Attempts()                  // this attempt included
j.Release()                   // back on the queue now
j.Release(10 * time.Second)   // ... after a delay
j.ReleaseUsingBackoff()       // ... after the backoff for this attempt
j.Delete()                    // remove it; a chain still continues
j.Fail()                      // fail now, without retrying
j.Fail(err)                   // ... with a cause
j.Fail("bad input")           // ... with a message
j.JobID(); j.BatchID(); j.Batch(ctx)

Middleware and code that only has the context can use rt, _ := perago.JobFrom(ctx) to reach the same runtime.

To stop retrying on specific errors everywhere, use m.DontRetry(ErrInvalid) or m.DontRetryWhen(func(err error) bool {...}). For a single job, use the FailOnException middleware.

Interruptible jobs

A worker that receives SIGTERM, SIGINT or SIGQUIT finishes its current job before it exits. To stop early, implement Interrupted(sig os.Signal):

func (j *ImportProducts) Interrupted(os.Signal) { j.stop.Store(true) }