Struct Response

Source

pub struct Response {
    pub status_code: u16,
    pub headers: Vec<(Cow<'static, str>, Cow<'static, str>)>,
    pub data: ResponseBody,
    pub upgrade: Option<Box<dyn Upgrade + Send>>,
}

Expand description

Contains a prototype of a response.

The response is only sent to the client when you return the Response object from your request handler. This means that you are free to create as many Response objects as you want.

Fields§

§status_code: u16

The status code to return to the user.

§headers: Vec<(Cow<'static, str>, Cow<'static, str>)>

List of headers to be returned in the response.

The value of the following headers will be ignored from this list, even if present:

Accept-Ranges
Connection
Content-Length
Content-Range
Trailer
Transfer-Encoding

Additionally, the Upgrade header is ignored as well unless the upgrade field of the Response is set to something.

The reason for this is that these headers are too low-level and are directly handled by the underlying HTTP response system.

The value of Content-Length is automatically determined by the ResponseBody object of the data member.

If you want to send back Connection: upgrade, you should set the value of the upgrade field to something.

§data: ResponseBody

An opaque type that contains the body of the response.

§upgrade: Option<Box<dyn Upgrade + Send>>

If set, rouille will give ownership of the client socket to the Upgrade object.

In all circumstances, the value of the Connection header is managed by the framework and cannot be customized. If this value is set, the response will automatically contain Connection: Upgrade.

Implementations§

Source §

impl Response

Source

pub fn is_success(&self) -> bool

Returns true if the status code of this Response indicates success.

This is the range [200-399].

§Example

use rouille::Response;
let response = Response::text("hello world");
assert!(response.is_success());

Source

pub fn is_error(&self) -> bool

Shortcut for !response.is_success().

§Example

use rouille::Response;
let response = Response::empty_400();
assert!(response.is_error());

Source

pub fn redirect_301<S>(target: S) -> Response
where S: Into<Cow<'static, str>>,

Builds a Response that redirects the user to another URL with a 301 status code. This semantically means a permanent redirect.

Note: If you’re uncertain about which status code to use for a redirection, 303 is the safest choice.

§Example

use rouille::Response;
let response = Response::redirect_301("/foo");

Source

pub fn redirect_302<S>(target: S) -> Response
where S: Into<Cow<'static, str>>,

Builds a Response that redirects the user to another URL with a 302 status code. This semantically means a temporary redirect.

Note: If you’re uncertain about which status code to use for a redirection, 303 is the safest choice.

§Example

use rouille::Response;
let response = Response::redirect_302("/bar");

Source

pub fn redirect_303<S>(target: S) -> Response
where S: Into<Cow<'static, str>>,

Builds a Response that redirects the user to another URL with a 303 status code. This means “See Other” and is usually used to indicate where the response of a query is located.

For example when a user sends a POST request to URL /foo the server can return a 303 response with a target to /bar, in which case the browser will automatically change the page to /bar (with a GET request to /bar).

Note: If you’re uncertain about which status code to use for a redirection, 303 is the safest choice.

§Example

use rouille::Response;
let user_id = 5;
let response = Response::redirect_303(format!("/users/{}", user_id));

Source

pub fn redirect_307<S>(target: S) -> Response
where S: Into<Cow<'static, str>>,

Builds a Response that redirects the user to another URL with a 307 status code. This semantically means a permanent redirect.

The difference between 307 and 301 is that the client must keep the same method after the redirection. For example if the browser sends a POST request to /foo and that route returns a 307 redirection to /bar, then the browser will make a POST request to /bar. With a 301 redirection it would use a GET request instead.

Note: If you’re uncertain about which status code to use for a redirection, 303 is the safest choice.

§Example

use rouille::Response;
let response = Response::redirect_307("/foo");

Source

pub fn redirect_308<S>(target: S) -> Response
where S: Into<Cow<'static, str>>,

Builds a Response that redirects the user to another URL with a 302 status code. This semantically means a temporary redirect.

The difference between 308 and 302 is that the client must keep the same method after the redirection. For example if the browser sends a POST request to /foo and that route returns a 308 redirection to /bar, then the browser will make a POST request to /bar. With a 302 redirection it would use a GET request instead.

Note: If you’re uncertain about which status code to use for a redirection, 303 is the safest choice.

§Example

use rouille::Response;
let response = Response::redirect_302("/bar");

Source

pub fn from_data<C, D>(content_type: C, data: D) -> Response
where C: Into<Cow<'static, str>>, D: Into<Vec<u8>>,

Builds a 200 Response with data.

§Example

use rouille::Response;
let response = Response::from_data("application/octet-stream", vec![1, 2, 3, 4]);

Source

