Skip to content
JustAPI

Coding Standards

Rust-First Mandate

Section titled “Rust-First Mandate”

If a feature can be implemented in Rust, it must be implemented in Rust. Python is reserved for:

  • Thin PyO3 re-exports (from ._justapi import X)
  • Translating Rust values to Python callables
  • User-facing helpers with no Rust equivalent

The following must live in Rust:

  • Networking, sockets, TLS, connection management
  • HTTP/protocol parsing and response writing
  • Routing, middleware, rate-limiting, auth
  • Scheduling, worker/thread pools
  • (De)serialization of framework data
  • Hot paths: parsing, validation, buffering, compression

Commit Messages

Section titled “Commit Messages”
<phase>: <what changed>

Examples:

  • p3: add per-request arena allocator
  • p42: implement paged KV cache

One logical change per commit.

Branch Naming

Section titled “Branch Naming”
phase-N/<short-description>

Examples:

  • phase-42/paged-kv-cache
  • phase-51/scheduler-engine

unsafe Code

Section titled “unsafe Code”

Every unsafe block must have a // SAFETY: comment explaining the invariant:

// SAFETY: The GIL is held, so the pointer is valid.
let ptr = obj.as_ptr();

Whenever feasible, add a test that would fail if the invariant were violated.

Error Handling

Section titled “Error Handling”
Code Location Error Type
Application code (CLI, bench) anyhow::Result
Library crates (core, py) Typed thiserror

Public API Changes

Section titled “Public API Changes”

All new public APIs require documentation (rustdoc or Python docstrings) before merge.

Pre-Submission Checklist

Section titled “Pre-Submission Checklist”
  • cargo test --workspace passes
  • cargo clippy --workspace --tests -- -D warnings clean
  • cargo fmt --check clean
  • cargo deny check clean (advisories, bans, licenses, sources)
  • cargo miri test -p justapi-core clean (if core touched)
  • Benchmarks appended to BENCHMARKS.md (no p99 regression >5%)
  • PLAN.md updated

See Also

Section titled “See Also”