Struct Request

pub struct Request { /* private fields */ }

An HTTP request, including body, headers, method, and URL.

Getting the client request

Call Request::from_client() to get the client request being handled by this execution of the Compute program.

Creation and conversion

New requests can be created programmatically with Request::new(). In addition, there are convenience constructors like Request::get() which automatically select the appropriate method.

For interoperability with other Rust libraries, Request can be converted to and from the http crate’s http::Request type using the From and Into traits.

Sending backend requests

Requests can be sent to a backend in blocking or asynchronous fashion using send(), send_async(), or send_async_streaming().

Builder-style methods

Request can be used as a builder, allowing requests 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 request in a single expression. For example:

Request::get("https://example.com")
    .with_header("my-header", "hello!")
    .with_header("my-other-header", "Здравствуйте!")
    .send("example_backend")?;

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 request involves conditional branches or loops. For example:

let mut req = Request::get("https://example.com").with_header("my-header", "hello!");
if needs_translation {
    req.set_header("my-other-header", "Здравствуйте!");
}
req.send("example_backend")?;

Implementations

impl Request

pub fn from_client() -> Request

Get the client request being handled by this execution of the Compute program.

Panics

This method panics if the client request has already been retrieved by this method or by the low-level handle API.

Incompatibility with fastly::main

This method cannot be used with fastly::main, as that attribute implicitly calls Request::from_client() to populate the request argument. Use an undecorated main() function instead, along with Response::send_to_client() or Response::stream_to_client() to send a response to the client.

pub fn is_from_client(&self) -> bool

Return true if this request is from the client of this execution of the Compute program.

pub fn new(method: impl ToMethod, url: impl ToUrl) -> Self

Create a new request with the given method and URL, no headers, and an empty body.

Argument type conversion

The method and URL arguments can be any types that implement ToMethod and ToUrl, respectively. See those traits for details on which types can be used and when panics may arise during conversion.

pub fn clone_without_body(&self) -> Request

Make a new request with the same method, url, headers, and version of this request, but no body.

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

Examples

let original = Request::post("https://example.com")
    .with_header("hello", "world!")
    .with_body("hello");
let new = original.clone_without_body();
assert_eq!(original.get_method(), new.get_method());
assert_eq!(original.get_url(), new.get_url());
assert_eq!(original.get_header("hello"), new.get_header("hello"));
assert_eq!(original.get_version(), new.get_version());
assert!(original.has_body());
assert!(!new.has_body());

pub fn clone_with_body(&mut self) -> Request

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

This method requires mutable access to this request 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 = Request::post("https://example.com")
    .with_header("hello", "world!")
    .with_body("hello");
let mut new = original.clone_with_body();
assert_eq!(original.get_method(), new.get_method());
assert_eq!(original.get_url(), new.get_url());
assert_eq!(original.get_header("hello"), new.get_header("hello"));
assert_eq!(original.get_version(), new.get_version());
assert_eq!(original.take_body_bytes(), new.take_body_bytes());

pub fn get(url: impl ToUrl) -> Self

Create a new GET Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn head(url: impl ToUrl) -> Self

Create a new HEAD Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn post(url: impl ToUrl) -> Self

Create a new POST Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn put(url: impl ToUrl) -> Self

Create a new PUT Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn delete(url: impl ToUrl) -> Self

Create a new DELETE Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn connect(url: impl ToUrl) -> Self

Create a new CONNECT Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn options(url: impl ToUrl) -> Self

Create a new OPTIONS Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn trace(url: impl ToUrl) -> Self

Create a new TRACE Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn patch(url: impl ToUrl) -> Self

Create a new PATCH Request with the given URL, no headers, and an empty body.

Argument type conversion

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

