Response

Append another Body to the body of this response without reading or writing any body contents.

If this response does not have a body, the appended body is set as the response's body.

This operation is performed in amortized constant time, and so should always be preferred to reading an entire body and then writing the same contents to another body.

This method should be used when combining bodies that have not necessarily been read yet, such as a body returned from a backend response. To append contents that are already in memory as strings or bytes, use get_body_mut() to write the contents to the end of the body.

Examples

let mut resp = Response::from_body("hello! backend says: ");
let backend_resp = Request::get("https://example.com/").send("example_backend")?;
resp.append_body(backend_resp.into_body());
resp.send_to_client();

Add a response header with given value.

Unlike set_header(), this does not discard existing values for the same header name.

Argument type conversion

The header name and value arguments can be any types that implement ToHeaderName and ToHeaderValue, respectively. See those traits for details on which types can be used and when panics may arise during conversion.

Examples

1
2
3
4
5
6
7
8
9
10
11

let mut resp = Response::new();

resp.set_header("hello", "world!");
assert_eq!(resp.get_header_str("hello"), Some("world!"));

resp.append_header("hello", "universe!");

let values = resp.get_header_all_str("hello");
assert_eq!(values.len(), 2);
assert!(values.contains(&"world!"));
assert!(values.contains(&"universe!"));

Clone this response by reading in its body, and then writing the same body to the original and the cloned response.

This method requires mutable access to this response because reading from and writing to the body can involve an HTTP connection.

This operation is potentially expensive if the body is large. Take care when using this method on bodies with unknown sizes. Consider using methods like BufRead::lines() or Body::read_chunks() to incrementally process a body while limiting the maximum size.

Examples

1
2
3
4
5
6
7
8

let mut original = Response::from_body("hello")
    .with_header("hello", "world!")
    .with_status(418);
let mut new = original.clone_with_body();
assert_eq!(original.get_header("hello"), new.get_header("hello"));
assert_eq!(original.get_status(), new.get_status());
assert_eq!(original.get_version(), new.get_version());
assert_eq!(original.take_body_bytes(), new.take_body_bytes());

Make a new response with the same headers, status, and version of this response, but no body.

If you also need to clone the response body, use clone_with_body()

Examples

1
2
3
4
5
6
7
8
9

let original = Response::from_body("hello")
    .with_header("hello", "world!")
    .with_status(418);
let new = original.clone_without_body();
assert_eq!(original.get_header("hello"), new.get_header("hello"));
assert_eq!(original.get_status(), new.get_status());
assert_eq!(original.get_version(), new.get_version());
assert!(original.has_body());
assert!(!new.has_body());

Returns whether the given header name is present in the response.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

let resp = Response::new().with_header("hello", "world!");
assert!(resp.contains_header("hello"));
assert!(!resp.contains_header("not-present"));

Create a new Response with the given value as the body.

Argument type conversion

See the From impls for Body to see which types can be used as a body.

Examples

let resp = Response::from_body("hello");
assert_eq!(&resp.into_body_str(), "hello");

let body_bytes: &[u8] = &[1, 2, 3];
let resp = Response::from_body(body_bytes);
assert_eq!(resp.into_body_bytes().as_slice(), body_bytes);

Create a Response from the a ResponseHandle and a BodyHandle.

The extra metadata associated with a backend response is not tracked by the low-level handle APIs. As a result, methods like get_backend() and get_backend_request() will always return None for a request created from handles.

Create a new response with the given status code.

Argument type conversion

See the From impls for Body to see which types can be used as a body.

Examples

use fastly::http::StatusCode;
let resp = Response::from_status(StatusCode::NOT_FOUND);
assert_eq!(resp.get_status().as_u16(), 404);

use fastly::http::StatusCode;
let resp = Response::from_status(404);
assert_eq!(resp.get_status(), StatusCode::NOT_FOUND);

The current age of the response, if it is cached.

Returns None if the response is not cached.

Get the backend this response came from, or None if the response is synthetic.

Examples

From a backend response:

let backend_resp = Request::get("https://example.com/").send("example_backend")?;
assert_eq!(backend_resp.get_backend().map(|b| b.name()), Some("example_backend"));

From a synthetic response:

