Crate courier [−] [src]
Custom derive functionality for Rocket applications.
Usage
Add courier
to your Cargo.toml
:
[dependencies]
courier = "0.3.1"
serde = "1.0"
serde_derive = "1.0"
serde_json = "1.0"
Import the crate and the necessary Serde dependencies into your project:
#[macro_use] extern crate courier; extern crate serde; #[macro_use] extern crate serde_derive; extern crate serde_json;
Note that you must have the #[macro_use]
attribute on the extern crate
statement in order to
use this crate's features.
You may now derive FromData
and Responder
for your custom types:
#[derive(Deserialize, FromData)] pub struct CustomRequest { // Some members go here. } #[derive(Serialize, Responder)] pub struct CustomResponse { // Some members go here. }
Supported Formats
courier
supports receiving request bodies and sending response bodies in multiple formats.
For each one you'd like to enable, you'll have to enable a feature in your Cargo.toml
and add the
relevant Serde crate(s) to your project. The following table shows which formats are currently
supported, the feature name for that format, and what Serde crate(s) you'll need to include.
Format | Feature Name | Serde Crate(s) |
---|---|---|
JSON | json |
serde_json |
MessagePack | msgpack |
rmp-serde |
By default, only JSON support is enabled. So, for example, if you'd like to add MessagePack support,
you'd edit your Cargo.toml
to enable the msgpack
feature and add rmp-serde as a dependency:
[dependencies]
rmp-serde = "0.13.6"
serde = "1.0"
serde_derive = "1.0"
serde_json = "1.0"
[dependencies.courier]
version = "0.3.1"
features = ["msgpack"]
And then add rmp-serde
to your project root:
#[macro_use] extern crate courier; extern crate rmp_serde; extern crate serde; #[macro_use] extern crate serde_derive; extern crate serde_json;
Note that, to also support JSON, you still need to include serde_json
as a dependency. If you do
not wish to support JSON, you can specify default-features = false
in your Cargo.toml
:
[dependencies.courier]
version = "0.3.1"
default-features = false
features = ["msgpack"]
Using Multiple Formats
When multiple formats are enabled at once, the Content-Type
header in the request is used to
determine which format the request data is in, and the Accept
header is used to determine which
format to use for the response.
While this mostly removes the need for rocket_contrib::Json
, it is still
possible to use it to override the behavior defined with courier
. For example, say you
specify a format for your Rocket route:
#[post("/endpoint", format = "application/json", data = "<request>")] pub fn handle_request(request: CustomRequest) -> CustomResponse { CustomResponse {} }
In that case, Rocket will check the content type before routing the request to handle_request
,
then the FromData
impl for CustomRequest
will check it again. If this isn't desirable, you
can use rocket_contrib::Json
to skip the second check:
use rocket_contrib::Json; #[post("/endpoint", format = "application/json", data = "<request>")] pub fn handle_request(request: Json<CustomRequest>) -> Json<CustomResponse> { Json(CustomResponse {}) }
Note, though, that recommended to not explicitly specify the format
parameter for your route
if you're using courier
. The code generated by courier
allows you to write
content type-agnostic route handlers, so manually specifying an expected format is unnecessary.