queue

Durable job queue with leases over std.sql: enqueue work, workers claim it with a lease, a worker that dies has its job reclaimed once the lease expires.

ecko get github.com/ecko-lang/queue
import queue

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.56.0 - source - MIT.


init(db)

Creates the queue's table and claim index if they do not already exist, and returns null. Safe to call every time a program starts; it never touches existing rows.

errors: sql when the table cannot be created.

queue.init(db)

enqueue(db, queue_name, payload, delay_ms = 0, run_at = null, max_attempts = 5, now = null)

Adds a job to queue_name and returns its id.

Pass the tx of your own sql.transaction to enqueue atomically with your other writes: the job commits with them or not at all. payload must be plain data that JSON gives back unchanged (null, bools, ints, floats, strings, and lists and maps of those), so claim hands back exactly what was enqueued. delay_ms or an absolute run_at (unix ms) delays when the job becomes claimable - run_at wins if both are given. max_attempts is how many times the job may be claimed: a job whose last attempt fails, or whose last lease expires, is dead-lettered. now overrides the clock.

errors: queue/not_storable when payload holds a decimal, record, secret, bytes or function; bug/bad_argument for an empty queue name, a negative delay_ms, a max_attempts that is not a positive Int, or a non-Int run_at or now; sql when the insert fails.

queue.enqueue(db, "emails", { to: "a@example.com" })
queue.enqueue(db, "reports", { id: 9 }, delay_ms: 60000, max_attempts: 3)

claim(db, queue_name, worker_id, lease_ms, now = null)

Atomically claims the oldest ready job for queue_name under a fresh lease of lease_ms, or returns null when nothing is ready.

A job is ready when its run_at has passed and it is either unclaimed or claimed with an expired lease and attempts to spare. It is marked "in_progress" and returned as { id, queue_name, payload, attempts, max_attempts, worker_id, lease_token, lease_expires }, where payload is the value passed to enqueue. A job whose lease expired on its last allowed attempt is dead-lettered here instead of being handed out again.

lease_token changes on every claim, including a reclaim of an expired lease - it is what makes a stale worker's complete/fail/extend fail instead of racing a worker that has since taken the job over. Pass the whole job back to those calls.

The claim is one update ... returning statement, so two workers can never take the same job. Give each concurrent worker its own connection to the same database file; brief "database is locked" contention between them is retried inside claim rather than thrown.

errors: bug/bad_argument for an empty queue name or worker id, a lease_ms that is not a positive Int, or a non-Int now; sql when the database refuses the claim for longer than the retries.

job = queue.claim(db, "emails", "worker-1", 30000)   # 30s lease, or null

complete(db, job, now = null)

Marks job (as returned by claim) done and returns null.

errors: queue/lease_lost if another worker has since reclaimed the job or it already finished; queue/not_found (with id) if the row is gone; bug/bad_argument when job is not a claimed job or now is not an Int.

queue.complete(db, job)

fail(db, job, reason, backoff_ms = 1000, backoff_max_ms = 60000, now = null)

Records a failed attempt on job and returns { status, attempts, run_at }.

While the job has attempts left it goes back to "ready" after an exponential backoff (backoff_ms, doubling per attempt, capped at backoff_max_ms); on its last attempt (attempts == max_attempts) it is moved to "dead" instead (see dead and retry_dead). reason is stored as last_error, as text.

errors: the lease errors of complete; bug/bad_argument when job is not a claimed job, backoff_ms is negative, backoff_max_ms is not a positive Int, or now is not an Int.

queue.fail(db, job, "smtp timeout")   # {attempts: 1, run_at: 1700000001000, status: ready}

extend(db, job, lease_ms, now = null)

Refreshes a claimed job's lease to lease_ms from now and returns the job with its new lease_expires, for work that legitimately needs longer than its original lease.

errors: the lease errors of complete; bug/bad_argument when job is not a claimed job, lease_ms is not a positive Int, or now is not an Int.

job2 = queue.extend(db, job, 60000)

stats(db, queue_name, now = null)

Counts the jobs of queue_name by state: { ready, scheduled, in_progress, expired, done, dead, total }.

ready is due and unclaimed right now; scheduled is "ready" status with run_at still in the future; in_progress is actively leased; expired is leased but past lease_expires with attempts to spare (claimable on the next claim); done and dead are terminal, and dead includes a job whose lease expired on its last attempt.

errors: bug/bad_argument when now is not an Int; sql when the table cannot be read.

queue.stats(db, "emails").ready   # 3

dead(db, queue_name, limit = 100)

The dead-lettered jobs of queue_name, newest first, at most limit of them: [{ id, payload, attempts, max_attempts, last_error, created_at, updated_at }, ...].

errors: bug/bad_argument when limit is not a positive Int; sql when the table cannot be read.

map(queue.dead(db, "emails"), fn(j) j.last_error)   # ["smtp timeout"]

retry_dead(db, id, now = null)

Moves the dead job id back to "ready" with its attempts reset and its last error cleared, claimable from now. Returns null.

errors: queue/not_found (with id) when id names no dead job; bug/bad_argument when now is not an Int.

for j in queue.dead(db, "emails") { queue.retry_dead(db, j.id) }