# I/O HTTP [](https://docs.rs/io-http/latest/io_http) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya) [](https://pimalaya.org/sponsor/)
HTTP client library for Rust
This library is composed of 3 feature-gated layers:
- Low-level **I/O-free** coroutines: no_std-compatible state machines containing the whole HTTP logic, usable anywhere
- Mid-level **light client**: a standard, blocking client wrapping a stream you opened yourself
- High-level **full client**: the light client plus TCP connections and TLS negotiations handled for you
## Table of contents
- [Features](#features)
- [RFC coverage](#rfc-coverage)
- [Usage](#usage)
- [Examples](#examples)
- [AI policy](https://github.com/pimalaya/.github/blob/master/AI_POLICY.md)
- [License](#license)
- [Social](#social)
- [Contributing](./CONTRIBUTING.md)
- [Sponsoring](#sponsoring)
## Features
- **I/O-free coroutines**: no_std state machines with no sockets and no async runtime, resumable from any blocking, async or in-memory test harness.
- **HTTP/1.0 and HTTP/1.1**: send a request and receive its response, with fixed-length, chunked and read-to-EOF body strategies; redirects are surfaced to the caller, never followed silently.
- **Streaming**: decode a long-lived chunked response one chunk at a time and consume server-sent events as they arrive.
- **Authentication helpers**: build and parse basic and bearer authorization values, with credentials redacted from debug output and logs.
- **Well-known discovery**: probe the reserved well-known location of a service and surface where it redirects.
- Light standard, blocking client wrapping a stream you opened yourself
- Full standard, blocking client with **TLS** support:
- [Rustls](https://crates.io/crates/rustls) with ring crypto (requires `rustls-ring` feature, enabled by default)
- [Rustls](https://crates.io/crates/rustls) with aws crypto (requires `rustls-aws` feature)
- [Native TLS](https://crates.io/crates/native-tls) (requires `native-tls` feature)
> [!TIP]
> I/O HTTP is written in [Rust](https://www.rust-lang.org/) and uses [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to gate backend support. The default feature set is declared in [Cargo.toml](./Cargo.toml) or on [docs.rs](https://docs.rs/crate/io-http/latest/features).
## RFC coverage
| RFC | What is covered |
|--------|------------------------------------------------------------------------------------------------------|
| [1945] | HTTP/1.0: send a request and receive its response, connections closing after each exchange by default |
| [6750] | Bearer authentication: carry an OAuth 2.0 access token in the authorization header |
| [7617] | Basic authentication: carry a base64-encoded username and password pair in the authorization header |
| [8615] | Well-known discovery: probe the reserved well-known path of an origin and surface the redirect target |
| [9110] | HTTP semantics: the version-agnostic request, response, status code and authentication challenge model shared by every wire format |
| [9112] | HTTP/1.1: send a request and receive its response, including chunked bodies, both whole and streamed |
| [SSE] | Server-sent events (WHATWG HTML Living Standard): decode an event stream one event at a time |
[1945]: https://www.rfc-editor.org/rfc/rfc1945
[6750]: https://www.rfc-editor.org/rfc/rfc6750
[7617]: https://www.rfc-editor.org/rfc/rfc7617
[8615]: https://www.rfc-editor.org/rfc/rfc8615
[9110]: https://www.rfc-editor.org/rfc/rfc9110
[9112]: https://www.rfc-editor.org/rfc/rfc9112
[SSE]: https://html.spec.whatwg.org/multipage/server-sent-events.html
## Usage
The whole API is documented on [docs.rs](https://docs.rs/io-http/latest/io_http), including runnable snippets for every coroutine and client.
## Examples
Complete runnable programs live in [./examples](./examples); the tests also demonstrate real usage.
## License
This project is licensed under either of:
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
## Social
- Chat on [Matrix](https://matrix.to/#/#pimalaya:matrix.org)
- News on [Mastodon](https://fosstodon.org/@pimalaya) or [RSS](https://fosstodon.org/@pimalaya.rss)
- Mail at [pimalaya.org@posteo.net](mailto:pimalaya.org@posteo.net)
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that have been financially supporting the project for years:
- 2022 → 2023: [NGI Assure](https://nlnet.nl/project/Himalaya/)
- 2023 → 2024: [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/)
- 2024 → 2026: [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/)
- 2026 → 2027: [NGI Zero Commons Fund](https://nlnet.nl/project/Pimalaya-pimdir/)
This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider [sponsoring](https://pimalaya.org/sponsor/) its development:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/soywod)
[](https://www.buymeacoffee.com/soywod)
[](https://liberapay.com/soywod)
[](https://thanks.dev/soywod)
[](https://www.paypal.com/paypalme/soywod)