async_h1/
lib.rs

1//! Streaming async HTTP 1.1 parser.
2//!
3//! At its core HTTP is a stateful RPC protocol, where a client and server
4//! communicate with one another by encoding and decoding messages between them.
5//!
6//! - `client` encodes HTTP requests, and decodes HTTP responses.
7//! - `server` decodes HTTP requests, and encodes HTTP responses.
8//!
9//! A client always starts the HTTP connection. The lifetime of an HTTP
10//! connection looks like this:
11//!
12//! ```txt
13//! 1. encode            2. decode
14//!         \            /
15//!         -> request  ->
16//!  client                server
17//!         <- response <-
18//!         /            \
19//! 4. decode            3. encode
20//! ```
21//!
22//! See also [`async-tls`](https://docs.rs/async-tls),
23//! [`async-std`](https://docs.rs/async-std).
24//!
25//! # Example
26//!
27//! __HTTP client__
28//!
29//! ```no_run
30//! use async_std::net::TcpStream;
31//! use http_types::{Method, Request, Url};
32//!
33//! #[async_std::main]
34//! async fn main() -> http_types::Result<()> {
35//!     let stream = TcpStream::connect("127.0.0.1:8080").await?;
36//!
37//!     let peer_addr = stream.peer_addr()?;
38//!     println!("connecting to {}", peer_addr);
39//!     let url = Url::parse(&format!("http://{}/foo", peer_addr))?;
40//!
41//!     let req = Request::new(Method::Get, url);
42//!     let res = async_h1::connect(stream.clone(), req).await?;
43//!     println!("{:?}", res);
44//!
45//!     Ok(())
46//! }
47//! ```
48//!
49//! __HTTP Server__
50//!
51//! ```no_run
52//! use async_std::net::{TcpStream, TcpListener};
53//! use async_std::prelude::*;
54//! use async_std::task;
55//! use http_types::{Response, StatusCode};
56//!
57//! #[async_std::main]
58//! async fn main() -> http_types::Result<()> {
59//!     // Open up a TCP connection and create a URL.
60//!     let listener = TcpListener::bind(("127.0.0.1", 8080)).await?;
61//!     let addr = format!("http://{}", listener.local_addr()?);
62//!     println!("listening on {}", addr);
63//!
64//!     // For each incoming TCP connection, spawn a task and call `accept`.
65//!     let mut incoming = listener.incoming();
66//!     while let Some(stream) = incoming.next().await {
67//!         let stream = stream?;
68//!         task::spawn(async {
69//!             if let Err(err) = accept(stream).await {
70//!                 eprintln!("{}", err);
71//!             }
72//!         });
73//!     }
74//!     Ok(())
75//! }
76//!
77//! // Take a TCP stream, and convert it into sequential HTTP request / response pairs.
78//! async fn accept(stream: TcpStream) -> http_types::Result<()> {
79//!     println!("starting new connection from {}", stream.peer_addr()?);
80//!     async_h1::accept(stream.clone(), |_req| async move {
81//!         let mut res = Response::new(StatusCode::Ok);
82//!         res.insert_header("Content-Type", "text/plain");
83//!         res.set_body("Hello");
84//!         Ok(res)
85//!     })
86//!     .await?;
87//!     Ok(())
88//! }
89//! ```
90
91#![forbid(unsafe_code)]
92#![deny(missing_debug_implementations, nonstandard_style, rust_2018_idioms)]
93#![warn(missing_docs, missing_doc_code_examples, unreachable_pub)]
94#![cfg_attr(test, deny(warnings))]
95#![allow(clippy::if_same_then_else)]
96#![allow(clippy::len_zero)]
97#![allow(clippy::match_bool)]
98#![allow(clippy::unreadable_literal)]
99
100/// The maximum amount of headers parsed on the server.
101const MAX_HEADERS: usize = 128;
102
103/// The maximum length of the head section we'll try to parse.
104/// See: https://nodejs.org/en/blog/vulnerability/november-2018-security-releases/#denial-of-service-with-large-http-headers-cve-2018-12121
105const MAX_HEAD_LENGTH: usize = 8 * 1024;
106
107mod body_encoder;
108mod chunked;
109mod date;
110mod read_notifier;
111
112pub mod client;
113pub mod server;
114
115use body_encoder::BodyEncoder;
116pub use client::connect;
117use futures_lite::io::Cursor;
118pub use server::{accept, accept_with_opts, ServerOptions};
119
120#[derive(Debug)]
121pub(crate) enum EncoderState {
122    Start,
123    Head(Cursor<Vec<u8>>),
124    Body(BodyEncoder),
125    End,
126}
127
128/// like ready! but early-returns the Poll<Result<usize>> early in all situations other than Ready(Ok(0))
129#[macro_export]
130macro_rules! read_to_end {
131    ($expr:expr) => {
132        match $expr {
133            Poll::Ready(Ok(0)) => (),
134            other => return other,
135        }
136    };
137}
async_h1/lib.rs

async_h1/
lib.rs
