RequestHandle

An invalid handle.

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

Add a request header with given value.

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

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.

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.

A byte string indicating the type of bot detected (e.g., SEARCH-ENGINE-CRAWLER, AI-CRAWLER, SUSPECTED-BOT). Returns None if bot detection was not executed.

Warning: Values may change over time. Use this for logging or informational purposes. For conditional logic, use the bot_category_kind() value.

A byte string identifying the specific bot detected (e.g., GoogleBot, GPTBot, Bingbot). Returns None if bot detection was not executed or no bot was detected.

Warning: Values may change over time. Use this for logging or informational purposes. For conditional logic, use the bot_category_kind() value.

Returns the number of headers in the client request as originally received.

If this is not a valid downstream handle then this will return None.

Returns the client request's header names exactly as they were originally received.

This includes both the original header name characters' cases, as well as the original order of the received headers.

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

Get the cipher suite used to secure the downstream client TLS connection, as a string, panicking if it is not UTF-8.

The value returned will be consistent with the OpenSSL name for the cipher suite.

Examples

let handle = RequestHandle::from_client();
assert_eq!(
    handle.client_tls_cipher_openssl_name().unwrap(),
    "ECDHE-RSA-AES128-GCM-SHA256"
);

Returns the ClientCertVerifyResult from the downstream client mTLS handshake.

Returns None if not available.

Get the raw bytes sent by the client in the TLS ClientHello message.

See RFC 5246 for details.

Get the client certificate used to secure the downstream client mTLS connection, as a string, panicking if it is not UTF-8.

The value returned will be based on PEM format.

Get the hostname sent by the client in the TLS ServerName Indication.

See RFC 6066 for details.

Get the TLS protocol version used to secure the downstream client TLS connection, as a string, panicking if it is not UTF-8.

Examples

let handle = RequestHandle::from_client();
assert_eq!(handle.client_tls_protocol().unwrap().as_deref(), Some("TLSv1.2"));

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/sendasync/sendasync_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()?;

Get a handle to the client request being handled by this execution of the Compute program.

Panics

This method panics if the client request has already been retrieved by this method, client_request_and_body(), or Request::from_client().

Turn a handle representation into a RequestHandle Handle, claiming ownership of the underlying resource.

Safety

This should only be used when calling the raw ABI directly, and care should be taken not to reuse or alias handle values.

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.

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.

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():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

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.

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.

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.

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.

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.

Acquire a new request handle.

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

Perform this send on behalf of another service, meaning that we will use that service's cache to look up and store the result.

Internal / Privileged

This operation is privileged, and attempts to use this functionality without proper privileges will cause errors. If you are interested in having two or more of your services share the same cache, please talk to your Fastly account representative. While we have no plans to offer this ability widely -- this capability is only currently allowed for Fastly-internal services -- we may revisit this decision given sufficient customer input.

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.

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.

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.

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.

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 program in decompressed form with the Content-Encoding and Content-Length headers removed.

Set the cache override behavior for this request.

This setting will override any cache directive headers returned in response to this request. Note that staleiferror is not overridden by this mechanism.