OptionalQuery extractor

[mikhailantoshkin]

• I have looked for existing issues (including closed) about this

Feature Request

Motivation

Currently, there is no ergonomic way to express the "handler accepts either all query parameters or none" in the handler signature.

Signature like this

pub async fn login_form(
    Query(query): Query<Option<QueryParams>>,
) ->impl IntoResponse {

results in an error message from the deserialization library on request without query parameters.

Signature like this

pub async fn login_form(
   query: Option<Query<QueryParams>>,
) ->impl IntoResponse {

works but silently swallows all parsing errors.

Proposal

Add an extractor OptionalQuery, similar to OptionalPath proposed in #1884 that succeeds with None if there are no query parameters present in the request URI, and attempts to deserialize the query parameters to T and return Some(T) on success, rejecting the request on failure.

Alternatives

All of the alternatives I can think of require the user of the library to perform verification logic or custom parsing.

• Use of Result as an extractor and then matching on Err variant will work, but it is much less ergonomic and requires nested match statements

pub async fn login_form(
    query: Result<Query<QueryParams>, QueryRejection>>,
) ->impl IntoResponse {

• Implementing custom parsing with RawQuery extractor is much less ergonomic and will duplicate parsing logic from the library into user code.

• Defining QueryParams like this and adding verification logic onto the struct also seems undesirable

struct QueryParams {
    a: Option<String>,
    b: Option<String>,
}

[davidpdrsn]

Sure! Are you up for making a PR? I think it should live in axum-extra like OptionalPath.

[mikhailantoshkin]

Yes, would love to contribute.

[vsuryamurthy]

Hello @davidpdrsn, the documentation suggests using a pattern such as json: Option<Json<...>>. Should it also contain some additional documentation pointing the user to the extractors in axum-extra?
It seems to me that OptionalQuery<> should be preferred to Option<Query<...>>.

[jplatte]

Seems like a good idea to note the presence of those extractors in that section of the docs, a PR would be appreciated.

Long-term, I would like to change how optional extractors work, see #2298 for discussion.

[vsuryamurthy]

Seems like a good idea to note the presence of those extractors in that section of the docs, a PR would be appreciated.

I can put in a PR.

Long-term, I would like to change how optional extractors work, see #2298 for discussion.

Nice PR. Only question being, why do you have to keep supporting optional query in axum-extra?

Edit: The PR is here: #2801

[jplatte]

Long-term, I would like to change how optional extractors work, see #2298 for discussion.

Nice PR. Only question being, why do you have to keep supporting optional query in axum-extra?

If that issue is resolved as I proposed, then we will remove all of those OptionalFoo extractors from axum-extra in the next breaking-change release.