Files
README.md

zttp #

an HTTP client for zig 0.17, built on std.http.Client. it adds the things a program calling servers it does not control needs and std leaves to the caller: timeouts, a response size cap, a retry for stale pooled connections, a redirect policy that keeps authorization on the origin it was meant for, and validation of URLs and headers.

install #

requires zig 0.17+. on 0.16, use v0.1.x.

zig fetch --save https://tangled.org/zat.dev/zttp/archive/main

then in build.zig:

const zttp = b.dependency("zttp", .{}).module("zttp");
exe.root_module.addImport("zttp", zttp);

use #

const zttp = @import("zttp");

var client = zttp.Client.initWithUserAgent(io, allocator, "myapp/1.0 (+https://example.com)");
defer client.deinit();

var res = try client.fetch(.{
    .url = "https://example.com/api",
    .capture_headers = &.{"content-type"},
});
defer res.deinit(allocator);

// res.status, res.body, res.headers.get("content-type"), res.rate_limit

fetch buffers the body in memory. to write it somewhere else, open returns once the response head has arrived and stream drains the body into any std.Io.Writer:

const response = try client.open(.{ .url = url });
defer response.deinit();
_ = try response.stream(&file_writer.interface, .{});

limits are fields on Client with defaults, and FetchOptions overrides them for one request.

what it adds to std.http.Client #

  • timeouts — one deadline covers connect, TLS, sending the request and waiting for the response head. the body is cut off if no bytes arrive for a while or if it arrives too slowly to finish. a request can also carry one overall deadline.
  • a size cap — a buffered response larger than the cap is an error.
  • retry of stale connections — when a pooled keep-alive connection turns out to be closed or reset before any response arrives, a request with an idempotent method and no body is sent again on a new connection. nothing else is retried.
  • redirects — zttp follows 3xx itself. authorization is dropped when a hop changes scheme, host or port, loops are an error, the number of hops is capped, and https to http is refused unless allowed.
  • input validation — a URL with a control character, or a header with CR or LF, is an error before anything is sent.
  • rate-limit headers — RateLimit-* and Retry-After are parsed into res.rate_limit, and delaySeconds turns them into one wait.
  • named errors — zttp.Error is the set of errors the client adds to std's.

the timeouts need an Io that can run tasks concurrently. on one that cannot, the request runs without them and zttp logs a warning.

docs/client.md explains each of these and why it is there.

develop #

zig build test    # loopback servers: stalls, silent peers, closed pooled connections, redirects
zig build smoke   # real servers over the network: TLS, gzip, redirects, a peer that never answers

license #

MIT


changelog

TLS trust #

Version 0.2.0-alpha.4 removes the four roots and eight compromised intermediate public keys from the October 2026 eMudhra incident from loaded CA bundles. This includes caller-supplied bundles. Chains anchored only at those roots fail, including otherwise valid certificates. Keep the OS trust store updated as well; Zig's macOS keychain loader does not apply native revocation policy.

zig build test verifies the original certificate fixtures offline. zig build trust-probe checks both public bad-chain hosts, the AT Protocol identity host, and an ordinary HTTPS control through the actual client.

The optional local macOS toolchain patch also protects Zig 0.17.0's own package fetcher. It defaults to dry-run, requires an exact source checksum, and retains a reversible backup.

Deadline and cancellation contract #

Head and total deadlines use absolute monotonic time across redirects and connection retries. A total deadline includes time between open and stream; deadline_remaining_ns is an informational snapshot at head arrival. Idle and rate checks use measured elapsed time. Configured guards require Io.concurrent and return ConcurrencyUnavailable when it cannot be provided.

Completion events wake deadline watchers immediately; stall/rate sampling uses a separate timer. Cancellation joins the operation before returning, and incomplete transfers retire their connections. Dropping an unread response closes its connection without draining the body. An absent response or a timeout does not establish whether the origin executed the request; automatic retries remain restricted to payload-free GET, HEAD and OPTIONS. Synchronous TLS cryptography and caller sinks remain cooperative CPU work; a deadline cannot forcibly preempt them.

HTTP qualification #

just conformance-tools prepares pinned tools. just conformance and just conformance --optimize ReleaseSafe run the isolated real-socket gate. See coverage and provenance and the audit findings.

Shutdown #

Client.shutdown(timeout_ns) stops new requests, waits for owned requests and responses, and closes idle TLS connections with close_notify. One absolute budget covers quiescence and all idle connections. New requests return ClientClosed; existing responses remain usable while shutdown waits. If that wait times out or is canceled, release/join those users before retrying shutdown.

deinit() requires all client users and responses to be finished. It attempts shutdown using shutdown_deadline_ns (250 ms by default), aborts on failure, and frees the HTTP client. Call shutdown explicitly to inspect its outcome; repeated shutdown after the transport is closed is a no-op. Zero budget forces abort when TLS writes would be needed. Concurrency exhaustion is reported without falling back to an unbounded write.

Successful connection retirement and pool eviction use the same bounded alert write. Abandoned or failed transfers abort immediately. The one-call fetch checks its total deadline after retirement cleanup too. No shutdown path waits for a peer's TLS alert. The Zig 0.17 pool adapter is isolated in src/connection_pool.zig and must be requalified on toolchain changes.