courier is a utility crate for the [Rocket] framework which allows you derive [FromData]
and [Responder] for your custom types. Here's an example using courier to handle sending
and recieving custom data to/from the client:
```rust
extern crate rocket;
extern crate courier; extern crate serde;
extern crate serdederive; extern crate serdejson;
pub struct CustomRequest { pub foo: String, pub bar: usize, }
pub struct CustomResponse { pub baz: usize, }
pub fn handle_request(request: CustomRequest) -> CustomResponse { if request.foo == "foo" { CustomResponse { baz: 0 } } else { CustomResponse { baz: request.bar } } } ```
In this example, the response will be encoded the same way that the request was, e.g. if the client sent the request body as JSON, then the response will be sent as JSON.
Add courier, as well as the relevant Serde crates to your Cargo.toml:
toml
[dependencies]
courier = "0.3"
serde = "1.0"
serde_derive = "1.0"
serde_json = "1.0"
Import the crates into your project:
```rust
extern crate courier;
extern crate serde;
extern crate serdederive; extern crate serdejson; ```
Note that you must have the #[macro_use] attribute on the extern crate statement in order to
use this crate's features.
You can now use #[derive(FromData)] and #[derive(Responder)] for your custom types.
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:
```toml [dependencies] rmp-serde = "0.13.6" serde = "1.0" serdederive = "1.0" serdejson = "1.0"
[dependencies.courier] version = "0.3" features = ["msgpack"] ```
And then add rmp-serde to your project root:
```rust
extern crate courier;
extern crate rmp_serde; extern crate serde;
extern crate serdederive; extern crate serdejson; ```
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:
toml
[dependencies.courier]
version = "0.3"
default-features = false
features = ["msgpack"]
When multiple formats are enabled at once, the [Content-Type] header in the request is used to
determine which format to use. A response will use the same content type specified in the request,
so a request sent with JSON will receive a response with JSON, a request sent with MessagePack
will get a response with MessagePack, and so on.
While this mostly removes the need for [rocket_contrib::Json] (and similar types), 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:
```rust
pub fn handle_request(request: CustomRequest) -> CustomResponse { if request.foo == "foo" { CustomResponse { baz: 0 } } else { CustomResponse { baz: request.bar } } } ```
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:
```rust use rocket_contrib::Json;
pub fn handle_request(request: Json
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.