Skip to content

MiniDist Tutorial

中文版

MiniDist compares four replication protocol families in one deterministic, in-process laboratory. Read the chapters in order: the first half establishes the comparison method, simulator, shared vocabulary, and asynchronous-primary mechanism; the second half follows failover fencing into Raft, compares seven experiments, then opens the WAL-shipping and ISR/HW mechanisms behind the two middle columns.

Chapters

  1. Why a Protocol Spectrum? — why this is not the 101st mini-Raft, and which trade-off questions the spectrum exposes.
  2. The Deterministic Simulation Foundation — SimNet, SimClock, Scheduler, FailureInjector, and event-for-event Trace replay.
  3. The Replication Group Abstraction — ReplicationGroup, acknowledgement/read levels, and explicit refusal of unsupported guarantees.
  4. Asynchronous Primary–Replica Replication — replica sinks, offsets, bounded backlog, partial resync, and full fallback.
  5. Failover and Generation Fencing — promotion, generation/lineage fences, active convergence, and stale full-sync rejection.
  6. Raft I: Election — terms, randomized timeouts, voting rules, and election safety.
  7. Raft II: Log Replication and Commit — AppendEntries consistency, current-term commit, and crash recovery.
  8. Seven Experiments Across Four Protocols — acknowledgement loss, slow replicas, reconnect windows, split-brain authority, and the closing read-consistency matrix.
  9. WAL Shipping, Flush Boundaries, and Timelines — logical WAL bytes, asynchronous/synchronous commit, retention, base backup, and promotion timeline fencing.
  10. ISR, High Watermark, and Controller Epochs — dynamic ISR membership, min.insync.replicas, HW, catch-up, clean election, leader-epoch fencing, and guarded reads.

How to use the book

Run commands from the repository root after uv sync --dev. Every pasted output is tied to a command and a source path. A simulation tick records event ordering, never milliseconds or performance. Exercises that propose code changes keep their reference patches inside folded notes; apply them only in a scratch branch or temporary copy, never as a prerequisite for later chapters.

The mechanism mapping, lab guide, and behavior/experiment matrix are reference material. Use the matrix as the support boundary: planned rows are not implementation evidence. The project README records repository-wide scope and installation requirements.