FromRequestParts 与 FromRequest

#[diagnostic::on_unimplemented(
    note = "Function argument is not a valid axum extractor. \nSee `https://docs.rs/axum/0.8/axum/extract/index.html` for details"
)]
pub trait FromRequestParts<S>: Sized {
    type Rejection: IntoResponse;

    fn from_request_parts(
        parts: &mut Parts,
        state: &S,
    ) -> impl Future<Output = Result<Self, Self::Rejection>> + Send;
}

#[diagnostic::on_unimplemented(
    note = "Function argument is not a valid axum extractor. \nSee `https://docs.rs/axum/0.8/axum/extract/index.html` for details"
)]
pub trait FromRequest<S, M = private::ViaRequest>: Sized {
    type Rejection: IntoResponse;

    fn from_request(
        req: Request,
        state: &S,
    ) -> impl Future<Output = Result<Self, Self::Rejection>> + Send;
}

The request body is an asynchronous stream that can only be consumed once.
Therefore you can only have one extractor that consumes the request body. axum
enforces this by requiring such extractors to be the _last_ argument your
handler takes.

axum = { version = "=0.8.9", default-features = false }

use axum::{Router, http::Method, routing::post};

async fn handler(body: String, method: Method) -> String {
  format!("{method} {body}")
}

fn main() {
  let _app: Router = Router::new().route("/", post(handler));
}

error[E0277]: the trait bound `fn(String, Method) -> impl Future<Output = String> {handler}: Handler<_, _>` is not satisfied
   --> src/bin/body_first.rs:8:52
    |
  8 |   let _app: Router = Router::new().route("/", post(handler));
    |                                               ---- ^^^^^^^ the trait `Handler<_, _>` is not implemented for fn item `fn(String, Method) -> impl Future<Output = String> {handler}`
    |                                               |
    |                                               required by a bound introduced by this call
    |
    = note: Consider using `#[axum::debug_handler]` to improve the error message
note: required by a bound in `post`
   --> axum-0.8.9/src/routing/method_routing.rs:167:16
    |
167 |             H: Handler<T, S>,
    |                ^^^^^^^^^^^^^ required by this bound in `post`
...
445 | top_level_handler_fn!(post, POST);
    | ---------------------------------
    | |                     |
    | |                     required by a bound in this function
    | in this macro invocation
    = note: this error originates in the macro `top_level_handler_fn` (in Nightly builds, run with -Z macro-backtrace for more info)

error: `String` consumes the request body and thus must be the last argument to the handler function
 --> src/bin/body_first_debug.rs:4:24
  |
4 | async fn handler(body: String, method: Method) -> String {
  |                        ^^^^^^

impl<S, T> FromRequest<S, private::ViaParts> for T
where
    S: Send + Sync,
    T: FromRequestParts<S>,
{
    type Rejection = <Self as FromRequestParts<S>>::Rejection;

    fn from_request(
        req: Request,
        state: &S,
    ) -> impl Future<Output = Result<Self, Self::Rejection>> {
        let (mut parts, _) = req.into_parts();
        async move { Self::from_request_parts(&mut parts, state).await }
    }
}

mod private {
    #[derive(Debug, Clone, Copy)]
    pub enum ViaParts {}

    #[derive(Debug, Clone, Copy)]
    pub enum ViaRequest {}
}

impl<S, T> FromRequestParts<S> for Result<T, T::Rejection>
where
    T: FromRequestParts<S>,
    S: Send + Sync,
{
    type Rejection = Infallible;

    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
        Ok(T::from_request_parts(parts, state).await)
    }
}

impl<S, T> FromRequestParts<S> for Option<T>
where
    T: FromRequestParts<S>,
    S: Send + Sync,
{
    type Rejection = Infallible;

    async fn from_request_parts(
        parts: &mut Parts,
        state: &S,
    ) -> Result<Option<T>, Self::Rejection> {
        Ok(T::from_request_parts(parts, state).await.ok())
    }
}

pub trait OptionalFromRequestParts<S>: Sized {
    type Rejection: IntoResponse;

    fn from_request_parts(
        parts: &mut Parts,
        state: &S,
    ) -> impl Future<Output = Result<Option<Self>, Self::Rejection>> + Send;
}

#[diagnostic::do_not_recommend]
impl<S, T> FromRequestParts<S> for Option<T>
where
    T: OptionalFromRequestParts<S>,
    S: Send + Sync,
{
    type Rejection = T::Rejection;

    #[allow(clippy::use_self)]
    fn from_request_parts(
        parts: &mut Parts,
        state: &S,
    ) -> impl Future<Output = Result<Option<T>, Self::Rejection>> {
        T::from_request_parts(parts, state)
    }
}

axum = { version = "=0.8.9", default-features = false, features = ["query"] }
serde = { version = "1", features = ["derive"] }

use axum::{Router, extract::Query, routing::get};
use serde::Deserialize;

#[derive(Deserialize)]
struct Page {
  n: u32,
}

async fn list(page: Option<Query<Page>>) -> String {
  format!("{:?}", page.map(|Query(p)| p.n))
}

fn main() {
  let _app: Router = Router::new().route("/", get(list));
}

error[E0277]: the trait bound `std::option::Option<Query<Page>>: FromRequest<(), _>` is not satisfied
  --> src/bin/option_query_debug.rs:10:21
   |
10 | async fn list(page: Option<Query<Page>>) -> String {
   |                     ^^^^^^ the trait `FromRequest<(), _>` is not implemented for `std::option::Option<Query<Page>>`
   |
   = note: Function argument is not a valid axum extractor. 
           See `https://docs.rs/axum/0.8/axum/extract/index.html` for details

/p/7     200 Option<Path>   = Some(7)
/p/abc   400 Invalid URL: Cannot parse `abc` to a `u32`
/p       200 Option<Path>   = None
/r/abc   200 Result<Path>   = Err(Invalid URL: Cannot parse `abc` to a `u32`)
/q?n=3   200 Result<Query>  = Ok(3)
/q?n=x   200 Result<Query>  = Err(Failed to deserialize query string: n: invalid digit found in string)
/q       200 Result<Query>  = Err(Failed to deserialize query string: missing field `n`)
/e       200 Option<Extension> is_some = false