Struct fastly::handle::ResponseHandle
source · #[repr(transparent)]pub struct ResponseHandle { /* private fields */ }
Expand description
A low-level interface to HTTP responses.
For most applications, you should use Response
instead of this interface. See the top-level
handle
documentation for more details.
Sending to the client
Each execution of a Compute@Edge program may send a single response back to the client:
If no response is explicitly sent by the program, a default 200 OK
response is sent.
Creation and conversion
Response handles can be created programmatically using ResponseHandle::new()
Response handles are also returned from backend requests:
Implementations§
source§impl ResponseHandle
impl ResponseHandle
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 response handle is invalid.
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 into_u32(self) -> u32
pub fn into_u32(self) -> u32
Turn a handle into its representation without closing the underlying resource.
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 new() -> Self
pub fn new() -> Self
Acquire a new response handle.
By default, the response will have a status code of 200 OK
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 response’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,
max_len: usize
) -> impl Iterator<Item = Result<HeaderValue, BufferSizeError>> + 'a
pub fn get_header_values<'a>(
&'a self,
name: &'a HeaderName,
max_len: usize
) -> impl Iterator<Item = Result<HeaderValue, BufferSizeError>> + 'a
Get a response’s header values given a header 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> = response
.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> = response
.get_header_values(&name, buf_size)
.collect::<Result<_, _>>()
.unwrap_or_else(|err: BufferSizeError| {
eprintln!("buffer size error: {}", err);
let larger_buf_size = 1024;
response
.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 response 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 response 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 response headers of the given name, and return whether any headers were removed.
sourcepub fn set_status(&mut self, status: StatusCode)
pub fn set_status(&mut self, status: StatusCode)
Set the HTTP status code of this response.
sourcepub fn get_status(&self) -> StatusCode
pub fn get_status(&self) -> StatusCode
Get the HTTP status code of this response.
sourcepub fn get_version(&self) -> Version
pub fn get_version(&self) -> Version
Get the HTTP version of this response.
sourcepub fn set_version(&mut self, v: Version)
pub fn set_version(&mut self, v: Version)
Set the HTTP version of this response.
sourcepub fn send_to_client(self, body: BodyHandle)
pub fn send_to_client(self, body: BodyHandle)
Immediately begin sending this response downstream to the client with the given body.
sourcepub fn stream_to_client(self, body: BodyHandle) -> StreamingBodyHandle ⓘ
pub fn stream_to_client(self, body: BodyHandle) -> StreamingBodyHandle ⓘ
Immediately begin sending this response downstream to the client, and return a
StreamingBodyHandle
that can accept further data to send.
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 response.
sourcepub fn close(self) -> Result<(), HandleError>
pub fn close(self) -> Result<(), HandleError>
Close the ResponseHandle by removing it from the host Session. If the handle has already been closed an error will be returned. A ResponseHandle is only consumed when you send a response to a client or stream one to a client. You should call close only if you don’t intend to use that Response anymore.
Examples
let response = ResponseHandle::new();
// The handle is not being used so we can close it out without any
// trouble
response.close()?;
Trait Implementations§
source§impl Debug for ResponseHandle
impl Debug for ResponseHandle
source§impl Drop for ResponseHandle
impl Drop for ResponseHandle
source§impl Hash for ResponseHandle
impl Hash for ResponseHandle
source§impl PartialEq<ResponseHandle> for ResponseHandle
impl PartialEq<ResponseHandle> for ResponseHandle
source§fn eq(&self, other: &ResponseHandle) -> bool
fn eq(&self, other: &ResponseHandle) -> bool
self
and other
values to be equal, and is used
by ==
.