# I/O Proxy [](https://docs.rs/io-proxy/latest/io_proxy) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya)
Proxy client library for Rust
This library is composed of 2 feature-gated layers:
- Low-level **I/O-free** coroutines: no_std-compatible state machines containing the whole proxy handshake logic, usable anywhere
- Mid-level **light client**: a standard, blocking pump driving a handshake over a stream you opened yourself
There is no full client with connection and TLS handling: the crate never opens a socket. It tunnels a stream you already hold, and any TLS negotiation happens on top of the established tunnel afterwards.
## Table of contents
- [Features](#features)
- [RFC coverage](#rfc-coverage)
- [Usage](#usage)
- [Examples](#examples)
- [AI disclosure](#ai-disclosure)
- [License](#license)
- [Social](#social)
- [Contributing](#contributing)
- [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.
- **SOCKS5 tunnelling**: open a tunnel through a SOCKS5 proxy, with the proxy resolving the target hostname, optionally authenticating with a username and password.
- **HTTP CONNECT tunnelling**: open a tunnel through an HTTP proxy, optionally authenticating with a Basic proxy authorization.
- **No over-read guarantee**: the handshake stops exactly at the tunnel boundary, leaving the socket positioned on the target's first byte, ready for a TLS handshake or a plaintext protocol.
- **Credential redaction**: usernames and passwords are kept out of debug output and logs.
- Light standard, blocking pump driving a handshake over a stream you opened yourself.
> [!TIP]
> I/O Proxy is written in [Rust](https://www.rust-lang.org/) and uses [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to gate protocol support. The default feature set is declared in [Cargo.toml](./Cargo.toml) or on [docs.rs](https://docs.rs/crate/io-proxy/latest/features).
## RFC coverage
| RFC | What is covered |
|---------|------------------------------------------------------------------------------------------------------|
| [1928] | SOCKS protocol version 5: method negotiation and the `CONNECT` command, with the proxy resolving the target host |
| [1929] | SOCKS5 username/password authentication sub-negotiation |
| [7617] | Basic authentication: the base64 username and password pair carried in the proxy authorization header |
| [9110] | HTTP `CONNECT` semantics: request a tunnel to an authority and treat a 2xx response as an open tunnel |
[1928]: https://www.rfc-editor.org/rfc/rfc1928
[1929]: https://www.rfc-editor.org/rfc/rfc1929
[7617]: https://www.rfc-editor.org/rfc/rfc7617
[9110]: https://www.rfc-editor.org/rfc/rfc9110#section-9.3.6
## Usage
The whole API is documented on [docs.rs](https://docs.rs/io-proxy/latest/io_proxy), including runnable snippets for every coroutine and the client pump.
## Examples
Complete runnable programs live in [./examples](./examples); the tests also demonstrate real usage.
## AI disclosure
This project is developed with AI assistance. This section documents how, so users and downstream packagers can make informed decisions.
- **Tools**: Claude Code (Anthropic), invoked locally with a persistent project-scoped memory and a small set of repo-specific rules.
- **Used for**: Refactors, mechanical multi-file edits, boilerplate (feature gates, error enums, derive macros, trait impls), test scaffolding, doc polish, exploratory design conversations.
- **Not used for**: Engineering, critical code, git manipulation (commit, merge, rebase…), real-world tests.
- **Verification**: Every AI-assisted change is read, compiled, tested, and formatted before commit. Behavioural correctness is verified against the relevant RFC or upstream spec, not assumed from the model output. Tests are never adjusted to fit AI-generated code; the code is adjusted to fit correct behaviour.
- **Limitations**: AI models occasionally produce code that compiles and passes tests but is subtly wrong. The verification workflow catches most of this; it does not catch all of it. Bug reports are welcome and taken seriously.
- **Last reviewed**: 26/07/2026
## License
This project is licensed under either of:
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
at your option.
## 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)
## Contributing
Contributions are welcome: start with [CONTRIBUTING.md](./CONTRIBUTING.md), which opens with the Pimalaya-wide guides to read first.
## 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/)
- *2027 in preparation…*
If you appreciate the project, feel free to donate using one of the following providers:
[](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)