nordisk/gunnar

The law: services behind traits, no new globals

The owner set this law on 2026-11-07, for Gunnar and Holger alike. It holds for every change from that day on. Holger has the same law in its docs/v2/14-code-shape.md.

1. No new process-wide state. Nobody adds a static that holds state, a OnceLock, OnceCell, LazyLock, lazy_static! or thread_local! that holds state, or a static mut, unless it is on the allow list xtask/globals-allow.txt. A const is fine, and so is an immutable static table with no interior mutability.
2. Every outside service is reached through a trait. When a module depends on a service from outside it (a store, the clock, a network fetch, the job queue, a scanner, a mailer, a cloud API, an identity), it reaches that service through a trait. Production passes the real implementation, and a test passes a fake. New code follows this at once. Old code moves when a change touches it.
3. Each test level uses what it is meant to use. The levels, smallest first:

UI tests stay where they are, in the UI repository.

The goal is the server object. Today 73 process-wide globals in Gunnar's server crates are wired in by hand, so a test that needs the server has to start a whole server. The goal is a Gunnar that a test can build in memory, with every outside service faked, and drive through its real API. Every global that moves behind a trait brings it closer. The server object is not built yet.

The guard

cargo xtask globals-law checks the law. It is a step of the quick CI set (cargo xtask ci --quick) and of the full set, and the xtask test no_new_process_wide_globals_in_the_server_crates runs the same check (cargo test -p xtask --lib globals_law). It builds nothing and takes about a second.

It lexes every .rs file git tracks in the server crates: the server binary gunnar, gunnar-server and the crates it links (common, core, store, wire, crypt, policy, lfs, heimdall, ssh, http, proto, grpc, repair, pairing-door), and gunnar-front. It leaves out tests/, benches/, examples/ and code under #[cfg(test)]. It counts a static mut, every static inside thread_local! or lazy_static!, a static whose type names an interior-mutable type (Mutex, RwLock, Cell, OnceLock, LazyLock, an Atomic* and the like), and a static of a named type that is built by a call or a struct literal. It then compares what it found with xtask/globals-allow.txt:

• A global that is not on the list fails the check. The message names its file:line and this chapter.
• A row whose global is gone fails too. The row must be removed.
• The list may not hold more rows than the ceiling in xtask/globals_law.rs, and when a row goes, the ceiling goes down with it. So the list only shrinks.

With F the keys found (<file>::<NAME>, #2 for a second one of a name in one file), A the keys on the list and c the ceiling, the check is two set differences and a count:

 git ls-files (scope) ─► lexer ─► F
 xtask/globals-allow.txt ───────► A (kind, reason)      ceiling c (xtask/globals_law.rs)
 new  = F \ A     gone = A \ F     pass ⇔ new = ∅ ∧ gone = ∅ ∧ |A| = c

For example, a lane adds static CACHE: Mutex<Vec<u8>> at crates/gunnar-server/src/x.rs:12. Then new = {crates/gunnar-server/src/x.rs::CACHE}, and the check fails with:

crates/gunnar-server/src/x.rs:12: a new process-wide global `CACHE` (static (interior-mutable)) breaks the law in docs/v2/code-shape.md. Pass the service in through a trait instead; a const or an immutable table is fine.

The fix is a field on the value that owns it, reached through a trait. Later a lane moves the twin's FOLLOWING flag into the follower value. Then gone = {crates/gunnar-server/src/twin.rs::FOLLOWING}, and the lane removes that row and lowers the ceiling from 73 to 72.

Each row has a kind and a one-line reason:

That is 73 rows in all. No global was moved when the law came in. Moving them is later work, one global at a time, each behind a trait and each with a test that uses a fake.