Project Philosophy

Principles

Explicit over clever — no magic helpers, no macros that hide control flow, no trait gymnastics. Code reads top-to-bottom. A new reader should understand what a function does without chasing through layers of indirection.
Pure functions — isolate decision logic from IO. A function that takes data and returns data is testable, composable, and easy to reason about. Keep it that way. Don't sneak in network calls or logging.
Linear flow — avoid callbacks, deep nesting, and async gymnastics where possible. A handler should read like a sequence of steps: look up the record, pick a volume, build the response.
Minimize shared state — pass values explicitly. The handler reads the healthy volume set as a snapshot, then works with that snapshot. Don't hold locks across IO. Don't reach into globals.
Minimize indirection — don't hide logic behind abstractions that exist "in case we need to swap the implementation later." We won't. A three-line function inline is better than a trait with one implementor.

Applying the principles: separate decisions from execution

Every request handler does two things: decides what should happen, then executes IO to make it happen. These should be separate functions.

A decision is a pure function. It takes data in, returns a description of what to do. It doesn't call the network, doesn't touch the database, doesn't log. It can be tested with assert_eq! and nothing else.

Execution is the messy part — HTTP calls, SQLite writes, error recovery. It reads the decision and carries it out. It's tested with integration tests.

Where this applies today

Already pure

hasher.rs — the entire module is pure. Ring is a data structure. get_volumes and key_path are deterministic functions of their inputs. No IO, no state mutation beyond construction. This is the gold standard for the project.

db.rs query functions — get, list_keys, all_records take a &Connection and return data. The connection is injected, not owned. The functions don't decide what to do with the data — they just retrieve it.

db.rs encode/parse — parse_volumes and encode_volumes are pure transformations between JSON strings and Vec<String>.

Mixed (decision + execution interleaved)

server.rs::put_key — this handler does three things in one function:

Decide which volumes to write to (pure — ring lookup)
Execute fan-out PUTs to nginx (IO)
Decide whether to rollback based on results (pure — check which succeeded)
Execute rollback DELETEs and/or index write (IO)

Steps 1 and 3 could be extracted as pure functions:

// Pure: given a key and ring, compute the placement plan
struct PutPlan {
    path: String,
    target_volumes: Vec<String>,
}

fn plan_put(ring: &Ring, key: &str, replication: usize) -> Result<PutPlan, AppError> {
    let path = Ring::key_path(key);
    let target_volumes = ring.get_volumes(key, replication);
    if target_volumes.len() < replication {
        return Err(AppError::VolumeError(...));
    }
    Ok(PutPlan { path, target_volumes })
}

// Pure: given fan-out results, decide what to do next
enum PutOutcome {
    AllSucceeded { volumes: Vec<String> },
    NeedsRollback { succeeded: Vec<String> },
}

fn evaluate_put_results(results: &[(String, Result<(), String>)]) -> PutOutcome { ... }

server.rs::get_key — the "pick a healthy volume" logic is a pure function hiding inside an async handler:

// Pure: given a record's volumes and the healthy set, pick one
fn pick_healthy_volume<'a>(
    record_volumes: &'a [String],
    healthy: &HashSet<String>,
) -> Option<&'a str> {
    record_volumes.iter().find(|v| healthy.contains(*v)).map(|v| v.as_str())
}

Intentionally impure

volume.rs — this is an IO boundary. It wraps reqwest and talks to nginx. There's no decision logic here to extract; it's a thin adapter. Testing it means mocking HTTP. That's fine.

health.rs — a side-effecting loop. It polls volumes and mutates shared state. No pure core to extract. Keep it simple.

db.rs writer thread — the batch-and-commit loop is inherently stateful. The execute_cmd function is close to pure (it takes a connection and a command, returns a result), but it mutates the database. The batching logic (drain channel, group into transaction) is a state machine. Not worth abstracting further.

Guidelines

If a function takes only data and returns only data, it's pure. Keep it that way. Don't sneak in logging, metrics, or "just one network call."
If a handler has an if or match that decides between outcomes, that decision can probably be a pure function. Extract it. Name it. Test it.
IO boundaries should be thin. volume.rs is a good example: format URL, make request, check status, return bytes. No business logic.
Don't over-abstract. A three-line pure function inline in a handler is fine. Extract it when it gets complex enough to need its own tests, or when the same decision appears in multiple places (e.g., rebuild and rebalance both need "compute desired placement").
Shared state should be read-only snapshots when possible. The handler reads healthy_volumes and ring under a read lock, then releases it before doing IO. This keeps the critical section small and makes the decision logic operate on a snapshot, not live-mutating state.
Errors are data. AppError is a value, not an exception. Functions return Result, handlers pattern-match on it. The IntoResponse impl is the only place where errors become HTTP responses — one place, one mapping.

Anti-patterns to avoid

God handler — a 100-line async fn that reads the DB, calls volumes, makes decisions, handles errors, and formats the response. Break it up.
Stringly-typed errors in business logic — volume.rs uses String errors because it's an IO boundary and the strings are for logging. Decision functions should use typed errors.
Hidden state reads — if a function needs the healthy volume set, pass it in. Don't reach into a global or lock a mutex inside a "pure" function.
Testing IO to test logic — if you need a Docker container running to test whether "pick a healthy volume" works correctly, the logic isn't separated from the IO.

6.5 KiB Raw Blame History