Skip to main content

turnloop_http/
lib.rs

1//! Sans-I/O HTTP codecs and host-driven client policy. No socket, executor or clock reads.
2//!
3//! # Getting started on turnloop
4//! Enable the `turnloop` feature for the `asynchronous` module. The embedding
5//! host owns `LocalExecutor` and calls `turn`; adapters await its streams and
6//! deadline futures. See the crate README and turnloop-io for ownership, streaming
7//! and cancellation examples. Default features retain the sans-I/O API.
8//!
9//! # The `Step` contract
10//!
11//! Both decoders here - [`http1::Decoder`] and [`http2::Connection`] - are
12//! driven the same way: call `receive` with everything you have, act on the step
13//! it returns, drain `consumed`, repeat. **`consumed` and `event` are
14//! independent, and a host has to look at both.** The rule is one line:
15//!
16//! ```text
17//! progressed = step.consumed > 0 || step.event.is_some()
18//! ```
19//!
20//! Call `receive` again while `progressed` is true. When it is false, read more
21//! bytes from the transport - or declare the end of input with `eof` - before
22//! calling again. Each half of that condition has cost a host a debugging cycle,
23//! so neither is optional:
24//!
25//! * **`consumed > 0` with no event** is progress with nothing to hand up: the
26//!   HTTP/2 client preface, a PRIORITY frame, an
27//!   unknown frame type, or a frame the peer had in flight for a stream that is
28//!   already gone; an HTTP/1 chunk-size line, chunk CRLF or empty trailer
29//!   block. A loop that continues only while an event came back stalls here, and
30//!   for HTTP/2 the first such step is the preface - so the connection never
31//!   starts at all.
32//! * **`consumed == 0` with an event** is an event that reads no input.
33//!   HTTP/1's [`http1::Event::End`] and [`http1::Event::Upgrade`] both arrive
34//!   this way. A loop that continues only while input was consumed - or only
35//!   while it has input to feed - drops the end of every message;
36//!   [`http1::Decoder::wants_step`] says when such an event is pending. HTTP/2
37//!   has no step of this shape: there an event always
38//!   consumes, and `consumed == 0` is always the stop case.
39//! * **`consumed == 0` with no event** is the only stop condition, and it is
40//!   returned whether the decoder needs more bytes or is finished for good. The
41//!   two are not distinguishable from the step: a host that has seen
42//!   [`http1::Event::End`] must remember it (or ask
43//!   [`http1::Decoder::reusable`]), and an HTTP/2 host closes on
44//!   [`http2::Connection::is_drained`].
45//!
46//! `receive` is not idempotent: it advances decoder state by `consumed`, so the
47//! host must drain exactly that many bytes before calling again. Feeding the
48//! same input back - which is what a stalled loop does when it retries - fails
49//! the connection.
50//!
51//! `asynchronous::Http1::event` and `asynchronous::Http2::event` are the
52//! reference drivers, and `Step`'s own documentation carries the per-decoder
53//! table.
54#![deny(unsafe_op_in_unsafe_fn)]
55pub mod client;
56pub mod compression;
57pub mod hpack;
58pub mod http1;
59pub mod http2;
60pub mod multipart;
61
62#[derive(Debug, Clone, Copy, PartialEq, Eq)]
63pub struct Error {
64    pub code: &'static str,
65    pub message: &'static str,
66}
67impl Error {
68    pub const fn new(code: &'static str, message: &'static str) -> Self {
69        Self { code, message }
70    }
71}
72impl std::fmt::Display for Error {
73    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
74        write!(f, "{}: {}", self.code, self.message)
75    }
76}
77impl std::error::Error for Error {}
78pub type Result<T> = std::result::Result<T, Error>;
79
80mod recycling;
81
82#[cfg(feature = "turnloop")]
83pub mod asynchronous;