Coding Standards

These rules apply to every line of code in Meridian. They are enforced by CI checks, pre-commit hooks, and code review.

Correctness

• No .unwrap() or .expect() in library code (meridian-core). Binary main() may use .expect() for one-time setup only.
• All public functions in core return Result<T, E>.
• Every error variant must be tested.
• All public types derive Debug. Data types also derive Clone, PartialEq where sensible.

Ownership & Allocation

• Borrow over clone. If you’re cloning, justify it.
• Zero allocations in hot-path packet parsing. The codec uses &[u8] slices.
• Arc for shared ownership across tasks. & references within a single task.

Concurrency

• Ordering::Relaxed for counters. SeqCst only with written justification.
• Circuit breaker uses RAII guards (CbGuard) — acquire on entry, drop on exit.
• Per-IP connection limiter uses RAII guards (ConnectionGuard).
• Arc<ConfigStore> with arc-swap for lock-free config reads.

Error Handling

• One error enum per module in core (e.g., CodecError, FilterError).
• Proxy crate uses anyhow::Result for application-level errors.
• Error responses to clients are generic — no internal topology leakage.
• Internal details go to structured logs only.

Security

• All network data is untrusted input. Codec validates headers, rejects smuggling.
• Path normalization before routing (collapse //, resolve ..).
• 60-second header-read timeout (Slowloris defense).
• 256 max connections per source IP (configurable).
• No unsafe without a // SAFETY: comment.

Formatting & Quality

# These must all pass before commit
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --workspace

• cargo fmt is law. No exceptions.
• cargo clippy -- -D warnings must pass. No #[allow] without a comment explaining why.
• Comments explain why, not what. No // increment counter above counter += 1.
• Module-level doc comments (///) on all public items.