Struct rouille::Response

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>>,
}

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

Additionnaly, 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

impl Response

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

pub fn is_error(&self) -> bool

Shortcut for !response.is_success().

Example

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

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

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

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

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

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

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

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

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

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

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

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 }`

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

pub fn empty_204() -> Response

Builds an empty Response with a 204 status code.

Example

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

pub fn empty_400() -> Response

Builds an empty Response with a 400 status code.

Example

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

pub fn empty_404() -> Response

Builds an empty Response with a 404 status code.

Example

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

pub fn empty_406() -> Response

Builds an empty Response with a 406 status code.

Example

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

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

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

Removes all headers from the response that match header.

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.

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 .

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

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.

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.

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

pub fn with_public_cache(self, max_age_seconds: u64) -> Response

Adds or replaces a Cache-Control header that specifies that the resource is public and can be cached for the given number of seconds.

Note: This function doesn’t do any caching itself. It just indicates that clients that receive this response are allowed to cache it.

pub fn with_private_cache(self, max_age_seconds: u64) -> Response

Adds or replaces a Cache-Control header that specifies that the resource is private and can be cached for the given number of seconds.

Only the browser or the final client is authorized to cache the resource. Intermediate proxies must not cache it.

Note: This function doesn’t do any caching itself. It just indicates that clients that receive this response are allowed to cache it.

pub fn with_no_cache(self) -> Response

Adds or replaces a Cache-Control header that specifies that the client must not cache the resource.

Trait Implementations

impl Debug for Response

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

Formats the value using the given formatter.