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.
- 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 and uses cargo features to gate protocol support. The default feature set is declared in Cargo.toml or on docs.rs.
| 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 |
The whole API is documented on docs.rs, including runnable snippets for every coroutine and the client pump.
Complete runnable programs live in ./examples; the tests also demonstrate real usage.
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
This project is licensed under either of:
at your option.
- Chat on Matrix
- News on Mastodon or RSS
- Mail at pimalaya.org@posteo.net
Contributions are welcome: start with CONTRIBUTING.md, which opens with the Pimalaya-wide guides to read first.
Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:
- 2022 → 2023: NGI Assure
- 2023 → 2024: NGI Zero Entrust
- 2024 → 2026: NGI Zero Core
- 2027 in preparation…
If you appreciate the project, feel free to donate using one of the following providers:
