pub struct Response { /* private fields */ }
Expand description
An HTTP response, including body, headers, and status code.
Sending to the client
Each execution of a Compute@Edge program may send a single response back to the client:
If no response is explicitly sent by the program, a default 200 OK
response is sent.
Creation and conversion
Responses can be created programmatically:
Responses are also returned from backend requests:
For interoperability with other Rust libraries, Response
can be converted to and from the
http
crate’s http::Response
type using the From
and
Into
traits.
Builder-style methods
Response
can be used as a
builder, allowing responses to
be constructed and used through method chaining. Methods with the with_
name prefix, such as
with_header()
, return Self
to allow chaining. The builder style is
typically most useful when constructing and using a response in a single expression. For
example:
Response::new()
.with_header("my-header", "hello!")
.with_header("my-other-header", "Здравствуйте!")
.send_to_client();
Setter methods
Setter methods, such as set_header()
, are prefixed by set_
, and can
be used interchangeably with the builder-style methods, allowing you to mix and match styles
based on what is most convenient for your program. Setter methods tend to work better than
builder-style methods when constructing a value involves conditional branches or loops. For
example:
let mut resp = Response::new().with_header("my-header", "hello!");
if needs_translation {
resp.set_header("my-other-header", "Здравствуйте!");
}
resp.send_to_client();
Implementations§
source§impl Response
impl Response
sourcepub fn new() -> Self
pub fn new() -> Self
Create a new Response
.
The new response is created with status code 200 OK
, no headers, and an empty body.
sourcepub fn is_from_backend(&self) -> bool
pub fn is_from_backend(&self) -> bool
Return whether the response is from a backend request.
sourcepub fn clone_without_body(&self) -> Response
pub fn clone_without_body(&self) -> Response
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
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());
sourcepub fn clone_with_body(&mut self) -> Response
pub fn clone_with_body(&mut self) -> Response
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
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());
sourcepub fn from_body(body: impl Into<Body>) -> Self
pub fn from_body(body: impl Into<Body>) -> Self
Create a new Response
with the given value as the body.
Argument type conversion.
See Body
for details on 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);
sourcepub fn from_status(status: impl ToStatusCode) -> Self
pub fn from_status(status: impl ToStatusCode) -> Self
Create a new response with the given status code.
Argument type conversion.
See Body
for details on 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);
sourcepub fn see_other(destination: impl ToHeaderValue) -> Self
pub fn see_other(destination: impl ToHeaderValue) -> Self
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");
sourcepub fn redirect(destination: impl ToHeaderValue) -> Self
pub fn redirect(destination: impl ToHeaderValue) -> Self
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");
sourcepub fn temporary_redirect(destination: impl ToHeaderValue) -> Self
pub fn temporary_redirect(destination: impl ToHeaderValue) -> Self
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");
sourcepub fn with_body(self, body: impl Into<Body>) -> Self
pub fn with_body(self, body: impl Into<Body>) -> Self
Builder-style equivalent of set_body()
.
sourcepub fn get_body_mut(&mut self) -> &mut Body ⓘ
pub fn get_body_mut(&mut self) -> &mut Body ⓘ
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!").unwrap();
assert_eq!(&resp.into_body_str(), "hello, world!");
sourcepub fn try_get_body_mut(&mut self) -> Option<&mut Body>
pub fn try_get_body_mut(&mut self) -> Option<&mut Body>
Get a shared reference to the body of this response if it has one, otherwise return None
.
Examples
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!").unwrap();
assert_eq!(&resp.into_body_str(), "hello, world!");
sourcepub fn get_body_prefix_mut(&mut self, length: usize) -> Prefix<'_>
pub fn get_body_prefix_mut(&mut self, length: usize) -> Prefix<'_>
Get a prefix of this response’s body containing up to the given number of bytes.
See Body::get_prefix_mut()
for details.
sourcepub fn get_body_prefix_str_mut(&mut self, length: usize) -> PrefixString<'_>
pub fn get_body_prefix_str_mut(&mut self, length: usize) -> PrefixString<'_>
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.
sourcepub fn try_get_body_prefix_str_mut(
&mut self,
length: usize
) -> Result<PrefixString<'_>, Utf8Error>
pub fn try_get_body_prefix_str_mut(
&mut self,
length: usize
) -> Result<PrefixString<'_>, Utf8Error>
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.
sourcepub fn set_body(&mut self, body: impl Into<Body>)
pub fn set_body(&mut self, body: impl Into<Body>)
Set the given value as the response’s body.
Argument type conversion.
See Body
for details on 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
.
sourcepub fn take_body(&mut self) -> Body ⓘ
pub fn take_body(&mut self) -> Body ⓘ
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()
.
sourcepub fn try_take_body(&mut self) -> Option<Body>
pub fn try_take_body(&mut self) -> Option<Body>
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.
sourcepub fn append_body(&mut self, other: Body)
pub fn append_body(&mut self, other: Body)
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").unwrap();
resp.append_body(backend_resp.into_body());
resp.send_to_client();
sourcepub fn into_body_bytes(self) -> Vec<u8> ⓘ
pub fn into_body_bytes(self) -> Vec<u8> ⓘ
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(b"hello, world!".to_vec());
let bytes = resp.into_body_bytes();
assert_eq!(&bytes, b"hello, world!");
sourcepub fn into_body_str(self) -> String
pub fn into_body_str(self) -> String
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!");
sourcepub fn into_body_str_lossy(self) -> String
pub fn into_body_str_lossy(self) -> String
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!");
sourcepub fn into_body(self) -> Body ⓘ
pub fn into_body(self) -> Body ⓘ
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()
.
sourcepub fn try_into_body(self) -> Option<Body>
pub fn try_into_body(self) -> Option<Body>
Consume the response and return its body if it has one, otherwise return None
.
sourcepub fn with_body_text_plain(self, body: &str) -> Self
pub fn with_body_text_plain(self, body: &str) -> Self
Builder-style equivalent of set_body_text_plain()
.
sourcepub fn set_body_text_plain(&mut self, body: &str)
pub fn set_body_text_plain(&mut self, body: &str)
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!");
sourcepub fn with_body_text_html(self, body: &str) -> Self
pub fn with_body_text_html(self, body: &str) -> Self
Builder-style equivalent of set_body_text_html()
.
sourcepub fn set_body_text_html(&mut self, body: &str)
pub fn set_body_text_html(&mut self, body: &str)
Set the given string as the request’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>");
sourcepub fn take_body_str(&mut self) -> String
pub fn take_body_str(&mut self) -> String
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!");
sourcepub fn take_body_str_lossy(&mut self) -> String
pub fn take_body_str_lossy(&mut self) -> String
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!");
sourcepub fn read_body_lines(&mut self) -> Lines<&mut Body>
pub fn read_body_lines(&mut self) -> Lines<&mut Body>
sourcepub fn with_body_octet_stream(self, body: &[u8]) -> Self
pub fn with_body_octet_stream(self, body: &[u8]) -> Self
Builder-style equivalent of set_body_octet_stream()
.
sourcepub fn set_body_octet_stream(&mut self, body: &[u8])
pub fn set_body_octet_stream(&mut self, body: &[u8])
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!");
sourcepub fn take_body_bytes(&mut self) -> Vec<u8> ⓘ
pub fn take_body_bytes(&mut self) -> Vec<u8> ⓘ
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(b"hello, world!".to_vec());
let bytes = resp.take_body_bytes();
assert!(resp.try_take_body().is_none());
assert_eq!(&bytes, b"hello, world!");
sourcepub fn read_body_chunks<'a>(
&'a mut self,
chunk_size: usize
) -> impl Iterator<Item = Result<Vec<u8>, Error>> + 'a
pub fn read_body_chunks<'a>(
&'a mut self,
chunk_size: usize
) -> impl Iterator<Item = Result<Vec<u8>, Error>> + 'a
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
fn remove_0s(resp: &mut Response) {
let mut no_0s = Body::new();
for chunk in resp.read_body_chunks(4096) {
let mut chunk = chunk.unwrap();
chunk.retain(|b| *b != 0);
no_0s.write_bytes(&chunk);
}
resp.set_body(no_0s);
}
sourcepub fn with_body_json(self, value: &impl Serialize) -> Result<Self, Error>
pub fn with_body_json(self, value: &impl Serialize) -> Result<Self, Error>
Builder-style equivalent of set_body_json()
.
sourcepub fn set_body_json(&mut self, value: &impl Serialize) -> Result<(), Error>
pub fn set_body_json(&mut self, value: &impl Serialize) -> Result<(), Error>
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
:
#[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:
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"}"#);
sourcepub fn take_body_json<T: DeserializeOwned>(&mut self) -> Result<T, Error>
pub fn take_body_json<T: DeserializeOwned>(&mut self) -> Result<T, Error>
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
:
#[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
:
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));
sourcepub fn with_body_form(self, value: &impl Serialize) -> Result<Self, Error>
pub fn with_body_form(self, value: &impl Serialize) -> Result<Self, Error>
Builder-style equivalent of set_body_form()
.
sourcepub fn set_body_form(&mut self, value: &impl Serialize) -> Result<(), Error>
pub fn set_body_form(&mut self, value: &impl Serialize) -> Result<(), Error>
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
#[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");
sourcepub fn take_body_form<T: DeserializeOwned>(&mut self) -> Result<T, Error>
pub fn take_body_form<T: DeserializeOwned>(&mut self) -> Result<T, Error>
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
#[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);
sourcepub fn get_content_type(&self) -> Option<Mime>
pub fn get_content_type(&self) -> Option<Mime>
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));
sourcepub fn with_content_type(self, mime: Mime) -> Self
pub fn with_content_type(self, mime: Mime) -> Self
Builder-style equivalent of set_content_type()
.
sourcepub fn set_content_type(&mut self, mime: Mime)
pub fn set_content_type(&mut self, mime: Mime)
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);
sourcepub fn get_content_length(&self) -> Option<usize>
pub fn get_content_length(&self) -> Option<usize>
Get the value of the response’s
Content-Length
header, if it exists.
sourcepub fn contains_header(&self, name: impl ToHeaderName) -> bool
pub fn contains_header(&self, name: impl ToHeaderName) -> bool
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"));
sourcepub fn with_header(
self,
name: impl ToHeaderName,
value: impl ToHeaderValue
) -> Self
pub fn with_header(
self,
name: impl ToHeaderName,
value: impl ToHeaderValue
) -> Self
Builder-style equivalent of set_header()
.
sourcepub fn get_header_str<'a>(&self, name: impl ToHeaderName) -> Option<&str>
pub fn get_header_str<'a>(&self, name: impl ToHeaderName) -> Option<&str>
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
HeaderValue::to_str()
.
Examples
let resp = Response::new().with_header("hello", "world!");
assert_eq!(resp.get_header_str("hello"), Some("world"));
sourcepub fn get_header_str_lossy(
&self,
name: impl ToHeaderName
) -> Option<Cow<'_, str>>
pub fn get_header_str_lossy(
&self,
name: impl ToHeaderName
) -> Option<Cow<'_, str>>
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")));
sourcepub fn get_header<'a>(&self, name: impl ToHeaderName) -> Option<&HeaderValue>
pub fn get_header<'a>(&self, name: impl ToHeaderName) -> Option<&HeaderValue>
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);
sourcepub fn get_header_all_str<'a>(&self, name: impl ToHeaderName) -> Vec<&str> ⓘ
pub fn get_header_all_str<'a>(&self, name: impl ToHeaderName) -> Vec<&str> ⓘ
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
HeaderValue::to_str()
.
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!"));
sourcepub fn get_headers(&self) -> impl Iterator<Item = (&HeaderName, &HeaderValue)>
pub fn get_headers(&self) -> impl Iterator<Item = (&HeaderName, &HeaderValue)>
Get an iterator of all the response’s header names and values.
Examples
You can turn the iterator into a collection, like Vec
:
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);
}
sourcepub fn get_header_all_str_lossy(
&self,
name: impl ToHeaderName
) -> Vec<Cow<'_, str>> ⓘ
pub fn get_header_all_str_lossy(
&self,
name: impl ToHeaderName
) -> Vec<Cow<'_, str>> ⓘ
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
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!")));
sourcepub fn get_header_all<'a>(
&'a self,
name: impl ToHeaderName
) -> impl Iterator<Item = &'a HeaderValue>
pub fn get_header_all<'a>(
&'a self,
name: impl ToHeaderName
) -> impl Iterator<Item = &'a HeaderValue>
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
:
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:
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) = value.to_str() {
println!("hello, {}", s);
} else {
println!("hello, invalid UTF-8!");
}
}
sourcepub fn get_header_names_str(&self) -> Vec<&str> ⓘ
pub fn get_header_names_str(&self) -> Vec<&str> ⓘ
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"));
sourcepub fn get_header_names(&self) -> impl Iterator<Item = &HeaderName>
pub fn get_header_names(&self) -> impl Iterator<Item = &HeaderName>
Get an iterator of all the response’s header names.
Examples
You can turn the iterator into a collection, like Vec
:
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);
}
sourcepub fn set_header(&mut self, name: impl ToHeaderName, value: impl ToHeaderValue)
pub fn set_header(&mut self, name: impl ToHeaderName, value: impl ToHeaderValue)
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
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!"));
sourcepub fn append_header(
&mut self,
name: impl ToHeaderName,
value: impl ToHeaderValue
)
pub fn append_header(
&mut self,
name: impl ToHeaderName,
value: impl ToHeaderValue
)
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
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!"));
sourcepub fn remove_header(&mut self, name: impl ToHeaderName) -> Option<HeaderValue>
pub fn remove_header(&mut self, name: impl ToHeaderName) -> Option<HeaderValue>
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());
sourcepub fn remove_header_str(&mut self, name: impl ToHeaderName) -> Option<String>
pub fn remove_header_str(&mut self, name: impl ToHeaderName) -> Option<String>
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
HeaderValue::to_str()
.
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());
sourcepub fn remove_header_str_lossy(
&mut self,
name: impl ToHeaderName
) -> Option<String>
pub fn remove_header_str_lossy(
&mut self,
name: impl ToHeaderName
) -> Option<String>
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());
sourcepub fn with_status(self, status: impl ToStatusCode) -> Self
pub fn with_status(self, status: impl ToStatusCode) -> Self
Builder-style equivalent of set_status()
.
sourcepub fn get_status(&self) -> StatusCode
pub fn get_status(&self) -> StatusCode
Get the HTTP status code of the response.
sourcepub fn set_status(&mut self, status: impl ToStatusCode)
pub fn set_status(&mut self, status: impl ToStatusCode)
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();
sourcepub fn with_version(self, version: Version) -> Self
pub fn with_version(self, version: Version) -> Self
Builder-style equivalent of set_version()
.
sourcepub fn get_version(&self) -> Version
pub fn get_version(&self) -> Version
Get the HTTP version of this response.
sourcepub fn set_version(&mut self, version: Version)
pub fn set_version(&mut self, version: Version)
Set the HTTP version of this response.
sourcepub fn set_framing_headers_mode(&mut self, mode: FramingHeadersMode)
pub fn set_framing_headers_mode(&mut self, mode: FramingHeadersMode)
Sets how Content-Length
and Transfer-Encoding
will be determined when sending this
request.
See FramingHeadersMode
for details on the options.
sourcepub fn with_framing_headers_mode(self, mode: FramingHeadersMode) -> Self
pub fn with_framing_headers_mode(self, mode: FramingHeadersMode) -> Self
Builder-style equivalent of
set_framing_headers_mode()
.
sourcepub fn get_backend_name(&self) -> Option<&str>
pub fn get_backend_name(&self) -> Option<&str>
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").unwrap();
assert_eq!(backend_resp.get_backend_name(), Some("example_backend"));
From a synthetic response:
let synthetic_resp = Response::new();
assert!(synthetic_resp.get_backend_name().is_none());
sourcepub fn get_backend(&self) -> Option<&Backend>
pub fn get_backend(&self) -> Option<&Backend>
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").unwrap();
assert_eq!(backend_resp.get_backend(), Some(&Backend::from_name("example_backend").unwrap()));
From a synthetic response:
let synthetic_resp = Response::new();
assert!(synthetic_resp.get_backend().is_none());
sourcepub fn get_backend_request(&self) -> Option<&Request>
pub fn get_backend_request(&self) -> Option<&Request>
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")
.unwrap();
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());
sourcepub fn take_backend_request(&mut self) -> Option<Request>
pub fn take_backend_request(&mut self) -> Option<Request>
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")
.unwrap();
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").unwrap();
From a synthetic response:
let mut synthetic_resp = Response::new();
assert!(synthetic_resp.take_backend_request().is_none());
sourcepub fn send_to_client(self)
pub fn send_to_client(self)
Begin sending the 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.
Once this method is called, 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 another response has already been sent to the client by this method,
by stream_to_client()
, or by the equivalent methods of
ResponseHandle
.
Incompatibility with fastly::main
This method cannot be used 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").unwrap().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").unwrap();
backend_resp.remove_header("bad-header");
backend_resp.send_to_client();
Sending a synthetic response:
Response::from_body("hello, world!").send_to_client();
sourcepub fn stream_to_client(self) -> StreamingBody ⓘ
pub fn stream_to_client(self) -> StreamingBody ⓘ
Begin sending the response to the client, and return a StreamingBody
that can accept
further data to send.
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.
Note that the client connection is only closed once the StreamingBody
is dropped. You
can explicitly drop the body once finished to avoid holding the connection open longer than
necessary.
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
.
Incompatibility with fastly::main
This method cannot be used 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:
use std::io::BufRead;
let mut backend_resp = Request::get("https://example.com/").send("example_backend").unwrap();
// 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.unwrap();
num_lines += 1;
// Write the line to the streaming client body
client_body.write_str(&line);
}
// Drop the streaming body to allow the client connection to close
drop(client_body);
println!("backend response body contained {} lines", num_lines);
sourcepub fn from_handles(
resp_handle: ResponseHandle,
body_handle: BodyHandle
) -> Result<Self, BufferSizeError>
pub fn from_handles(
resp_handle: ResponseHandle,
body_handle: BodyHandle
) -> Result<Self, BufferSizeError>
Create a Response
from the a ResponseHandle
and a BodyHandle
, returning an error
if any ResponseLimits
are exceeded.
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.
sourcepub fn into_handles(self) -> (ResponseHandle, BodyHandle)
pub fn into_handles(self) -> (ResponseHandle, BodyHandle)
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.