Struct rocket::Response

source ·
pub struct Response<'r> { /* private fields */ }
Expand description

A response, as returned by types implementing Responder.

Implementations§

source§

impl<'r> Response<'r>

source

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

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

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

§Example
use rocket::Response;

let builder = Response::build();
source

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

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

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

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

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

pub fn cookies(&self) -> Vec<Cookie<'_>>

Returns a vector of the cookies set 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!"));
assert_eq!(response.cookies(), vec![Cookie::new("hello", "world!")]);
source

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

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

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

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

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

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

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

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

pub fn body(&mut self) -> Option<Body<&mut dyn 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!"));
assert_eq!(response.body_string(), Some("Hello, world!".to_string()));
source

pub fn body_string(&mut self) -> Option<String>

Consumes self's body and reads it into a string. If self doesn’t have a body, reading fails, or string conversion (for non-UTF-8 bodies) fails, returns None. Note that self’s body is consumed after a call to this method.

§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_eq!(response.body_string(), Some("Hello, world!".to_string()));
assert!(response.body().is_none());
source

pub fn body_bytes(&mut self) -> Option<Vec<u8>>

Consumes self's body and reads it into a Vec of u8 bytes. If self doesn’t have a body or reading fails returns None. Note that self’s body is consumed after a call to this method.

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

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

response.set_sized_body(Cursor::new("hi!"));
assert_eq!(response.body_bytes(), Some(vec![0x68, 0x69, 0x21]));
assert!(response.body().is_none());
source

pub fn take_body(&mut self) -> Option<Body<Box<dyn 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());
source

pub 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!"));
assert_eq!(response.body_string(), Some("Hello, world!".to_string()));
source

pub 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.

Normally, data will be buffered and sent only in complete chunks. If you need timely transmission of available data, rather than buffering, enable the sse feature and use the WouldBlock technique described in Stream.

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

let mut response = Response::new();
response.set_streamed_body(repeat(97).take(5));
assert_eq!(response.body_string(), Some("aaaaa".to_string()));
source

pub 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);
assert_eq!(response.body_string(), Some("aaaaa".to_string()));
source

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

assert_eq!(response.body_string(), Some("Hello!".to_string()));
source

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

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§

source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> Response<'r>

Returns the “default value” for a type. Read more
source§

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

source§

fn respond_to(self, _: &Request<'_>) -> Result<Response<'r>, Status>

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

Auto Trait Implementations§

§

impl<'r> Freeze for Response<'r>

§

impl<'r> !RefUnwindSafe for Response<'r>

§

impl<'r> !Send for Response<'r>

§

impl<'r> !Sync for Response<'r>

§

impl<'r> Unpin for Response<'r>

§

impl<'r> !UnwindSafe for Response<'r>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T, I> AsResult<T, I> for T
where I: Input,

source§

fn as_result(self) -> Result<T, ParseErr<I>>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoCollection<T> for T

§

fn into_collection<A>(self) -> SmallVec<A>
where A: Array<Item = T>,

Converts self into a collection.
§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>
where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> Typeable for T
where T: Any,

source§

fn get_type(&self) -> TypeId

Get the TypeId of this object.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V