Skip to main content
A job is one run of a task or workflow, stored as a record in your database. A queue is a name on that record. Queuing a job only saves it; a runner that covers its queue claims and runs it later. Use the API through req.frogbot.jobs in hooks and endpoints, or frogbot.jobs on your initialized instance.

Queue a job

Use workflow instead of task for a registered workflow. Pass waitUntil: new Date(...) to delay the job. An explicit queue takes precedence over the workflow’s configured queue; otherwise jobs use default.

Where to queue

For example, notify subscribers when a post is published:
And from a server function, after checking the user yourself:

Queue options

Every method that accepts req takes a FrogBotRequest. overrideAccess defaults to false, which runs the matching jobs.access rule against req.user; pass true to skip it.

Reserve a jobId

jobId is an optional string, unique among unfinished jobs across all tasks, workflows, and queues. It stays reserved while the job is waiting (including a future waitUntil), processing, failed with retries left, or paused at waitFor. A paused workflow keeps it through delays, resumable waits, expiry, and the resumed run. A duplicate jobs.queue with a reserved jobId creates nothing, does not throw, and resolves with the existing job record: the same id, original task or workflow, input, queue, waitUntil, and meta. The new call’s arguments are ignored, so use an ID that identifies the work, not just the caller. Concurrent calls from many instances end with one job on every supported database, subject to the MongoDB transaction exception below.
  • The returned job.id remains the generated primary key. Use it for runByID and cancelByID.
  • Omitting jobId preserves ordinary enqueue behavior; multiple jobs can omit it.
  • Completion, failure for good, cancellation, or deletion frees the ID. Completion frees it whether the record is kept or deleted, with either jobs.deleteJobOnComplete setting.
jobId means “first live job wins; later duplicates are absorbed.” concurrency.supersedes instead deletes older pending jobs with the same concurrencyKey first, including paused workflows, freeing their IDs before inserting the replacement. A job that is already processing is not superseded; the duplicate resolves with it. jobId is not an “only ever once” key and does not give exactly-once execution. After a job finishes, the same ID queues new work; recovery can also repeat an external side effect. Check your own records for side effects that must happen once.

Transactions

A duplicate inside your transaction resolves with the existing job and leaves the transaction usable on Postgres and SQLite. On Postgres, a duplicate of a job inserted by another still-open transaction waits until that transaction ends. On MongoDB, if two uncommitted transactions enqueue the same new jobId at the same moment, the server aborts the losing transaction with its retryable transient transaction error. FrogBot passes that error through unchanged; retry the whole transaction. Duplicates of committed jobs and calls outside a transaction do not error because of a duplicate. Unrelated database errors still reject.

Run jobs

Pick one way to run jobs for each queue: Every runner needs to cover the queues your jobs use. Keep one covering default too: FrogBot’s own frogbot-sweep-waitpoints task runs there every minute.

Local API

For example, a maintenance loop can schedule and run across every queue:
Jobs in a batch run in parallel unless sequential: true. Queue, run, and cancel operations run the matching jobs.access rule unless overrideAccess: true is passed. The default rule allows a signed-in user, so workers, crons and other calls without a user pass overrideAccess: true. An exceptional completion or database-write failure can reject a batch before already-started sibling work finishes. The batch promise does not guarantee that siblings have drained after such a failure.
Local API run({ limit: 0 }) means unlimited. Only the worker CLI treats --limit 0 as “run no jobs.”

Run options

Run jobs over HTTP

FrogBot mounts two GET routes on the jobs collection, under your API prefix. Both check jobs.access.run, and answer 401 when it fails. On a serverless host, have a cron service call run with a shared secret. Let that secret pass the run check:
Then call it every minute from your host’s scheduler, or any cron:
Each call runs one batch of at most limit jobs, so choose a cron interval and limit that keep up with your queue. A crashed call’s jobs wait for their lease to expire, then a later call claims them.

Processing order

Runners claim the oldest jobs first. Set jobs.processingOrder to change that, globally, per queue, or with a function of the run arguments:
run({ processingOrder }) overrides it for one batch.

Check a job’s status

jobs.queue resolves with the job record. Read it again later through the jobs collection, payload-jobs, with overrideAccess: true; its access rules deny everything else by default.
Completed jobs are deleted unless jobs.deleteJobOnComplete is false, so a missing record usually means success. Failed and cancelled jobs are kept.

Show jobs in the admin

The jobs collection is hidden from the admin, because job inputs, outputs, and errors can hold sensitive data. To give admins a read-only list, override it:
Keep create, update, and delete denied, and change jobs through frogbot.jobs so access rules and leases apply.

Cancel jobs

A cancelled job gets hasError: true and error: { cancelled: true }, and frees its jobId. A job that is running finishes its current step, then stops before the next one. Cancelling a paused workflow ends its wait; see Durable waits.

Access

Each rule receives { req } and returns a boolean or a promise of one. Set them in jobs.access. These rules guard frogbot.jobs. Reads and writes on the payload-jobs collection itself follow the collection’s access, set through jobsCollectionOverrides.

Callbacks, hooks, and requests

Job execution uses atomic claims and direct job-record updates at depth 0. It does not run jobs collection hooks. Ordinary application collection hooks, including those invoked by collection operations inside a task, remain supported. Task handlers, onSuccess and onFail, workflow handlers, and inlineTask callbacks receive a FrogBotRequest, so req.frogbot is set, as in hooks and endpoints. Task handlers given as a file path do not get it.

Leases and crash recovery

Each run claims jobs with a fresh processingToken and a processingUntil lease, and renews the lease while the jobs run. Task and workflow handlers need no heartbeat code. A job whose lease has passed can be claimed by any worker; an old worker can’t update a job once a successor holds it. FrogBot’s SQL adapters claim with FOR UPDATE SKIP LOCKED on Postgres, so concurrent workers take different jobs. Choose a duration with headroom for event-loop pauses and database delays; it is not a maximum job runtime. A crash doesn’t use up a retry. Keep a scheduler and worker running that cover the default queue, or use allQueues: true for both scheduling and execution. They can share one process. The default queue runs the frogbot-sweep-waitpoints task, which expires waits and wakes their jobs. It also deletes failed scheduled jobs whose task is no longer registered, such as one an upgrade removed; the schedule queues a fresh job if the task comes back. Recovery is at least once. A crash, database outage, or event-loop stall can lose the lease after an external action has already happened. The lease protects job updates, not external effects. Make external operations idempotent, for example with the destination service’s idempotency key.