Atomic state machine.

The atomic-updates pattern starts from a race. A read-modify-write — read a value, compute a new one, write it back — is three steps, and any other client can act in the gaps. The source's worked example is a balance: read account:123:balance, subtract 100, write the result. Two clients that both read the old balance before either writes both compute from the same number, and one update is lost.

Applied to the queue, the value being updated is a job's location. A worker completing a job reads the row's fencing token, checks it still holds the lease, and writes the move out of active. A lease-expiry sweep, running at the same instant, reads the same job still in active past its deadline and returns it to pending for redelivery. Run as separate commands, the two interleave: one process retires the job while the other re-queues it. The concurrent writers are the completing worker and the reaper (EchoMQ.Stalled, on the server clock), and the value they race on is the job's place in the queue.

A Lua script executes atomically — no other command runs between its first line and its last. So each transition folds the whole read-decide-write into one script: read the row's attempts token, decide whether it still matches and whether the attempt is past max, then write every move. No second client can interleave, because Valkey runs the script to completion before it serves the next command. In EchoMQ the leased state machine is EchoMQ.Jobs: enqueue/4 writes the row and the pending entry; claim/3 pops the oldest member, HINCRBYs the row's attempts to mint the lease token, and scores it into active; complete/5 checks the token and retires the row; retry/7 checks the token and either reschedules or moves the row to dead.

The client issues exactly one command per transition: the EVALSHA. Each script is declared inline with EchoMQ.Script.new(name, lua), which precomputes the SHA1, and dispatched by EchoMQ.Connector.eval/5, which runs EVALSHA first and falls back to SCRIPT LOAD + a re-run EVALSHA on a NOSCRIPT reply:

The script body runs the queue moves — ZPOPMIN over pending, ZADD into active/schedule/dead, ZREM from active, HINCRBY on the row's attempts, HSET on its state — but those reach Valkey inside the one cached-script call. Every key the script touches is declared in KEYS (the v2 law); the branded JOB id is gated before the key is built (EchoMQ.Keyspace.job_key/2 raises on an ill-formed id).

Use the atomic-script transition when a job's move reads state, branches on it, and writes across more than one key — and a second process can run the same move at the same time. A queue's completion is exactly that: it reads the fencing token, branches on whether the token still matches and whether the attempt is past max, and writes across the active set, the row hash, and the metric. A lease-expiry sweep runs concurrently by design.

Avoid it when the update is a single key and a single command — INCR, SET … GET, and GETDEL are already atomic on their own. And keep the keys on one node: a Lua script may only touch keys in the same slot, so EchoMQ braces the queue name — emq:{q}:pending, emq:{q}:active, emq:{q}:job:<id> — so every key of one queue hash-tags into one slot and a multi-key script can run at all (the R2.05 hash-tag treatment, built into the keyspace).

Each dive takes one part of the transition, in order: a job's states are emq:{q}: locations, the move between them is one EVALSHA per inline script, and the cached script reaches the server by SHA with a NOSCRIPT fallback. Read them in order — the locations first, the atomic move second, the SHA mechanics third.