req.frogbot.jobs in hooks and endpoints, or frogbot.jobs on your initialized instance.
Queue a job
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:
Queue options
Every method that acceptsreq 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.idremains the generated primary key. Use it forrunByIDandcancelByID. - Omitting
jobIdpreserves 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.deleteJobOnCompletesetting.
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 newjobId 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:
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 twoGET 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:
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. Setjobs.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:frogbot.jobs so access rules and leases apply.
Cancel jobs
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 freshprocessingToken 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.