Crate body_image

This crate provides a few separately usable but closely related HTTP ecosystem components.

In the root module, BodyImage, BodySink and supporting types provide a strategy for safely handling potentially large HTTP request or response bodies without risk of allocation failure, or the need to impose awkwardly low size limits in the face of high concurrency. Tunables size thresholds can be used to decide when to accumulate the body in RAM vs the filesystem, including when the length is unknown in advance.

See the top level README for additional rationale.

A Dialog defines a complete HTTP request and response recording, using BodyImage for the request and response bodies and http crate types for the headers and other components.

The barc module defines a container file format, reader and writer for dialog records. This has broad use cases, from convenient test fixtures for web applications, to caching and web crawling.

Optional Features

The following features may be enabled or disabled at build time. All are enabled by default.

async: The async module for input to BodySink, output of BodyImage, and recording of HTTP Dialogs via hyper 0.12+ and tokio. Originally the async module was named client , but this would be misleading as async is also usable in a server (request or response contexts as well). The client path name, now a re-export, is deprecated as of 0.4.0 in preference to the async name.

cli: The barc command line tool for viewing (e.g. compressed) records and copying records across BARC files. If the async feature is enabled, then a record command is also provided for live BARC recording from the network.

brotli: Brotli transfer/content decoding in async module, and Brotli BARC record compression (in barc), via the native-rust brotli crate. (Gzip, via the flate2 crate, is standard.)

mmap: Adds BodyImage::mem_map support for memory mapping from FsRead state.

Re-exports

pub use async as client;

Modules

async	Asynchronous HTTP integration and utilities.
barc	Body Archive container file format, reader and writer.

Structs

BodyImage	A logical buffer of bytes, which may or may not be RAM resident.
BodySink	A logical buffer of bytes, which may or may not be RAM resident, in the process of being written. This is the write-side corollary to BodyImage.
Dialog	An HTTP request and response recording.
Tunables	A collection of size limits and performance tuning constants. Setters are available via Tuner
Tuner	A builder for Tunables. Invariants are asserted in the various setters and finish.

Enums

BodyError	Error enumeration for BodyImage and BodySink types. This may be extended in the future so exhaustive matching is gently discouraged with an unused variant.
BodyReader	Provides a Read reference for a BodyImage in any state.
Encoding	A subset of supported HTTP Transfer or Content-Encoding values. The Display/ToString representation is as per the HTTP header value.
ExplodedImage	Exploded representation of the possible BodyImage states, obtained via BodyImage::explode.

Statics

VERSION

The crate version string.

Traits

Recorded	Access by reference for HTTP request (via RequestRecorded) and response recording types.
RequestRecorded	Access by reference for HTTP request recording types.
TryFrom	Similar to the TryFrom trait proposed but not yet available in std.
TryInto	Similar to the TryInto trait proposed but not yet available in std. Blanket implemented for all TryFrom.