kvca_proxy/AGENTS.md

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.