body 0.1.0

Policy-managed body lifecycle primitives for Rust systems.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# body

Policy-managed body lifecycle primitives for Rust systems.

`body` is about the lifecycle of payloads: limits, draining, replay,
shutdown, failure semantics, observability, and ownership boundaries.

It does not replace `http-body`, `http-body-util`, `hyper`, `tower`, or
`bytes`. Those crates provide excellent protocol-level and utility-level
building blocks. `body` aims to provide a higher-level policy layer around
them.

## Status

`body` is an early foundation release.

The initial API is intentionally small: it establishes the vocabulary, policy
types, and lifecycle model that later protocol integrations will build on.
Support for `http-body`, `hyper`, `tower`, and async runtimes is planned as the
semantics settle.

## Why

Bodies are not just bytes.

A request, response, message, stream, or payload body has operational
consequences:

- it may be streamed, buffered, rejected, drained, replayed, or aborted
- it may exceed limits
- it may begin as a future body that is not a stream yet
- it may outlive the request or message head
- it may affect connection reuse
- it may interact with graceful shutdown
- it may need observability and accounting
- it may need different behavior under upstream failure

`body` exists to make those semantics explicit.

## Protocol Independence

`body` is protocol-independent.

It treats a body as a payload lifecycle boundary, not as an HTTP-only type.
HTTP request and response bodies are important use cases, but the same policy
questions appear in TCP, Unix sockets, UDP, QUIC, WebTransport, WebSocket, RPC,
uploads, downloads, and other streamed payload systems.

Protocol integrations will come later as optional crates or features.

## Non-goals

- This crate does not replace `http-body`.
- This crate does not compete with `http-body-util`.
- This crate does not hide protocol crates behind a large framework.
- This crate does not force a single async runtime.
- This crate does not promise every protocol integration in `0.1`.

## Initial API

The first public API focuses on policy and lifecycle vocabulary:

- `BodyPolicy`
- `BodyState`
- `BodyGuard`
- `BodyDecision`
- `OverflowPolicy`
- `DropPolicy`
- `DrainPolicy`
- `ReplayPolicy`
- `ShutdownPolicy`

## Example

```rust
use body::{BodyDecision, BodyGuard, OverflowPolicy};

let mut body = BodyGuard::new(())
    .max_bytes(1024)
    .overflow(OverflowPolicy::DrainThenReject);

assert_eq!(body.observe_bytes(512), BodyDecision::Continue);
assert_eq!(body.observe_bytes(600), BodyDecision::DrainThenReject);
```

## Planned timeline

### 0.1

Foundation release.

- core policy types
- lifecycle state model
- minimal `BodyGuard<B>`
- protocol-independent byte accounting decisions
- documentation of semantics and non-goals

### 0.2

HTTP body integration.

- `http-body` compatibility
- byte counting
- limit enforcement
- error classification

### 0.3

Operational semantics.

- drain helpers
- timeout hooks
- shutdown behavior
- observability hooks

### 0.4

Integration layer.

- optional `hyper` support
- optional `tower` support
- test bodies for slow, endless, partial, and failing streams

## Philosophy

The head declares intent.

The body carries consequence.