← the depth behind redis-patterns R5 · Streams & Events
The Bus · module 02
The stream log
Where an event says a thing once and is gone, the log remembers — in the order it happened.
The stream log is the append-only record of what happened, ordered the way the store is ordered —
by the branded id. One verb carries the whole idea: EchoMQ.Stream.append/4 mints an
EVT record id host-side, derives the explicit XADD
id from it, appends it direct onto emq:{q}:stream:<name>, and returns
{:ok, branded} — the id is the receipt. What holds the log together is
the order theorem: stream order, id sort, and mint order are one fact, proven by construction. When the
invariant is broken, the wire tells the truth — {:error, :nonmonotonic}, never swallowed.
It is all real code.
Append, and the log remembers
A stream is the same idea as an event made durable. An event is broadcast and gone; an entry appended to the log
stays, ordered by the branded id, replayable by anyone at their own pace. Step the append below — mint the
EVT id host-side, derive its explicit XADD id, append it direct,
keep the receipt — and watch the new entry land at the tail in mint order.
The append · step the writer
One wire: an event says it once, the stream remembers — minted host-side, appended in mint order, and handed back as a branded receipt the caller keeps.
The dives
Three dives, each grounding in the real echo/apps/echo_mq code — the host-side
mint and the kind door, the order theorem that holds the log together, and the claims-only id field with the
minimal read-back.
The host-side mint
append/4: mint the EVT id host-side, derive the explicit XADD id, append direct, keep the receipt — and the kind door that raises before the wire.
The order theorem
Stream order == id sort == mint order, proven by construction. A single writer is never rejected; a real violation surfaces as :nonmonotonic, never a silent * retry.
The claims-only id
The branded id stored as the stream id field; read/6 (XRANGE) recovers {branded, fields_map} in mint order — the doors to time-travel and the archive.
Redis Patterns Applied
This module is the depth behind the Redis Patterns Applied chapter that doors here: R5 · Streams & Events — the append-only log, event sourcing, and replay that this writer makes concrete. There the pattern is the door; here is the wire.
The rest of the pillar
The stream log is the writer. The rest of the Bus reads it: consumer groups deliver entries at-least-once, time-travel reads the log by a mint instant, and retention bounds it — folding what it trims into the durable floor. The events channel beside it is the present-tense surface the log makes durable.
The Bus
The pillar landing: the two surfaces, one wire — events and the stream log.
The Protocol
The braced keyspace and the branded-id gate the stream keys are born to.
The Queue
Distribute work over the same wire: the lifecycle, jobs, lanes, flows.
Echo Persistence
The durable floor a trimmed stream history folds into — the archive frontier.
The events channel, consumer groups, time-travel, and retention are the Bus's other modules, each added as its pages land. This module is the writer they all read.
References
Sources
- Valkey — Introduction to Streams — the append-only log
XADDandXRANGEoperate on. - Valkey — XADD — the append, issued direct with an explicit entry id.
- Valkey — Cluster specification — the
{q}hashtag co-locates a queue and its stream on one of 16384 slots. - Kreps — The Log — the log as the unifying abstraction beneath a stream.
Related in this course
- The host-side mint — the append and the receipt.
- The order theorem — why order is a theorem.
- The claims-only id — the stored id field and the read-back.
- The Bus — the pillar landing.
- The Branded Component System · the Bus — the manuscript chapter this module realizes.