Module body 

HTTP body buffering and streaming utilities for transparent caching.

Design Rationale: Cache Layer Transparency

Hitbox aims to be a transparent caching layer - upstream services and clients should see the same behavior with or without the cache.

Why BufferedBody::Partial exists

When predicates inspect request/response bodies, they consume bytes from the stream. To maintain transparency, these bytes must be forwarded to upstream. Since you can’t “un-read” from a stream, we must:

1. Buffer the consumed prefix
2. Preserve the unconsumed remaining stream
3. Replay prefix + remaining to upstream

This enables:

• Resumable uploads/downloads (e.g., large file transfers)
• Accurate error reporting (errors occur at the same byte position)
• Zero data loss or corruption
• Support for partial transfer protocols (HTTP Range requests, etc.)

Example: Large File Upload

Without cache:
  Client → Upstream: 500MB uploaded, error at byte 300MB

With transparent cache:
  Client → Hitbox (reads 10MB for predicate) → Upstream
  Upstream receives: 10MB (replayed) + 290MB (streamed) + error
  Total: Same 300MB, same error position ✅

Body States

• Complete: Body was fully read and buffered (within configured size limits)
• Partial: Body was partially read - contains buffered prefix plus remaining stream or error
• Passthrough: Body was not inspected at all (zero overhead)

The Partial state is critical for maintaining transparency when:

• Body size exceeds configured limits but must still be forwarded
• Network or upstream errors occur mid-stream
• Predicates need to inspect body content without blocking large transfers

Structs

PartialBufferedBody

A partially consumed body: buffered prefix plus remaining stream.

Enums

BufferedBody

A body wrapper that represents different consumption states.

CollectExactResult

Result of attempting to collect at least N bytes from a body.

Remaining

What remains of a body stream after partial consumption.