pub fn with_before_send( self, f: impl Fn(&mut Request) -> Result<(), SendErrorCause> + Send + Sync + 'static, ) -> Self

Builder-style equivalent of set_before_send().

pub fn set_before_send( &mut self, f: impl Fn(&mut Request) -> Result<(), SendErrorCause> + Send + Sync + 'static, )

Sets a callback to be invoked if a request is going all the way to a backend, allowing the request to be modified beforehand.

This callback is useful when, for example, a backend requires an additional header to be inserted, but that header is expensive to produce. The callback will only be invoked if the original request cannot be responded to from the cache, so the header is only computed when it is truly needed.

pub fn with_after_send( self, f: impl Fn(&mut CandidateResponse) -> Result<(), SendErrorCause> + Send + Sync + 'static, ) -> Self

Builder-style equivalent of set_after_send().

pub fn set_after_send( &mut self, f: impl Fn(&mut CandidateResponse) -> Result<(), SendErrorCause> + Send + Sync + 'static, )

Sets a callback to be invoked after a response is returned from a backend, but before it is stored into the cache.

This callback allows for cache properties like TTL to be customized beyond what the backend resopnse headers specify. It also allows for the response itself to be modified prior to storing into the cache.

pub fn send(self, backend: impl ToBackend) -> Result<Response, SendError>

Retrieve a reponse for the request, either from cache or by sending it to the given backend server. Returns once the response headers have been received, or an error occurs.

Argument type conversion

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

Examples

Sending the client request to a backend without modification:

let backend_resp = Request::from_client().send("example_backend").expect("request succeeds");
assert!(backend_resp.get_status().is_success());

Sending a synthetic request:

let backend_resp = Request::get("https://example.com")
    .send("example_backend")
    .expect("request succeeds");
assert!(backend_resp.get_status().is_success());

pub fn send_async( self, backend: impl ToBackend, ) -> Result<PendingRequest, SendError>

Begin sending the request to the given backend server, and return a PendingRequest that can yield the backend response or an error.

This method returns as soon as the request begins sending to the backend, and transmission of the request body and headers will continue in the background.

This method allows for sending more than one request at once and receiving their responses in arbitrary orders. See PendingRequest for more details on how to wait on, poll, or select between pending requests.

This method is also useful for sending requests where the response is unimportant, but the request may take longer than the Compute program is able to run, as the request will continue sending even after the program that initiated it exits.

Argument type conversion

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

Examples

Sending a request to two backends and returning whichever response finishes first:

let backend_resp_1 = Request::get("https://example.com/")
    .send_async("example_backend_1")
    .expect("request 1 begins sending");
let backend_resp_2 = Request::get("https://example.com/")
    .send_async("example_backend_2")
    .expect("request 2 begins sending");
let (resp, _) = fastly::http::request::select(vec![backend_resp_1, backend_resp_2]);
resp.expect("request succeeds").send_to_client();

Sending a long-running request and ignoring its result so that the program can exit before it completes:

let _ = Request::post("https://example.com")
    .with_body(some_large_file)
    .send_async("example_backend");

pub fn send_async_streaming( self, backend: impl ToBackend, ) -> Result<(StreamingBody, PendingRequest), SendError>

Begin sending the request to the given backend server, and return a PendingRequest that can yield the backend response or an error along with a StreamingBody that can accept further data to send.

The backend connection is only closed once StreamingBody::finish() is called. The PendingRequest will not yield a Response until the StreamingBody is finished.

This method is most useful for programs that do some sort of processing or inspection of a potentially-large client request 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 request begins sending to the backend, and transmission of the request body and headers will continue in the background.

Examples

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

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

let mut req = Request::from_client();
// Take the body so we can iterate through its lines later
let req_body = req.take_body();
// Start sending the client request to the client with a now-empty body
let (mut backend_body, pending_req) = req
    .send_async_streaming("example_backend")
    .expect("request begins sending");

let mut num_lines = 0;
for line in req_body.lines() {
    let line = line.unwrap();
    num_lines += 1;
    // Write the line to the streaming backend body
    backend_body.write_all(line.as_bytes()).unwrap();
}
// Finish the streaming body to allow the backend connection to close
backend_body.finish().unwrap();

println!("client request body contained {} lines", num_lines);

pub fn with_body(self, body: impl Into<Body>) -> Self

Builder-style equivalent of set_body().

pub fn has_body(&self) -> bool

Returns true if this request has a body.

pub fn get_body_mut(&mut self) -> &mut Body

Get a mutable reference to the body of this request.

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 req = Request::post("https://example.com").with_body("hello,");
write!(req.get_body_mut(), " world!").unwrap();
assert_eq!(&req.into_body_str(), "hello, world!");

pub fn try_get_body_mut(&mut self) -> Option<&mut Body>

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

Examples

use std::io::Write;

let mut req = Request::post("https://example.com");
assert!(req.try_get_body_mut().is_none());

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

pub fn get_body_prefix_mut(&mut self, length: usize) -> Prefix<'_>

Get a prefix of this request’s body containing up to the given number of bytes.

See Body::get_prefix_mut() for details.

pub fn get_body_prefix_str_mut(&mut self, length: usize) -> PrefixString<'_>

Get a prefix of this request’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.

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.

pub fn set_body(&mut self, body: impl Into<Body>)

Set the given value as the request’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.

pub fn take_body(&mut self) -> Body

Take and return the body from this request.

After calling this method, this request 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().

pub fn try_take_body(&mut self) -> Option<Body>

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

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

pub fn append_body(&mut self, other: Body)

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

If this request does not have a body, the appended body is set as the request’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 the body of the client. To append contents that are already in memory as strings or bytes, you should instead use get_body_mut() to write the contents to the end of the body.

Examples

let mut req = Request::post("https://example.com").with_body("hello! client says: ");
req.append_body(Request::from_client().into_body());
req.send("example_backend").unwrap();

pub fn into_body_bytes(self) -> Vec<u8>

Consume the request 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 req = Request::post("https://example.com").with_body(b"hello, world!".to_vec());
let bytes = req.into_body_bytes();
assert_eq!(&bytes, b"hello, world!");

pub fn into_body_str(self) -> String

Consume the request 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 req = Request::post("https://example.com").with_body("hello, world!");
let string = req.into_body_str();
assert_eq!(&string, "hello, world!");

pub fn into_body_str_lossy(self) -> String

Consume the request 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 req = Request::post("https://example.com");
req.set_body_octet_stream(b"\xF0\x90\x80 hello, world!");
let string = req.into_body_str_lossy();
assert_eq!(&string, "� hello, world!");

pub fn into_body(self) -> Body

Consume the request 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().

pub fn try_into_body(self) -> Option<Body>

Consume the request and return its body if it has one, otherwise return None.

pub fn with_body_text_plain(self, body: &str) -> Self

Builder-style equivalent of set_body_text_plain().

pub fn set_body_text_plain(&mut self, body: &str)

Set the given string as the request’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 req = Request::post("https://example.com");
req.set_body_text_plain("hello, world!");
assert_eq!(req.get_content_type(), Some(fastly::mime::TEXT_PLAIN_UTF_8));
assert_eq!(&req.into_body_str(), "hello, world!");

pub fn with_body_text_html(self, body: &str) -> Self

Builder-style equivalent of set_body_text_html().

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 req = Request::post("https://example.com");
req.set_body_text_html("<p>hello, world!</p>");
assert_eq!(req.get_content_type(), Some(fastly::mime::TEXT_HTML_UTF_8));
assert_eq!(&req.into_body_str(), "<p>hello, world!</p>");

pub fn take_body_str(&mut self) -> String

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

After calling this method, this request 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 req = Request::post("https://example.com").with_body("hello, world!");
let string = req.take_body_str();
assert!(req.try_take_body().is_none());
assert_eq!(&string, "hello, world!");

pub fn take_body_str_lossy(&mut self) -> String

Take and return the body from this request 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 request 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 req = Request::post("https://example.com");
req.set_body_octet_stream(b"\xF0\x90\x80 hello, world!");
let string = req.take_body_str_lossy();
assert!(req.try_take_body().is_none());
assert_eq!(&string, "� hello, world!");

pub fn read_body_lines(&mut self) -> Lines<&mut Body>

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

Examples

use std::io::Write;

fn remove_es(req: &mut Request) {
    let mut no_es = Body::new();
    for line in req.read_body_lines() {
        writeln!(no_es, "{}", line.unwrap().replace("e", "")).unwrap();
    }
    req.set_body(no_es);
}

pub fn with_body_octet_stream(self, body: &[u8]) -> Self

Builder-style equivalent of set_body_octet_stream().

pub fn set_body_octet_stream(&mut self, body: &[u8])

Set the given bytes as the request’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 req = Request::post("https://example.com");
req.set_body_octet_stream(b"hello, world!");
assert_eq!(req.get_content_type(), Some(fastly::mime::APPLICATION_OCTET_STREAM));
assert_eq!(&req.into_body_bytes(), b"hello, world!");

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

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

After calling this method, this request 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 req = Request::post("https://example.com").with_body(b"hello, world!".to_vec());
let bytes = req.take_body_bytes();
assert!(req.try_take_body().is_none());
assert_eq!(&bytes, b"hello, world!");

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 request 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

use std::io::Write;
fn remove_0s(req: &mut Request) {
    let mut no_0s = Body::new();
    for chunk in req.read_body_chunks(4096) {
        let mut chunk = chunk.unwrap();
        chunk.retain(|b| *b != 0);
        no_0s.write_all(&chunk).unwrap();
    }
    req.set_body(no_0s);
}

pub fn with_body_json(self, value: &impl Serialize) -> Result<Self, Error>

Builder-style equivalent of set_body_json().

pub fn set_body_json(&mut self, value: &impl Serialize) -> Result<(), Error>

Convert the given value to JSON and set that JSON as the request’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 req = Request::post("https://example.com");
req.set_body_json(&my_data).unwrap();
assert_eq!(req.get_content_type(), Some(fastly::mime::APPLICATION_JSON));
assert_eq!(&req.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 req = Request::post("https://example.com");
req.set_body_json(&my_data).unwrap();
assert_eq!(req.get_content_type(), Some(fastly::mime::APPLICATION_JSON));
assert_eq!(&req.into_body_str(), r#"{"count":1024,"name":"Computers"}"#);

pub fn take_body_json<T: DeserializeOwned>(&mut self) -> Result<T, Error>

Take the request 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 request 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 req = Request::post("https://example.com")
    .with_body(r#"{"name":"Computers","count":1024}"#);
let my_data = req.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 req = Request::post("https://example.com")
    .with_body(r#"{"name":"Computers","count":1024}"#);
let my_data = req.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));

pub fn with_body_form(self, value: &impl Serialize) -> Result<Self, Error>

Builder-style equivalent of set_body_form().

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 request’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 req = Request::post("https://example.com");
req.set_body_form(&my_data).unwrap();
assert_eq!(req.get_content_type(), Some(fastly::mime::APPLICATION_WWW_FORM_URLENCODED));
assert_eq!(&req.into_body_str(), "name=Computers&count=1024");

pub fn take_body_form<T: DeserializeOwned>(&mut self) -> Result<T, Error>

Take the request 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 request 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 req = Request::post("https://example.com").with_body("name=Computers&count=1024");
let my_data = req.take_body_form::<MyData>().unwrap();
assert_eq!(&my_data.name, "Computers");
assert_eq!(my_data.count, 1024);

pub fn get_content_type(&self) -> Option<Mime>

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

Examples

let req = Request::post("https://example.com").with_body_text_plain("hello, world!");
assert_eq!(req.get_content_type(), Some(fastly::mime::TEXT_PLAIN_UTF_8));

pub fn with_content_type(self, mime: Mime) -> Self

Builder-style equivalent of set_content_type().

pub fn set_content_type(&mut self, mime: Mime)

Set the MIME type described by the request’s Content-Type header.

Any existing Content-Type header values will be overwritten.

Examples

let mut req = Request::post("https://example.com").with_body("hello,world!");
req.set_content_type(fastly::mime::TEXT_CSV_UTF_8);

pub fn get_content_length(&self) -> Option<usize>

Get the value of the request’s Content-Length header, if it exists.

pub fn contains_header(&self, name: impl ToHeaderName) -> bool

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

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 req = Request::get("https://example.com").with_header("hello", "world!");
assert!(req.contains_header("hello"));
assert!(!req.contains_header("not-present"));

pub fn with_header( self, name: impl ToHeaderName, value: impl ToHeaderValue, ) -> Self

Builder-style equivalent of append_header().

pub fn with_set_header( self, name: impl ToHeaderName, value: impl ToHeaderValue, ) -> Self

Builder-style equivalent of set_header().

pub fn get_header_str(&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 std::str::from_utf8().

Examples

let req = Request::get("https://example.com").with_header("hello", "world!");
assert_eq!(req.get_header_str("hello"), Some("world"));

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 req = Request::get("https://example.com").with_header("hello", header_value);
assert_eq!(req.get_header_str_lossy("hello"), Some(Cow::from("� world")));

pub fn get_header(&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 req = Request::get("https://example.com").with_header("hello", "world!");
assert_eq!(req.get_header("hello"), Some(&HeaderValue::from_static("world")));

Safely handling invalid UTF-8 values:

let invalid_utf8 = &"🐈".as_bytes()[0..3];
let req = Request::get("https://example.com").with_header("hello", invalid_utf8);
assert_eq!(req.get_header("hello").unwrap().as_bytes(), invalid_utf8);

pub fn get_header_all_str(&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 std::str::from_utf8().

Examples

let req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("hello", "universe!");
let values = req.get_header_all_str("hello");
assert_eq!(values.len(), 2);
assert!(values.contains(&"world!"));
assert!(values.contains(&"universe!"));

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 req = Request::get("https://example.com")
    .with_header("hello", world_value)
    .with_header("hello", universe_value);
let values = req.get_header_all_str_lossy("hello");
assert_eq!(values.len(), 2);
assert!(values.contains(&Cow::from("� world!")));
assert!(values.contains(&Cow::from("� universe!")));

pub fn get_header_all( &self, name: impl ToHeaderName, ) -> impl Iterator<Item = &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 req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("hello", invalid_utf8);

let values: Vec<&HeaderValue> = req.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 req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("hello", invalid_utf8);

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

pub fn get_headers(&self) -> impl Iterator<Item = (&HeaderName, &HeaderValue)>

Get an iterator of all the request’s header names and values.

Examples

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

let req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("hello", "universe!");

let headers: Vec<(&HeaderName, &HeaderValue)> = req.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 req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("hello", "universe!");

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

pub fn get_header_names_str(&self) -> Vec<&str>

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

Examples

let req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("goodbye", "latency!");
let names = req.get_header_names_str();
assert_eq!(names.len(), 2);
assert!(names.contains(&"hello"));
assert!(names.contains(&"goodbye"));

pub fn get_header_names(&self) -> impl Iterator<Item = &HeaderName>

Get an iterator of all the request’s header names.

Examples

You can turn the iterator into collection, like Vec:

let req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("goodbye", "latency!");

let values: Vec<&HeaderName> = req.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 req = Request::get("https://example.com")
    .with_header("hello", "world!")
    .with_header("goodbye", "latency!");

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

pub fn set_header(&mut self, name: impl ToHeaderName, value: impl ToHeaderValue)

Set a request 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 req = Request::get("https://example.com");

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

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

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

pub fn append_header( &mut self, name: impl ToHeaderName, value: impl ToHeaderValue, )

Add a request 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 req = Request::get("https://example.com");

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

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

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

pub fn remove_header(&mut self, name: impl ToHeaderName) -> Option<HeaderValue>

Remove all request 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, 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 mut req = Request::get("https://example.com").with_header("hello", "world!");
assert_eq!(req.get_header_str("hello"), Some("world!"));
assert_eq!(req.remove_header("hello"), Some(HeaderValue::from_static("world!")));
assert!(req.remove_header("not-present").is_none());

pub fn remove_header_str(&mut self, name: impl ToHeaderName) -> Option<String>

Remove all request 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 req = Request::get("https://example.com").with_header("hello", "world!");
assert_eq!(req.get_header_str("hello"), Some("world!"));
assert_eq!(req.remove_header_str("hello"), Some("world!".to_string()));
assert!(req.remove_header_str("not-present").is_none());

pub fn remove_header_str_lossy( &mut self, name: impl ToHeaderName, ) -> Option<String>

Remove all request 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 req = Request::get("https://example.com")
    .with_header("hello", header_value);
assert_eq!(req.get_header_str_lossy("hello"), Some(Cow::from("� world")));
assert_eq!(req.remove_header_str_lossy("hello"), Some(String::from("� world")));
assert!(req.remove_header_str_lossy("not-present").is_none());

pub fn with_method(self, method: impl ToMethod) -> Self

Builder-style equivalent of set_method().

pub fn get_method_str(&self) -> &str

Get the request method as a string.

Examples

let req = Request::get("https://example.com");
assert_eq!(req.get_method_str(), "GET");

pub fn get_method(&self) -> &Method

Get the request method.

Examples

use fastly::http::Method;
fn log_method(req: &Request) {
    match req.get_method() {
        &Method::GET | &Method::HEAD => println!("method was a GET or HEAD"),
        &Method::POST => println!("method was a POST"),
        _ => println!("method was something else"),
    }
}

pub fn set_method<'a>(&mut self, method: impl ToMethod)

Set the request method.

Argument type conversion

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

Examples

use fastly::http::Method;

let mut req = Request::get("https://example.com");
req.set_method(Method::POST);
assert_eq!(req.get_method(), &Method::POST);

pub fn with_url(self, url: impl ToUrl) -> Self

Builder-style equivalent of set_url().

pub fn get_url_str(&self) -> &str

Get the request URL as a string.

Examples

let req = Request::get("https://example.com");
assert_eq!(req.get_url_str(), "https://example.com");

pub fn get_url(&self) -> &Url

Get a shared reference to the request URL.

Examples

let req = Request::get("https://example.com/hello#world");
let url = req.get_url();
assert_eq!(url.host_str(), Some("example.com"));
assert_eq!(url.path(), "/hello");
assert_eq!(url.fragment(), Some("world"));

pub fn get_url_mut(&mut self) -> impl DerefMut<Target = Url> + '_

Get a mutable reference to the request URL.

Examples

let mut req = Request::get("https://example.com/");

let mut url = req.get_url_mut();
url.set_path("/hello");
url.set_fragment(Some("world"));
drop(url);

assert_eq!(req.get_url_str(), "https://example.com/hello#world");

pub fn set_url(&mut self, url: impl ToUrl)

Set the request URL.

Argument type conversion

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

pub fn get_path(&self) -> &str

Get the path component of the request URL.

Examples

let req = Request::get("https://example.com/hello#world");
assert_eq!(req.get_path(), "/hello");

pub fn with_path(self, path: &str) -> Self

Builder-style equivalent of set_path().

pub fn set_path(&mut self, path: &str)

Set the path component of the request URL.

Examples

let mut req = Request::get("https://example.com/");
req.set_path("/hello");
assert_eq!(req.get_url_str(), "https://example.com/hello");

pub fn get_query_str(&self) -> Option<&str>

Get the query component of the request URL, if it exists, as a percent-encoded ASCII string.

This is a shorthand for self.get_url().query(); see Url::query() for details and other query manipulation functions.

pub fn get_query_parameter(&self, parameter: &str) -> Option<&str>

Get the value of a query parameter in the request’s URL.

This assumes that the query string is a & separated list of parameter=value pairs. The value of the first occurrence of parameter is returned. No URL decoding is performed.

Examples

let req = Request::get("https://example.com/page?foo=bar&baz=qux");
assert_eq!(req.get_query_parameter("foo"), Some("bar"));
assert_eq!(req.get_query_parameter("baz"), Some("qux"));
assert_eq!(req.get_query_parameter("other"), None);

pub fn get_query<T: DeserializeOwned>(&self) -> Result<T, Error>

Attempt to parse the query component of the request URL into the specified datatype.

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

Errors

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

Examples

Parsing into a vector of string pairs:

let req = Request::get("https://example.com/foo?hello=%F0%9F%8C%90!&bar=baz");
let pairs: Vec<(String, String)> = req.get_query().unwrap();
assert_eq!((pairs[0].0.as_str(), pairs[0].1.as_str()), ("hello", "🌐!"));

Parsing into a mapping between strings (note that duplicates are removed since HashMap is not a multimap):

use std::collections::HashMap;
let req = Request::get("https://example.com/foo?hello=%F0%9F%8C%90!&bar=baz&bar=quux");
let map: HashMap<String, String> = req.get_query().unwrap();
assert_eq!(map.len(), 2);
assert_eq!(map["hello"].as_str(), "🌐!");

Parsing into a custom type that derives serde::de::Deserialize:

#[derive(serde::Deserialize)]
struct MyData {
    name: String,
    count: u64,
}
let mut req = Request::get("https://example.com/?name=Computers&count=1024");
let my_data = req.take_body_form::<MyData>().unwrap();
assert_eq!(&my_data.name, "Computers");
assert_eq!(my_data.count, 1024);

pub fn with_query_str(self, query: impl AsRef<str>) -> Self

Builder-style equivalent of set_query_str().

pub fn set_query_str(&mut self, query: impl AsRef<str>)

Set the query string of the request URL query component to the given string, performing percent-encoding if necessary.

Examples

let mut req = Request::get("https://example.com/foo");
req.set_query_str("hello=🌐!&bar=baz");
assert_eq!(req.get_url_str(), "https://example.com/foo?hello=%F0%9F%8C%90!&bar=baz");

pub fn with_query(self, query: &impl Serialize) -> Result<Self, Error>

Builder-style equivalent of set_query().

pub fn set_query(&mut self, query: &impl Serialize) -> Result<(), Error>

Convert the given value to application/x-www-form-urlencoded format and set that data as the request URL query component.

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

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 req = Request::get("https://example.com/foo");
req.set_query(&my_data).unwrap();
assert_eq!(req.get_url_str(), "https://example.com/foo?name=Computers&count=1024");

pub fn remove_query(&mut self)

Remove the query component from the request URL, if one exists.

Examples

let mut req = Request::get("https://example.com/foo?hello=%F0%9F%8C%90!&bar=baz");
req.remove_query();
assert_eq!(req.get_url_str(), "https://example.com/foo");

pub fn with_version(self, version: Version) -> Self

Builder-style equivalent of set_version().

pub fn get_version(&self) -> Version

Get the HTTP version of this request.

pub fn set_version(&mut self, version: Version)

Set the HTTP version of this request.

pub fn with_pass(self, pass: bool) -> Self

Builder-style equivalent of set_pass().

pub fn set_pass(&mut self, pass: bool)

Set whether this request should be cached if sent to a backend.

By default this is false, which means the backend will only be reached if a cached response is not available. Set this to true to send the request directly to the backend without caching.

Overrides

Setting this to true overrides any other custom caching behaviors for this request, such as Request::set_ttl() or Request::set_surrogate_key().

pub fn with_ttl(self, ttl: u32) -> Self

Builder-style equivalent of set_ttl().

pub fn set_ttl(&mut self, ttl: u32)

Override the caching behavior of this request to use the given Time to Live (TTL), in seconds.

Overrides

This overrides the behavior specified in the response headers, and sets the pass behavior to false.

pub fn with_stale_while_revalidate(self, swr: u32) -> Self

Builder-style equivalent of set_stale_while_revalidate().

pub fn set_stale_while_revalidate(&mut self, swr: u32)

Override the caching behavior of this request to use the given stale-while-revalidate time, in seconds.

Overrides

This overrides the behavior specified in the response headers, and sets the pass behavior to false.

pub fn with_pci(self, pci: bool) -> Self

Builder-style equivalent of set_pci().

pub fn set_pci(&mut self, pci: bool)

Override the caching behavior of this request to enable or disable PCI/HIPAA-compliant non-volatile caching.

By default, this is false, which means the request may not be PCI/HIPAA-compliant. Set it to true to enable compliant caching.

See the Fastly PCI-Compliant Caching and Delivery documentation for details.

Overrides

This sets the pass behavior to false.

pub fn with_surrogate_key(self, sk: HeaderValue) -> Self

Builder-style equivalent of set_surrogate_key().

pub fn set_surrogate_key(&mut self, sk: HeaderValue)

Override the caching behavior of this request to include the given surrogate key(s), provided as a header value.

The header value can contain more than one surrogate key, separated by spaces.

Surrogate keys must contain only printable ASCII characters (those between 0x21 and 0x7E, inclusive). Any invalid keys will be ignored.

See the Fastly surrogate keys guide for details.

Overrides

This sets the pass behavior to false, and extends (but does not replace) any Surrogate-Key response headers from the backend.

pub fn get_client_ip_addr(&self) -> Option<IpAddr>

Returns the IP address of the client making the HTTP request.

Returns None if this is not the client request.

pub fn get_server_ip_addr(&self) -> Option<IpAddr>

Returns the IP address on which this server received the HTTP request.

Returns None if this is not the client request.

pub fn get_original_header_names(&self) -> Option<impl Iterator<Item = String>>

Returns the client request’s header names exactly as they were originally received.

This includes both the original character cases, as well as the original order of the received headers.

Returns None if this is not the client request.

pub fn get_original_header_count(&self) -> Option<u32>

Returns the number of headers in the client request as originally received.

Returns None if this is not the client request.

pub fn get_tls_client_hello(&self) -> Option<&[u8]>

Get the raw bytes sent by the client in the TLS ClientHello message.

See RFC 5246 for details.

Returns None if this is not the client request.

pub fn get_tls_ja3_md5(&self) -> Option<[u8; 16]>

Get the JA3 hash of the TLS ClientHello message.

Returns None if this is not available.

pub fn get_tls_ja4(&self) -> Option<&str>

Get the JA4 hash of the TLS ClientHello message.

Returns None if this is not available.

pub fn get_tls_raw_client_certificate(&self) -> Option<&'static str>

Get the raw client certificate in the mutual TLS handshake message as a string, panicking if it is not UTF-8. It is in PEM format. Returns None if this is not mTLS or available.

pub fn get_tls_raw_client_certificate_bytes(&self) -> Option<&'static [u8]>

Like Self::get_tls_raw_client_certificate, but supports non-UTF-8 byte sequences.

pub fn get_tls_client_cert_verify_result( &self, ) -> Option<ClientCertVerifyResult>

Returns the error code defined in ClientCertVerifyResult.

If your service is set up for mTLS (see this documentation), then this will return information about the client’s mTLS certificate, if provided. If the certificate is not provided, you will receive a ClientCertVerifyResult::CertificateMissing value, if the certificate properly matches your mTLS configuration, you will receive a ClientCertVerifyResult::Ok, etc.

If your service is not set up for mTLS, this function will always return Some(ClientCertVerifyResult::Ok).

If you have a service that may be run with some domains that are mTLS protected, and some that are not mTLS protected, then we advise checking for both the existence of a certificate (by verifying that get_tls_raw_client_certificate or get_tls_raw_client_certificate_bytes return Some) before checking the result of this function. Doing both makes sure that you both received a certificate and that it was valid, and will work for both the mTLS-protected and non-mTLS-protected domains.

This function returns None in the case that this Request is not from the client, but was instead generated by other parts of the code. (In other words, it will return None if this request was neither the argument to a function marked fastly::main nor generated with Request::from_client.)

pub fn get_tls_cipher_openssl_name(&self) -> Option<&'static str>

Get the cipher suite used to secure the client TLS connection, as a string, panicking if it is not UTF-8.

The value returned will be consistent with the OpenSSL name for the cipher suite.

Returns None if this is not the client request.

Examples

assert_eq!(Request::from_client().get_tls_cipher_openssl_name().unwrap(), "ECDHE-RSA-AES128-GCM-SHA256");

pub fn get_tls_cipher_openssl_name_bytes(&self) -> Option<&'static [u8]>

Like Self::get_tls_cipher_openssl_name_bytes, but supports non-UTF-8 byte strings.

pub fn get_tls_protocol(&self) -> Option<&'static str>

Get the TLS protocol version used to secure the client TLS connection, as a string, panicking if it is not UTF-8.

Returns None if this is not the client request.

Examples

assert_eq!(Request::from_client().get_tls_protocol().unwrap(), "TLSv1.2");

pub fn get_tls_protocol_bytes(&self) -> Option<&'static [u8]>

Like Self::get_tls_protocol, but supports non-UTF-8 byte strings.

pub fn set_auto_decompress_gzip(&mut self, gzip: bool)

Set whether a gzip-encoded response to this request will be automatically decompressed.

If the response to this request is gzip-encoded, it will be presented in decompressed form, and the Content-Encoding and Content-Length headers will be removed.

pub fn with_auto_decompress_gzip(self, gzip: bool) -> Self

Builder-style equivalent of set_auto_decompress_gzip().

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.

pub fn with_framing_headers_mode(self, mode: FramingHeadersMode) -> Self

Builder-style equivalent of set_framing_headers_mode().

pub fn from_handles( req_handle: RequestHandle, body_handle: Option<BodyHandle>, ) -> Self

Create a Request from the low-level handle API.

pub fn into_handles(self) -> (RequestHandle, Option<BodyHandle>)

Convert a Request into the low-level handle API.

pub fn fastly_key_is_valid(&self) -> bool

Returns whether or not the client request had a Fastly-Key header which is valid for purging content for the service.

This function ignores the current value of any Fastly-Key header for this request.

pub fn handoff_websocket(self, backend: &str) -> Result<(), SendError>

Pass the WebSocket directly to a backend.

This can only be used on services that have the WebSockets feature enabled and on requests that are valid WebSocket requests.

The sending completes in the background. Once this method has been called, no other response can be sent to this request, and the application can exit without affecting the send.

pub fn handoff_fanout(self, backend: &str) -> Result<(), SendError>

Pass the request through the Fanout GRIP proxy and on to a backend.

This can only be used on services that have the Fanout feature enabled.

The sending completes in the background. Once this method has been called, no other response can be sent to this request, and the application can exit without affecting the send.

pub fn on_behalf_of<S: AsRef<str>>( self, service: S, ) -> Result<Self, FastlyStatus>

Send this request on behalf of another service.

Running it on behalf of another service means that the cache store used for this request will be of that service, not the currently running one.

Internal / Privileged

This operation is privileged, and attempts to use this functionality without proper privileges will cause errors. If you are interested in having two or more of your services share the same cache, please talk to your Fastly account representative. While we have no plans to offer this ability widely – this capability is only currently allowed for Fastly-internal services – we may revisit this decision given sufficient customer input.

pub fn set_cache_key(&mut self, key: impl Into<Vec<u8>>)

Set the cache key to be used when attempting to satisfy this request from a cached response.

pub fn with_cache_key(self, key: impl Into<Vec<u8>>) -> Self

Builder-style equivalent of set_cache_key().

pub fn is_cacheable(&mut self) -> bool

Gets whether the request is potentially cacheable.

Trait Implementations

impl Debug for Request

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

Formats the value using the given formatter.

impl From<Request<Body>> for Request

fn from(from: Request<Body>) -> Self

Converts to this type from the input type.

impl From<RequestHandle> for Request

fn from(handle: RequestHandle) -> Self

Converts to this type from the input type.

impl Into<Request<Body>> for Request

fn into(self) -> Request<Body>

Converts this type into the (usually inferred) input type.

impl RequestCacheKey for Request

fn set_cache_key(&mut self, key: [u8; 32])

Set the cache key to be used when attempting to satisfy this request from a cached response.

Stability

This is part of an experimental API that is subject to change or removal even in minor versions of this crate.

fn with_cache_key(self, key: [u8; 32]) -> Self

Builder-style equivalent of set_cache_key().

Stability

This is part of an experimental API that is subject to change or removal even in minor versions of this crate.

fn set_cache_key_fn( &mut self, f: impl Fn(&Request) -> [u8; 32] + Send + Sync + 'static, )

Set the function that will be used to compute the cache key for this request.

Stability

This is part of an experimental API that is subject to change or removal even in minor versions of this crate.

fn with_cache_key_fn( self, f: impl Fn(&Request) -> [u8; 32] + Send + Sync + 'static, ) -> Self

Builder-style equivalent of set_cache_key_fn().

Stability

This is part of an experimental API that is subject to change or removal even in minor versions of this crate.

fn set_cache_key_str(&mut self, key_str: impl AsRef<[u8]>)

Set a string as the cache key to be used when attempting to satisfy this request from a cached response.

The string representation of the key is hashed to the same [u8; 32] representation used by set_cache_key().

Stability

This is part of an experimental API that is subject to change or removal even in minor versions of this crate.

fn with_cache_key_str(self, key_str: impl AsRef<[u8]>) -> Self

Builder-style equivalent of set_cache_key_str().

Stability

This is part of an experimental API that is subject to change or removal even in minor versions of this crate.

impl RequestUpgradeWebsocket for Request

fn handoff_websocket(self, backend: &str) -> Result<(), SendError>

👎Deprecated since 0.10.0: The RequestUpgradeWebsocket::handoff_websocket() trait method is now part of Request.

Pass the WebSocket directly to a backend.

This can only be used on services that have the WebSockets feature enabled and on requests that are valid WebSocket requests.

The sending completes in the background. Once this method has been called, no other response can be sent to this request, and the application can exit without affecting the send.

fn handoff_fanout(self, backend: &str) -> Result<(), SendError>

👎Deprecated since 0.10.0: The RequestUpgradeWebsocket::handoff_fanout() trait method is now part of Request.

Pass the request through the Fanout GRIP proxy and on to a backend.

This can only be used on services that have the Fanout feature enabled.

The sending completes in the background. Once this method has been called, no other response can be sent to this request, and the application can exit without affecting the send.