Python Async Proxy

A small authenticated HTTPS CONNECT proxy for Linux. The server is written in Cython, runs one uvloop event loop, and relays TLS without decrypting it.

Security: the default username:password credential is compiled into the extension and Basic proxy authentication is plaintext until the tunnel is established. The proxy binds to 127.0.0.1; do not expose it to an untrusted network without adding proper credential management, destination policy, rate limits, and admission control.

Performance

Authenticated HTTPS-over-CONNECT throughput on one WSL2 host, with 100 Siege users and 3,000 fresh TCP + CONNECT + TLS 1.3 transactions per payload and process. Values are means from four fresh processes.

Payload	Siege tx/s
HTML	911.02
1 KiB	826.61
16 KiB	804.93
128 KiB	769.76
1 MiB	512.13

All 60,000 measured transactions completed. See the CONNECT benchmark report for the protocol, individual samples, and the required Siege authentication fix. Results are local evidence, not portable capacity guarantees.

How it works

1. Read one CONNECT host:port header under a 10-second deadline and a 64 KiB limit.
2. Require exactly one matching Proxy-Authorization header.
3. Open the IPv4 destination and return 200 Connection Established; any TLS bytes coalesced with the request header are preserved.
4. Relay both directions with independent event-loop tasks. A clean EOF becomes a write half-close, so the opposite direction can finish normally.

The proxy does not terminate TLS and does not implement general HTTP forwarding. On SIGINT or SIGTERM, it closes active connections and prints connection, bandwidth, failure, and client-disconnect counters.

Build and run

Requirements: Linux, Python 3.11+, a C compiler, Python development headers, GNU Make, Cython 3.2, and uvloop.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'setuptools>=80' 'Cython>=3.2.9,<3.3' uvloop
make build
python -u -c 'import proxy'

Test the tunnel from another terminal:

curl --proxy http://127.0.0.1:8888 \
  --proxy-user username:password \
  https://example.com/

Importing proxy starts the server and blocks until shutdown. Bind address, credential, timeouts, and buffer sizes are constants near the top of proxy.pyx.

The extension defaults to -O3 -march=native and full LTO. Build-time controls are CC, PROXY_ARCH, PROXY_LTO, PROXY_CFLAGS, and PROXY_LDFLAGS; for example:

CC=clang-21 PROXY_LTO=thin PROXY_LDFLAGS='-fuse-ld=lld' make build

Test

make test

The 10 black-box integration tests cover a real TLS handshake and HTTPS request through authenticated CONNECT, full-duplex traffic, both half-close orders, fragmented headers, coalesced tunnel bytes, resets, 407/431/502 responses, and graceful shutdown metrics.

Status and license

This is a deliberately narrow IPv4 loopback proxy, not a hardened public service. The repository has no LICENSE file; source availability alone does not grant permission to use, modify, or redistribute it.