Reproduce the real experiments

Supported baseline

Python 3.11+, Node.js 18+ for the model tests, macOS or Linux on arm64/amd64. The runner pins etcd 3.6.6 (Git SHA d2809cf, upstream Go 1.24.10). This is an explicit teaching baseline, not a claim about the newest release or a production version recommendation. No Docker, API key, paid service or Python package installation is required.

Three actual etcd processes share one host, use separate data directories and dynamically selected loopback ports. Each has GOMAXPROCS=2, GOMEMLIMIT=128MiB as a soft GC target, and a 64MiB backend quota. The full machine's memory is not bounded by GOMEMLIMIT. Experiments execute sequentially and normally take about a minute for three repetitions; this is an estimate, not a measured service target.

Download or clone

Portable source ZIP · Public companion repository. The companion is independently runnable so you can change fault schedules and inspect implementation code. It contains only this Lab's original course, synthetic evidence and runner. The personal homepage source remains private.

unzip distributed-systems-lab.zip
cd distributed-systems-lab
python3 scripts/install_etcd.py
python3 scripts/run_all.py --repeats 3 --out build/my-results
python3 scripts/run_network.py --repeats 3 --out build/my-network.json
node tests/demo-models.test.mjs
node tests/checker.test.mjs
python3 -m unittest discover -s tests -v
python3 scripts/build_site.py
python3 scripts/check_site.py
python3 -m http.server 18915 --directory build/site

Open http://127.0.0.1:18915/distributed-systems-lab/en/. The build renders committed results/, so a separate --out build/my-results will not replace the baseline. To intentionally regenerate your own course evidence, run with --out results, then rebuild and inspect the diff. Linux CI uses one new repetition in build/ci-results and does not rewrite the committed macOS record.

What the installer verifies

install_etcd.py downloads the official public release archive from the upstream storage location and verifies its SHA-256 against the release asset digest. Only etcd, etcdctl and etcdutl executables are extracted. Binaries, upstream archives and WAL files are excluded from downloads and publication. See the pinned release and the exact four-platform digest table in the installer.

Process ownership and bounded cleanup

The runner obtains an atomic heavy-runtime lock. In the shared authoring workspace it uses the existing ops lock; a standalone download or CI uses a build-local lock. If another workload owns it, the runner stops instead of deleting it. It only signals subprocesses that it created and closes their handles in cleanup. It never changes host firewall/routing, requires root, prunes containers, or kills unrelated processes.

Raw member logs, WAL data and SQLite sink state remain under ignored build/runs/. The report exporter constructs selected synthetic fields; it does not copy logs or scan the host. On an interrupted run, inspect the owner and the owning process before cleaning up your own artifacts. Do not delete another workload's lock by age.

Read or modify the implementation

• lab/runtime.py: loopback members, signals, JSON gateway calls, cleanup.
• lab/services.py: atomic counter/dedup Txn and SQLite fence.
• lab/worker.py: separate worker process resumed for the late write.
• scripts/run_all.py: schedule, assertions, repetitions and report schema.
• web/checker.mjs: bounded search; tests/checker.test.mjs: independent permutation oracle.

Read the source before increasing fault scope. A failed assertion is evidence to investigate, not a request to weaken the invariant. Preserve the failing raw run and compare versions, topology and conditions.

Unexecuted extensions

Packet-level asymmetric partitions, multi-host clock uncertainty, disk corruption, disaster restore, membership changes, Byzantine faults and external-system exactly-once protocols are outside this release. The code deliberately exposes a small learning surface rather than a production client library.

Interactive and course-linked practice

Seven interactive scenes make the concepts manipulable. The real peer-proxy exercise keeps nodes alive while cutting their connections. The searchable MIT 6.5840 map links all seven units to specific official materials and original runnable practice. CI executes both the original mechanisms and the new network control on Linux.