rust-web-backend

Rust Web Backend

Agent Workflow (MANDATORY)

Before building the service, spawn in parallel:

1. fuse-ai-pilot:explore-codebase — detect the existing router, state, and DB layer
2. fuse-ai-pilot:research-expert — verify current axum/sqlx APIs via Context7/Exa (axum 0.8 changed several APIs)
3. mcp__context7__query-docs — pull exact extractor/handler signatures

After building, run fuse-ai-pilot:sniper.

---

The 2026 standard stack

Layer	Crate	Why
Runtime	tokio	De-facto async runtime; everything targets it
HTTP framework	axum 0.8.x	Tower-based, extractor ergonomics, minimal magic
Middleware	tower / tower-http	Composable layers (trace, cors, timeout, compression)
Database	sqlx 0.9	Async, query! compile-time-checked SQL, no DSL; Postgres/MySQL/SQLite
Observability	tracing + tracing-subscriber	Structured, async-aware spans and logs

Honest alternatives: sea-orm (ActiveRecord-style ORM, higher-level than sqlx), diesel 2.x (mature, synchronous — needs spawn_blocking or a sync pool in async apps). Prefer sqlx for the standard stack; reach for these only when their model fits.

---

Critical Rules

1. axum 0.8 path syntax is /{id}, not /:id — /*rest became /{*rest}. The old matchit syntax will not compile.
2. Errors implement IntoResponse — never .unwrap() in a handler. Map domain errors to a status + body via one app error type.
3. Share state with State<T>, wrapped once — put the pool/config in an Arc-friendly struct; extract it with State, do not use globals.
4. sqlx::query! needs DATABASE_URL at compile time — or a committed .sqlx/ offline cache (cargo sqlx prepare). Plan this before CI.
5. No #[async_trait] on axum extractors — 0.8 uses RPITIT; custom FromRequestParts impls must drop the macro.

---

Reference Guide

Concepts

Topic	Reference	When to Consult
Architecture	architecture.md	Router, extractors, State, tower middleware layout
Error handling	error-handling.md	App error type + IntoResponse
Database	database.md	sqlx pool, query!, migrations, alternatives
Observability	observability.md	tracing spans, subscriber, request logging

Templates

Template	When to Use
rest-service.md	Complete minimal REST service (router + state + handlers + errors + tracing)

---

Quick Reference

Router with the 0.8 path syntax

let app = Router::new()
    .route("/users", get(list).post(create))
    .route("/users/{id}", get(show))   // NOT /:id
    .with_state(state);

→ See architecture.md

Compile-time-checked query

let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
    .fetch_optional(&pool)
    .await?;

→ See database.md

---

Best Practices

DO

• Keep one app error type that implements IntoResponse.
• Layer cross-cutting concerns (trace, timeout, cors) via tower-http.
• Verify queries at compile time with query!/query_as!.

DON'T

• Use /:id route syntax (0.7 and earlier only).
• .unwrap() in handlers — return a typed error.
• Reach for diesel in async code without accounting for its sync nature.

---

Sources (verified)

• tokio.rs/blog/2025-01-01-announcing-axum-0-8-0 — path syntax, Option extractor, #[async_trait] removal (fetched 2026-07-05)
• crates.io — axum 0.8.9, sqlx 0.9.0, tokio 1.52.3, tracing 0.1.44 (current at fetch)