let synthetic_resp = Response::new();
assert!(synthetic_resp.get_backend().is_none());

Get the address of the backend this response came from, or None when the response is synthetic or cached.

Examples

From a backend response:

let backend_resp = Request::get("https://example.com/")
    .with_pass(true)
    .send("example_backend")?;
assert_eq!(backend_resp.get_backend_addr(), Some(&"127.0.0.1:443".parse::<SocketAddr>().unwrap()));

From a synthetic response:

let synthetic_resp = Response::new();
assert!(synthetic_resp.get_backend_addr().is_none());

Get the name of the Backend this response came from, or None if the response is synthetic.

Examples

From a backend response:

let backend_resp = Request::get("https://example.com/").send("example_backend")?;
assert_eq!(backend_resp.get_backend_name(), Some("example_backend"));
Ok(()) }

From a synthetic response:

let synthetic_resp = Response::new();
assert!(synthetic_resp.get_backend_name().is_none());

Get the request this response came from, or None if the response is synthetic.

Note that the returned request will only have the headers and metadata of the original request, as the body is consumed when sending the request.

This method only returns a reference to the backend request. To instead take and return the owned request (for example, to subsequently send the request again), use take_backend_request().

Examples

From a backend response:

let backend_resp = Request::post("https://example.com/")
    .with_body("hello")
    .send("example_backend")?;
let backend_req = backend_resp.get_backend_request().expect("response is not synthetic");
assert_eq!(backend_req.get_url_str(), "https://example.com/");
assert!(!backend_req.has_body());

From a synthetic response:

let synthetic_resp = Response::new();
assert!(synthetic_resp.get_backend_request().is_none());

Get a mutable reference to the body of this response.

An empty body is returned if no body has been set, or if it has previously been returned by a method like take_body().

Examples

use std::io::Write;

let mut resp = Response::from_body("hello,");
write!(resp.get_body_mut(), " world!")?;
assert_eq!(&resp.into_body_str(), "hello, world!");

Get a prefix of this response's body containing up to the given number of bytes.

See Body::get_prefix_mut() for details.

Get a prefix of this response's body as a string containing up to the given number of bytes.

See Body::get_prefix_str_mut() for details.

Panics

If the prefix contains invalid UTF-8 bytes, this function will panic. The exception to this is if the bytes are invalid because a multi-byte codepoint is cut off by the requested prefix length. In this case, the invalid bytes are left off the end of the prefix.

To explicitly handle the possibility of invalid UTF-8 bytes, use try_get_body_prefix_str_mut(), which returns an error on failure rather than panicking.

Get the MIME type described by the response's Content-Type header, or None if that header is absent or contains an invalid MIME type.

Examples

let resp = Response::new().with_body_text_plain("hello, world!");
assert_eq!(resp.get_content_type(), Some(fastly::mime::TEXT_PLAIN_UTF_8));

Get the value of a header, or None if the header is not present.

If there are multiple values for the header, only one is returned, which may be any of the values. See get_header_all() if you need to get all of the values.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

Handling UTF-8 values explicitly:

let resp = Response::new().with_header("hello", "world!");
assert_eq!(resp.get_header("hello"), Some(&HeaderValue::from_static("world")));

Safely handling invalid UTF-8 values:

let invalid_utf8 = &"🐈".as_bytes()[0..3];
let resp = Response::new().with_header("hello", invalid_utf8);
assert_eq!(resp.get_header("hello").unwrap().as_bytes(), invalid_utf8);

Get an iterator of all the values of a header.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

You can turn the iterator into collection, like Vec:

1
2
3
4
5
6
7
8
9

let invalid_utf8 = &"🐈".as_bytes()[0..3];
let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("hello", invalid_utf8);

let values: Vec<&HeaderValue> = resp.get_header_all("hello").collect();
assert_eq!(values.len(), 2);
assert!(values.contains(&&HeaderValue::from_static("world!")));
assert!(values.contains(&&HeaderValue::from_bytes(invalid_utf8).unwrap()));

You can use the iterator in a loop:

1
2
3
4
5
6
7
8
9
10
11
12

let invalid_utf8 = &"🐈".as_bytes()[0..3];
let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("hello", invalid_utf8);

