The Protocol · module 03
The Lua layer
Every state change is one atomic script. The wire is not a list of commands — it is the set of scripts.
To enqueue a job is to run the @enqueue script; to claim one is to run
@claim; to finish one is to run @complete. Each is the whole
transition — read, decide, write — in a single server-side step no other client can interleave. That is why the
scripts are the protocol: the transitions live below the language line, every key
declared in KEYS[], loaded once and run by SHA. This
module reads the @enqueue script in two beats, the declared-keys law, and the EVALSHA
dispatch.
The wire is the set of scripts
Three transitions carry a job's life: enqueue, claim, complete. Each is one named script that declares its keys and runs atomically. Pick a verb to read its handle, the keys it declares, and the transition it performs — the catalog is the protocol.
The script catalog · pick a verb
Each verb is one declared-key script run atomically. Learn the catalog and you have read the wire.
The dives
Three dives read the Lua layer in depth, each grounded in real echo/apps/echo_mq and
echo/apps/echo_wire code: the enqueue transition in two beats, the declared-keys law,
and the EVALSHA dispatch that runs a script by its SHA.
Scripts are the protocol
The @enqueue handle, then its decoded Lua body — the branded-id gate, idempotency, the row write, the pending insertion. One atomic transition.
Declared keys
Every key passed in KEYS[]; none built from data. Why the host owns address — and how it unlocks thread-per-shard placement.
EVALSHA dispatch
EchoMQ.Script.new/2 precomputes the SHA1; EchoMQ.Connector.eval/5 runs EVALSHA-first, loading the source once on a NOSCRIPT miss.
Pattern & implementation
Where Redis Patterns Applied teaches the move — a pattern, pushed below the language line, becomes a protocol — this module is where the move lands. The scripts are the protocol.
An atomic multi-step update, expressed as one server-side script, becomes a protocol when the agreement is pushed below the language line. Patterns become protocol and Coordination teach it.
EchoMQ.Jobs's @enqueue / @claim /
@complete each run one transition atomically, every key declared in
KEYS[]; EchoMQ.Connector.eval/5 runs them by SHA.
Take the dives in order, or jump to the EVALSHA dispatch if you already know the transition. The next module — Immutability & branded ids — reads what holds the wire together.
References
Sources
- Valkey — EVALSHA — load-once, run-by-SHA dispatch of a declared-keys script.
- Redis — EVAL — atomic server-side scripting, the mechanism the Lua layer is.
- Valkey — Documentation — the substrate of record EchoMQ is backed by.
- DragonflyDB — Server flags —
--lock_on_hashtags, the thread-per-shard placement the declared-key discipline is built for.
Related in this course
- The Protocol — the chapter this module belongs to.
- The owned keyspace — where the keys the scripts declare are built.
- The record hash — the row the scripts write.
- redis-patterns · Patterns become protocol — the near side of the door.
- redis-patterns · Coordination — atomic updates and one-slot Lua.