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
//! # io-http
//!
//! I/O-free HTTP client coroutines. Every network exchange is a
//! resumable state machine that emits read and write requests instead
//! of performing I/O itself: the caller owns the socket and pumps the
//! coroutine with the bytes it read, whatever the runtime (blocking,
//! async, in-memory tests). The `client` feature ships a ready-made
//! std-blocking pump for callers who just want a working client.
//!
//! ## Layout: one folder per RFC
//!
//! io-http covers HTTP in general; today HTTP/1.0 and HTTP/1.1 are
//! implemented. The source tree mirrors how the HTTP specification
//! itself is split, one module per RFC, so the RFC number is the
//! version discriminator: a future version (HTTP/2, HTTP/3) would slot
//! in as its own RFC modules alongside the existing ones.
//! [`rfc9110`] holds the version-agnostic semantics shared by every
//! wire format: the request and response types, status codes, header
//! name constants, authentication challenge parsing, and the output
//! and yield types common to both send coroutines. [`rfc1945`]
//! implements the HTTP/1.0 wire protocol and [`rfc9112`] the HTTP/1.1
//! one: each ships its request serialiser and send coroutine, and
//! HTTP/1.1 adds the response-head parser plus two chunked
//! transfer-coding decoders (whole-body and streaming).
//!
//! Around the wire protocols, [`rfc6750`] and [`rfc7617`] provide the
//! bearer and basic authorization header helpers, with secrets
//! redacted from debug output; [`rfc8615`] wraps the HTTP/1.1 send
//! coroutine into a well-known URI discovery coroutine surfacing the
//! redirect target.
//!
//! Two modules span the RFC modules and therefore live at the crate
//! root: [`coroutine`] defines the coroutine contract every state
//! machine implements, and [`sse`] parses W3C Server-Sent Events
//! frames (a WHATWG HTML Living Standard, not an RFC, hence its own
//! name). The optional [`client`] module (`client` feature) is the
//! std-blocking pump: a light client wrapping any stream you opened
//! yourself, or a full client opening the TCP/TLS connection itself
//! when one of the TLS features is enabled.
//!
//! ## The coroutine contract
//!
//! Every coroutine implements [`coroutine::HttpCoroutine`]: a resume
//! method taking the bytes read since the last step and returning
//! either an intermediate yield or a terminal completion. Standard
//! coroutines yield the shared read/write requests of
//! [`coroutine::HttpYield`]; richer coroutines declare their own yield
//! type, like the send coroutines surfacing 3xx redirects to the
//! caller instead of following them, or the streaming decoders
//! yielding one frame at a time. Completion carries a per-coroutine
//! output or error; the [`http_try`] macro chains an inner coroutine
//! step inside an outer resume, re-yielding and short-circuiting like
//! the question mark operator.
//!
//! ## Conventions
//!
//! The crate is no_std with alloc; std only enters behind the `client`
//! feature. Public items carry the version-agnostic `Http` prefix when
//! they belong to the shared semantics, and the version-scoped
//! `Http10` / `Http11` prefix when they are tied to a wire format; the
//! `Sse` family keeps its own deliberate namespace. Logging follows
//! the library rules: state changes at debug level, in-process steps
//! and data dumps at trace level.
extern crate alloc;
extern crate std;