Rust Web Services

Rust Web Services

Build Rust HTTP services with explicit state, typed boundaries, observable behavior, and production-grade runtime contracts.

Operating Model

1. Read the existing service shape first: router setup, app state, middleware layers, config, database access, tests, deployment scripts, and observability. 2. Prefer axum plus tower layers for new HTTP services unless the repo already standardizes on another framework. 3. Keep handlers thin. Extract inputs, call domain/service code, map results into HTTP responses. 4. Make app state explicit and clone-cheap. Avoid hidden globals and ad hoc connection creation per request. 5. Treat errors, tracing, timeouts, request size limits, and shutdown as part of the feature, not afterthoughts.

Reference Map

• references/axum-tower-architecture.md for router structure, state, extractors, middleware, errors, and versioned APIs.
• references/runtime-config-data.md for Tokio runtime concerns, config, database access, background jobs, and graceful shutdown.
• references/testing-observability.md for integration tests, tracing, metrics, contract tests, and production readiness.

Defaults

• Use tokio with only required features unless the repo uses full feature sets consistently.
• Use serde DTOs at HTTP boundaries and domain types internally.
• Use thiserror for domain errors and typed response mapping at the HTTP edge.
• Use tracing/tracing-subscriber with structured spans and request IDs.
• Use sqlx for database-backed services when compile-time query checking and async pooling are useful.

Verification

For service changes:

cargo fmt --all --check
cargo test --all-targets
cargo clippy --all-targets --all-features -- -D warnings

Add integration tests for new routes, error status mapping, auth/authorization branches, config parsing, database behavior, and graceful shutdown or background work when touched.

Axum and Tower Architecture

Router Shape

Keep router construction boring and discoverable:

• one root Router
• scoped route modules for feature areas
• explicit app state type
• middleware/layers applied at the narrowest sensible scope
• versioning when API compatibility matters

Avoid route handlers that create clients, parse global config, or own long-running background work.

Handlers

Handlers should:

1. Extract typed path/query/body/state. 2. Validate boundary DTOs. 3. Call domain/service code. 4. Map domain results to response DTOs. 5. Map errors to status codes in one consistent layer.

Do not put database query strings, retry loops, or authorization policy scattered across many handlers.

State

Use an app state struct with clone-cheap members:

• database pools
• HTTP clients
• config snapshots
• service structs
• telemetry handles

Use Arc where sharing is needed. Avoid Mutex around state that should be modeled as a database transaction, channel, cache, or service.

Middleware and Layers

Use tower layers for cross-cutting concerns:

• request IDs
• tracing
• timeouts
• compression
• body limits
• auth context extraction
• CORS when needed

Keep authorization decisions close to domain requirements. Middleware can authenticate and attach identity, but route/domain code should still enforce resource-specific authorization.

Errors

Define typed domain errors and map them to HTTP responses at the boundary. Include stable error codes when clients branch on failures. Avoid leaking internal database or upstream error text to clients.

Runtime, Config, and Data

Tokio

• Spawn tasks deliberately and keep cancellation paths.
• Use JoinSet or tracked task handles for groups of background workers.
• Apply timeouts to external calls.
• Avoid blocking CPU or filesystem-heavy work on async worker threads; use spawn_blocking or a dedicated worker model when necessary.

Configuration

Parse config once at startup into typed structs. Keep required settings explicit and fail fast. Redact secrets when logging effective config.

Use environment variables for deploy-time settings and config files only when the deployment model needs them. Do not let handlers read env vars per request.

Database

For sqlx:

• Own one pool in app state.
• Use transactions for multi-step mutations.
• Prefer compile-time checked queries where repo workflow supports the required database metadata.
• Keep migrations reviewed and tested.

For background jobs:

• Make jobs idempotent.
• Use leases or unique constraints for duplicate prevention.
• Add retry/backoff policy instead of unbounded loops.

Graceful Shutdown

Shutdown should:

• stop accepting new work
• signal background tasks
• wait with a timeout
• flush traces/logs when practical
• close resources cleanly

Test shutdown-adjacent code when adding long-running tasks or worker pools.

Testing and Observability

Integration Tests

Use in-process service tests where possible:

• construct router with test state
• send HTTP requests through tower::ServiceExt
• assert status, headers, and response body
• use temporary databases or test containers only when the repo already supports them

Test:

• happy paths
• validation failures
• authorization failures
• not found/conflict semantics
• database transaction behavior
• timeout/upstream failure mapping

Observability

Use structured tracing:

• request ID
• route/method/status
• authenticated principal or tenant when safe
• latency
• upstream call names
• error kind

Do not log secrets, bearer tokens, raw cookies, sensitive headers, or large request bodies by default.

Readiness

Production services should have:

• health/readiness endpoints if deployed behind orchestration
• request body limits
• timeouts
• CORS policy when browser-facing
• metrics or traces wired to the deployment platform
• clear config failure messages

Keep readiness checks cheap and avoid using them to run expensive database migrations.