Struct fastly::handle::RequestHandle
source · #[repr(transparent)]pub struct RequestHandle { /* private fields */ }
Expand description
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§
source§impl RequestHandle
impl RequestHandle
sourcepub const INVALID: Self = _
pub const INVALID: Self = _
An invalid handle.
This is primarily useful to represent uninitialized values when using the interfaces in
fastly_sys
.
sourcepub const fn is_invalid(&self) -> bool
pub const fn is_invalid(&self) -> bool
Returns true
if the request handle is invalid.
sourcepub fn as_u32(&self) -> u32
pub fn as_u32(&self) -> u32
Get the underlying representation of the handle.
This should only be used when calling the raw ABI directly, and care should be taken not to reuse or alias handle values.
sourcepub fn as_u32_mut(&mut self) -> &mut u32
pub fn as_u32_mut(&mut self) -> &mut u32
Get a mutable reference to the underlying u32
representation of the handle.
This should only be used when calling the raw ABI directly, and care should be taken not to reuse or alias handle values.
sourcepub fn from_client() -> Self
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()
.
sourcepub fn new() -> Self
pub fn new() -> Self
Acquire a new request handle.
By default, the request will have a GET
method, a URL of /
, and empty headers.
sourcepub fn get_header_names<'a>(
&'a self,
buf_size: usize
) -> impl Iterator<Item = Result<HeaderName, BufferSizeError>> + 'a
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.
sourcepub fn get_header_values<'a>(
&'a self,
name: &'a HeaderName,
buf_size: usize
) -> impl Iterator<Item = Result<HeaderValue, BufferSizeError>> + 'a
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()
});
sourcepub fn set_header_values<'a, I>(&mut self, name: &HeaderName, values: I)where
I: IntoIterator<Item = &'a HeaderValue>,
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.
sourcepub fn get_header_value(
&self,
name: &HeaderName,
max_len: usize
) -> Result<Option<HeaderValue>, BufferSizeError>
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.
sourcepub fn insert_header(&mut self, name: &HeaderName, value: &HeaderValue)
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.
sourcepub fn append_header(&mut self, name: &HeaderName, value: &HeaderValue)
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.
sourcepub fn remove_header(&mut self, name: &HeaderName) -> bool
pub fn remove_header(&mut self, name: &HeaderName) -> bool
Remove all request headers of the given name, and return whether any headers were removed.
sourcepub fn get_version(&self) -> Version
pub fn get_version(&self) -> Version
Get the HTTP version of this request.
sourcepub fn set_version(&mut self, v: Version)
pub fn set_version(&mut self, v: Version)
Set the HTTP version of this request.
sourcepub fn get_method(&self, max_length: usize) -> Result<Method, BufferSizeError>
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.
sourcepub fn set_method(&self, method: &Method)
pub fn set_method(&self, method: &Method)
Set the request method.
sourcepub fn get_url(&self, max_length: usize) -> Result<Url, BufferSizeError>
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.
sourcepub fn send(
self,
body: BodyHandle,
backend: &str
) -> Result<(ResponseHandle, BodyHandle), SendErrorCause>
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.
sourcepub fn send_async(
self,
body: BodyHandle,
backend: &str
) -> Result<PendingRequestHandle, SendErrorCause>
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.
sourcepub fn send_async_streaming(
self,
body: BodyHandle,
backend: &str
) -> Result<(StreamingBodyHandle, PendingRequestHandle), SendErrorCause>
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.
StreamingBodyHandle::finish()
must be called in order to finish sending the request.
sourcepub fn set_cache_override(&mut self, cache_override: &CacheOverride)
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.
sourcepub fn close(self) -> Result<(), HandleError>
pub fn close(self) -> Result<(), HandleError>
Close the RequestHandle by removing it from the host Session. If the handle has already
been closed an error will be returned. When calling
send/send_async/send_async_streaming the RequestHandle is consumed and
it’s cleaned up. You should only call close
if you have not sent a
request yet and want to clean up the resources if not being used.
Examples
let request = RequestHandle::new();
// The handle is not being used so we can close it out without any
// trouble
request.close()?;
sourcepub fn set_auto_decompress_response(
&mut self,
content_encodings: ContentEncodings
)
pub fn set_auto_decompress_response( &mut self, content_encodings: ContentEncodings )
Set the content encodings to automatically decompress responses to this request.
If the response to this request is encoded by one of the encodings set by this method, the
response will be presented to the Compute@Edge program in decompressed form with the
Content-Encoding
and Content-Length
headers removed.
sourcepub fn set_framing_headers_mode(&mut self, mode: FramingHeadersMode)
pub fn set_framing_headers_mode(&mut self, mode: FramingHeadersMode)
Sets the way that framing headers are determined for this request.
Trait Implementations§
source§impl Debug for RequestHandle
impl Debug for RequestHandle
source§impl Drop for RequestHandle
impl Drop for RequestHandle
source§impl Hash for RequestHandle
impl Hash for RequestHandle
source§impl PartialEq<RequestHandle> for RequestHandle
impl PartialEq<RequestHandle> for RequestHandle
source§fn eq(&self, other: &RequestHandle) -> bool
fn eq(&self, other: &RequestHandle) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl RequestHandleUpgradeWebsocket for RequestHandle
impl RequestHandleUpgradeWebsocket for RequestHandle
source§fn handoff_websocket(&mut self, backend: &str) -> Result<(), SendErrorCause>
fn handoff_websocket(&mut self, backend: &str) -> Result<(), SendErrorCause>
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.
source§fn handoff_fanout(&mut self, backend: &str) -> Result<(), SendErrorCause>
fn handoff_fanout(&mut self, backend: &str) -> Result<(), SendErrorCause>
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.