--- title: ResponseHandle summary: A low-level interface to HTTP responses. url: https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.ResponseHandle/ --- **Kind:** Struct **Module:** [handle](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/) **Package:** fastly 0.13.1 **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#48 ```rust pub struct ResponseHandle { /* private fields */ } ``` A low-level interface to HTTP responses. For most applications, you should use [`Response`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/struct.Response/) instead of this interface. See the top-level [`handle`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/) documentation for more details. ## Sending to the client Each execution of a Compute program may send a single response back to the client: - [`ResponseHandle::send_to_client()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.ResponseHandle/#method-send_to_client) - [`ResponseHandle::stream_to_client`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.ResponseHandle/#method-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()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.ResponseHandle/#method-new) Response handles are also returned from backend requests: - [`RequestHandle::send()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.RequestHandle/#method-send) - [`RequestHandle::send_async()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.RequestHandle/#method-send_async) - [`RequestHandle::send_async_streaming()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.RequestHandle/#method-send_async_streaming) ## Constants ### INVALID **Type:** `Self` **Flags:** read-only **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#64 An invalid handle. This is primarily useful to represent uninitialized values when using the interfaces in [`fastly_sys`](https://docs.rs/fastly_sys/latest/fastly_sys/index.html). ## Methods ### append_header **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#412 ```rust fn append_header(&mut self, name: &HeaderName, value: &HeaderValue) ``` Add a response header with given value. Unlike [`insert_header()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.ResponseHandle/#method-insert_header), this does not discard existing values for the same header name. **Parameters** - `self`: `&mut Self` - `name`: `&HeaderName` - `value`: `&HeaderValue` ### as_u32 **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#103 ```rust 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. **Parameters** - `self`: `&Self` **Returns** `u32` ### as_u32_mut **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#118 ```rust 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. **Parameters** - `self`: `&mut Self` **Returns** `&mut u32` ### close **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#539 ```rust 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 ```rust let response = ResponseHandle::new(); // The handle is not being used so we can close it out without any // trouble response.close()?; ``` **Parameters** - `self`: `Self` **Returns** `Result<(), HandleError>` ### get_header_names **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#170 ```rust fn get_header_names(&self, buf_size: usize) -> impl Iterator> + '_ ``` 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`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/error/struct.BufferSizeError/); you can retry with a larger buffer size if necessary. **Parameters** - `self`: `&Self` - `buf_size`: `usize` **Returns** `impl Iterator> + '_` ### get_header_value **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#355 ```rust fn get_header_value(&self, name: &HeaderName, max_len: usize) -> Result, 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()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.ResponseHandle/#method-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`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/error/struct.BufferSizeError/); you can retry with a larger buffer size if necessary. **Parameters** - `self`: `&Self` - `name`: `&HeaderName` - `max_len`: `usize` **Returns** `Result, BufferSizeError>` ### get_header_values **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#271 ```rust fn get_header_values<'a>(&'a self, name: &'a HeaderName, max_len: usize) -> impl Iterator> + '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`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/error/struct.BufferSizeError/); you can retry with a larger buffer size if necessary. ###### Examples Collect all the header values into a [`Vec`](https://doc.rust-lang.org/stable/alloc/vec/struct.Vec.html): ```rust let name = HeaderName::from_static("My-App-Header"); let buf_size = 128; let header_values: Vec = response .get_header_values(&name, buf_size) .collect::, _>>()?; ``` To try again with a larger buffer if the first call fails, you can use [`unwrap_or_else()`](https://doc.rust-lang.org/stable/core/result/Result/fn.unwrap_or_else.html): ```rust let name = HeaderName::from_static("My-App-Header"); let buf_size = 128; // Collect header values into a `Vec`, 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 = response .get_header_values(&name, buf_size) .collect::>() .unwrap_or_else(|err: BufferSizeError| { eprintln!("buffer size error: {}", err); let larger_buf_size = 1024; response .get_header_values(&name, larger_buf_size) .collect::>() .unwrap() }); ``` **Parameters** - `self`: `&Self` - `name`: `&HeaderName` - `max_len`: `usize` **Returns** `impl Iterator> + 'a` ### get_status **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#453 ```rust fn get_status(&self) -> StatusCode ``` Get the HTTP status code of this response. **Parameters** - `self`: `&Self` **Returns** `StatusCode` ### get_version **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#464 ```rust fn get_version(&self) -> Version ``` Get the HTTP version of this response. **Parameters** - `self`: `&Self` **Returns** `Version` ### insert_header **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#392 ```rust 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. **Parameters** - `self`: `&mut Self` - `name`: `&HeaderName` - `value`: `&HeaderValue` ### into_u32 **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#133 ```rust 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. **Parameters** - `self`: `Self` **Returns** `u32` ### is_invalid **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#88 ```rust const fn is_invalid(&self) -> bool ``` Returns `true` if the response handle is invalid. **Parameters** - `self`: `&Self` **Returns** `bool` ### is_valid **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#76 ```rust const fn is_valid(&self) -> bool ``` Returns `true` if the response handle is valid. **Parameters** - `self`: `&Self` **Returns** `bool` ### new **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#157 ```rust fn new() -> Self ``` Acquire a new response handle. By default, the response will have a status code of `200 OK` and empty headers. **Returns** `Self` ### remote_addr **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#547 ```rust fn remote_addr(&self) -> Result, AddrParseError> ``` Get the address of the server that sent the response. **Parameters** - `self`: `&Self` **Returns** `Result, AddrParseError>` ### remove_header **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#429 ```rust fn remove_header(&mut self, name: &HeaderName) -> bool ``` Remove all response headers of the given name, and return whether any headers were removed. **Parameters** - `self`: `&mut Self` - `name`: `&HeaderName` **Returns** `bool` ### send_to_client **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#486 ```rust fn send_to_client(self, body: BodyHandle) ``` Immediately begin sending this response downstream to the client with the given body. **Parameters** - `self`: `Self` - `body`: `BodyHandle` ### set_framing_headers_mode **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#508 ```rust fn set_framing_headers_mode(&mut self, mode: FramingHeadersMode) ``` Sets the way that framing headers are determined for this response. **Parameters** - `self`: `&mut Self` - `mode`: `FramingHeadersMode` ### set_header_values **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#329 ```rust fn set_header_values<'a, I>(&mut self, name: &HeaderName, values: I) where I: IntoIterator, ``` Set the values for the given header name, replacing any headers that previously existed for that name. **Parameters** - `self`: `&mut Self` - `name`: `&HeaderName` - `values`: `I` ### set_status **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#446 ```rust fn set_status(&mut self, status: StatusCode) ``` Set the HTTP status code of this response. **Parameters** - `self`: `&mut Self` - `status`: `StatusCode` ### set_version **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#477 ```rust fn set_version(&mut self, v: Version) ``` Set the HTTP version of this response. **Parameters** - `self`: `&mut Self` - `v`: `Version` ### stream_to_client **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#496 ```rust fn stream_to_client(self, body: BodyHandle) -> StreamingBodyHandle ``` Immediately begin sending this response downstream to the client, and return a [`StreamingBodyHandle`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/handle/struct.StreamingBodyHandle/) that can accept further data to send. **Parameters** - `self`: `Self` - `body`: `BodyHandle` **Returns** `StreamingBodyHandle` ## Trait implementations ### impl Debug for ResponseHandle #### fmt **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#45 ```rust fn fmt(&self, f: &mut Formatter<'_>) -> Result ``` **Parameters** - `self`: `&Self` - `f`: `&mut $crate::fmt::Formatter` **Returns** `$crate::fmt::Result` ### impl Drop for ResponseHandle #### drop **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#585 ```rust fn drop(&mut self) ``` **Parameters** - `self`: `&mut Self` ### impl Hash for ResponseHandle #### hash **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#46 ```rust fn hash<__H: Hasher>(&self, state: &mut __H) ``` **Parameters** - `self`: `&Self` - `state`: `&mut __H` ### impl PartialEq for ResponseHandle #### eq **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/http/response/handle.rs#46 ```rust fn eq(&self, other: &Self) -> bool ``` **Parameters** - `self`: `&Self` - `other`: `&Self` **Returns** `bool` ## Auto trait implementations - `Freeze` - `RefUnwindSafe` - `Send` - `Sync` - `Unpin` - `UnsafeUnpin` - `UnwindSafe` ## Blanket implementations - `Any` - `Borrow` - `BorrowMut` - `Downcast` - `DowncastSync` - `Equivalent` - `ErasedDestructor` - `From` - `Into` - `IntoEither` - `Same` - `TryFrom` - `TryInto`