cld-toys › Toys
Toys
Small Python programs that each teach exactly one mechanism of infrastructure software — a rate limiter, a write-ahead log, an LSM tree. Each builds a working mental model of how the thing works, never a usable reimplementation.
A toy is 100–200 lines of core code you can hold in your head at once. Every toy here comes with a commentary: a study guide that explains the concept from scratch, walks the real source in reading order, derives the demo's result arithmetically, and points at the background reading. Click a card to read one.
Every number on these pages was run, not recalled
Demo transcripts, counterfactual experiments, and the arithmetic behind each claim are captured from real runs of the real toy before publishing. Where a commentary says "change this character and the result flips," that variant was actually executed.
Available now
Data stores
wal-kv
A key-value store that survives crashes by writing its log first. Then the discovery that the experiment you'd run to prove it works cannot fail: with fsync switched off entirely, kill -9 still returns all five records. Turning fsync on changes nothing — because the bytes were in the kernel, and the kernel isn't what died.
146 lines · stdlib only · 10 sections · 5 self-check questions
Networking
rate-limiter
Token bucket and sliding window log, tuned to the same average rate, fed one identical trace — and they disagree twice, in opposite directions. The bucket's generosity at t=2.5 turns out to be the exact cause of its stinginess at t=5.0.
52 lines · stdlib only · 10 sections · 5 self-check questions
Coming next
The backlog from BACKLOG.md, grouped as it is there. Each names the mechanism it teaches and the "aha" its demo should produce.
- Data stores lsm-tree — memtable, sorted segments, compaction; writes are always sequential appends
- Data stores btree-index — point lookups are O(log n) node reads, not a scan
- Data stores inverted-index — query time tracks postings list length, not corpus size
- Data stores mvcc-store — a long reader neither blocks nor sees a concurrent writer
- Distributed raft-toy — kill the leader, watch a new one get elected
- Distributed consistent-hashing — adding a node reshuffles ~1/N of keys, not all
- Distributed quorum-replication — W+R > N always reads the latest write; drop to N and watch a stale read slip through
- Distributed distributed-lock — a client that pauses past its lease loses the lock without knowing
- Distributed failure-detector — fixed timeouts false-positive under jitter; phi-accrual adapts
- Networking http-from-sockets — curl gets a real response with zero framework code
- Networking pubsub-broker — one slow subscriber doesn't block the others
- Concurrency mini-asyncio — two "sleeping" tasks interleave without threads
- Concurrency work-stealing-queue — an uneven workload still finishes near optimal
- Interpreters tiny-interpreter — tokens to AST to result, step by step
- Interpreters regex-engine — matching as a graph walk, not backtracking
- OS-ish toy-filesystem — deleting a file just frees blocks; contents remain
- OS-ish malloc-arena — watch fragmentation happen, then get fixed by coalescing
- Caching lru-cache — eviction order falls out of access order, not insertion order
- Caching bloom-filter — false positives at a rate you can predict; false negatives never
- Security merkle-tree — verifying one leaf needs O(log n) hashes, not the dataset
- Observability circuit-breaker — after N failures it stops calling, then probes and recovers
The full list, with the aha each demo should produce, is in BACKLOG.md. A suggested ramp rather than picking randomly: wal-kv → lsm-tree → consistent-hashing → raft-toy → tiny-interpreter → mini-asyncio.