Struct Response

source

pub struct Response { /* private fields */ }

Expand description

Represents an HTTP response.

use pavex::response::Response;
use pavex::http::{HeaderValue, header::SERVER};

// Create a new response with:
// - status code `OK`
// - HTTP version `HTTP/1.1`
// - the `Server` header set to `Pavex`
// - the `Content-Type` header set to `text/plain; charset=utf-8`
// - the body set to `Hello, world!`
let response = Response::ok()
    .insert_header(SERVER, HeaderValue::from_static("Pavex"))
    .set_typed_body("Hello, world!");

The response is composed of a head (ResponseHead) and an optional body.

Check out Response::new for details on how to build a new Response.
You might also want to check out the following methods to further customize your response:

set_status to change the status code.
set_version to change the HTTP version.
append_header to append a value to a header.
insert_header to upsert a header value.
set_typed_body to set the body and automatically set the Content-Type header.

There are other methods available on Response that you might find useful, but the ones listed above are the most commonly used and should be enough to get you started.

Implementations§

source §

impl Response

source

pub fn new(status_code: StatusCode) -> Self

Build a new Response with the given status code.
The HTTP version is set to HTTP 1.1, there are no headers and the body is empty.

§Example

use pavex::http::StatusCode;
use pavex::response::Response;
     
let response = Response::new(StatusCode::OK);

§Alternatives

Pavex’s provides a set of shorthands for building a new Response using well-known status code. For example, the following code is equivalent to the example above:

use pavex::response::Response;
     
let response = Response::ok();

Check out Response’s API documentation for a complete list of all the supported shorthands.

source §

impl Response

source

pub fn set_status(self, status: StatusCode) -> Self

Change the status code of the Response.

§Example

use pavex::http::StatusCode;
use pavex::response::Response;

let mut response = Response::ok();
assert_eq!(response.status(), StatusCode::OK);

// Change the status code to `CREATED`.
response = response.set_status(StatusCode::CREATED);
assert_eq!(response.status(), StatusCode::CREATED);

source

pub fn status_mut(&mut self) -> &mut StatusCode

Get a mutable reference to the Response status.

§Example

use pavex::http::StatusCode;
use pavex::response::Response;
use pavex::http::header::CONTENT_TYPE;

let mut response = Response::ok();

assert_eq!(response.status(), StatusCode::OK);

// Get a mutable reference to the status.
let status = response.status_mut();

// Change the Status
*status = StatusCode::NOT_FOUND;

assert_eq!(response.status(), StatusCode::NOT_FOUND);

source

pub fn set_version(self, version: Version) -> Self

Change the HTTP version of the Response.

§Example

use pavex::http::Version;
use pavex::response::Response;

let mut response = Response::ok();
// By default, the HTTP version is HTTP/1.1.
assert_eq!(response.version(), Version::HTTP_11);

// Change the HTTP version to HTTP/2.
response = response.set_version(Version::HTTP_2);
assert_eq!(response.version(), Version::HTTP_2);

source

pub fn append_header(self, key: HeaderName, value: HeaderValue) -> Self

Append a value to a Response header.

If the header is not present, it is added with the given value.
If the header is present, the value is appended to the end of the comma-separated list of existing values for that header.

§Example

use pavex::http::{header::HOST, HeaderValue};
use pavex::response::Response;

let mut response = Response::ok();
assert!(response.headers().get("host").is_none());

// Append a value to the `host` header.
let value = HeaderValue::from_static("world");
response = response.append_header(HOST, value);

let headers: Vec<_> = response.headers().get_all("host").iter().collect();
assert_eq!(headers.len(), 1);
assert_eq!(headers[0], "world");

// Append another value to the `host` header.
let value = HeaderValue::from_static("earth");
response = response.append_header(HOST, value);

let headers: Vec<_> = response.headers().get_all("host").iter().collect();
assert_eq!(headers.len(), 2);
assert_eq!(headers[0], "world");
assert_eq!(headers[1], "earth");

§Alternatives

If you want to replace the value of a header instead of appending to it, use insert_header instead.

source

pub fn insert_header(self, key: HeaderName, value: HeaderValue) -> Self

Insert a header value into the Response.

If the header key is not present, it is added with the given value. If the header key is present, its value is replaced with the given value.

§Example

use pavex::http::{header::HOST, HeaderValue};
use pavex::response::Response;
     
let mut response = Response::ok();
assert!(response.headers().get("host").is_none());
     
// Insert a value into the `host` header.
let value = HeaderValue::from_static("world");
response = response.insert_header(HOST, value);

let headers: Vec<_> = response.headers().get_all("host").iter().collect();
assert_eq!(headers.len(), 1);
assert_eq!(headers[0], "world");

// Insert another value into the `host` header.
let value = HeaderValue::from_static("earth");
response = response.insert_header(HOST, value);
     
