One transition, run twice

A node here is one Valkey server, and the workshop needs two. Each is defined by what it runs and by the value its {emq}:version key holds, the brand the Elixir connector and the job-core write verbs each check.

The connector and the job-core write verbs read the same key, and each accepts one value. The connector’s fence runs on every connect and reconnect, after the boot commands and before the socket carries anything else, and the connection’s wire picks its clause. On the default wire: 4 its own brand passes. An absent key is claimed with SET … NX and read back. Any other value, echomq:6.0.0 included, is a {:version_fence, got} error, and that error stops the connector at start and on every reconnect. Opened with wire: 6, the connector writes nothing: it calls EMQ.VERSION and requires the wire echomq:6.0.0, module major 0 and the fourteen job-core tokens, then reads the key and accepts only echomq:6.0.0. An absent key stops it with {:version_fence, :absent}.

The native fence runs inside every job-core write verb, after its shape and layout checks and before any domain read. It reads the key as the caller and only reads. echomq:6.0.0 passes; an absent key or any other string refuses with an EMQWIRE text, and nothing is written.

One key holds one value, so no brand passes both fences: the wire: 4 connector that sends the scripts stops on the module’s brand, and the module’s job-core write verbs refuse the connector’s. A node serves the scripts or the job-core write verbs, never both; a wire: 6 connector is a client of the verbs and connects only to the module’s node. On an absent key, the first writer sets the role. The wire: 4 connector’s SET … NX brands a scripts’ node. EMQ.INSTALL 1 {emq}:version brands a module’s node and takes no brand from its caller: on an absent key it writes echomq:6.0.0 and replies 1, on echomq:6.0.0 it replies 0 and writes nothing, and any other string refuses with the text the job-core verbs’ fence returns, EMQWIRE expected echomq:6.0.0 found <brand>. It runs no fence: it reads the key itself, and a value that is not a string passes the server’s WRONGTYPE through.

Read the four values down the three speakers. Only an absent key admits two writers, and the first one to write sets the role: after it, one side passes and the other refuses. A wire: 6 connector is not a third writer: it only reads the key, and it connects where EMQ.INSTALL has written echomq:6.0.0. On the stand the two roles sit on two nodes: the Echo service node loads no module, and its contract forbids loading one; the module runs on a separate node of its own.

The transition is the first two moves of the job lifecycle: enqueue a job, then claim it. On both nodes EchoMQ.Jobs.enqueue/5 and claim/3 send them through EchoMQ.Connector.eval/5, which builds one line per script call: the command, the script’s SHA-1, the number of keys, the keys, then the values. It hands the line to the connection with the script’s wire6 declaration, and the connection’s wire decides what is sent.

A native command keeps that line and swaps its head: EMQ.<VERB> numkeys key … arg … is the EVALSHA line with the command name in place of EVALSHA and the sha. A wire: 6 connection makes that swap for every script that declares its verb, as @enqueue declares EMQ.ENQUEUE and @claim2 declares EMQ.CLAIM. Both handlers name their form and check their shape first, the count of keys and then the count of values.

Here is the transition as each node receives it. The queue is quotes, the job is JOB0KHTOWnGLuC, the lease is 30000 milliseconds, and <payload> stands for the bytes sent. Replies show strings in quotes and integers bare. The two shas are the SHA-1 of the @enqueue and @claim2 sources, as EchoMQ.Script.new/2 computes them; the harness in step 3 pins the same two values.

The keys sit in the same places, the values too, and the replies match. What moves lies outside the tail. The scripted claim reads the pause flag in a round trip of its own before the script runs, so the flag lives in the host: a raw EVALSHA of @claim2 claims a paused queue. EMQ.CLAIM reads the flag inside the command and answers an empty array. claim/3 keeps its own read on both wires, so through the connector a paused queue answers :empty and neither line is sent. A server without the script cached answers the first EVALSHA with NOSCRIPT, and the connector loads the source once and sends the line again; a command has no sha to miss.

After the enqueue the two nodes hold the same keys under the queue’s hashtag: the row emq:{quotes}:job:JOB0KHTOWnGLuC with state pending, attempts 0 and the payload, and the id in emq:{quotes}:pending at score 0. After the claim the pending set is gone, the active set holds the id at the lease deadline, and the row says state active and attempts 1. The module’s row carries one field more, lease_epoch, set to the server’s run_id; the scripts write no such field.

The scripted claim is EchoMQ.Jobs @claim2, the handle claim/3 evaluates. Its body, read for what it leaves behind:

The native claim makes the same four writes after its write guard, checks two of them against what its reads predicted, and puts the epoch into the row’s HSET:

The deadline follows one rule on both: the server’s time in milliseconds plus the lease. The script reads it with TIME; the handler reads the command’s cached clock, the value TIME reports. On two nodes the instants differ, so the two scores differ by when each claim ran. The module’s writes reach the AOF and replicas as the plain commands the handler called, ZADD <key> <absolute score> <id> among them, and no EMQ.* record is written: a replay runs no handler, and the deadline replays as the score that was written.

The scripts are the reference the ported handlers are held to, and the differential harness is how. It sends the script bodies with EVAL rather than through the connector, so no wire-4 fence runs, and one scratch server branded echomq:6.0.0 serves both sides. Each case runs twice, on two separate queues: once as the wire-4 operation exactly as EchoMQ performs it, the host steps plus EVAL of the body read verbatim from the Elixir source at a pinned commit, and once as the EMQ.* command with the same tail. The harness refuses to measure unless each body’s two digests match their pins; the two shas in step 2 are among them.

It compares the typed reply and every key under each queue’s hashtag, with the queue’s name taken out of the key names and each lease score matched to the window of server time around its call. A field the native side adds by a declared delta, such as lease_epoch, must hold its expected value, here the server’s run_id, on every row the call leased, and is then masked on both sides; everything else must compare equal. In its lease-exact cases the harness runs the script, the command and a TIME read in one MULTI/EXEC, so both sides read one cached time and the scores must be equal. It then checks that no EMQ.* record reached the AOF and that the state is the same after a restart that loads the AOF. A case whose native behavior differs by design is judged against its declaration, never against Lua. Two native verbs, EMQ.RESCHEDULE and EMQ.REQUEUE, have no scripted twin; the harness runs executable checks from their specification instead.

That is Lua’s role beside the module. By default the Elixir side runs its job transitions as these scripts: every production caller opens EchoMQ.Connector on wire: 4, which evaluates them. Opened with wire: 6, the connector runs this same transition as EMQ.ENQUEUE and EMQ.CLAIM where wire 4 sends EVALSHA, sends the other job-core verbs the library’s scripts declare the same way, and refuses every script that declares neither a verb nor a read, so no Lua write reaches the module’s node through it. The architecture gives Lua “an explicitly versioned compatibility/reference path” and says it “should not remain a second production implementation of every native transition”. So the roles divide: the native module takes over the transitions on its node, and the scripts stay as wire 4, the compatibility path and the reference the ported handlers are held to.

The workshop runs one pattern on two executors and checks one against the other.

The part read the module as it loads and registers, the grammar its job-core write verbs run and the job core it carries; Blocking, timers and the bus and TRA and native values paired what runs today with where the specifications take it. This page ran one transition through both executors: two nodes kept apart by one key’s value; one enqueue and one claim sent as EVALSHA and as EMQ.* with the same tail; and the keys they leave, equal under the harness’s comparison once lease_epoch, the one field the module’s claim adds, is accounted for.