tokio-rs/axum
github.com/tokio-rs/axum ↗ · 500 files · 1.7 MB
axum axum is an HTTP routing and request-handling library that focuses on ergonomics and modularity.
Overview
Axum is a Rust HTTP routing and request-handling library for developers building asynchronous services with Tokio, Hyper, and Tower. Its distinctive interface connects ordinary async handlers to typed request extractors and response conversions, while reusing Tower middleware rather than introducing a separate middleware protocol. This brief examines commit f8b02f22cf10bee707bda19b58265b9e33677535, including the four library crates, every listed binary entrypoint, selected internals, tests, and CI; the inspection is bounded, and no repository code or tests were executed.
System map
The repository is a library ecosystem with application examples, rather than one deployable service. The root workspace divides foundational contracts, HTTP execution, optional utilities, and procedural macros across four crates. Example binaries assemble their own listeners, application state, middleware, and external integrations in a separate workspace. Build and release behavior is described by Cargo manifests and GitHub Actions.
- The root workspace includes axum and axum-* members, uses resolver 2, declares Rust 1.80, and forbids unsafe code through workspace lints.
- axum-core exposes body, extract, response, RequestExt, and RequestPartsExt; its crate documentation recommends it for libraries implementing FromRequest or IntoResponse.
- axum explicitly targets Tokio and Hyper; runtime and transport independence are not stated goals, while Tower Service supplies its middleware integration.
- Router stores an Arc<RouterInner<S>> containing a PathRouter and catch-all fallback; PathRouter stores endpoints in a vector indexed by RouteId and matches paths through matchit.
- axum-extra gates utilities behind Cargo features, while axum-macros is a proc-macro crate built with syn, quote, and proc-macro2.
- examples/Cargo.toml defines a separate workspace; example binaries bind listeners and pass application routers to axum::serve, with database and session ownership established inside those binaries.
- CI specifies locked workspace tests and all-target, all-feature Clippy checks for both workspaces, plus formatting, documentation, feature, MSRV, ARM, and selected WASM checks.
- Release-plz runs on main and v0.8.x for the tokio-rs owner; configuration disables release-on-every-commit behavior and automatic changelog updates, while README warns that main contains forthcoming 0.9 breaking changes.
Feature catalog
The principal user-facing surface is Rust APIs for routing, typed request extraction, middleware composition, and response generation. Feature flags add protocol and serialization capabilities without making every dependency mandatory. Optional crates extend the surface with cookies, typed routes, streaming formats, and compile-time diagnostics. The inspected examples demonstrate authentication, database access, forms, validation, static assets, TLS, and live connections.
- Router supports handler routes and arbitrary infallible services; repeated registration of different methods at an existing path merges MethodRouter endpoints.
- MethodRouter dispatches GET, POST, OPTIONS, PATCH, PUT, DELETE, TRACE, CONNECT, QUERY, and HEAD; HEAD falls back to GET, and unmatched methods use a fallback with configurable Allow-header handling.
- Typed inputs include Path, Query, Json, Form, State, and Multipart; Query deserializes URI parameters, Json requires an application/json-compatible content type, and Multipart parses a boundary before exposing fields.
- Handlers return IntoResponse values, including Result branches and Json; Json serialization sets application/json on success and returns a 500 text response if serialization fails.
- Middleware can wrap routers, method routers, or individual handlers; the documented Tower ecosystem supplies tracing, CORS, compression, request IDs, and timeouts, and from_fn exposes Next::run for async middleware.
- WebSocketUpgrade supports HTTP/1 upgrade and HTTP/2 CONNECT handshakes; Sse converts event streams to text/event-stream responses and can add keep-alive events.
- axum-extra offers private and signed cookies, typed headers and routing, file streams, attachments, Protobuf, JSON Lines, cached extraction, and rejection adapters; macros add TypedPath, FromRef, and debug_handler support.
- Examples expose JWT authorization, Discord OAuth login, PostgreSQL queries and user persistence, validated forms, static-file service variants, and Rustls TLS connections.
Data flow
Incoming connections are converted into per-connection services, and incoming HTTP bodies are normalized before routing. Path matching enriches request extensions, method dispatch selects an endpoint, and handler adapters construct typed arguments in sequence. Response conversion provides the common output boundary for successful values and rejections. Durable data, session storage, and file writes are owned by example applications rather than the routing library.
- handle_connection waits for make_service readiness, calls it with IncomingStream, maps Hyper Incoming bodies into axum Body, and wraps the resulting Tower service with TowerToHyperService.
- PathRouter preserves OriginalUri when enabled, matches uri.path(), installs MatchedPath and URL parameters, then dispatches the indexed endpoint; a missing path returns the request and state to Router's fallback.
- Handler::call splits the request, extracts all preceding arguments from mutable Parts, reconstructs the request for the last extractor, and returns immediately on any rejection before invoking the handler.
- Json extraction validates content type, delegates buffering to Bytes::from_request, deserializes with serde_path_to_error, and calls deserializer.end() to reject trailing data.
- State<InnerState> derives application substates through FromRef<OuterState>; Router::with_state distributes supplied state to its path router and catch-all fallback.
- The key-value example transforms a path capture and body bytes into a HashMap insertion under a write lock; reads clone stored Bytes under a read lock and return 404 when absent.
- Diesel create_user deserializes NewUser, acquires a pooled connection, inserts values inside interact, retrieves the returned User, and serializes it as Json; the migration defines the corresponding users table.
- PrivateCookieJar obtains a key from state, retains only successfully decrypted request cookies, and writes jar changes into response headers through IntoResponseParts.
Behavior traces
The inspected flows span library execution and concrete example applications. Server startup proceeds from application construction to listener acceptance and Hyper connection execution. Request processing includes conditional rejection before business logic, while authentication and persistence examples introduce additional state and network boundaries. These traces describe source execution order; none were exercised at runtime.
- Startup: the key-value main initializes tracing, creates SharedState, composes routes and middleware, supplies state, binds 127.0.0.1:3000, and awaits axum::serve; Serve::run then repeatedly accepts and calls handle_connection.
- Request dispatch: Router::call_with_state calls PathRouter::call_with_state, which matches the path and calls MethodRouter::call_with_state; the selected endpoint becomes a Route, and Handler::call extracts arguments before calling the async function.
- Key-value write/read: POST /{key} selects kv_set with DefaultBodyLimit disabled and a 5,120,000-byte RequestBodyLimitLayer; kv_set inserts bytes, and subsequent GET /{key} uses kv_get's compressed response or 404 branch.
- JWT flow: POST /authorize extracts AuthPayload, rejects empty or incorrect demonstration credentials, creates Claims, encodes a token, and returns AuthBody; GET /protected extracts a Bearer header and decodes Claims with Validation::default before protected runs.
- OAuth initiation: discord_auth creates an identify-scoped authorization URL and random CSRF token, stores the token in MemoryStore, sets a Secure/HttpOnly/SameSite=Lax session cookie, and redirects to Discord.
- OAuth callback: login_authorized calls csrf_token_validation_workflow, which loads and destroys the old session before comparing state; it then exchanges the code, fetches Discord user JSON, stores a new user session, sets its cookie, and redirects home.
- Persistence startup/action: Diesel main builds a pool and runs embedded pending migrations before binding; POST /user/create invokes create_user's insert-and-return path, while GET /user/list loads Users through another interact closure.
- Graceful shutdown: the signal task drops signal_tx, the accept loop exits on channel closure, connection tasks call Hyper graceful_shutdown, and the server waits for close_tx.closed(); a connection age limit can separately initiate shutdown and enforce a grace deadline.
Testing signals
Tests and CI were inspected, not executed; test existence is not evidence of a passing result. The inspected suite combines Tokio runtime tests, direct Tower service calls, real HTTP/WebSocket clients, and nightly compile-time fixtures. Assertions cover several important protocol and rejection behaviors, while individual example tests have narrower scopes. This is a bounded assessment without measured coverage or live integration verification.
- CI declares stable/beta locked all-feature, all-target tests for both workspaces, a separate nightly macro job, and Rust 1.80 tests after minimal-version dependency selection; these configurations were read, not run.
- The internal #[crate::test] helper expands to #[tokio::test] and generates an additional nest_service variant when a test contains matching nest calls; TestClient launches an ephemeral localhost server and uses reqwest with redirects disabled.
- Routing tests assert inherited versus overridden nested fallbacks; HEAD tests use Router::oneshot directly and assert preserved headers with an empty response body for handlers and services.
- Json tests assert successful deserialization, 415 without JSON content type, accepted +json media types, 400 for syntax/trailing-data errors, and 422 with a field path for invalid typed data.
- Server tests use paused Tokio time and duplex IO to assert stalled-header closure; graceful_shutdown_completes_inflight_request holds a handler open, signals shutdown, then checks that its response completes before the server resolves.
- Macro UI tests use trybuild pass/fail fixtures only on nightly, become a no-op on other toolchains, and accept AXUM_TEST_ONLY; inspected failures exercise wrong extractor order and a non-Send future.
- The WebSocket example tests one text echo through a real tokio-tungstenite connection and through mocked Sink/Stream channels; the SSE example integration test takes one event and asserts its data is hi!.
- Form tests check GET markup and one POST response; validator tests check missing, empty, short, and valid names; the inspected static-file test checks one root-path fallback returning index HTML with 404, rather than every service variant.
Risk map
These findings are source observations and explicitly identified hypotheses, not confirmed vulnerabilities. The main boundaries worth reviewing are request resource limits, example authentication, network integrations, HTML generation, database startup, and upload IO. Framework safeguards have conditions: extractor-local limits do not cover every body consumer, and middleware placement affects which requests receive protection. Example code should be assessed in its deployment context before reuse.
- DefaultBodyLimit bounds cooperating extractors to 2,097,152 bytes by default, but direct body consumption bypasses it; the upload example's Request-based path streams the body without applying that extractor-local limit.
- JWT authorization is demonstration logic with fixed accepted credentials and a fixed expiry; KEYS reads JWT_SECRET lazily with expect, so missing configuration panics when key use first initializes it.
- OAuth explicitly warns against its MemoryStore in production; User extraction panics for unexpected cookie-header errors and unwraps session loading, creating request-path failure points despite normal missing-session redirects.
- The form and validator handlers interpolate user-provided strings directly into Html responses without an escaping transform in those handlers; validation in the latter checks name length.
- Upload IO validates a single normal path component, then joins it beneath a working-directory-relative uploads directory and uses File::create; multipart iteration exits on next_field errors and still returns its normal redirect.
- Database examples require external services: Diesel runs migrations before listening, tokio-postgres uses NoTls, and SQLx/Diesel internal_error expose error strings in 500 responses.
- Middleware placement is a coupling hotspot: Router::layer wraps previously added routes and repeated layers run outermost-last, whereas ServiceBuilder composes a different ordering; the error example depends on TraceLayer enclosing log_app_errors.
- Dependency policy excludes unpublished packages, disables unmaintained-advisory reporting, and permits selected duplicate trees; CI marks the advisories matrix entry continue-on-error, so that job alone does not make advisories a blocking gate.
Extension points
Extensions are expressed through Rust traits, router builders, Cargo features, and generated implementations. Applications can add typed request inputs and outputs without changing the router internals. Tower services and layers supply middleware composition, while Listener and Executor customize serving within the Tokio/Hyper architecture. axum-extra and axum-macros provide additional integration points for typed routes, cookies, and generated extraction.
- Implement FromRequestParts<S> for metadata-only inputs or FromRequest<S> for body-consuming inputs; both define an IntoResponse rejection and receive application state.
- Implement IntoResponse for domain outputs and errors; its Result implementation converts either branch, allowing application errors to remain HTTP responses rather than Tower service failures.
- Router::route_service accepts cloneable infallible Tower services with IntoResponse outputs, while PathRouter merges method registrations at the same path.
- Tower Layer can wrap individual handlers through Handler::layer; from_fn middleware receives a Next continuation that executes the remaining service stack.
- FromRef connects aggregate application state to substates; the OAuth example independently extracts MemoryStore and BasicClient from AppState, and axum-macros exposes a FromRef derive.
- TypedPath links a handler's first argument to a route, derives capture-compatible extraction and percent-encoded Display output, and supports custom rejections; vpath! separately validates static path syntax at compile time.
- Custom Listener implementations choose IO/address types and own accept-error retry behavior; ListenerExt adds connection limits, while Serve::with_executor substitutes an Executor returning Tokio JoinHandles.
- FromRequest derives accept container-level via, rejection, and state attributes; expansion chooses explicit state or infers it from fields and delegation, providing a generated-wrapper extension path.
Contributor handoff
Start future work from the pinned source and the owning crate rather than assuming released behavior matches main. Keep changes aligned with crate boundaries, feature gates, and the distinction between library contracts and runnable examples. Tests and CI were inspected, not executed; future execution needs its own authorization and reported results. This brief is bounded and does not establish whole-repository coverage, live integration health, or confirmed vulnerabilities.
- Read README's branch warning before using released API assumptions: main targets 0.9 breaking changes even though the inspected axum manifest declares version 0.8.9.
- Choose the owning boundary first: reusable extractor/response contracts belong in axum-core where possible; optional utility exposure must follow axum-extra's feature gates rather than unconditional dependencies.
- For dispatch edits, read Router, PathRouter, MethodRouter, and Handler together; preserve path metadata installation, HEAD-to-GET selection, rejection short-circuiting, and state delivery.
- Body-limit edits require coordinated documentation and implementation review: RequestExt explicitly points to default_body_limit.rs and extract.md when changing DEFAULT_LIMIT, and direct consumers need separate scrutiny.
- Keep example checks in their workspace: CI uses --manifest-path examples/Cargo.toml separately from the root, and example binaries may connect to databases or run startup migrations.
- Tests and CI were inspected, not executed in this investigation; for authorized future validation, use a filtered affected-package test first and follow CI's locked workspace tests, formatting, and all-feature Clippy commands as scope requires.
- Macro diagnostic work needs nightly trybuild coverage, optionally narrowed with AXUM_TEST_ONLY; stable/beta runs skip that harness, and debug_handler itself emits checks only with debug_assertions enabled.
- Preserve compatibility conventions: workspace lints forbid unsafe code, Clippy disallows BoxCloneService in favor of BoxCloneSyncService, and axum-extra deliberately retains its older serde_html_form behavior for deprecated Query/Form migration support.
Languages
| Language | Files | Share of source |
|---|---|---|
| Rust | 301 | 80% |
| TOML | 64 | 17% |
| Markdown | 39 | docs/config |
| HTML | 8 | docs/config |
| JavaScript | 5 | 1% |
| YAML | 5 | docs/config |
| SQL | 4 | 1% |
| JSON | 2 | docs/config |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
axum/ (85 files)
Source layout — axum/
| Path | Files |
|---|---|
axum/benches/ | 1 |
axum/src/ | 79 |
axum/tests/ | 1 |
axum/CHANGELOG.md | 1 |
axum/Cargo.toml | 1 |
axum/LICENSE | 1 |
axum/README.md | 1 |
Repository structure
| Top-level path | Files |
|---|---|
axum-macros/ | 184 |
examples/ | 153 |
axum/ | 85 |
axum-extra/ | 37 |
axum-core/ | 23 |
.github/ | 8 |
contrib/ | 1 |
Docs found: CONTRIBUTING.mdREADME.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeexamples/jwt/src/main.rs— Rust binary entrypointexamples/testing-websockets/src/main.rs— Rust binary entrypointexamples/key-value-store/src/main.rs— Rust binary entrypointexamples/error-handling/src/main.rs— Rust binary entrypointexamples/static-file-server/src/main.rs— Rust binary entrypointexamples/form/src/main.rs— Rust binary entrypointexamples/serve-with-hyper/src/main.rs— Rust binary entrypointexamples/sse/src/main.rs— Rust binary entrypointexamples/tokio-postgres/src/main.rs— Rust binary entrypoint
Structural health signals
Average score 6.7/10 across 96 analyzed source files; 27 hotspots surfaced.
axum/src/serve/mod.rs— 2009 lines, score 4 (Large file, Deep nesting)axum-macros/src/from_request/mod.rs— 1075 lines, score 4 (Large file, Deep nesting)axum/src/routing/method_routing.rs— 1770 lines, score 5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
f8b02f22cf102026-09-30 — axum: Don't wrap merged service routes in another Route (#3909)83366c2b27552026-09-29 — chore(deps): bump crate-ci/typos from 1.50.2 to 1.50.3 (#3908)d775cb202bea2026-09-28 — examples: Remove unused axum-extra dependency (#3906)09e767e6667b2026-09-28 — axum-extra: Avoid duplicate typed header error output (#3903)bc8d491243522026-09-25 — feat: add InnerPath extractor (#3856)