Struct fastly::handle::ResponseHandle

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

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:

• ResponseHandle::send_to_client()
• ResponseHandle::stream_to_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::new()
• Response::from_body()

Response handles are also returned from backend requests:

• RequestHandle::send()
• RequestHandle::send_async()
• RequestHandle::send_async_streaming()

Implementations

impl ResponseHandle

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 response handle is valid.

pub fn is_invalid(&self) -> bool

Returns true if the response handle is invalid.

pub fn new() -> Self

Acquire a new response handle.

By default, the response will have a status code of 200 OK and empty headers.

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.

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()
    });

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 response 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 response 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 response headers of the given name, and return whether any headers were removed.

pub fn set_status(&mut self, status: StatusCode)

Set the HTTP status code of this response.

pub fn get_status(&self) -> StatusCode

Get the HTTP status code of this response.

pub fn get_version(&self) -> Version

Get the HTTP version of this response.

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

Set the HTTP version of this response.

pub fn send_to_client(self, body: BodyHandle)

Immediately begin sending this response downstream to the client with the given body.

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.

Trait Implementations

impl Debug for ResponseHandle

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

Formats the value using the given formatter.

impl Hash for ResponseHandle

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<ResponseHandle> for ResponseHandle

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

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

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

This method tests for !=.

impl Eq for ResponseHandle

impl StructuralEq for ResponseHandle

impl StructuralPartialEq for ResponseHandle