Crate io_proxy 

io-proxy

I/O-free proxy client coroutines. A proxy handshake is a resumable state machine that emits read and write requests instead of performing I/O itself: the caller owns the socket and pumps the coroutine with the bytes it read, whatever the runtime (blocking, async, in-memory tests). The client feature ships a ready-made std-blocking pump for callers who just want a tunnelled socket.

Scope

Client-side tunnelling only — enough to carry an arbitrary TCP connection (IMAP, SMTP, HTTP, …) through a proxy:

• socks — SOCKS5 CONNECT (RFC 1928 + RFC 1929), behind the socks5 feature. The proxy resolves the target hostname (socks5h semantics).
• http — HTTP CONNECT tunnelling (RFC 9110 §9.3.6), behind the http feature. CONNECT exists only to establish a proxy tunnel, so it lives here rather than in a general HTTP crate.

BIND, UDP ASSOCIATE, plaintext HTTP forward proxying and the server side of either protocol are out of scope.

Layout

One module per protocol, each behind a cargo feature, versioned from within (socks::v5) so a future SOCKS4 or protocol revision slots in alongside. coroutine spans them and holds the shared contract; the optional client module (client feature) is the std-blocking pump.

The coroutine contract

Every coroutine implements coroutine::ProxyCoroutine: a resume method taking the bytes read since the last step and returning either an intermediate yield or a terminal completion. The read yield carries an exact byte count (coroutine::ProxyYield::WantsRead): SOCKS5 reads its length-framed messages directly, and HTTP CONNECT scans for the header terminator one byte at a time — so neither ever consumes tunnel payload past the handshake, leaving the socket positioned exactly at the start of the tunnel.

Conventions

The conventions every Pimalaya repository shares are described in the org ARCHITECTURE and GUIDELINES; this crate’s own deviations and its build matrix live in CONTRIBUTING.md, and its living spec and history in the cairn/ folder. Logging follows the library rules: debug marks the lifecycle points, trace carries the data; credentials never reach the logs.

A runnable example driving the SOCKS5 pump lives in examples/.

Modules

clientclient and (http or socks5)

Standard, blocking pump driving the proxy coroutines over any Read + Write stream.

coroutinehttp or socks5

Generator-shape coroutine driver mirroring core::ops::Coroutine: a Yield associated type for intermediate progress, a Return for terminal output, and a two-variant ProxyCoroutineState (Yielded / Complete). Shared by every proxy protocol.

httphttp

HTTP proxy tunnelling.

sockssocks5

SOCKS proxy protocol, versioned from within.