rust-axum-service

Rust Service (axum on tokio)

Overview

Rust moves a class of bugs to compile time, and leaves two to you: panics on a request path and blocking the async runtime. Most of the rules below are about those two.

Core principle: the repository's framework, error crates, database crate and workspace layout win. Handlers stay thin; the domain is plain Rust that compiles without the web framework.

Layers

In a workspace the domain is often its own crate; a crate that does not depend on axum cannot leak it.

Patterns

• Toolchain: rust-toolchain.toml when present; edition from Cargo.toml (2024 for a new crate). Commit Cargo.lock for a binary. Add crates with cargo add, the version from crates.io, not memory.
• No panics on a request path: no unwrap(), expect(), indexing that can go out of bounds, or as casts that truncate on input-derived values. Use ? with a typed error. expect is for startup invariants with a message that says why it cannot fail.
• Errors: a domain error enum with thiserror; an application error that implements IntoResponse and maps each variant to 400/404/409 in the repository's problem shape, logging the source of a 500 and never returning it. anyhow belongs in main and scripts, not in a library or a handler's signature.
• Parse, don't validate: request DTOs #[derive(Deserialize)] (with #[serde(deny_unknown_fields)] where the contract is strict), converted into domain newtypes (TaskTitle::try_from(String)) whose constructors enforce the invariant. A malformed JSON body is already a 4xx through Json's rejection — keep that rejection in the same error shape.
• State: one AppState (Clone, cheap: Arcs and pools inside) passed with .with_state(state) and taken by State<AppState>; no global mutable statics.
• Never block the runtime: blocking I/O or CPU-heavy work goes to tokio::task::spawn_blocking; no std::thread::sleep in async code (tokio::time::sleep); never hold a std::sync::Mutex guard across .await — restructure, or use tokio::sync::Mutex when the lock must span an await.
• Timeouts and limits: tower_http layers — TimeoutLayer, RequestBodyLimitLayer, TraceLayer, CorsLayer configured, not permissive() in production. Outbound reqwest clients built once with a timeout and shared.
• Database: sqlx with bound parameters (query! / query_as! checked at compile time; keep the offline .sqlx data committed with cargo sqlx prepare when the repository uses offline mode) or the repository's diesel / sea-orm. Never format! a SQL string with input. Migrations with sqlx migrate add <name> (reversible when the repository's are) applied by sqlx::migrate!() or the deploy step; postgres-migrations covers safe DDL.
• Logging: tracing with structured fields and #[tracing::instrument(skip(state, body))] on handlers and service methods — skip anything secret or large; JSON output from tracing-subscriber where the repository logs JSON.
• Graceful shutdown: axum::serve(listener, app).with_graceful_shutdown(signal) on SIGTERM / Ctrl-C.
• unsafe: none in a feature task. If a dependency forces it, say so in a task comment; the security agent reviews every unsafe block.