Struct fastly::handle::RequestHandle

#[repr(transparent)]
pub struct RequestHandle { /* fields omitted */ }

The low-level interface to HTTP requests.

For most applications, you should use Request instead of this interface. See the top-level handle documentation for more details.

Getting the client request

Call RequestHandle::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 RequestHandle::new(). In addition, you can convert to and from Request using Request::from_handles() and Request::into_handles().

Sending backend requests

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

Implementations

impl RequestHandle

pub const INVALID: Self

An invalid handle.

This is primarily useful to represent uninitialized values when using the interfaces in fastly_sys.

pub fn is_valid(&self) -> bool

Returns true if the request handle is valid.

pub fn is_invalid(&self) -> bool

Returns true if the request handle is invalid.

pub fn from_client() -> Self

Get a handle to 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, client_request_and_body(), or Request::from_client().

pub fn new() -> Self

Acquire a new request handle.

By default, the request will have a GET method, a URL of /, and empty headers.

pub fn get_header_names<'a>(
    &'a self,
    buf_size: usize
) -> impl Iterator<Item = Result<HeaderName, BufferSizeError>> + 'a

Read the request’s header names via a buffer of the provided size.

If there is a header name that is longer than buf_size, this will return a BufferSizeError; you can retry with a larger buffer size if necessary.

pub fn get_header_values<'a>(
    &'a self,
    name: &'a HeaderName,
    buf_size: usize
) -> impl Iterator<Item = Result<HeaderValue, BufferSizeError>> + 'a

Get the header values for the given name via a buffer of the provided size.

If there is a header value that is longer than the buffer, this will return a BufferSizeError; you can retry with a larger buffer size if necessary.

Examples

Collect all the header values into a Vec:

let name = HeaderName::from_static("My-App-Header");
let buf_size = 128;
let header_values: Vec<HeaderValue> = request
    .get_header_values(&name, buf_size)
    .collect::<Result<Vec<HeaderValue>, _>>()?;

To try again with a larger buffer if the first call fails, you can use unwrap_or_else():

let name = HeaderName::from_static("My-App-Header");
let buf_size = 128;

// Collect header values into a `Vec<HeaderValue>`, with a buffer size of `128`.
// If the first call fails, print our error and then try to collect header values
// again. The second call will use a larger buffer size of `1024`.
let header_values: Vec<HeaderValue> = request
    .get_header_values(&name, buf_size)
    .collect::<Result<_, _>>()
    .unwrap_or_else(|err: BufferSizeError| {
        let larger_buf_size = 1024;
        request
            .get_header_values(&name, larger_buf_size)
            .collect::<Result<_, _>>()
            .unwrap()
    });

pub fn set_header_values<'a, I>(&mut self, name: &HeaderName, values: I) where
    I: IntoIterator<Item = &'a HeaderValue>, 

Set the values for the given header name, replacing any headers that previously existed for that name.

pub fn get_header_value(
    &self,
    name: &HeaderName,
    max_len: usize
) -> Result<Option<HeaderValue>, BufferSizeError>

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. See get_header_values() if you need to get all of the values.

If the value is longer than max_len, this will return a BufferSizeError; you can retry with a larger buffer size if necessary.

pub fn insert_header(&mut self, name: &HeaderName, value: &HeaderValue)

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

pub fn append_header(&mut self, name: &HeaderName, value: &HeaderValue)

Add a request header with given value.

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

pub fn remove_header(&mut self, name: &HeaderName) -> bool

Remove all request headers of the given name, and return whether any headers were removed.

pub fn get_version(&self) -> Version

Get the HTTP version of this request.

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

Set the HTTP version of this request.

pub fn get_method(&self, max_length: usize) -> Result<Method, BufferSizeError>

Get the request method.

If the method is longer than max_length, this will return a BufferSizeError; you can retry with a larger buffer size if necessary.

pub fn set_method(&self, method: &Method)

Set the request method.

pub fn get_url(&self, max_length: usize) -> Result<Url, BufferSizeError>

Get the request URL.

If the URL is longer than max_length, this will return a BufferSizeError; you can retry with a larger buffer size if necessary.

pub fn get_uri(&self, max_length: usize) -> Result<Uri, BufferSizeError>

👎 Deprecated since 0.6.0:

replaced by RequestHandle::get_url()

Get the request Uri.

Deprecated in favor of RequestHandle::get_url().

pub fn set_url(&mut self, url: &Url)

Set the request URL.

pub fn set_uri(&mut self, uri: &Uri)

👎 Deprecated since 0.6.0:

replaced by RequestHandle::set_url()

Set the request Uri.

Deprecated in favor of RequestHandle::set_url().

pub fn send(
    self,
    body: BodyHandle,
    backend: &str
) -> Result<(ResponseHandle, BodyHandle), SendErrorCause>

Send the request to the given backend server, and return once the response headers have been received, or an error occurs.

pub fn send_async(
    self,
    body: BodyHandle,
    backend: &str
) -> Result<PendingRequestHandle, SendErrorCause>

Send a request asynchronously via the given backend, returning as soon as the request has begun sending.

The resulting PendingRequestHandle can be evaluated using PendingRequestHandle::poll(), PendingRequestHandle::wait(), or select_handles(). It can also be discarded if the request was sent for effects it might have, and the response is unimportant.

pub fn send_async_streaming(
    self,
    body: BodyHandle,
    backend: &str
) -> Result<(StreamingBodyHandle, PendingRequestHandle), SendErrorCause>

Send a request asynchronously via the given backend, and return a StreamingBodyHandle to allow continued writes to the request body.

The resulting StreamingBodyHandle must be dropped in order to finish sending the request.

pub fn set_cache_override(&mut self, cache_override: &CacheOverride)

Set the cache override behavior for this request.

This setting will override any cache directive headers returned in response to this request.

Trait Implementations

impl Debug for RequestHandle

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

Formats the value using the given formatter.

impl Hash for RequestHandle

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl PartialEq<RequestHandle> for RequestHandle

fn eq(&self, other: &RequestHandle) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &RequestHandle) -> bool

This method tests for !=.

impl RequestHandleCacheKey for RequestHandle

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.

impl Eq for RequestHandle

impl StructuralEq for RequestHandle

impl StructuralPartialEq for RequestHandle