add Created helper type

[2ndDerivative]

add Created, a helper type that forces the user to set a Location header when returning 201 CREATED

Motivation

When looking at how to guarantee the CREATED status code's semantics I came up with this, maybe it's helpful.

[mladedav]

The doc comment mentions that 201 is recommended to have a Location header according to an RFC. Do you mean this part?

The 201 (Created) status code indicates that the request has been
fulfilled and has resulted in one or more new resources being
created. The primary resource created by the request is identified
by either a Location header field in the response or, if no Location
field is received, by the effective request URI.

I don't see that as a recommendation to be honest, it just states, that if you send the header, it has special meaning but not that you SHOULD send it.

[2ndDerivative]

Even though I read the part you mentioned to make this contribution, yeah it doesn't use the keyword which is probably an indicator you're right.

Looking it up again though it says this under POST:

If a resource has been created on the origin server, the response
SHOULD be 201 (Created) and contain an entity which describes the
status of the request and refers to the new resource, and a Location
header (see section 14.30).

If you guys think this change is worth is is frankly up to you, I just wanted to get this out because I use it in my project and found it useful

[mladedav]

Right.

In that case it does make sense but I think there should also be a way to explicitly create the response without the header.

So I think having constructors like with_location and at_request_path (feel free to bikeshed the names; then there would be the constructors with bodies or a with_body method or something like that), changing the header value in the struct to an Option and making the internals private would provide the flexibility I think we should keep while also pointing users to what they should do.

Maybe other maintainers will have different opinions though.

[2ndDerivative]

Right.

In that case it does make sense but I think there should also be a way to explicitly create the response without the header.

So I think having constructors like with_location and at_request_path (feel free to bikeshed the names; then there would be the constructors with bodies or a with_body method or something like that), changing the header value in the struct to an Option and making the internals private would provide the flexibility I think we should keep while also pointing users to what they should do.

Maybe other maintainers will have different opinions though.

can you even do at_request_path? Or do you mean like to give a URI as an argument?
Because I don't think you can access the original requests URI inside the into_response definition, right?

[mladedav]

I meant it as with the implicit location, at which the resource was created, which is the request URI. The name I came up with might not be as clear as it should be.

The primary resource created by the request is identified by either a Location header field in the response or, if no Location header field is received, by the target URI.

[jplatte]

Since this is trivial to write in user code with the semantics each user wants (I could see some always using it as a unit struct that always results in an empty body as another example), I'm inclined to not include this in axum. Thoughts?