Snoozing jobs

Snoozing allows a worker to try a job again at a later time by returning the result of JobSnooze. The job will be put back into the queue and scheduled to run again after the specified duration.

Under normal circumstances, jobs that return an error are scheduled to be retried. This is done under the assumption that the problem they ran into was intermittent, or can be corrected by a code deploy that fixes a worker bug. However, sometimes a worker might want to execute the same job again in the future, even if no error has occurred.

While this could be achieved by enqueueing a new job, doing so can result in having many separate jobs in the database. The other option is to return an error from the job, but that doesn't offer control over the retry interval and can eventually cause the job to exhaust its maximum attempts. Snoozing avoids these issues.

To snooze a job for later execution, return the result of JobSnooze from a worker:

func (w *SnoozingWorker) Work(ctx context.Context, j *river.Job[SnoozingArgs]) error {
    if tryAgainLater {
        return river.JobSnooze(30*time.Second)
    }
    return nil
}

See the JobSnooze example for complete code.

JobSnooze takes one argument — the duration (after time.Now()) to snooze until the job should be attempted again. It returns an error that River will recognize as a signal to snooze the job (rather than counting it as an actual error).

After the snooze duration, the next execution of the scheduler will put the job into available state so that a client can fetch and work it. Although there is no minimum snooze interval, in practice you will be limited by the scheduler's run interval.

Snoozing is an intentional decision by the worker to try a job again later and isn't considered an error. By extension, snoozing does not affect a job's retry behavior. Each time a job is snoozed, its MaxAttempts are incremented by 1 so that a job can keep snoozing indefinitely. If a snoozed job later encounters an error and requires a retry, the previous snoozes will not be counted as errors when determining the retry backoff duration.