eggfetch_http_connect/lib.rs
1//! Reusable HTTP/1 CONNECT wire mechanics over a caller-owned async stream.
2//!
3//! This crate serializes `CONNECT` request bytes and parses CONNECT
4//! response heads. It does not dial sockets, perform TLS, retry, decide
5//! whether a status is acceptable, or own request deadlines.
6//!
7//! - The caller supplies an already-connected async byte stream.
8//! - [`ConnectTarget`] owns authority formatting (including IPv6 rules).
9//! - [`encode_connect_request`] serializes the request head.
10//! - [`read_connect_response_head`] parses the bounded response head while
11//! preserving read-ahead bytes for the tunnel.
12//! - Timeouts stay with the caller: wrap the encode/write future with a
13//! write deadline and the read future with a read deadline.
14//!
15//! ```rust
16//! use eggfetch_http_connect::{
17//! ConnectRequest, ConnectResponseLimits, ConnectTarget,
18//! encode_connect_request, read_connect_response_head,
19//! };
20//! use tokio::io::BufReader;
21//!
22//! # #[tokio::main(flavor = "current_thread")]
23//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
24//! let target = ConnectTarget::new("example.com", 443)?;
25//! let request = ConnectRequest {
26//! target: &target,
27//! proxy_authorization: None,
28//! extra_headers: &[],
29//! max_head_bytes: 64 * 1024,
30//! };
31//! let bytes = encode_connect_request(&request)?;
32//! assert!(bytes.starts_with(b"CONNECT example.com:443 HTTP/1.1\r\n"));
33//!
34//! // In-memory stream: response head plus tunneled payload in one write.
35//! let payload = b"HTTP/1.1 200 Connection Established\r\n\r\ntunneled-bytes";
36//! let stream = tokio::io::duplex(1024);
37//! let (mut client, mut server) = stream;
38//! {
39//! use tokio::io::AsyncWriteExt;
40//! server.write_all(payload).await?;
41//! drop(server);
42//! }
43//! let mut reader = BufReader::new(client);
44//! let head =
45//! read_connect_response_head(&mut reader, &ConnectResponseLimits::default()).await?;
46//! assert_eq!(head.status, 200);
47//! // Read-ahead remains readable through the same buffered stream.
48//! {
49//! use tokio::io::AsyncReadExt;
50//! let mut rest = Vec::new();
51//! reader.read_to_end(&mut rest).await?;
52//! assert_eq!(rest, b"tunneled-bytes");
53//! }
54//! # Ok(())
55//! # }
56//! ```
57
58mod error;
59mod request;
60mod response;
61mod target;
62
63pub use error::ConnectError;
64pub use request::{basic_auth_value, encode_connect_request, ConnectRequest};
65pub use response::{read_connect_response_head, ConnectResponseHead, ConnectResponseLimits};
66pub use target::ConnectTarget;