45 lines
2.9 KiB
Markdown
45 lines
2.9 KiB
Markdown
# 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.
|