Struct rocket::Response

pub struct Response<'r> { /* fields omitted */ }

A response, as returned by types implementing Responder.

See Builder for docs on how a Response is typically created.

Implementations

impl<'r> Response<'r>

pub fn new() -> Response<'r>

Creates a new, empty Response without a status, body, or headers. Because all HTTP responses must have a status, if a default Response is written to the client without a status, the status defaults to 200 Ok.

Example

use rocket::Response;
use rocket::http::Status;

let mut response = Response::new();

assert_eq!(response.status(), Status::Ok);
assert_eq!(response.headers().len(), 0);
assert!(response.body().is_none());

pub fn build() -> Builder<'r>

Returns a Builder with a base of Response::new().

Example

use rocket::Response;

let builder = Response::build();

pub fn build_from(other: Response<'r>) -> Builder<'r>

Returns a Builder with a base of other.

Example

use rocket::Response;

let other = Response::new();
let builder = Response::build_from(other);

pub fn status(&self) -> Status

Returns the status of self.

Example

use rocket::Response;
use rocket::http::Status;

let mut response = Response::new();
assert_eq!(response.status(), Status::Ok);

response.set_status(Status::NotFound);
assert_eq!(response.status(), Status::NotFound);

pub fn set_status(&mut self, status: Status)

Sets the status of self to status.

Example

use rocket::Response;
use rocket::http::Status;

let mut response = Response::new();
response.set_status(Status::ImATeapot);
assert_eq!(response.status(), Status::ImATeapot);

pub fn content_type(&self) -> Option<ContentType>

Returns the Content-Type header of self. If the header is not present or is malformed, returns None.

Example

use rocket::Response;
use rocket::http::ContentType;

let mut response = Response::new();
response.set_header(ContentType::HTML);
assert_eq!(response.content_type(), Some(ContentType::HTML));

pub fn set_raw_status(&mut self, code: u16, reason: &'static str)

Sets the status of self to a custom status with status code code and reason phrase reason. This method should be used sparingly; prefer to use set_status instead.

Example

use rocket::Response;
use rocket::http::Status;

let mut response = Response::new();
response.set_raw_status(699, "Tripped a Wire");
assert_eq!(response.status(), Status::new(699, "Tripped a Wire"));

pub fn cookies(&self) -> impl Iterator<Item = Cookie<'_>>

Returns an iterator over the cookies in self as identified by the Set-Cookie header. Malformed cookies are skipped.

Example

use rocket::Response;
use rocket::http::Cookie;

let mut response = Response::new();
response.set_header(Cookie::new("hello", "world!"));
let cookies: Vec<_> = response.cookies().collect();
assert_eq!(cookies, vec![Cookie::new("hello", "world!")]);

pub fn headers(&self) -> &HeaderMap<'r>

Returns a HeaderMap of all of the headers in self.

Example

use rocket::Response;
use rocket::http::Header;

let mut response = Response::new();
response.adjoin_raw_header("X-Custom", "1");
response.adjoin_raw_header("X-Custom", "2");

let mut custom_headers = response.headers().iter();
assert_eq!(custom_headers.next(), Some(Header::new("X-Custom", "1")));
assert_eq!(custom_headers.next(), Some(Header::new("X-Custom", "2")));
assert_eq!(custom_headers.next(), None);

pub fn set_header<'h: 'r, H: Into<Header<'h>>>(&mut self, header: H) -> bool

Sets the header header in self. Any existing headers with the name header.name will be lost, and only header will remain. The type of header can be any type that implements Into<Header>. This includes Header itself, ContentType and hyper::header types.

Example

use rocket::Response;
use rocket::http::ContentType;

let mut response = Response::new();

response.set_header(ContentType::HTML);
assert_eq!(response.headers().iter().next(), Some(ContentType::HTML.into()));
assert_eq!(response.headers().len(), 1);

response.set_header(ContentType::JSON);
assert_eq!(response.headers().iter().next(), Some(ContentType::JSON.into()));
assert_eq!(response.headers().len(), 1);

pub fn set_raw_header<'a: 'r, 'b: 'r, N, V>(
    &mut self,
    name: N,
    value: V
) -> bool where
    N: Into<Cow<'a, str>>,
    V: Into<Cow<'b, str>>, 

Sets the custom header with name name and value value in self. Any existing headers with the same name will be lost, and the new custom header will remain. This method should be used sparingly; prefer to use set_header instead.

Example

use rocket::Response;
use rocket::http::Header;

let mut response = Response::new();

response.set_raw_header("X-Custom", "1");
assert_eq!(response.headers().get_one("X-Custom"), Some("1"));
assert_eq!(response.headers().len(), 1);

response.set_raw_header("X-Custom", "2");
assert_eq!(response.headers().get_one("X-Custom"), Some("2"));
assert_eq!(response.headers().len(), 1);

pub fn adjoin_header<'h: 'r, H: Into<Header<'h>>>(&mut self, header: H)

Adds the header header to self. If self contains headers with the name header.name, another header with the same name and value header.value is added. The type of header can be any type that implements Into<Header>. This includes Header itself, ContentType and hyper::header types.

Example

use rocket::Response;
use rocket::http::Header;
use rocket::http::hyper::header::ACCEPT;

let mut response = Response::new();
response.adjoin_header(Header::new(ACCEPT.as_str(), "application/json"));
response.adjoin_header(Header::new(ACCEPT.as_str(), "text/plain"));

let mut accept_headers = response.headers().iter();
assert_eq!(accept_headers.next(), Some(Header::new(ACCEPT.as_str(), "application/json")));
assert_eq!(accept_headers.next(), Some(Header::new(ACCEPT.as_str(), "text/plain")));
assert_eq!(accept_headers.next(), None);

pub fn adjoin_raw_header<'a: 'r, 'b: 'r, N, V>(&mut self, name: N, value: V) where
    N: Into<Cow<'a, str>>,
    V: Into<Cow<'b, str>>, 

Adds a custom header with name name and value value to self. If self already contains headers with the name name, another header with the same name and value is added. The type of header can be any type implements Into<Header>. This includes Header itself, ContentType and hyper::header types.

Example

use rocket::Response;
use rocket::http::Header;

let mut response = Response::new();
response.adjoin_raw_header("X-Custom", "one");
response.adjoin_raw_header("X-Custom", "two");

let mut custom_headers = response.headers().iter();
assert_eq!(custom_headers.next(), Some(Header::new("X-Custom", "one")));
assert_eq!(custom_headers.next(), Some(Header::new("X-Custom", "two")));
assert_eq!(custom_headers.next(), None);

pub fn remove_header(&mut self, name: &str)

Removes all headers with the name name.

Example

use rocket::Response;

let mut response = Response::new();

response.adjoin_raw_header("X-Custom", "one");
response.adjoin_raw_header("X-Custom", "two");
response.adjoin_raw_header("X-Other", "hi");
assert_eq!(response.headers().len(), 3);

response.remove_header("X-Custom");
assert_eq!(response.headers().len(), 1);

pub fn body(&self) -> &Body<'r>

Returns an immutable borrow of the body of self, if there is one.

Example

use std::io::Cursor;
use rocket::Response;

let mut response = Response::new();
assert!(response.body().is_none());

let string = "Hello, world!";
response.set_sized_body(string.len(), Cursor::new(string));
assert!(response.body().is_some());

pub fn body_mut(&mut self) -> &mut Body<'r>

Returns a mutable borrow of the body of self, if there is one. A mutable borrow allows for reading the body.

Example

use std::io::Cursor;
use rocket::Response;

let mut response = Response::new();
assert!(response.body().is_none());

let string = "Hello, world!";
response.set_sized_body(string.len(), Cursor::new(string));
let string = response.body_mut().to_string().await;
assert_eq!(string.unwrap(), "Hello, world!");

pub fn set_sized_body<B, S>(&mut self, size: S, body: B) where
    B: AsyncRead + AsyncSeek + Send + 'r,
    S: Into<Option<usize>>, 

Sets the body of self to be the fixed-sized body with size size, which may be None. If size is None, the body’s size will be computing with calls to seek just before being written out in a response.

Example

use std::io;
use rocket::Response;

let string = "Hello, world!";

let mut response = Response::new();
response.set_sized_body(string.len(), io::Cursor::new(string));
assert_eq!(response.body_mut().to_string().await?, "Hello, world!");

pub fn set_streamed_body<B>(&mut self, body: B) where
    B: AsyncRead + Send + 'r, 

Sets the body of self to body, which will be streamed.

The max chunk size is configured via Response::set_max_chunk_size() and defaults to Body::DEFAULT_MAX_CHUNK.

Example

use tokio::io::{repeat, AsyncReadExt};
use rocket::Response;

let mut response = Response::new();
response.set_streamed_body(repeat(97).take(5));
assert_eq!(response.body_mut().to_string().await?, "aaaaa");

pub fn set_max_chunk_size(&mut self, size: usize)

Sets the body’s maximum chunk size to size bytes.

The default max chunk size is Body::DEFAULT_MAX_CHUNK. The max chunk size is a property of the body and is thus reset whenever a body is set via Response::set_streamed_body(), Response::set_sized_body(), or the corresponding builer methods.

This setting does not typically need to be changed. Configuring a high value can result in high memory usage. Similarly, configuring a low value can result in excessive network writes. When unsure, leave the value unchanged.

Example

use tokio::io::{repeat, AsyncReadExt};
use rocket::Response;

let mut response = Response::new();
response.set_streamed_body(repeat(97).take(5));
response.set_max_chunk_size(3072);

pub fn merge(&mut self, other: Response<'r>)

Replaces this response’s status and body with that of other, if they exist in other. Any headers that exist in other replace the ones in self. Any in self that aren’t in other remain in self.

Example

use rocket::Response;
use rocket::http::{Status, ContentType};

let base = Response::build()
    .status(Status::NotFound)
    .header(ContentType::HTML)
    .raw_header("X-Custom", "value 1")
    .finalize();

let response = Response::build()
    .status(Status::ImATeapot)
    .raw_header("X-Custom", "value 2")
    .raw_header_adjoin("X-Custom", "value 3")
    .merge(base)
    .finalize();

assert_eq!(response.status(), Status::NotFound);

let ctype: Vec<_> = response.headers().get("Content-Type").collect();
assert_eq!(ctype, vec![ContentType::HTML.to_string()]);

let custom_values: Vec<_> = response.headers().get("X-Custom").collect();
assert_eq!(custom_values, vec!["value 1"]);

pub fn join(&mut self, other: Response<'r>)

Sets self’s status and body to that of other if they are not already set in self. Any headers present in both other and self are adjoined.

Example

use rocket::Response;
use rocket::http::{Status, ContentType};

let other = Response::build()
    .status(Status::NotFound)
    .header(ContentType::HTML)
    .raw_header("X-Custom", "value 1")
    .finalize();

let response = Response::build()
    .status(Status::ImATeapot)
    .raw_header("X-Custom", "value 2")
    .raw_header_adjoin("X-Custom", "value 3")
    .join(other)
    .finalize();

assert_eq!(response.status(), Status::ImATeapot);

let ctype: Vec<_> = response.headers().get("Content-Type").collect();
assert_eq!(ctype, vec![ContentType::HTML.to_string()]);

let custom_values: Vec<_> = response.headers().get("X-Custom").collect();
assert_eq!(custom_values, vec!["value 2", "value 3", "value 1"]);

Trait Implementations

impl Debug for Response<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'r> Default for Response<'r>

fn default() -> Response<'r>

Returns the “default value” for a type.