pub fn from_file<C>(content_type: C, file: File) -> Response
where C: Into<Cow<'static, str>>,

Builds a 200 Response with the content of a file.

§Example

use std::fs::File;
use rouille::Response;

let file = File::open("image.png").unwrap();
let response = Response::from_file("image/png", file);

Source

pub fn html<D>(content: D) -> Response
where D: Into<String>,

Builds a Response that outputs HTML.

§Example

use rouille::Response;
let response = Response::html("<p>hello <strong>world</strong></p>");

Source

pub fn svg<D>(content: D) -> Response
where D: Into<String>,

Builds a Response that outputs SVG.

§Example

use rouille::Response;
let response = Response::svg("<svg xmlns='http://www.w3.org/2000/svg'/>");

Source

pub fn text<S>(text: S) -> Response
where S: Into<String>,

Builds a Response that outputs plain text.

§Example

use rouille::Response;
let response = Response::text("hello world");

Source

pub fn json<T>(content: &T) -> Response
where T: Serialize,

Builds a Response that outputs JSON.

§Example

extern crate serde;
#[macro_use] extern crate serde_derive;
#[macro_use] extern crate rouille;
use rouille::Response;

#[derive(Serialize)]
struct MyStruct {
    field1: String,
    field2: i32,
}

let response = Response::json(&MyStruct { field1: "hello".to_owned(), field2: 5 });
// The Response will contain something like `{ field1: "hello", field2: 5 }`

Source

pub fn basic_http_auth_login_required(realm: &str) -> Response

Builds a Response that returns a 401 Not Authorized status and a WWW-Authenticate header.

§Example

use rouille::Response;
let response = Response::basic_http_auth_login_required("realm");

Source

pub fn empty_204() -> Response

Builds an empty Response with a 204 status code.

§Example

use rouille::Response;
let response = Response::empty_204();

Source

pub fn empty_400() -> Response

Builds an empty Response with a 400 status code.

§Example

use rouille::Response;
let response = Response::empty_400();

Source

pub fn empty_404() -> Response

Builds an empty Response with a 404 status code.

§Example

use rouille::Response;
let response = Response::empty_404();

Source

pub fn empty_406() -> Response

Builds an empty Response with a 406 status code.

§Example

use rouille::Response;
let response = Response::empty_406();

Source

pub fn with_status_code(self, code: u16) -> Response

Changes the status code of the response.

§Example

use rouille::Response;
let response = Response::text("hello world").with_status_code(500);

Source

pub fn without_header(self, header: &str) -> Response

Removes all headers from the response that match header.

Source

pub fn with_additional_header<H, V>(self, header: H, value: V) -> Response
where H: Into<Cow<'static, str>>, V: Into<Cow<'static, str>>,

Adds an additional header to the response.

Source

pub fn with_unique_header<H, V>(self, header: H, value: V) -> Response
where H: Into<Cow<'static, str>>, V: Into<Cow<'static, str>>,

Removes all headers from the response whose names are header, and replaces them .

Source

pub fn with_etag<E>(self, request: &Request, etag: E) -> Response
where E: Into<Cow<'static, str>>,

Adds or replaces a ETag header to the response, and turns the response into an empty 304 response if the ETag matches a If-None-Match header of the request.

An ETag is a unique representation of the content of a resource. If the content of the resource changes, the ETag should change as well. The purpose of using ETags is that a client can later ask the server to send the body of a response only if it still matches a certain ETag the client has stored in memory.

Note: You should always try to specify an ETag for responses that have a large body.

§Example

use rouille::Request;
use rouille::Response;

fn handle(request: &Request) -> Response {
    Response::text("hello world").with_etag(request, "my-etag-1234")
}

Source

pub fn simplify_if_etag_match(self, request: &Request) -> Response

Turns the response into an empty 304 response if the ETag that is stored in it matches a If-None-Match header of the request.

Source

pub fn with_etag_keep<E>(self, etag: E) -> Response
where E: Into<Cow<'static, str>>,

Adds a ETag header to the response, or replaces an existing header if there is one.

Note: Contrary to with_etag, this function doesn’t try to turn the response into a 304 response. If you’re unsure of what to do, prefer with_etag.

Source

pub fn with_content_disposition_attachment(self, filename: &str) -> Response

Adds or replace a Content-Disposition header of the response. Tells the browser that the body of the request should fire a download popup instead of being shown in the browser.

§Example

use rouille::Request;
use rouille::Response;

fn handle(request: &Request) -> Response {
    Response::text("hello world").with_content_disposition_attachment("book.txt")
}

When the response is sent back to the browser, it will show a popup asking the user to download the file “book.txt” whose content will be “hello world”.

Source