Timeouts

Cooperative timeouts and the worker lease.

For cooperative timeouts, combine the provided signal with AbortSignal.timeout and pass the combined signal to the work. When the timeout fires, the handler below completes with a timedOut output; on any other error, including the worker's signal aborting, it rethrows so the job is rescheduled with backoff:

src/timeouts.ts

"fetch-report": {
  attemptHandler: async ({ signal, job, complete }) => {
    const timeoutSignal = AbortSignal.timeout(job.input.timeoutMs);

    try {
      const data = await fetchReport(job.input.url, {
        signal: AbortSignal.any([signal, timeoutSignal]),
      });
      return await stateAdapter.withTransaction(async (txCtx) =>
        complete({ ...txCtx, output: { data } }),
      );
    } catch (error) {
      if (!timeoutSignal.aborted) throw error;
      return stateAdapter.withTransaction(async (txCtx) =>
        complete({ ...txCtx, output: { timedOut: true } }),
      );
    }
  },
},

The worker's lease, set by leaseConfig, is not a runtime limit: it bounds how long a crashed worker's jobs wait before another worker picks them up. Each worker's heartbeat renews its lease every heartbeatMs, however many attempts it runs, so a handler may run far longer than the lease's durationMs. The lease only expires when the worker stops renewing it — it crashed, its event loop stalled, or it lost its database connection. On SQLite, a user transaction that holds an async provider's write lock, or blocks the thread with a synchronous provider, past the worker's local deadline also makes the worker give up its lease. Either way the jobs running under it are reclaimed and start a new attempt. Use the cooperative signal pattern above for real runtime limits.

The worker runner below holds a lease of 1000 ms, renewed every 300 ms, and rebuild-search-index waits for its job.input.durationMs, which the example sets to 3000 ms: it completes on its first attempt because the heartbeat keeps renewing the lease. heartbeatMs must stay below a third of the lease's durationMs.

src/timeouts.ts

await using workerRunner = createWorkerRunner({
  client,
  leaseConfig: { durationMs: 1000, heartbeatMs: 300 },
  processors: createProcessors({
    client,
    jobTypes,
    processors: {
      "rebuild-search-index": {
        attemptHandler: async ({ job, complete }) => {
          await delay(job.input.durationMs);
          return stateAdapter.withTransaction(async (txCtx) =>
            complete({ ...txCtx, output: { rebuiltOnAttempt: job.attempt } }),
          );
        },
      },
    },
  }),
});

See examples/guides/src/timeouts.ts for the runnable code. See also Error Handling and the Worker Lease reference.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open