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
//! Sans-I/O HTTP codecs and host-driven client policy. No socket, executor or clock reads.
//!
//! # Getting started on turnloop
//! Enable the `turnloop` feature for the `asynchronous` module. The embedding
//! host owns `LocalExecutor` and calls `turn`; adapters await its streams and
//! deadline futures. See the crate README and turnloop-io for ownership, streaming
//! and cancellation examples. Default features retain the sans-I/O API.
//!
//! # The `Step` contract
//!
//! Both decoders here - [`http1::Decoder`] and [`http2::Connection`] - are
//! driven the same way: call `receive` with everything you have, act on the step
//! it returns, drain `consumed`, repeat. **`consumed` and `event` are
//! independent, and a host has to look at both.** The rule is one line:
//!
//! ```text
//! progressed = step.consumed > 0 || step.event.is_some()
//! ```
//!
//! Call `receive` again while `progressed` is true. When it is false, read more
//! bytes from the transport - or declare the end of input with `eof` - before
//! calling again. Each half of that condition has cost a host a debugging cycle,
//! so neither is optional:
//!
//! * **`consumed > 0` with no event** is progress with nothing to hand up: the
//! HTTP/2 client preface, a PRIORITY frame, an
//! unknown frame type, or a frame the peer had in flight for a stream that is
//! already gone; an HTTP/1 chunk-size line, chunk CRLF or empty trailer
//! block. A loop that continues only while an event came back stalls here, and
//! for HTTP/2 the first such step is the preface - so the connection never
//! starts at all.
//! * **`consumed == 0` with an event** is an event that reads no input.
//! HTTP/1's [`http1::Event::End`] and [`http1::Event::Upgrade`] both arrive
//! this way. A loop that continues only while input was consumed - or only
//! while it has input to feed - drops the end of every message;
//! [`http1::Decoder::wants_step`] says when such an event is pending. HTTP/2
//! has no step of this shape: there an event always
//! consumes, and `consumed == 0` is always the stop case.
//! * **`consumed == 0` with no event** is the only stop condition, and it is
//! returned whether the decoder needs more bytes or is finished for good. The
//! two are not distinguishable from the step: a host that has seen
//! [`http1::Event::End`] must remember it (or ask
//! [`http1::Decoder::reusable`]), and an HTTP/2 host closes on
//! [`http2::Connection::is_drained`].
//!
//! `receive` is not idempotent: it advances decoder state by `consumed`, so the
//! host must drain exactly that many bytes before calling again. Feeding the
//! same input back - which is what a stalled loop does when it retries - fails
//! the connection.
//!
//! `asynchronous::Http1::event` and `asynchronous::Http2::event` are the
//! reference drivers, and `Step`'s own documentation carries the per-decoder
//! table.
pub type Result<T> = Result;