for value in resp.get_header_all("hello") {
    if let Ok(s) = std::str::from_utf8(value.as_bytes()) {
        println!("hello, {}", s);
    } else {
        println!("hello, invalid UTF-8!");
    }
}

Get all values of a header as strings, or an empty vector if the header is not present.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Panics

This method panics if any of the header values are not valid UTF-8 strings. To handle the possibility of non-UTF-8 data, use get_header_all_str_lossy() for lossy conversion, or use get_header_all() and then convert the bytes with std::str::from_utf8().

Examples

let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("hello", "universe!");
let values = resp.get_header_all_str("hello");
assert_eq!(values.len(), 2);
assert!(values.contains(&"world!"));
assert!(values.contains(&"universe!"));

Get all values of a header as strings, including invalid characters, or an empty vector if the header is not present.

Only the valid UTF-8 characters present are returned. Invalid UTF-8 characters are replaced with U+FFFD REPLACEMENT CHARACTER.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

1
2
3
4
5
6
7
8
9

let world_value = HeaderValue::from_bytes(b"\xF0\x90\x80 world!").unwrap();
let universe_value = HeaderValue::from_bytes(b"\xF0\x90\x80 universe!").unwrap();
let resp = Response::new()
    .with_header("hello", world_value)
    .with_header("hello", universe_value);
let values = resp.get_header_all_str_lossy("hello");
assert_eq!(values.len(), 2);
assert!(values.contains(&Cow::from("� world!")));
assert!(values.contains(&Cow::from("� universe!")));

Get an iterator of all the response's header names.

Examples

You can turn the iterator into a collection, like Vec:

1
2
3
4
5
6
7
8

let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("goodbye", "latency!");

let values: Vec<&HeaderName> = resp.get_header_names().collect();
assert_eq!(values.len(), 2);
assert!(values.contains(&&HeaderName::from_static("hello")));
assert!(values.contains(&&HeaderName::from_static("goodbye")));

You can use the iterator in a loop:

let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("goodbye", "latency!");

for name in resp.get_header_names() {
    println!("saw header: {:?}", name);
}

Get all of the response's header names as strings, or an empty vector if no headers are present.

Examples

let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("goodbye", "latency!");
let names = resp.get_header_names_str();
assert_eq!(names.len(), 2);
assert!(names.contains(&"hello"));
assert!(names.contains(&"goodbye"));

Get the value of a header as a string, or None if the header is not present.

If there are multiple values for the header, only one is returned, which may be any of the values. See get_header_all_str() if you need to get all of the values.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Panics

This method panics if the value of the header is not a valid UTF-8 string. To handle the possibility of invalid UTF-8 data, use get_header_str_lossy() for lossy conversion, or use get_header() and then convert the bytes with std::str::from_utf8().

Examples

let resp = Response::new().with_header("hello", "world!");
assert_eq!(resp.get_header_str("hello"), Some("world"));

Get the value of a header as a string, including invalid characters, or None if the header is not present.

Only the valid UTF-8 characters present are returned. Invalid UTF-8 characters are replaced with U+FFFD REPLACEMENT CHARACTER.

If there are multiple values for the header, only one is returned, which may be any of the values. See get_header_all_str_lossy() if you need to get all of the values.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

let header_value = HeaderValue::from_bytes(b"\xF0\x90\x80 world!").unwrap();
let resp = Response::new().with_header("hello", header_value);
assert_eq!(resp.get_header_str_lossy("hello"), Some(Cow::from("� world")));

Get an iterator of all the response's header names and values.

Examples

You can turn the iterator into a collection, like Vec:

1
2
3
4
5
6
7
8

let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("hello", "universe!");

let headers: Vec<(&HeaderName, &HeaderValue)> = resp.get_headers().collect();
assert_eq!(headers.len(), 2);
assert!(headers.contains(&(&HeaderName::from_static("hello"), &HeaderValue::from_static("world!"))));
assert!(headers.contains(&(&HeaderName::from_static("hello"), &HeaderValue::from_static("universe!"))));

You can use the iterator in a loop:

let resp = Response::new()
    .with_header("hello", "world!")
    .with_header("hello", "universe!");

for (n, v) in resp.get_headers() {
    println!("Header -  {}: {:?}", n, v);
}

Gets the time for which the response can safely be used if (synchronous) revalidation produces an error.

