Starstruk Logo MarkStarstruk

axum-v0.8.0

tokio-rs/axumaxum-v0.8.0Jan 1, 2025by jplatte

AI Summary

A major version bump featuring significant changes to WebSocket types, path syntax, and request handling requirements.

Key Highlights

  • Changed `ws::Message` to use `Bytes` and `Utf8Bytes` instead of `Vec<u8>` and `String`.
  • Updated path syntax from `/:single` to `/{single}` and `/*many` to `/{*many}`.
  • Made `Sync` a requirement for all handlers and services added to `Router`.
  • Introduced `serde_path_to_error` for better Query/Form parsing error reporting.

Breaking Changes

  • Changed `ws::Message` types to `Bytes` and `Utf8Bytes`.
  • Path parameter syntax changed to `/{single}` and `/{*many}`.
  • Handlers and services now require `Sync`.
  • Removed `OptionalFromRequestParts` impl for `Query`.
  • Moved `Host` extractor to `axum-extra`.
  • Removed `WebSocket::close` method.
  • Changed `serve` to be generic over listener and IO types.
  • Removed `Serve::tcp_nodelay` and `WithGracefulShutdown::tcp_nodelay`.
  • Changed `Option<Path<T>>` behavior to reject instead of swallowing errors.

New Features

  • Added `method_not_allowed_fallback` for missing method handlers.
  • Added `NoContent` shortcut for `StatusCode::NO_CONTENT`.
  • Added support for WebSockets over HTTP/2.
  • Added `MethodFilter::CONNECT` and related routing methods.
  • Extended `FailedToDeserializePathParams` with `ErrorKind::DeserializeError`.

Full Release Notes

## since rc.1

<details>

- **breaking:** `axum::extract::ws::Message` now uses `Bytes` in place of `Vec<u8>`,
  and a new `Utf8Bytes` type in place of `String`, for its variants ([#3078])
- **breaking:** Remove `OptionalFromRequestParts` impl for `Query` ([#3088])
- **changed:** Upgraded `tokio-tungstenite` to 0.26 ([#3078])
- **changed:** Query/Form: Use `serde_path_to_error` to report fields that failed to parse ([#3081])

</details>

## full changelog

*You can also read the blog post on [tokio](https://tokio.rs/blog/2025-01-01-announcing-axum-0-8-0)*

*Note: there are further relevant changes in [axum-core's changelog](https://github.com/tokio-rs/axum/releases/tag/axum-core-v0.5.0)*

- **breaking:** Upgrade matchit to 0.8, changing the path parameter syntax from `/:single` and `/*many` to `/{single}` and `/{*many}`; the old syntax produces a panic to avoid silent change in behavior ([#2645])
- **breaking:** Require `Sync` for all handlers and services added to `Router` and `MethodRouter` ([#2473])
- **breaking:** The tuple and tuple_struct `Path` extractor deserializers now check that the number of parameters matches the tuple length exactly ([#2931])
- **breaking:** Move `Host` extractor to `axum-extra` ([#2956])
- **breaking:** Remove `WebSocket::close`. Users should explicitly send close messages themselves. ([#2974])
- **breaking:** Make `serve` generic over the listener and IO types ([#2941])
- **breaking:** Remove `Serve::tcp_nodelay` and `WithGracefulShutdown::tcp_nodelay`.
  See `serve::ListenerExt` for an API that let you set arbitrary TCP stream properties. ([#2941])
- **breaking:** `Option<Path<T>>` no longer swallows all error conditions,
  instead rejecting the request in many cases; see its documentation for details ([#2475])
- **breaking:** `axum::extract::ws::Message` now uses `Bytes` in place of `Vec<u8>`,
  and a new `Utf8Bytes` type in place of `String`, for its variants ([#3078])
- **fixed:** Skip SSE incompatible chars of `serde_json::RawValue` in `Event::json_data` ([#2992])
- **fixed:** Don't panic when array type is used for path segment ([#3039])
- **fixed:** Avoid setting `content-length` before middleware.
  This allows middleware to add bodies to requests without needing to manually set `content-length` ([#2897])
- **change:** Update minimum rust version to 1.75 ([#2943])
- **changed:** Upgraded `tokio-tungstenite` to 0.26 ([#3078])
- **changed:** Query/Form: Use `serde_path_to_error` to report fields that failed to parse ([#3081])
- **added:** Add `method_not_allowed_fallback` to set a fallback when a path matches but there is no handler for the given HTTP method ([#2903])
- **added:** Add `NoContent` as a self-described shortcut for `StatusCode::NO_CONTENT` ([#2978])
- **added:** Add support for WebSockets over HTTP/2. They can be enabled by changing `get(ws_endpoint)` handlers to `any(ws_endpoint)` ([#2894])
- **added:** Add `MethodFilter::CONNECT`, `routing::connect[_service]` and `MethodRouter::connect[_service]` ([#2961])
- **added:** Extend `FailedToDeserializePathParams::kind` enum with (`ErrorKind::DeserializeError`). This new variant captures both `key`, `value`, and `message` from named path parameters parse errors, instead of only deserialization error message in `ErrorKind::Message`. ([#2720])

[#2475]: https://github.com/tokio-rs/axum/pull/2475
[#2897]: https://github.com/tokio-rs/axum/pull/2897
[#2903]: https://github.com/tokio-rs/axum/pull/2903
[#2894]: https://github.com/tokio-rs/axum/pull/2894
[#2956]: https://github.com/tokio-rs/axum/pull/2956
[#2961]: https://github.com/tokio-rs/axum/pull/2961
[#2974]: https://github.com/tokio-rs/axum/pull/2974
[#2978]: https://github.com/tokio-rs/axum/pull/2978
[#2992]: https://github.com/tokio-rs/axum/pull/2992
[#2720]: https://github.com/tokio-rs/axum/pull/2720
[#3039]: https://github.com/tokio-rs/axum/pull/3039
[#2941]: https://github.com/tokio-rs/axum/pull/2941
[#2473]: https://github.com/tokio-rs/axum/pull/2473
[#2645]: https://github.com/tokio-rs/axum/pull/2645
[#2931]: https://github.com/tokio-rs/axum/pull/2931
[#2943]: https://github.com/tokio-rs/axum/pull/2943
[#3078]: https://github.com/tokio-rs/axum/pull/3078
[#3081]: https://github.com/tokio-rs/axum/pull/3081
[#3088]: https://github.com/tokio-rs/axum/pull/3088