Repository navigation
This release rewrites significant parts of Httpx.zig for Zig 0.17.0, with a focus on removing unnecessary client-side APIs, establishing a cleaner public API structure, simplifying configuration, and making allocator and I/O ownership explicit throughout the library. It also improves HTTP protocol handling, strengthens security defaults, refines internal module boundaries, and updates documentation and examples to reflect the new architecture.
Major Breaking Changes: This release intentionally introduces substantial API and behavioral changes. Existing applications may require significant code changes to migrate. Refer to the updated documentation for the complete list of changes, new API structures, initialization requirements, and migration guidance before upgrading.
Client API and Structure
Rewrite the client-facing API to remove unnecessary convenience functions, redundant entry points, duplicate abstractions, and confusing API relationships.
Establish a consistent client workflow centered on the canonical httpx.Client entry point. Remove obsolete root-level request shortcuts where they duplicate the initialized-client workflow, and organize request construction and execution around a clearer API structure.
Simplify the public API by removing unnecessary aliases and re-exports while preserving functionality that provides distinct value. Improve naming consistency, module responsibilities, request configuration, and resource lifecycle handling. Update all affected call sites, tests, examples, and documentation to use the revised API.
Explicit Allocator and I/O Ownership
Make allocator and I/O ownership explicit rather than implicit across client, server, networking, protocol, streaming, and background-task implementations.
Use explicit allocator and std.Io parameters wherever required by the revised APIs. Clarify allocation responsibilities, response-body cleanup, buffer lifetimes, connection ownership, cancellation, and shutdown behavior. Standardize default configuration initialization with .{} wherever supported by the relevant types.
Remove unnecessary abstractions that hide resource ownership or duplicate initialization behavior. Ensure error paths and cleanup operations follow the same ownership rules as successful operations.
Configuration and Environment Access
Simplify configuration and separate environment access from normal client and server initialization.
Replace automatic environment-to-configuration mappings with generic, application-controlled environment access. Applications select the environment values they need, validate or convert those values, and explicitly populate their configuration.
Support environment-file loading and typed lookups where provided by the integrated dependency. Keep environment access opt-in and avoid automatic .env loading, implicit configuration changes, or per-module adapters that map environment variables directly into configuration fields.
Preserve ordinary configuration defaults and explicit application overrides without requiring environment variables.
Dependency Integration and Module Boundaries
Remove unnecessary dependency re-export wrappers, pass-through modules, and redundant implementations. Use installed dependencies directly where their functionality is appropriate, and retain dedicated protocol parsers and state machines where specialized behavior is necessary.
Organize source modules around clear responsibilities and reusable implementations. Avoid duplicate APIs, unnecessary configuration layers, and wrappers that simply forward calls without adding meaningful behavior.
Client Requests and Downloads
Improve request construction, authentication, headers, query parameters, cookies, timeouts, and proxy options within the revised client API.
Refine download functionality where implemented, including progress reporting, resumable transfers, checksum verification, and batch operations. Improve terminal detection and progress output for interactive and headless environments. Clarify partial-download handling, streaming behavior, cancellation, integrity checks, and resource cleanup.
HTTP Protocols and Networking
Strengthen HTTP/1.x message framing, chunked transfer-coding validation, buffering limits, and connection handling. Improve HTTP/2 stream management, HPACK integration, flow control, frame validation, pseudo-header checks, and graceful shutdown.
Refine HTTP/3 and QUIC transport handling where implemented, including connection IDs, stream management, QPACK, loss recovery, congestion control, and connection lifecycle behavior.
Improve TCP and UDP resource management, DNS caching, proxy support, timeout handling, and monotonic deadline management. Ensure that protocol and networking components use explicit I/O and allocator ownership and clean up resources consistently across success and failure paths.
TLS and Security
Enable HTTPS peer certificate and hostname verification by default. Improve TLS session handling, ALPN negotiation, and certificate-related functionality where implemented.
Strengthen HTTP framing validation, malformed-header rejection, resource limits, authentication middleware, security headers, rate limiting, and trusted-proxy handling. Improve error handling and cleanup across security-sensitive paths.
Advanced TLS capabilities must be described according to their actual implementation and verification status.
Web Framework
Improve template inheritance, control flow, and filters where implemented. Refine multipart parsing and encoding, including streaming uploads where supported. Strengthen WebSocket frame validation, connection lifecycle handling, keep-alive, and compression where implemented.
Improve static-file serving, SPA fallback behavior, filesystem path validation, and cross-platform file watching where supported. Align framework components with the revised API structure and explicit resource-ownership conventions.
Documentation and Examples
Update API references, guides, configuration instructions, protocol documentation, security guidance, and examples to reflect the rewritten API structure.
Replace obsolete client-side convenience APIs and old initialization patterns. Document explicit allocator and I/O ownership, resource cleanup requirements, environment access, configuration behavior, and breaking changes.
Update VitePress configuration, navigation, and documentation workflows where necessary. Modernize examples for Zig 0.17.0 and use Bun for documentation commands where configured.
Breaking Changes
This release intentionally breaks compatibility with previous versions.
Client-side convenience functions and redundant API entry points may be removed in favor of the revised httpx.Client workflow. Client and server initialization require explicit allocator and I/O parameters. Resource ownership and cleanup requirements may change for callers. Environment variables are no longer automatically mapped into configuration fields. HTTPS certificate and hostname verification are enabled by default, and malformed or ambiguous HTTP framing and protocol headers are rejected more strictly. Dependency re-export wrappers and redundant APIs may also be removed.
Update existing applications, tests, integrations, and examples to use the new APIs. Refer to the updated documentation for the complete list of breaking changes and migration instructions.
Validation
Verify the rewritten APIs and implementation against the actual Zig 0.17.0 compiler and standard-library APIs. Run formatting, build, runtime, integration, protocol, and security tests as applicable. Compile and, where practical, execute examples, and validate the documentation build.
Report only checks that have actually been executed. Compilation alone does not establish runtime correctness, security, or complete protocol compliance. Document skipped checks and known limitations accurately.
Upgrade Notice
Httpx.zig v0.2.3 is a major breaking release centered on rewriting the client API structure, removing unnecessary APIs, simplifying module boundaries, and making allocator and I/O ownership explicit rather than implicit.
Review the updated documentation and migration guidance before upgrading. Existing applications should expect to update initialization, request construction, configuration, and resource cleanup code to follow the new API structure.