pub struct Request { /* private fields */ }
Expand description
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@Edge 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
Get the client request being handled by this execution of the Compute@Edge program.
Panics
This method panics if the client request has already been retrieved by this method,
Request::try_from_client()
, or by the low-level handle API.
If the request exceeds the limits specified by RequestLimits
, this method sends an empty
response with a 400 BAD REQUEST
HTTP status to the client, and then panics. Use
try_from_client()
if you want to explicitly handle these
errors, for example by returning a customized error page.
Get the client request being handled by this execution of the Compute@Edge program, or an
error if the request exceeds the limits specified by RequestLimits
.
Panics
This method panics if the client request has already been retrieved by this method,
Request::from_client()
, or by the low-level handle API.
Return true
if this request is from the client of this execution of the Compute@Edge
program.
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.
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());
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());
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.
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.
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.
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.
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.
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.
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.
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.
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.
Send the request to the given backend server, and return 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.
Panics
Panics if the backend response exceeds any of the limits configured by
ResponseLimits
.
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());
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@Edge program is able to run, as the request will continue sending even after the program that intitiated 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>
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.
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.
Note that the backend 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. The PendingRequest
will not yield a Response
until the StreamingBody
is closed.
Examples
Count the number of lines in a UTF-8 client request body while sending it to the backend:
use std::io::BufRead;
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_str(&line);
}
// Drop the streaming body to allow the backend connection to close
drop(backend_body);
println!("client request body contained {} lines", num_lines);
Builder-style equivalent of set_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!");
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!");
Get a prefix of this request’s body containing up to the given number of bytes.
See Body::get_prefix_mut()
for details.
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>
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.
Set the given value as the request’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
.
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()
.
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.
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();
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!");
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!");
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!");
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()
.
Consume the request and return its body if it has one, otherwise return None
.
👎 Deprecated since 0.7.0: renamed to Request::with_body_text_plain()
renamed to Request::with_body_text_plain()
Deprecated alias of with_body_text_plain()
Builder-style equivalent of set_body_text_plain()
.
👎 Deprecated since 0.7.0: renamed to Request::set_body_text_plain()
renamed to Request::set_body_text_plain()
Deprecated alias of set_body_text_plain()
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!");
Builder-style equivalent of set_body_text_html()
.
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>");
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!");
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!");
👎 Deprecated since 0.8.1: renamed to Request::with_body_octet_stream()
renamed to Request::with_body_octet_stream()
Deprecated alias of with_body_octet_stream()
👎 Deprecated since 0.8.1: renamed to Request::set_body_octet_stream()
renamed to Request::set_body_octet_stream()
Deprecated alias of set_body_octet_stream()
Builder-style equivalent of set_body_octet_stream()
.
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!");
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!");
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
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_bytes(&chunk);
}
req.set_body(no_0s);
}
Builder-style equivalent of set_body_json()
.
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"}"#);
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));
Builder-style equivalent of set_body_form()
.
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");
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);
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));
Builder-style equivalent of set_content_type()
.
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);
Get the value of the request’s
Content-Length
header, if it exists.
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"));
Builder-style equivalent of set_header()
.
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 req = Request::get("https://example.com").with_header("hello", "world!");
assert_eq!(req.get_header_str("hello"), Some("world"));
Get the value of a header as a string, including invalid characters, or None
if the header
is not present.
Only the valid UTF-8 characters present are returned.
Invalid UTF-8 characters are replaced with U+FFFD REPLACEMENT CHARACTER
.
If there are multiple values for the header, only one is returned, which may be any of the
values. See get_header_all_str_lossy()
if you need
to get all of the values.
Argument type conversion
The header name argument can be any type that implements ToHeaderName
; see that trait for
details on which types can be used and when panics may arise during conversion.
Examples
let header_value = HeaderValue::from_bytes(b"\xF0\x90\x80 world!").unwrap();
let req = Request::get("https://example.com").with_header("hello", header_value);
assert_eq!(req.get_header_str_lossy("hello"), Some(Cow::from("� world")));
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);
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 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!"));
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!")));
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) = value.to_str() {
println!("hello, {}", s);
} else {
println!("hello, invalid UTF-8!");
}
}
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"));
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);
}
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!"));
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!"));
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());
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
HeaderValue::to_str()
.
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());
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());
Builder-style equivalent of set_method()
.
Get the request method as a string.
Examples
let req = Request::get("https://example.com");
assert_eq!(req.get_method_str(), "GET");
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"),
}
}
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);
Get the request URL as a string.
Examples
let req = Request::get("https://example.com");
assert_eq!(req.get_url_str(), "https://example.com");
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"));
Get a mutable reference to the request URL.
Examples
let mut req = Request::get("https://example.com/");
let url = req.get_url_mut();
url.set_path("/hello");
url.set_fragment(Some("world"));
assert_eq!(req.get_url_str(), "https://example.com/hello#world");
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.
Get the path component of the request URL.
Examples
let req = Request::get("https://example.com/hello#world");
assert_eq!(req.get_path(), "/hello");
Builder-style equivalent of set_path()
.
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");
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.
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);
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);
Builder-style equivalent of set_query_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");
Builder-style equivalent of set_query()
.
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");
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");
Builder-style equivalent of set_version()
.
Get the HTTP version of this request.
Set the HTTP version of this request.
Builder-style equivalent of set_pass()
.
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()
.
Builder-style equivalent of set_stale_while_revalidate()
.
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
.
Builder-style equivalent of set_surrogate_key()
.
Override the caching behavior of this request to include the given surrogate key, provided as a header value.
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.
Returns the IP address of the client making the HTTP request.
Returns None
if this is not the client request.
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.
Returns the number of headers in the client request as originally received.
Returns None
if this is not the client request.
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.
Get the cipher suite used to secure the client TLS connection.
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");
Get the TLS protocol version used to secure the client TLS connection.
Returns None
if this is not the client request.
Examples
assert_eq!(Request::from_client().get_tls_protocol().unwrap(), "TLSv1.2");
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.
Builder-style equivalent of
set_auto_decompress_gzip()
.
pub fn from_handles(
req_handle: RequestHandle,
body_handle: Option<BodyHandle>
) -> Result<Self, BufferSizeError>
pub fn from_handles(
req_handle: RequestHandle,
body_handle: Option<BodyHandle>
) -> Result<Self, BufferSizeError>
Create a Request
from the low-level handle
API.
Errors
This conversion can fail if the request exceeds the limits specified by RequestLimits
.
Convert a Request
into the low-level handle
API.
Returns whether or not the client request came with a valid Fastly-Key for the service.
Trait Implementations
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.
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.
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.
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.
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.
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.