Versions and Migration

Crate versions this skill targets, what changed between the releases people still run, and how to migrate. Check Cargo.lock before advising: many "it does not compile" questions are version mismatches.

#Contents

• Version matrix
• axum 0.6 -> 0.7
• axum 0.7 -> 0.8
• tower and tower-http
• tokio 1.x
• tokio-util
• Rust editions and language features
• Mismatch symptoms

#Version matrix

Mixing majors (tower-http 0.5 with axum 0.8, or two hyper majors) produces trait errors that look unrelated to versions: "the trait Service<Request<Body>> is not implemented", "expected axum::body::Body, found hyper::Body".

#axum 0.6 -> 0.7

axum 0.7 moved to hyper 1.0:

• axum::Server::bind(..).serve(app.into_make_service()) is gone: use axum::serve(tokio::net::TcpListener::bind(addr).await?, app).await?.
• Request/response bodies are axum::body::Body (no generic body type parameter on handlers and middleware).
• Middleware written against hyper::Body must be ported; tower-http 0.5 pairs with axum 0.7.
• Graceful shutdown: axum::serve(..).with_graceful_shutdown(signal).

#axum 0.7 -> 0.8

axum 0.8 (released January 2025) changes, in the order you will hit them:

Migration steps: bump axum = "0.8", tower-http = "0.6", tower = "0.5"; run the service_hygiene scanner (TK017 finds old paths); delete #[async_trait] on extractor impls; fix Option<..> extractors; run tests.

#tower and tower-http

• tower 0.5 removed some re-exports and reorganised ServiceExt; enable features = ["util"] for oneshot/ready.
• tower-http 0.6: every middleware is behind a feature. Newer 0.6 releases deprecate TimeoutLayer::new(d) in favour of TimeoutLayer::with_status_code(StatusCode::REQUEST_TIMEOUT, d).
• Layer order in ServiceBuilder is outermost first. TimeoutLayer requires a Default response body, so put RequestBodyLimitLayer before it (outside), not after.
• tower's own tower::timeout::TimeoutLayer returns an error instead of a response; with axum it needs HandleErrorLayer. Prefer tower-http's.

#tokio 1.x

• tokio 1.x is stable: minor releases add APIs without breaking. It publishes long-term-support minor versions (listed in its README); pin with tokio = "~1.NN" only if your policy needs an LTS line.
• Feature flags: full for applications; libraries should enable only what they use (rt, macros, net, time, sync, signal, fs, process, io-util). Tests that pause time need test-util.
• JoinSet (tokio::task) manages a dynamic group of tasks and aborts them on drop; JoinHandle::abort and AbortHandle cancel single tasks.
• tokio::task::spawn_blocking has its own large thread pool (default up to 512 threads); CPU-heavy work belongs on rayon or a bounded pool instead.
• tokio-console needs RUSTFLAGS="--cfg tokio_unstable" and the console-subscriber crate.

#tokio-util

• sync::CancellationToken: hierarchical cancellation (child_token, cancelled().await, cancelled_owned() for 'static futures), always available.
• task::TaskTracker (feature rt): track spawned tasks, close() then wait() for graceful shutdown; unlike JoinSet it does not abort on drop and does not keep results.
• codec (feature codec): Framed, LinesCodec, LengthDelimitedCodec, the cancel-safe way to read framed protocols inside select! loops.

#Rust editions and language features

Edition 2024 if let rescoping helps services: if let Some(v) = map.lock().unwrap().get(k) { .. } else { .. } no longer holds the guard in the else branch.

#Mismatch symptoms