This time is relative to the start of the "stale" period; that is, it matches the meaning of the Cache-Control: stale-if-error= directive in RFC 5861. See Fastly's documentation on HTTP caching for more details.

Returns None if the response is not cached.

The time for which the response can safely be used despite being considered stale, if it is cached.

This time is relative to the start of the "stale" period; that is, it matches the meaning of the Cache-Control: stale-while-revalidate= directive in RFC 5861. See Fastly's documentation on HTTP caching for more details.

Returns None if the response is not cached.

Get the Time to Live (TTL) in the cache for this response, if it is cached.

The TTL provides the duration of "freshness" for the cached response after it is inserted into the cache. If the response is stale, the TTL is 0 (i.e. this returns Some(0).

Returns None if the response is not cached.

Consume the response and return its body.

An empty body is returned if no body has been set, or if it has previously been returned by a method like take_body().

Consume the response and return its body as a byte vector.

Memory usage

This method will cause the entire body to be buffering in WebAssembly memory. You should take care not to exceed the WebAssembly memory limits, and consider using methods like read_body_lines() or read_body_chunks() to control how much of the body you process at once.

Examples

let resp = Response::from_body("hello, world!");
let bytes = resp.into_body_bytes();
assert_eq!(&bytes, b"hello, world!");

Consume the response and return its body as a string.

Memory usage

This method will cause the entire body to be buffering in WebAssembly memory. You should take care not to exceed the WebAssembly memory limits, and consider using methods like read_body_lines() or read_body_chunks() to control how much of the body you process at once.

Panics

If the body does not contain a valid UTF-8 string, this function will panic. To explicitly handle the possibility of invalid UTF-8 data, use into_body_str_lossy() for lossy conversion, or use into_body_bytes() and then convert the bytes explicitly with a function like String::from_utf8.

Examples

let resp = Response::from_body("hello, world!");
let string = resp.into_body_str();
assert_eq!(&string, "hello, world!");

Consume the response and return its body as a string, including invalid characters.

Only the valid UTF-8 characters present are returned. Invalid UTF-8 characters are replaced with U+FFFD REPLACEMENT CHARACTER.

Memory usage

This method will cause the entire body to be buffering in WebAssembly memory. You should take care not to exceed the WebAssembly memory limits, and consider using methods like read_body_lines() or read_body_chunks() to control how much of the body you process at once.

Examples

let mut resp = Response::new();
resp.set_body_octet_stream(b"\xF0\x90\x80 hello, world!");
let string = resp.into_body_str_lossy();
assert_eq!(&string, "� hello, world!");

Create a ResponseHandle/BodyHandle pair from a Response.

The extra metadata associated with a backend response is not tracked by the low-level handle APIs. As a result, converting to handles will cause the backend and request associated with a backend response to be lost.

Create a new Response.

The new response is created with status code 200 OK, no headers, and an empty body.

Return an iterator that reads the response body in chunks of at most the given number of bytes.

If chunk_size does not evenly divide the length of the body, then the last chunk will not have length chunk_size.

Examples

1
2
3
4
5
6
7
8
9
10
11

use std::io::Write;
fn remove_0s(resp: &mut Response) -> Result<(), Box<dyn std::error::Error>>  {
    let mut no_0s = Body::new();
    for chunk in resp.read_body_chunks(4096) {
        let mut chunk = chunk?;
        chunk.retain(|b| *b != 0);
        no_0s.write_all(&chunk)?;
    }
    resp.set_body(no_0s);
    Ok(())
}

Return a Lines iterator that reads the response body a line at a time.

Examples

1
2
3
4
5
6
7
8
9
10

use std::io::Write;

fn remove_es(resp: &mut Response) -> Result<(), Box<dyn std::error::Error>>  {
    let mut no_es = Body::new();
    for line in resp.read_body_lines() {
        writeln!(no_es, "{}", line?.replace("e", ""))?;
    }
    resp.set_body(no_es);
    Ok(())
}

Create a 308 Permanent Redirect response with the given value as the Location header.

Examples

let resp = Response::redirect("https://www.fastly.com");
assert_eq!(resp.get_status(), StatusCode::PERMANENT_REDIRECT);
assert_eq!(resp.get_header_str(header::LOCATION).unwrap(), "https://www.fastly.com");

Remove all response headers of the given name, and return one of the removed header values if any were present.

If the header has multiple values, one is returned arbitrarily. To get all of the removed header values, or to get a specific value, use get_header_all().

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

let mut resp = Response::new().with_header("hello", "world!");
assert_eq!(resp.get_header_str("hello"), Some("world!"));
assert_eq!(resp.remove_header("hello"), Some(HeaderValue::from_static("world!")));
assert!(resp.remove_header("not-present").is_none());

Remove all response headers of the given name, and return one of the removed header values as a string if any were present.

If the header has multiple values, one is returned arbitrarily. To get all of the removed header values, use get_header_all() before removing.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Panics

This method panics if the value of the header is not a valid UTF-8 string. To handle the possibility of invalid UTF-8 data, use remove_header_str_lossy() for lossy conversion, or use remove_header() and then convert the bytes with std::str::from_utf8().

Examples

let mut resp = Response::new().with_header("hello", "world!");
assert_eq!(resp.get_header_str("hello"), Some("world!"));
assert_eq!(resp.remove_header_str("hello"), Some("world!".to_string()));
assert!(resp.remove_header_str("not-present").is_none());

Remove all response headers of the given name, and return one of the removed header values as a string, including invalid characters, if any were present.

Only the valid UTF-8 characters present are returned. Invalid UTF-8 characters are replaced with U+FFFD REPLACEMENT CHARACTER.

If the header has multiple values, one is returned arbitrarily. To get all of the removed header values, use get_header_all() before removing.

Argument type conversion

The header name argument can be any type that implements ToHeaderName; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

let header_value = HeaderValue::from_bytes(b"\xF0\x90\x80 world!").unwrap();
let mut resp = Response::new().with_header("hello", header_value);
assert_eq!(resp.get_header_str_lossy("hello"), Some(Cow::from("� world")));
assert_eq!(resp.remove_header_str_lossy("hello"), Some(String::from("� world")));
assert!(resp.remove_header_str_lossy("not-present").is_none());

Create a 303 See Other response with the given value as the Location header.

Examples

let resp = Response::see_other("https://www.fastly.com");
assert_eq!(resp.get_status(), StatusCode::SEE_OTHER);
assert_eq!(resp.get_header_str(header::LOCATION).unwrap(), "https://www.fastly.com");

Begin sending a response to the client.

This method returns as soon as the response header begins sending to the client, and transmission of the response will continue in the background.

This method may be used to send 103 Early Hints responses to the client. Any number of 103 Early Hints responses may be sent before sending the final response. Any response with status code other than 103 will be treated as the final response.

Once this method is called with a final response, nothing else may be added to the response body. To stream additional data to a response body after it begins to send, use stream_to_client.

Panics

This method panics if any response with status code other than 103 has already been sent to the client by this method, by stream_to_client(), or by the equivalent methods of ResponseHandle.

Compatibility with fastly::main

This method cannot be used to send final responses with fastly::main, as that attribute implicitly calls Response::send_to_client() on the returned response. Use an undecorated main() function instead, along with Request::from_client() if the client request is needed.

Examples

Sending a backend response without modification:

Request::get("https://example.com/").send("example_backend")?.send_to_client();

Removing a header from a backend response before sending to the client:

let mut backend_resp = Request::get("https://example.com/").send("example_backend")?;
backend_resp.remove_header("bad-header");
backend_resp.send_to_client();

Sending a synthetic response:

Response::from_body("hello, world!").send_to_client();

Sending 103 Early Hints responses followed by forwarding a final response from a backend:

1
2
3
4
5
6
7
8

use fastly::{Error, Request, Response};
#[fastly::main]
fn main(ds_req: Request) -> Result<Response, Error> {
    let early_hint = Response::from_status(103)
       .with_header("Link", "</script.js>; rel=preload; as=scrypt");
    early_hint.send_to_client();
    Ok(ds_req.send("example_backend")?)
}

Set the given value as the response's body.

Argument type conversion

See the From impls for Body to see which types can be used as a body. Any previous body that may have been set on the response is discarded. To add to an existing body, use get_body_mut() and write to the returned Body.

Convert the given value to application/x-www-form-urlencoded format and set that data as the response's body.

The given value must implement serde::Serialize; see the trait documentation for details.

Any previous body that may have been set on the response is discarded. To add to an existing body, use get_body_mut() and write to the returned Body.

Content type

This method sets the content type to application/x-www-form-urlencoded.

Errors

This method returns serde_urlencoded::ser::Error if serialization fails.

Examples

1
2
3
4
5
6
7
8
9
10

#[derive(serde::Serialize)]
struct MyData {
    name: String,
    count: u64,
}
let my_data = MyData { name: "Computers".to_string(), count: 1024 };
let mut resp = Response::new();
resp.set_body_form(&my_data).unwrap();
assert_eq!(resp.get_content_type(), Some(fastly::mime::APPLICATION_WWW_FORM_URLENCODED));
assert_eq!(&resp.into_body_str(), "name=Computers&count=1024");

Convert the given value to JSON and set that JSON as the response's body.

The given value must implement serde::Serialize. You can either implement that trait for your own custom type, or use serde_json::Value to create untyped JSON values. See serde_json for details.

Any previous body that may have been set on the response is discarded. To add to an existing body, use get_body_mut() and write to the returned Body.

Content type

This method sets the content type to application/json.

Errors

This method returns serde_json::Error if serialization fails.

Examples

Using a type that derives serde::Serialize:

1
2
3
4
5
6
7
8
9
10

#[derive(serde::Serialize)]
struct MyData {
    name: String,
    count: u64,
}
let my_data = MyData { name: "Computers".to_string(), count: 1024 };
let mut resp = Response::new();
resp.set_body_json(&my_data).unwrap();
assert_eq!(resp.get_content_type(), Some(fastly::mime::APPLICATION_JSON));
assert_eq!(&resp.into_body_str(), r#"{"name":"Computers","count":1024}"#);

Using untyped JSON and the serde_json::json macro:

1
2
3
4
5
6
7
8

let my_data = serde_json::json!({
    "name": "Computers",
    "count": 1024,
});
let mut resp = Response::new();
resp.set_body_json(&my_data).unwrap();
assert_eq!(resp.get_content_type(), Some(fastly::mime::APPLICATION_JSON));
assert_eq!(&resp.into_body_str(), r#"{"count":1024,"name":"Computers"}"#);

Set the given bytes as the response's body.

Any previous body that may have been set on the response is discarded. To add to an existing body, use get_body_mut() and write to the returned Body.

Content type

This method sets the content type to application/octet-stream.

Examples

let mut resp = Response::new();
resp.set_body_octet_stream(b"hello, world!");
assert_eq!(resp.get_content_type(), Some(fastly::mime::APPLICATION_OCTET_STREAM));
assert_eq!(&resp.into_body_bytes(), b"hello, world!");

Set the given string as the response's body with content type text/html; charset=UTF-8.

Any previous body that may have been set on the response is discarded. To add to an existing body, use get_body_mut() and write to the returned Body.

Content type

This method sets the content type to text/html; charset=utf-8.

Examples

let mut resp = Response::new();
resp.set_body_text_html("<p>hello, world!</p>");
assert_eq!(resp.get_content_type(), Some(fastly::mime::TEXT_HTML_UTF_8));
assert_eq!(&resp.into_body_str(), "<p>hello, world!</p>");

Set the given string as the response's body with content type text/plain; charset=UTF-8.

Any previous body that may have been set on the response is discarded. To add to an existing body, use get_body_mut() and write to the returned Body.

Content type

This method sets the content type to text/plain; charset=utf-8.

Examples

let mut resp = Response::new();
resp.set_body_text_plain("hello, world!");
assert_eq!(resp.get_content_type(), Some(fastly::mime::TEXT_PLAIN_UTF_8));
assert_eq!(&resp.into_body_str(), "hello, world!");

Set the MIME type described by the response's Content-Type header.

Any existing Content-Type header values will be overwritten.

Examples

let mut resp = Response::new().with_body("hello,world!");
resp.set_content_type(fastly::mime::TEXT_CSV_UTF_8);

Sets how Content-Length and Transfer-Encoding will be determined when sending this response.

See FramingHeadersMode for details on the options.

Set a response header to the given value, discarding any previous values for the given header name.

Argument type conversion

The header name and value arguments can be any types that implement ToHeaderName and ToHeaderValue, respectively. See those traits for details on which types can be used and when panics may arise during conversion.

Examples

1
2
3
4
5
6
7
8
9
10
11

let mut resp = Response::new();

resp.set_header("hello", "world!");
assert_eq!(resp.get_header_str("hello"), Some("world!"));

resp.set_header("hello", "universe!");

let values = resp.get_header_all_str("hello");
assert_eq!(values.len(), 1);
assert!(!values.contains(&"world!"));
assert!(values.contains(&"universe!"));

Set the HTTP status code of the response.

Argument type conversion

The status code argument can be any type that implements ToStatusCode; see that trait for details on which types can be used and when panics may arise during conversion.

Examples

Using the constants from StatusCode:

use fastly::http::StatusCode;

let mut resp = Response::from_body("not found!");
resp.set_status(StatusCode::NOT_FOUND);
resp.send_to_client();

Using a u16:

let mut resp = Response::from_body("not found!");
resp.set_status(404);
resp.send_to_client();

Begin sending the response to the client, and return a StreamingBody that can accept further data to send.

The client connection must be closed when finished writing the response by calling StreamingBody::finish().

This method is most useful for programs that do some sort of processing or inspection of a potentially-large backend response body. Streaming allows the program to operate on small parts of the body rather than having to read it all into memory at once.

This method returns as soon as the response header begins sending to the client, and transmission of the response will continue in the background.

Panics

This method panics if another response has already been sent to the client by this method, by send_to_client(), or by the equivalent methods of ResponseHandle.

Compatibility with fastly::main

This method cannot be used to send final responses with fastly::main, as that attribute implicitly calls Response::send_to_client() on the returned response. Use an undecorated main() function instead, along with Request::from_client() if the client request is needed.

Examples

Count the number of lines in a UTF-8 backend response body while sending it to the client:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use std::io::{BufRead, Write};

let mut backend_resp = Request::get("https://example.com/").send("example_backend")?;
// Take the body so we can iterate through its lines later
let backend_resp_body = backend_resp.take_body();
// Start sending the backend response to the client with a now-empty body
let mut client_body = backend_resp.stream_to_client();

let mut num_lines = 0;
for line in backend_resp_body.lines() {
    let line = line?;
    num_lines += 1;
    // Write the line to the streaming client body
    client_body.write_all(line.as_bytes())?;
}
// Finish the streaming body to close the client connection
client_body.finish()?;

println!("backend response body contained {} lines", num_lines);

Take and return the request this response came from, or None if the response is synthetic.

Note that the returned request will only have the headers and metadata of the original request, as the body is consumed when sending the request.

Examples

From a backend response:

let mut backend_resp = Request::post("https://example.com/")
    .with_body("hello")
    .send("example_backend")?;
let backend_req = backend_resp.take_backend_request().expect("response is not synthetic");
assert_eq!(backend_req.get_url_str(), "https://example.com/");
assert!(!backend_req.has_body());
backend_req.with_body("goodbye").send("example_backend")?;

From a synthetic response:

let mut synthetic_resp = Response::new();
assert!(synthetic_resp.take_backend_request().is_none());

Take and return the body from this response.

After calling this method, this response will no longer have a body.

An empty body is returned if no body has been set, or if it has previously been returned by a method like take_body().

Take and return the body from this response as a string.

After calling this method, this response will no longer have a body.

Memory usage

This method will cause the entire body to be buffering in WebAssembly memory. You should take care not to exceed the WebAssembly memory limits, and consider using methods like read_body_lines() or read_body_chunks() to control how much of the body you process at once.

Examples

let mut resp = Response::from_body("hello, world!");
let bytes = resp.take_body_bytes();
assert!(resp.try_take_body().is_none());
assert_eq!(&bytes, b"hello, world!");

Take the response body and attempt to parse it as a application/x-www-form-urlencoded formatted string.

The return type chosen for this function must implement serde::de::Deserialize without any non-static lifetimes; see the trait documentation for details.

After calling this method, this response will no longer have a body.

Errors

This method returns serde_urlencoded::de::Error if deserialization fails.

Examples

1
2
3
4
5
6
7
8
9

#[derive(serde::Deserialize)]
struct MyData {
    name: String,
    count: u64,
}
let mut resp = Response::from_body("name=Computers&count=1024");
let my_data = resp.take_body_form::<MyData>().unwrap();
assert_eq!(&my_data.name, "Computers");
assert_eq!(my_data.count, 1024);

Take the response body and attempt to parse it as a JSON value.

The return type must implement serde::Deserialize without any non-static lifetimes. You can either implement that trait for your own custom type, or use serde_json::Value to deserialize untyped JSON values. See serde_json for details.

After calling this method, this response will no longer have a body.

Errors

This method returns serde_json::Error if deserialization fails.

Examples

Using a type that derives serde::de::DeserializeOwned:

1
2
3
4
5
6
7
8
9

#[derive(serde::Deserialize)]
struct MyData {
    name: String,
    count: u64,
}
let mut resp = Response::from_body(r#"{"name":"Computers","count":1024}"#);
let my_data = resp.take_body_json::<MyData>().unwrap();
assert_eq!(&my_data.name, "Computers");
assert_eq!(my_data.count, 1024);

Using untyped JSON with serde_json::Value:

1
2
3
4
5
6
7
8

let my_data = serde_json::json!({
    "name": "Computers",
    "count": 1024,
});
let mut resp = Response::from_body(r#"{"name":"Computers","count":1024}"#);
let my_data = resp.take_body_json::<serde_json::Value>().unwrap();
assert_eq!(my_data["name"].as_str(), Some("Computers"));
assert_eq!(my_data["count"].as_u64(), Some(1024));

Take and return the body from this response as a string.

After calling this method, this response will no longer have a body.

Memory usage

This method will cause the entire body to be buffering in WebAssembly memory. You should take care not to exceed the WebAssembly memory limits, and consider using methods like read_body_lines() or read_body_chunks() to control how much of the body you process at once.

Panics

If the body does not contain a valid UTF-8 string, this function will panic. To handle the possibility of invalid UTF-8 data, use take_body_str_lossy() for lossy conversion, or use take_body_bytes() and then convert the bytes with a function like String::from_utf8.

Examples

let mut resp = Response::from_body("hello, world!");
let string = resp.take_body_str();
assert!(resp.try_take_body().is_none());
assert_eq!(&string, "hello, world!");

Take and return the body from this response as a string, including invalid characters.

Only the valid UTF-8 characters present are returned. Invalid UTF-8 characters are replaced with U+FFFD REPLACEMENT CHARACTER.

After calling this method, this response will no longer have a body.

Memory usage

This method will cause the entire body to be buffering in WebAssembly memory. You should take care not to exceed the WebAssembly memory limits, and consider using methods like read_body_lines() or read_body_chunks() to control how much of the body you process at once.

Examples

let mut resp = Response::new();
resp.set_body_octet_stream(b"\xF0\x90\x80 hello, world!");
let string = resp.take_body_str_lossy();
assert!(resp.try_take_body().is_none());
assert_eq!(&string, "� hello, world!");

If this Response represents a stale-if-error response, returns the SendError that this response replaced. If this Response is not a stale-if-error response from cache, returns None.

This also returns None if Response::takebackendrequest was called previously. (The SendError includes the backend request.)

Create a 307 Temporary Redirect response with the given value as the Location header.

Examples

let resp = Response::temporary_redirect("https://www.fastly.com");
assert_eq!(resp.get_status(), StatusCode::TEMPORARY_REDIRECT);
assert_eq!(resp.get_header_str(header::LOCATION).unwrap(), "https://www.fastly.com");

Get a shared reference to the body of this response if it has one, otherwise return None.

Examples

1
2
3
4
5
6
7
8

use std::io::Write;

let mut resp = Response::new();
assert!(resp.try_get_body_mut().is_none());

resp.set_body("hello,");
write!(resp.try_get_body_mut().expect("body now exists"), " world!")?;
assert_eq!(&resp.into_body_str(), "hello, world!");

Try to get a prefix of the body as a string containing up to the given number of bytes.

See Body::try_get_prefix_str_mut() for details.

Take and return the body from this response if it has one, otherwise return None.

After calling this method, this response will no longer have a body.