Fri, 24 Jul 2026 16:13:44 +0800

2026-07-24 16:13:44 +08:00
commit 7381b59874
29 changed files with 3832 additions and 0 deletions
@@ -0,0 +1,44 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This Rust 2024 project is a KV-cache-aware proxy for OpenAI-compatible chat-completion backends.
+
+- `src/main.rs`: Axum server setup and background cache vacuum worker.
+- `src/config.rs`: validation and loading for `config.toml`.
+- `src/cbr.rs` and `src/merkle.rs`: canonical prompt identity and Merkle block chain.
+- `src/blockmap.rs`: block-to-backend replica locations, expiry deadlines, and vacuum heap.
+- `src/router.rs`: cache-aware selection and atomic load reservations.
+- `src/proxy.rs`: header-preserving streaming upstream proxy.
+- `docs/adr/`: accepted architectural decisions; update these when changing durable design choices.
+- `CONTEXT.md`: domain glossary; keep it free of implementation details.
+
+Tests are co-located with implementation code in `#[cfg(test)] mod tests` blocks. Build artifacts belong under `target/`.
+
+## Build, Test, and Development Commands
+
+- `cargo build`: compile a debug binary.
+- `cargo build --release`: build the optimized production binary.
+- `cargo test`: run all unit and async tests.
+- `cargo test router`: run tests whose names contain `router`.
+- `cargo fmt --check`: verify Rust formatting; use `cargo fmt` to apply it.
+- `cargo clippy --all-targets -- -D warnings`: enforce warning-free idiomatic Rust.
+- `./target/release/kvca_proxy --config <PATH>`: run with a selected TOML file; omitting the option uses `config.toml`.
+
+## Coding Style & Naming Conventions
+
+Use four-space indentation and standard Rust naming: `snake_case` for functions and variables, `CamelCase` for types, and `SCREAMING_SNAKE_CASE` for constants. Group imports as `std`, external crates, then `crate::`, separated by blank lines. Prefer recoverable `Result` errors; reserve `expect` or `unwrap` for startup invariants and tests. Avoid unused public APIs and unrelated refactors.
+
+## Testing Guidelines
+
+Name tests `test_<scenario>`. Use `#[tokio::test]` for asynchronous routing, expiry, and proxy behavior. Non-trivial public behavior should have a happy-path test and an edge-case or failure-path test. Keep tests isolated and use short deterministic timeouts where lifecycle behavior is involved.
+
+Before handing off changes, run formatting, the full test suite, strict Clippy, and a release build.
+
+## Security & Configuration
+
+Never commit credentials to `config.toml`. Request authorization and backend-specific end-to-end headers are forwarded upstream. Preserve hop-by-hop header filtering and avoid total timeouts that can truncate response streams.
+
+## Commit & Pull Request Guidelines
+
+No established Git history is available. Use imperative, capitalized commit subjects of about 50 characters; wrap bodies at 72 columns. PRs should explain the change, motivation, validation performed, and relevant trade-offs. Link issues and ADRs when applicable; screenshots are unnecessary unless user-visible output changes.