Struct rocket::Response

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

An HTTP/Rocket response, returned by Responders.

Methods

impl<'r> Response<'r>

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().count(), 0);
assert!(response.body().is_none());

fn build() -> ResponseBuilder<'r>

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

Example

use rocket::Response;

let builder = Response::build();

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

Returns a ResponseBuilder with a base of other.

Example

use rocket::Response;

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

fn status(&self) -> Status

Returns the status of the 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);

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);

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"));

fn headers<'a>(&'a self) -> impl Iterator<Item=Header<'a>>

Returns an iterator over all of the headers stored in self. Multiple headers with the same name may be returned, but all of the headers with the same name will be appear in a group in the iterator. The values in this group will be emitted in the order they were added to self. Aside from this grouping, there are no other ordering guarantees.

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 headers = response.headers();
assert_eq!(headers.next(), Some(Header::new("X-Custom", "1")));
assert_eq!(headers.next(), Some(Header::new("X-Custom", "2")));
assert_eq!(headers.next(), None);

fn header_values<'h>(&'h self, name: &str) -> impl Iterator<Item=&'h str>

Returns an iterator over all of the values stored in self for the header with name name. The values are returned in FIFO order.

Example

use rocket::Response;

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

let values: Vec<_> = response.header_values("X-Custom").collect();
assert_eq!(values, vec!["1", "2"]);

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().next(), Some(ContentType::HTML.into()));
assert_eq!(response.headers().count(), 1);

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

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().next(), Some(Header::new("X-Custom", "1")));
assert_eq!(response.headers().count(), 1);

response.set_raw_header("X-Custom", "2");
assert_eq!(response.headers().next(), Some(Header::new("X-Custom", "2")));
assert_eq!(response.headers().count(), 1);

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::hyper::header::Accept;

let mut response = Response::new();
response.adjoin_header(Accept::json());
response.adjoin_header(Accept::text());

let mut accept_headers = response.headers();
assert_eq!(accept_headers.next(), Some(Accept::json().into()));
assert_eq!(accept_headers.next(), Some(Accept::text().into()));
assert_eq!(accept_headers.next(), None);

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 that 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();
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);

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

Removes all headers with the name name.

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");
response.adjoin_raw_header("X-Other", "hi");
assert_eq!(response.headers().count(), 3);

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

fn body(&mut self) -> Option<Body<&mut Read>>

Returns a mutable borrow of the body of self, if there is one. The body is borrowed mutably to allow for reading.

Example

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

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

response.set_sized_body(Cursor::new("Hello, world!"));

let body_string = response.body().and_then(|b| b.into_string());
assert_eq!(body_string, Some("Hello, world!".to_string()));
assert!(response.body().is_some());

fn take_body(&mut self) -> Option<Body<Box<Read + 'r>>>

Moves the body of self out and returns it, if there is one, leaving no body in its place.

Example

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

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

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

let body = response.take_body();
let body_string = body.and_then(|b| b.into_string());
assert_eq!(body_string, Some("Hello, world!".to_string()));
assert!(response.body().is_none());

fn set_sized_body<B>(&mut self, body: B) where B: Read + Seek + 'r

Sets the body of self to be the fixed-sized body. The size of the body is obtained by seeking to the end and then seeking back to the start.

Panics

If either seek fails, this method panics. If you believe it is possible for seek to panic for B, use set_raw_body instead.

Example

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

let mut response = Response::new();
response.set_sized_body(Cursor::new("Hello, world!"));

let body_string = response.body().and_then(|b| b.into_string());
assert_eq!(body_string, Some("Hello, world!".to_string()));

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

Sets the body of self to be body, which will be streamed. The chunk size of the stream is DEFAULT_CHUNK_SIZE. Use set_chunked_body for custom chunk sizes.

Example

use std::io::{Read, repeat};
use rocket::Response;

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

let body_string = response.body().and_then(|b| b.into_string());
assert_eq!(body_string, Some("aaaaa".to_string()));

fn set_chunked_body<B>(&mut self, body: B, chunk_size: u64) where B: Read + 'r

Sets the body of self to be body, which will be streamed with chunk size chunk_size.

Example

use std::io::{Read, repeat};
use rocket::Response;

let mut response = Response::new();
response.set_chunked_body(repeat(97).take(5), 10);

let body_string = response.body().and_then(|b| b.into_string());
assert_eq!(body_string, Some("aaaaa".to_string()));

fn set_raw_body<T: Read + 'r>(&mut self, body: Body<T>)

Sets the body of self to be body. This method should typically not be used, opting instead for one of set_sized_body, set_streamed_body, or set_chunked_body.

Example

use std::io::Cursor;
use rocket::response::{Response, Body};

let body = Body::Sized(Cursor::new("Hello!"), 6);

let mut response = Response::new();
response.set_raw_body(body);

let body_string = response.body().and_then(|b| b.into_string());
assert_eq!(body_string, Some("Hello!".to_string()));

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.header_values("Content-Type").collect();
assert_eq!(ctype, vec![ContentType::HTML.to_string()]);

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

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

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.header_values("Content-Type").collect();
assert_eq!(ctype, vec![ContentType::HTML.to_string()]);

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

Trait Implementations

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

fn default() -> Response<'r>

Returns the "default value" for a type.

impl<'r> Debug for Response<'r>

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

Formats the value using the given formatter.

impl<'r> Responder<'r> for Response<'r>

fn respond(self) -> Result<Response<'r>, Status>

This is the identity implementation. It simply returns Ok(self).