tinyproxy-zig

A Zig implementation of the tinyproxy HTTP/HTTPS proxy daemon.

Built on top of the zio coroutine and async I/O framework.

Design

• Single-threaded coroutine model: one coroutine per connection
• Async I/O: zio provides io_uring (Linux), kqueue (macOS), epoll fallback
• Feature parity goal: implement all tinyproxy features in idiomatic Zig

Features

Phase 1: Infrastructure

• Configuration file parsing (tinyproxy-compatible directives)
• Logging system (file/stderr/syslog + rotation on SIGUSR1)

Phase 2: Core Proxy

• Forward proxy (HTTP)
• HTTPS CONNECT tunnel
• HTTP header processing (Via, hop-by-hop removal, response headers)
• Anonymous mode (header whitelist)
• Custom headers (AddHeader)

Phase 3: Access Control

• ACL (Allow/Deny by IP/subnet)
• Basic Auth (with BasicAuthRealm)
• Connect port restriction
• URL/domain filtering (fnmatch, bre/ere patterns)

Phase 4: Advanced Proxy Modes

• Upstream proxy (HTTP + SOCKS4/SOCKS5 + NoUpstream)
• Reverse proxy (ReversePath, ReverseOnly, ReverseMagic, ReverseBaseURL)
• Transparent proxy (Linux SO_ORIGINAL_DST)

Phase 5: Production

• Statistics page (StatHost, StatFile)
• Signal handling (SIGTERM/SIGINT/SIGUSR1/SIGHUP)
• Config reload on SIGHUP
• Daemon mode (daemonize, PID file, privilege drop)
• Custom error pages (ErrorFile, DefaultErrorFile)

Quick Start

Build

zig build

Run

zig build run

Proxy will listen on 127.0.0.1:9999 (see src/config.zig).

Test

# Run unit tests
zig build test

# Test HTTP proxy
curl -x http://127.0.0.1:9999 http://ipinfo.io/ip

# Test HTTPS tunnel
curl -x http://127.0.0.1:9999 https://ipinfo.io/ip

# Benchmark
wrk -c 100 -t 4 http://127.0.0.1:9999

Development

See docs/roadmap.md for detailed implementation plan.

Project Structure

src/
├── main.zig          # Entry point
├── runtime.zig       # zio runtime wrapper
├── child.zig         # Connection accept loop
├── request.zig       # Request handling
├── relay.zig         # Bidirectional data relay
├── buffer.zig        # Line reader
├── config.zig        # Configuration (WIP)
└── ...

Debugging

Use mitmproxy for HTTP layer inspection or wireshark for TCP layer.

License

MIT License - Copyright Dacheng Gao