Expand description
Low-level interfaces to the Compute APIs.
For most applications, you should instead use the types in the top level of the crate, such as
Request
and Response
.
Reasons not to use handles
-
The high-level interface has many more conveniences for application development. For example, there are methods for transparently reading and writing HTTP bodies as JSON, and common function argument types such as header values can accept and convert a variety of types automatically.
-
BodyHandle
andStreamingBodyHandle
are unbuffered. Performance can suffer dramatically if repeated small reads and writes are made to these types. The higher-level equivalents,Body
andStreamingBody
are buffered automatically, though you can explicitly control some aspects of the buffering usingstd::io::BufRead
andstd::io::Write::flush()
. -
Explicit buffer sizes are required to get data such as header values from the Compute host. If the size you choose isn’t large enough, the operation will fail with an error and make you try again. The high-level interfaces automatically retry any such operations with the necessary buffer sizes, within limits set by the
limits
module. -
The high-level interface keeps data about a request or response in WebAssembly memory until it is sent to the client or a backend, whereas the handle interface is backed by memory in the Compute host.
Suppose your application needs to manipulate headers in multiple functions. The handle interface would require you to either manually keep track of the headers separately from the handle they came from, or perform redundant copies to and from WebAssembly memory. The high-level interface would keep all of your header information in WebAssembly until it’s ready to use, improving performance.
When to use handles
The list of cases where we recommend using the handle interface is rather short, but that doesn’t mean there aren’t more that we haven’t thought of. If you find more cases where the handle interface gives you an advantage over the high-level interface, we would love to hear from you!
-
If your application needs to forward requests or responses with very large headers, but never needs to inspect or log those headers, the handle interface will allow you to avoid copying those headers into and out of WebAssembly memory unnecessarily.
-
If you are building your own higher-level abstractions for HTTP, or connecting the
fastly
crate to another HTTP library ecosystem, you may find it more direct to use the handle interface. Do note, however, that the high-levelRequest
andResponse
types can be cheaply converted to and fromhttp::Request
andhttp::Response
, which are widely used by other libraries.
Re-exports
pub use crate::http::request::handle::client_h2_fingerprint;
pub use crate::http::request::handle::client_oh_fingerprint;
Modules
- Low-level Compute Config Store interfaces.
- dictionaryDeprecatedLow-level Compute Dictionary interfaces.
Structs
- A low-level interface to HTTP bodies.
- A handle to a pending asynchronous request returned by
RequestHandle::send_async()
orRequestHandle::send_async_streaming()
. - The low-level interface to HTTP requests.
- A low-level interface to HTTP responses.
- A low-level interface to a streaming HTTP body.
Enums
- Optional override for response caching behavior.
- The result of a call to
PendingRequestHandle::poll()
.
Functions
- Returns the IP address of the client making the HTTP request.
- Returns the number of headers in the client request as originally received.
- Returns the client request’s header names exactly as they were originally received.
- Get handles to the client request headers and body at the same time.
- Get the id of the current equest if available
- Get the cipher suite used to secure the downstream client TLS connection, as a string, panicking if it is not UTF-8.
- Get the raw bytes sent by the client in the TLS ClientHello message.
- Get the JA3 hash of the TLS ClientHello message.
- Get the TLS protocol version used to secure the downstream client TLS connection, as a string, panicking if it is not UTF-8.
- Given a collection of
PendingRequestHandle
s, block until the result of one of the handles is ready.