Getting Started

httpx.zig is a modern, feature-rich HTTP library for the Zig programming language. It is under active development, supporting robust client and server implementations with focus on performance and developer experience.

Features

• Protocol Support: HTTP/1.0/1.1/2/3 client/server runtime paths plus full HTTP/2 and HTTP/3 protocol primitives.
• Cross-Platform: Validated on Linux, Windows, and macOS with x86_64, aarch64, and x86 architectures.
• Client:
  • Connection pooling and keep-alive.
  • Automatic retries with exponential backoff.
  • Request/Response interceptors.
  • Cookie management.
  • Idiomatic, grouped configuration structs with sensible defaults.
• Server:
  • Pattern-based routing.
  • Middleware architecture.
  • Static file serving.
  • JSON helpers.
• Concurrency: Built-in thread pool and async primitives (all, any, race).
• Security: Custom TLS 1.2/1.3 implementation with ALPN negotiation, ECDSA certificate verification, and custom CA handling.
• Modern Architecture: Minimal, unified client and server APIs, explicit resource ownership, and zero boilerplate.

Custom HTTP/2, HTTP/3, and TLS Implementation

Zig's standard library does not provide HTTP/2, HTTP/3, QUIC, or TLS/ALPN support. httpx.zig implements these protocols entirely from scratch, including:

• TLS 1.2 and 1.3 with full handshake support (RFC 5246 / RFC 8446) — key exchange: X25519; AEAD cipher suites: ChaCha20-Poly1305, AES-128-GCM, AES-256-GCM; ALPN negotiation (RFC 7301); X.509 certificate parsing and verification (client-side)
• HPACK header compression (RFC 7541) with Without Indexing / Never Indexed security for HTTP/2
• HTTP/2 stream multiplexing, flow control (WINDOW_UPDATE), SETTINGS enforcement, GOAWAY/RST_STREAM, PRIORITY, CONTINUATION frames, PING, and connection pooling (RFC 7540)
• QPACK header compression (RFC 9204) with static/dynamic tables and decoder/encoder stream instructions for HTTP/3
• QUIC transport frame encoding/decoding (RFC 9000) with RESET_STREAM/STOP_SENDING cancellation, version negotiation, and transport parameters
• HTTP/3 frame types, SETTINGS, GOAWAY, and CONNECTION_CLOSE handling

Requirements

• Zig Version: 0.16.0 or later
• Operating System: Windows, Linux, or macOS

Upgrading from 0.1.x

v0.2.0 is a breaking release (Zig 0.16.0 required) with no compatibility wrappers. Review the updated Client/Server/Router usage in this guide when migrating from any 0.1.x (or older).

Platform Support

Operating Systems

Platform	Status	Notes
Linux	✅ Full	All major distributions (Ubuntu, Debian, Fedora, Arch, etc.)
Windows	✅ Full	Windows 10/11, Server 2019+
macOS	✅ Full	macOS 11+ (Big Sur and later)

Architectures

Architecture	Linux	Windows	macOS	Notes
x86_64 (64-bit)	✅	✅	✅	Primary development target
aarch64 (ARM64)	✅	✅	✅	Apple Silicon, AWS Graviton, Raspberry Pi 4+
x86 (32-bit)	✅	✅	❌	Legacy x86 support on Linux/Windows

Cross-Compilation

Zig's built-in cross-compilation makes it easy to build for any target:

# Build for Linux x86_64
zig build -Dtarget=x86_64-linux

# Build for Linux ARM64
zig build -Dtarget=aarch64-linux

# Build for Windows x86_64
zig build -Dtarget=x86_64-windows

# Build for Windows x86 (32-bit)
zig build -Dtarget=x86-windows

# Build for macOS ARM64 (Apple Silicon)
zig build -Dtarget=aarch64-macos

# Build for macOS x86_64 (Intel)
zig build -Dtarget=x86_64-macos

Next Steps

• Check out the Installation guide to add httpx.zig to your project.
• Learn how to make Basic Requests with the client.
• Set up a simple Server.
• Explore HTTP/2 and HTTP/3 protocol support.
• Review API Overview for explicit root exports and aliases.