Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing

The rules for everyone who changes the repository, people and AI agents alike, are in AGENTS.md. They are binding. This page is a map for newcomers and does not replace it: when the two differ, AGENTS.md wins.

For the design, read docs/design.md (German) and the decision records in docs/adr. The design document describes the current system; the ADRs keep the reasons.

Crate map

CrateWhat
lotse-rtThe only seam to the outside world: Clock, Disk, SegmentFile, Spawn, Rng, Net, Host, Http traits
lotse-rt-tokioProduction runtime: Tokio, file system, TLS 1.3 or plain TCP on loopback
lotse-recordBatch format: header, ZigZag-varint records, CRC32C, zstd and lz4 blocks, control batches
lotse-logSegmented partition log, which is also the Raft log
lotse-raftSans-I/O Raft core and Multi-Raft
lotse-queueQueue semantics free of I/O: ack index and dispatcher
lotse-authSCRAM, OAUTHBEARER, roles; free of I/O
lotse-routeExchanges and bindings: direct, topic, fanout, headers
lotse-protoNative protocol: frames, error codes, requests and responses
lotse-serverBroker node: Replica, Node, client serving, metadata, membership
lotse-nodeThe lotse binary
lotse-clientRust client
lotse-simDeterministic simulation
lotse-consoleManagement console backend; the frontend is in console/web

The full map, with the files inside lotse-server, is in AGENTS.md.

The runtime seam

Nothing above lotse-rt touches the real world directly. Code takes a Clock, Disk, Spawn, Rng or Net instead of calling Instant::now, SystemTime::now, std::thread, OS randomness or ambient Tokio APIs. Use BTreeMap and BTreeSet, never HashMap or HashSet, because iteration order would make simulations unrepeatable. clippy.toml enforces most of this. unsafe is forbidden. The reasons are in ADR 0006.

The Raft core is sans-I/O: it never does I/O. A driver persists a Ready in a fixed order: snapshot, truncate, entries (synced), hard state, apply, send (ADR 0023).

Deterministic simulation

lotse-sim runs the real code on a seeded executor with virtual time, disks that crash and lose or tear unsynced writes, and a network that drops, delays and partitions. A run is a function of its seed, so a failure is reproduced exactly.

cargo test --workspace                                                   # unit tests and short simulations
LOTSE_SIM_SEEDS=5000 cargo test -p lotse-sim -p lotse-server --release   # CI depth
LOTSE_SIM_SEED=1234 cargo test -p lotse-sim                              # exactly one seed
  • Simulations take seeds from lotse_sim::check_seeds, which panics with the seed and the command that reproduces it. Scenario tests whose value does not grow with seeds use check_few_seeds.
  • A simulation’s oracle is written in the test, never borrowed from the code it checks.
  • Simulations live in crates/lotse-sim/tests/ and in a crate’s tests/; for example crates/lotse-server/tests/clients.rs runs the Rust client against a faulty cluster.
  • A failing seed is a bug until proven otherwise. Find the cause, then decide whether the code or the check is wrong, and say which in the commit. Never weaken a check to make a test pass.
  • After you add faults or operations, check with a quick statistic that they happen (crashes per run, snapshots installed, reads served) before you trust a green run.

Pull requests do not run the simulations at depth. The release workflow runs all of them at 5,000 seeds before anything is built for a release, and a failure there blocks the release (ADR 0088). So run the simulations your change touches yourself, at CI depth where it matters, or run the release workflow by hand on your branch: run by hand, it runs the simulations only (ADR 0010).

Mutation checking

When you add or change a rule that safety depends on, break it on purpose and confirm that a test fails. If none does, add one: a simulation, or a deterministic unit test for rules that depend on timing, because random simulation rarely reaches those. Restore the rule afterwards. State which mutants you tried in your report.

Before you push

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Also run the affected simulation at CI depth. After you change a message or the batch format, run make sdk-vectors and make sdk-test; a change to a message needs the codecs of the Java, C# and Node.js SDKs updated. After you change an API type of the console, run npm run api in console/web.

Decisions: the ADR process

A changed decision gets an ADR in the same change.

  1. Copy docs/adr/template.md to the next number, for example 0082-short-title.md.
  2. Write context, decision and consequences. State what you rejected and why.
  3. Add it to the index in docs/adr/README.md.
  4. Update the design document to match. It stays German.

A superseded decision keeps its ADR, marked as superseded, so the reasons stay readable.

Conventions

  • Code, comments, docs and commit messages are in English; the design document is German.
  • Comments explain why, not what. Public items have doc comments.
  • Errors use thiserror and say what happened and, where useful, what to do.
  • Dependencies go through [workspace.dependencies].
  • Docs and UI copy follow the brand voice: calm, exact, short, units named, no hype, no exclamation marks, no emoji.
  • Commits have an imperative subject line and a body that explains why.

Working on this guide

The guides live in docs/guide/ and are built with mdBook (ADR 0081). Examples that could drift are included with {{#include}}, not pasted. Where the repository documents no procedure, the guide says so.