let headers: Vec<_> = response.headers().get_all("host").iter().collect();
assert_eq!(headers.len(), 1);
assert_eq!(headers[0], "earth");

§Alternatives

If you want to append to the current header value instead of replacing it, use append_header instead.

source

pub fn set_typed_body<NewBody>(self, body: NewBody) -> Response
where NewBody: TypedBody, <<NewBody as TypedBody>::Body as RawBody>::Error: Into<Box<dyn Error + Send + Sync>>,

Set the Response body.

The provided body must implement the TypedBody trait.
The Content-Type header is automatically set to the value returned by TypedBody::content_type.

If a body is already set, it is replaced.

§Example

use pavex::response::{Response, body::Html};
use pavex::http::header::CONTENT_TYPE;

let typed_body = "Hello, world!";
let response = Response::ok().set_typed_body(typed_body);

// The `Content-Type` header is set automatically
// when using `set_typed_body`.
assert_eq!(response.headers()[CONTENT_TYPE], "text/plain; charset=utf-8");

§Built-in `TypedBody` implementations

Pavex provides several implementations of TypedBody out of the box, to cover the most common use cases:

String, &'static str and Cow<'static, str> for text/plain; charset=utf-8 responses.
Vec<u8>, &'static [u8], Cow<'static, [u8]> and Bytes for application/octet-stream responses.
Json for application/json responses.
Html for text/html; charset=utf-8 responses.

Check out the body sub-module for an exhaustive list.

§Raw body

If you don’t want Pavex to automatically set the Content-Type header, you might want to use Response::set_raw_body instead.

source

pub fn set_raw_body<NewBody>(self, body: NewBody) -> Response
where NewBody: RawBody<Data = Bytes> + Send + 'static, <NewBody as RawBody>::Error: Into<Box<dyn Error + Send + Sync>>,

Set the body of the Response to the given value, without setting the Content-Type header.

This method should only be used if you need fine-grained control over the Content-Type header or the body type. In all other circumstances, use set_typed_body.

§Example

use pavex::response::Response;
use pavex::response::body::raw::{Bytes, Full};
use pavex::http::header::CONTENT_TYPE;
     
let raw_body: Full<Bytes> = Full::new("Hello, world!".into());
let response = Response::ok().set_raw_body(raw_body);

// The `Content-Type` header is not set automatically
// when using `set_raw_body`.
assert_eq!(response.headers().get(CONTENT_TYPE), None);

source

pub fn body_mut(&mut self) -> &mut ResponseBody

Get a mutable reference to the Response body.

source

pub fn headers_mut(&mut self) -> &mut HeaderMap

Get a mutable reference to the Response headers.

§Example

use pavex::response::Response;
use pavex::http::{header::CONTENT_TYPE, HeaderValue};
use mime::TEXT_PLAIN_UTF_8;

let mut response = Response::ok();

// Get a mutable reference to the headers.
let headers = response.headers_mut();

// Insert a header.
let value = HeaderValue::from_static(TEXT_PLAIN_UTF_8.as_ref());
headers.insert(CONTENT_TYPE, value);

assert_eq!(headers.len(), 1);

// Remove a header.
headers.remove(CONTENT_TYPE);

assert!(headers.is_empty());

source §

impl Response

source

pub fn status(&self) -> StatusCode

Get a reference to the Response status code.

§Example

use pavex::{http::StatusCode, response::Response};

let response = Response::bad_request();
assert_eq!(response.status(), StatusCode::BAD_REQUEST);

§Mutation

Check out Response::set_status if you need to modify the status code of the Response.

source

pub fn version(&self) -> Version

Get a reference to the version of the HTTP protocol used by the Response.

§Example

use pavex::http::Version;
use pavex::response::Response;

let mut response = Response::ok();
// By default, the HTTP version is HTTP/1.1.
assert_eq!(response.version(), Version::HTTP_11);

§Mutation

Check out Response::set_version if you need to modify the HTTP protocol version used by the Response.

source

pub fn headers(&self) -> &HeaderMap

Get a reference to the Response headers.

§Example

use pavex::http::{header::{HOST, SERVER}, HeaderValue};
use pavex::response::Response;
     
let response = Response::ok()
    .append_header(HOST, HeaderValue::from_static("world"))
    .append_header(HOST, HeaderValue::from_static("earth"))
    .insert_header(SERVER, HeaderValue::from_static("Pavex"));

let headers = response.headers();
assert_eq!(headers.len(), 3);

let host_values: Vec<_> = response.headers().get_all("host").iter().collect();
assert_eq!(host_values.len(), 2);
assert_eq!(host_values[0], "world");
assert_eq!(host_values[1], "earth");

assert_eq!(headers[SERVER], "Pavex");