Skip to content

Wire representation

Pavex uses two types to model the request data as it arrives on the wire: RequestHead and RawIncomingBody.

RequestHead

RequestHead encapsulates the data transmitted at the beginning of an HTTP request: method, HTTP version, request target and headers.
All the data in the RequestHead has been read from the wire by the time Pavex invokes your code.

Injection

RequestHead is a framework primitive, you don't have to register a constructor to inject it.

use pavex::get;
use pavex::http::StatusCode;
use pavex::request::RequestHead;

#[get(path = "/head")]
pub fn request_head(head: &RequestHead /* (1)! */) -> StatusCode {
    println!("The HTTP method is {}", head.method);
    println!("The HTTP version is {:?}", head.version);
    println!("The request target is {}", head.target);
    println!("There are {} headers", head.headers.len());
    // [...]
}
  1. All our operations are read-only, so it's enough to inject a shared reference as input (i.e. &RequestHead).

RequestHead is a dependency for a wide range of extractors.
We recommend injecting a shared reference as input (i.e. &RequestHead) rather than consuming RequestHead by value.

RawIncomingBody

RawIncomingBody gives you access to the raw body of the incoming HTTP request.

It sits at the lowest level of abstraction when it comes to body processing. You're looking at the stream of bytes coming from the network. There are no safeguards nor conveniences.

In most situations, you're better off avoiding RawIncomingBody entirely: prefer working with the higher-level body abstractions provided by Pavex.

Injection

RawIncomingBody is a framework primitive, you don't have to register a constructor to inject it.

use pavex::http::StatusCode;
use pavex::post;
use pavex::request::body::RawIncomingBody;

#[post(path = "/body")]
pub fn raw_body(body: RawIncomingBody) -> StatusCode {
    // [...]
}

Most abstractions built on top of RawIncomingBody consume it by value.
You can't really share an instance of RawIncomingBody: you need exclusive access to pull data from the stream of bytes. Pavex will return a borrow-checking error if you try to consume the same RawIncomingBody from different components.

No Request type

There is no over-arching Request type in Pavex.
The access patterns for the data in the request head (headers, method, path) and the body are different. The request head is primarily accessed through a shared reference (i.e. &RequestHead) while the body is consumed by value (i.e. RawIncomingBody).
By keeping them separate, we reduce the occurrence of annoying borrow-checking errors in your day-to-day Pavex work.

You can always inject both types if you need to look at the entire request at once.