Skip to content
Standard libraryZig 0.17.0Official documentation
Sourcestd/http/Client.zig

Source line 1

HTTP(S) Client implementation.

Connections are opened in a thread-safe manner, but individual Requests are not.

TLS support may be disabled via std.options.http_disable_tls.

Fields

allocator: Allocator

Used for all client allocations. Must be thread-safe.

io: Io

Used for opening TCP connections.

ca_bundle_lock: if (disable_tls) void else Io.RwLock = if (disable_tls) {} else .init
ca_bundle: if (disable_tls) void else std.crypto.Certificate.Bundle = if (disable_tls) {} else .empty
tls_buffer_size: if (disable_tls) u0 else usize = if (disable_tls) 0 else std.crypto.tls.Client.min_buffer_len

Used both for the reader and writer buffers.

ssl_key_log: ?*std.crypto.tls.Client.SslKeyLog = null

If non-null, ssl secrets are logged to a stream. Creating such a stream allows other processes with access to that stream to decrypt all traffic over connections created with this Client.

now: ?Io.Timestamp = null

The time used to decide whether certificates are expired.

When this is null, the next time this client performs an HTTPS request, it will first check the time and rescan the system for root certificates.

connection_pool: ConnectionPool = .{}

The pool of connections that can be reused (and currently in use).

read_buffer_size: usize = 8192

Each Connection allocates this amount for the reader buffer.

If the entire HTTP header cannot fit in this amount of bytes, error.HttpHeadersOversize will be returned from Request.wait.

write_buffer_size: usize = 1024

Each Connection allocates this amount for the writer buffer.

http_proxy: ?*Proxy = null

If populated, all http traffic travels through this third party. This field cannot be modified while the client has active connections. Pointer to externally-owned memory.

https_proxy: ?*Proxy = null

If populated, all https traffic travels through this third party. This field cannot be modified while the client has active connections. Pointer to externally-owned memory.

std.http.Client.Allocator

alias

Source line 17

Alias of std.mem.Allocator

std.http.Client.assert

alias

Source line 18

Alias of std.debug.assert

std.http.Client.basic_authorization

namespace

Source line 1376

std.http.Client.basic_authorization.max_password_len

constant

Source line 1378

std.http.Client.basic_authorization.max_user_len

constant

Source line 1377

std.http.Client.basic_authorization.max_value_len

constant

Source line 1379

std.http.Client.basic_authorization.value

function

Source line 1401

pub fn value(uri: Uri, out: []u8) []u8

Parameters

uri: Uri
out: []u8

std.http.Client.basic_authorization.valueLength

function

Source line 1381

pub fn valueLength(user_len: usize, password_len: usize) usize

Parameters

user_len: usize
password_len: usize

std.http.Client.basic_authorization.valueLengthFromUri

function

Source line 1385

pub fn valueLengthFromUri(uri: Uri) usize

Parameters

uri: Uri

std.http.Client.basic_authorization.write

function

Source line 1407

pub fn write(uri: Uri, out: *Writer) Writer.Error!void

Parameters

uri: Uri
out: *Writer

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.builtin

constant

Source line 9

std.http.Client.Client

alias

Source line 7

Alias of std.http.Client

std.http.Client.connect

function

Source line 1600

Connect to host:port using the specified protocol. This will reuse a connection if one is already open.

If a proxy is configured for the client, then the proxy will be used to connect to the host.

This function is threadsafe.

pub fn connect( client: *Client, host: HostName, port: u16, protocol: Protocol, ) ConnectError!*Connection

Parameters

client: *Client
host: HostName
port: u16
protocol: Protocol

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure RequestError
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidHostName RequestError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
UnsupportedUriScheme RequestError
UriMissingHost RequestError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

std.http.Client.ConnectError

error-set

Source line 1591

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure RequestError
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidHostName RequestError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
UnsupportedUriScheme RequestError
UriMissingHost RequestError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

std.http.Client.Connection

container

Source line 229

Fields

client: *Client
stream_writer: Io.net.Stream.Writer
stream_reader: Io.net.Stream.Reader
pool_node: std.DoublyLinkedList.Node

Entry in ConnectionPool.used or ConnectionPool.free.

port: u16
host_len: u8
proxied: bool
closing: bool
protocol: Protocol

std.http.Client.Connection.destroy

function

Source line 420

If this is called without calling flush or end, data will be dropped unsent.

pub fn destroy(c: *Connection, io: Io) void

Parameters

c: *Connection
io: Io

std.http.Client.Connection.end

function

Source line 473

If the connection is a TLS connection, sends the close_notify alert.

Flushes all buffers.

pub fn end(c: *Connection) Writer.Error!void

Parameters

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Connection.flush

function

Source line 461

pub fn flush(c: *Connection) Writer.Error!void

Parameters

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Connection.getReadError

function

Source line 387

pub fn getReadError(c: *const Connection) ?ReadError

Parameters

c: *const Connection

std.http.Client.Connection.getStream

function

Source line 400

fn getStream(c: *Connection) Io.net.Stream

Parameters

std.http.Client.Connection.host

function

Source line 404

pub fn host(c: *Connection) HostName

Parameters

std.http.Client.Connection.Plain

container

Source line 241

Fields

connection: Connection

std.http.Client.Connection.Plain.allocLen

function

Source line 284

fn allocLen(client: *Client, host_len: usize) usize

Parameters

client: *Client
host_len: usize

std.http.Client.Connection.Plain.create

function

Source line 244

fn create( client: *Client, remote_host: HostName, port: u16, stream: Io.net.Stream, ) error{OutOfMemory}!*Plain

Parameters

client: *Client
remote_host: HostName
port: u16
stream: Io.net.Stream

Errors

OutOfMemory

std.http.Client.Connection.Plain.destroy

function

Source line 277

fn destroy(plain: *Plain) void

Parameters

plain: *Plain

std.http.Client.Connection.Plain.host

function

Source line 288

fn host(plain: *Plain) HostName

Parameters

plain: *Plain

std.http.Client.Connection.reader

function

Source line 450

HTTP protocol from server to client. This either comes directly from stream_reader, or from a TLS client.

pub fn reader(c: *Connection) *Reader

Parameters

std.http.Client.Connection.ReadError

error-set

Source line 385

Errors

AccessDenied Error

File descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer Error
ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

NetworkDown Error
SocketUnconnected Error
SystemResources Error
TlsAlert ReadError

The alert description will be stored in alert.

TlsBadLength ReadError
TlsBadRecordMac ReadError
TlsConnectionTruncated ReadError
TlsDecodeError ReadError
TlsIllegalParameter ReadError
TlsRecordOverflow ReadError
TlsSequenceOverflow ReadError
TlsUnexpectedMessage ReadError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.http.Client.Connection.Tls

container

Source line 294

Fields

client: std.crypto.tls.Client
connection: Connection

std.http.Client.Connection.Tls.allocLen

function

Source line 373

fn allocLen(client: *Client, host_len: usize) usize

Parameters

client: *Client
host_len: usize

std.http.Client.Connection.Tls.create

function

Source line 299

Asserts that client.now is non-null.

fn create( client: *Client, remote_host: HostName, port: u16, stream: Io.net.Stream, ) !*Tls

Parameters

client: *Client
remote_host: HostName
port: u16
stream: Io.net.Stream

std.http.Client.Connection.Tls.destroy

function

Source line 366

fn destroy(tls: *Tls) void

Parameters

tls: *Tls

std.http.Client.Connection.Tls.host

function

Source line 379

fn host(tls: *Tls) HostName

Parameters

tls: *Tls

std.http.Client.Connection.writer

function

Source line 437

HTTP protocol from client to server. This either goes directly to stream_writer, or to a TLS client.

pub fn writer(c: *Connection) *Writer

Parameters

std.http.Client.ConnectionPool

container

Source line 65

A Least-Recently-Used cache of open connections to be reused.

Fields

mutex: Io.Mutex = .init
used: std.DoublyLinkedList = .{}

Open connections that are currently in use.

free: std.DoublyLinkedList = .{}

Open connections that are not currently in use.

free_len: usize = 0
free_size: usize = 32

std.http.Client.ConnectionPool.acquire

function

Source line 114

Acquires an existing connection from the connection pool. This function is threadsafe.

pub fn acquire(pool: *ConnectionPool, io: Io, connection: *Connection) Io.Cancelable!void

Parameters

pool: *ConnectionPool
io: Io
connection: *Connection

Errors

Canceled

Caller has requested the async operation to stop.

std.http.Client.ConnectionPool.acquireUnsafe

function

Source line 106

Acquires an existing connection from the connection pool. This function is not threadsafe.

pub fn acquireUnsafe(pool: *ConnectionPool, connection: *Connection) void

Parameters

pool: *ConnectionPool
connection: *Connection

std.http.Client.ConnectionPool.addUsed

function

Source line 151

Adds a newly created node to the pool of used connections. This function is threadsafe.

pub fn addUsed(pool: *ConnectionPool, io: Io, connection: *Connection) Io.Cancelable!void

Parameters

pool: *ConnectionPool
io: Io
connection: *Connection

Errors

Canceled

Caller has requested the async operation to stop.

std.http.Client.ConnectionPool.Criteria

container

Source line 75

The criteria for a connection to be considered a match.

Fields

host: HostName
port: u16
protocol: Protocol

std.http.Client.ConnectionPool.deinit

function

Source line 182

Frees the connection pool and closes all connections within.

All future operations on the connection pool will deadlock.

Threadsafe.

pub fn deinit(pool: *ConnectionPool, io: Io) void

Parameters

pool: *ConnectionPool
io: Io

std.http.Client.ConnectionPool.findConnection

function

Source line 85

Finds and acquires a connection from the connection pool matching the criteria. If no connection is found, null is returned.

Threadsafe.

pub fn findConnection(pool: *ConnectionPool, io: Io, criteria: Criteria) Io.Cancelable!?*Connection

Parameters

pool: *ConnectionPool
io: Io
criteria: Criteria

Errors

Canceled

Caller has requested the async operation to stop.

std.http.Client.ConnectionPool.release

function

Source line 125

Tries to release a connection back to the connection pool. If the connection is marked as closing, it will be closed instead.

Threadsafe.

pub fn release(pool: *ConnectionPool, connection: *Connection, io: Io) void

Parameters

pool: *ConnectionPool
connection: *Connection
io: Io

std.http.Client.ConnectionPool.resize

function

Source line 163

Resizes the connection pool.

If the new size is smaller than the current size, then idle connections will be closed until the pool is the new size.

Threadsafe.

pub fn resize(pool: *ConnectionPool, io: Io, new_size: usize) Io.Cancelable!void

Parameters

pool: *ConnectionPool
io: Io
new_size: usize

Errors

Canceled

Caller has requested the async operation to stop.

std.http.Client.connectProxied

function

Source line 1526

Connect to proxied_host:proxied_port using the specified proxy with HTTP CONNECT. This will reuse a connection if one is already open.

This function is threadsafe.

pub fn connectProxied( client: *Client, proxy: *Proxy, proxied_host: HostName, proxied_port: u16, ) !*Connection

Parameters

client: *Client
proxy: *Proxy
proxied_host: HostName
proxied_port: u16

std.http.Client.connectTcp

function

Source line 1426

Reuses a Connection if one matching host and port is already open.

Threadsafe.

pub fn connectTcp( client: *Client, host: HostName, port: u16, protocol: Protocol, ) ConnectTcpError!*Connection

Parameters

client: *Client
host: HostName
port: u16
protocol: Protocol

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

std.http.Client.ConnectTcpError

error-set

Source line 1419

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

std.http.Client.connectTcpOptions

function

Source line 1445

pub fn connectTcpOptions(client: *Client, options: ConnectTcpOptions) ConnectTcpError!*Connection

Parameters

client: *Client
options: ConnectTcpOptions

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

std.http.Client.ConnectTcpOptions

container

Source line 1435

Fields

host: HostName
port: u16
protocol: Protocol
proxied_host: ?HostName = null
proxied_port: ?u16 = null
timeout: Io.Timeout = .none

std.http.Client.connectUnix

function

Source line 1490

Connect to path as a unix domain socket. This will reuse a connection if one is already open.

This function is threadsafe.

pub fn connectUnix(client: *Client, path: []const u8) ConnectUnixError!*Connection

Parameters

client: *Client
path: []const u8

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

NameTooLong
OutOfMemory Error

std.http.Client.ConnectUnixError

error-set

Source line 1485

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

NameTooLong
OutOfMemory Error

std.http.Client.createProxyFromEnvVar

function

Source line 1343

fn createProxyFromEnvVar( arena: Allocator, environ_map: *const std.process.Environ.Map, env_var_names: []const []const u8, ) !?*Proxy

Parameters

arena: Allocator
environ_map: *const std.process.Environ.Map
env_var_names: []const []const u8

std.http.Client.deinit

function

Source line 1307

Release all associated resources with the client.

All pending requests must be de-initialized and all active connections released before calling this function.

pub fn deinit(client: *Client) void

Parameters

client: *Client

std.http.Client.disable_tls

constant

Source line 23

std.http.Client.fetch

function

Source line 1807

Perform a one-shot HTTP request with the provided options.

This function is threadsafe.

pub fn fetch(client: *Client, options: FetchOptions) FetchError!FetchResult

Parameters

client: *Client
options: FetchOptions

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure RequestError
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
HttpChunkInvalid ReceiveHeadError
HttpChunkTruncated ReceiveHeadError
HttpConnectionClosing HeadError

The client sent 0 bytes of headers before closing the stream. This happens when a keep-alive connection is finally closed.

HttpContentEncodingUnsupported ReceiveHeadError
HttpHeadersInvalid ReceiveHeadError

Server sent headers that did not conform to the HTTP protocol.

To find out more detailed diagnostics, http.Reader.head_buffer can be passed directly to Request.Head.parse.

HttpHeadersOversize HeadError

Too many bytes of HTTP headers.

The HTTP specification suggests to respond with a 431 status code before closing the connection.

HttpRedirectLocationInvalid ReceiveHeadError
HttpRedirectLocationMissing ReceiveHeadError
HttpRedirectLocationOversize ReceiveHeadError
HttpRequestTruncated HeadError

Partial HTTP request was received but the connection was closed before fully receiving the headers.

InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidFormat ParseError
InvalidHostName ParseError
InvalidPort ParseError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ReadFailed HeadError

Transitive error occurred reading from in.

RedirectRequiresResend ReceiveHeadError

This can be avoided by calling receiveHead before sending the request body.

ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
StreamTooLong
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
TooManyHttpRedirects ReceiveHeadError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnexpectedCharacter ParseError
UnknownHostName LookupError
UnsupportedCompressionMethod
UnsupportedUriScheme RequestError
UriMissingHost RequestError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

WriteFailed ReceiveHeadError

Sending the request failed. Error code can be found on the Connection object.

std.http.Client.FetchError

error-set

Source line 1797

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure RequestError
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
HttpChunkInvalid ReceiveHeadError
HttpChunkTruncated ReceiveHeadError
HttpConnectionClosing HeadError

The client sent 0 bytes of headers before closing the stream. This happens when a keep-alive connection is finally closed.

HttpContentEncodingUnsupported ReceiveHeadError
HttpHeadersInvalid ReceiveHeadError

Server sent headers that did not conform to the HTTP protocol.

To find out more detailed diagnostics, http.Reader.head_buffer can be passed directly to Request.Head.parse.

HttpHeadersOversize HeadError

Too many bytes of HTTP headers.

The HTTP specification suggests to respond with a 431 status code before closing the connection.

HttpRedirectLocationInvalid ReceiveHeadError
HttpRedirectLocationMissing ReceiveHeadError
HttpRedirectLocationOversize ReceiveHeadError
HttpRequestTruncated HeadError

Partial HTTP request was received but the connection was closed before fully receiving the headers.

InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidFormat ParseError
InvalidHostName ParseError
InvalidPort ParseError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ReadFailed HeadError

Transitive error occurred reading from in.

RedirectRequiresResend ReceiveHeadError

This can be avoided by calling receiveHead before sending the request body.

ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
StreamTooLong
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
TooManyHttpRedirects ReceiveHeadError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnexpectedCharacter ParseError
UnknownHostName LookupError
UnsupportedCompressionMethod
UnsupportedUriScheme RequestError
UriMissingHost RequestError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

WriteFailed ReceiveHeadError

Sending the request failed. Error code can be found on the Connection object.

std.http.Client.FetchOptions

container

Source line 1760

Fields

redirect_buffer: ?[]u8 = null

null means it will be heap-allocated. RFC 9110 recommends at least 8000 bytes.

decompress_buffer: ?[]u8 = null

null means it will be heap-allocated.

redirect_behavior: ?Request.RedirectBehavior = null
response_writer: ?*Writer = null

If the server sends a body, it will be written here.

location: Location
method: ?http.Method = null
payload: ?[]const u8 = null
raw_uri: bool = false
keep_alive: bool = true
headers: Request.Headers = .{}

Standard headers that have default, but overridable, behavior.

extra_headers: []const http.Header = &.{}

These headers are kept including when following a redirect to a different domain. Externally-owned; must outlive the Request.

privileged_headers: []const http.Header = &.{}

These headers are stripped when following a redirect to a different domain. Externally-owned; must outlive the Request.

std.http.Client.FetchOptions.Location

container

Source line 1787

Fields

url: []const u8
uri: Uri

std.http.Client.FetchResult

container

Source line 1793

Fields

status: http.Status

std.http.Client.HostName

alias

Source line 21

Alias of std.Io.net.HostName

std.http.Client.http

alias

Source line 14

Alias of std.http

std.http.Client.initDefaultProxies

function

Source line 1321

Populates http_proxy and https_proxy via standard proxy environment variables. Asserts the client has no active connections. Uses arena for a few small allocations that must outlive the client, or at least until those fields are set to different values.

pub fn initDefaultProxies(client: *Client, arena: Allocator, environ_map: *const std.process.Environ.Map) !void

Parameters

client: *Client
arena: Allocator
environ_map: *const std.process.Environ.Map

std.http.Client.Io

alias

Source line 12

Alias of std.Io

std.http.Client.mem

alias

Source line 15

Alias of std.mem

std.http.Client.Protocol

container

Source line 203

Fields

plain
tls

std.http.Client.Protocol.fromScheme

function

Source line 214

pub fn fromScheme(scheme: []const u8) ?Protocol

Parameters

scheme: []const u8

std.http.Client.Protocol.fromUri

function

Source line 224

pub fn fromUri(uri: Uri) ?Protocol

Parameters

uri: Uri

std.http.Client.Protocol.port

function

Source line 207

fn port(protocol: Protocol) u16

Parameters

protocol: Protocol

std.http.Client.Proxy

container

Source line 1295

Fields

protocol: Protocol
host: HostName
authorization: ?[]const u8
port: u16
supports_connect: bool

std.http.Client.Reader

alias

Source line 20

Alias of std.Io.Reader

std.http.Client.request

function

Source line 1684

Open a connection to the host specified by uri and prepare to send a HTTP request.

The caller is responsible for calling deinit() on the Request. This function is threadsafe.

Asserts that "\r\n" does not occur in any header name or value.

pub fn request( client: *Client, method: http.Method, uri: Uri, options: RequestOptions, ) RequestError!Request

Parameters

client: *Client
method: http.Method
uri: Uri
options: RequestOptions

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidHostName
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
UnsupportedUriScheme
UriMissingHost
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

std.http.Client.Request

container

Source line 784

Fields

uri: Uri

This field is provided so that clients can observe redirected URIs.

Its backing memory is externally provided by API users when creating a request, and then again provided externally via redirect_buffer to receiveHead.

client: *Client
connection: ?*Connection

This is null when the connection is released.

reader: http.Reader
keep_alive: bool
method: http.Method
version: http.Version = .@"HTTP/1.1"
transfer_encoding: TransferEncoding
redirect_behavior: RedirectBehavior
accept_encoding: @TypeOf(default_accept_encoding) = default_accept_encoding
handle_continue: bool

Whether the request should handle a 100-continue response before sending the request body.

headers: Headers

Standard headers that have default, but overridable, behavior.

response_content_length: ?u64 = null

Populated in receiveHead; used in deinit to determine whether to discard the body to reuse the connection.

response_transfer_encoding: http.TransferEncoding = .none

Populated in receiveHead; used in deinit to determine whether to discard the body to reuse the connection.

extra_headers: []const http.Header

These headers are kept including when following a redirect to a different domain. Externally-owned; must outlive the Request.

privileged_headers: []const http.Header

These headers are stripped when following a redirect to a different domain. Externally-owned; must outlive the Request.

std.http.Client.Request.default_accept_encoding

constant

Source line 826

[@typeInfo(http.ContentEncoding).@"enum".field_names.len]bool

std.http.Client.Request.deinit

function

Source line 885

Returns the request's Connection back to the pool of the Client.

pub fn deinit(r: *Request) void

Parameters

r: *Request

std.http.Client.Request.emitOverridableHeader

function

Source line 1282

Returns true if the default behavior is required, otherwise handles writing (or not writing) the header.

fn emitOverridableHeader(prefix: []const u8, v: Headers.Value, bw: *Writer) Writer.Error!bool

Parameters

prefix: []const u8
v: Headers.Value
bw: *Writer

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Request.Headers

container

Source line 840

Fields

host: Value = .default
authorization: Value = .default
user_agent: Value = .default
connection: Value = .default
accept_encoding: Value = .default
content_type: Value = .default

std.http.Client.Request.Headers.Value

container

Source line 848

Fields

default
omit
override: []const u8

std.http.Client.Request.receiveHead

function

Source line 1128

If handling redirects and the request has no payload, then this function will automatically follow redirects.

If a request payload is present, then this function will error with error.RedirectRequiresResend.

This function takes an auxiliary buffer to store the arbitrarily large URI which may need to be merged with the previous URI, and that data needs to survive across different connections, which is where the input buffer lives.

redirect_buffer must outlive accesses to Request.uri. If this buffer capacity would be exceeded, error.HttpRedirectLocationOversize is returned instead. This buffer may be empty if no redirects are to be handled. RFC 9110 recommends making this at least 8000 bytes.

If this fails with error.ReadFailed then the Connection.getReadError method of r.connection can be used to get more detailed information.

pub fn receiveHead(r: *Request, redirect_buffer: []u8) ReceiveHeadError!Response

Parameters

r: *Request
redirect_buffer: []u8

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure RequestError
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
HttpChunkInvalid
HttpChunkTruncated
HttpConnectionClosing HeadError

The client sent 0 bytes of headers before closing the stream. This happens when a keep-alive connection is finally closed.

HttpContentEncodingUnsupported
HttpHeadersInvalid

Server sent headers that did not conform to the HTTP protocol.

To find out more detailed diagnostics, http.Reader.head_buffer can be passed directly to Request.Head.parse.

HttpHeadersOversize HeadError

Too many bytes of HTTP headers.

The HTTP specification suggests to respond with a 431 status code before closing the connection.

HttpRedirectLocationInvalid
HttpRedirectLocationMissing
HttpRedirectLocationOversize
HttpRequestTruncated HeadError

Partial HTTP request was received but the connection was closed before fully receiving the headers.

InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidHostName RequestError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ReadFailed HeadError

Transitive error occurred reading from in.

RedirectRequiresResend

This can be avoided by calling receiveHead before sending the request body.

ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
TooManyHttpRedirects
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
UnsupportedUriScheme RequestError
UriMissingHost RequestError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

WriteFailed

Sending the request failed. Error code can be found on the Connection object.

std.http.Client.Request.ReceiveHeadError

error-set

Source line 1086

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure RequestError
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
HttpChunkInvalid
HttpChunkTruncated
HttpConnectionClosing HeadError

The client sent 0 bytes of headers before closing the stream. This happens when a keep-alive connection is finally closed.

HttpContentEncodingUnsupported
HttpHeadersInvalid

Server sent headers that did not conform to the HTTP protocol.

To find out more detailed diagnostics, http.Reader.head_buffer can be passed directly to Request.Head.parse.

HttpHeadersOversize HeadError

Too many bytes of HTTP headers.

The HTTP specification suggests to respond with a 431 status code before closing the connection.

HttpRedirectLocationInvalid
HttpRedirectLocationMissing
HttpRedirectLocationOversize
HttpRequestTruncated HeadError

Partial HTTP request was received but the connection was closed before fully receiving the headers.

InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidHostName RequestError
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ReadFailed HeadError

Transitive error occurred reading from in.

RedirectRequiresResend

This can be avoided by calling receiveHead before sending the request body.

ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
TooManyHttpRedirects
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
UnsupportedUriScheme RequestError
UriMissingHost RequestError
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

WriteFailed

Sending the request failed. Error code can be found on the Connection object.

std.http.Client.Request.redirect

function

Source line 1206

This function takes an auxiliary buffer to store the arbitrarily large URI which may need to be merged with the previous URI, and that data needs to survive across different connections, which is where the input buffer lives.

aux_buf must outlive accesses to Request.uri.

fn redirect(r: *Request, head: *const Response.Head, aux_buf: *[]u8) !void

Parameters

r: *Request
head: *const Response.Head
aux_buf: *[]u8

std.http.Client.Request.RedirectBehavior

container

Source line 857

Any value other than not_allowed or unhandled means that integer represents how many remaining redirects are allowed.

Fields

not_allowed = 0

The next redirect will cause an error.

unhandled = std.math.maxInt(u16)

Redirects are passed to the client to analyze the redirect response directly.

_

std.http.Client.Request.RedirectBehavior.init

function

Source line 865

pub fn init(n: u16) RedirectBehavior

Parameters

n: u16

std.http.Client.Request.RedirectBehavior.remaining

function

Source line 878

pub fn remaining(rb: RedirectBehavior) u16

Parameters

std.http.Client.Request.RedirectBehavior.subtractOne

function

Source line 870

pub fn subtractOne(rb: *RedirectBehavior) void

Parameters

std.http.Client.Request.sendBodiless

function

Source line 907

Sends and flushes a complete request as only HTTP head, no body.

pub fn sendBodiless(r: *Request) Writer.Error!void

Parameters

r: *Request

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Request.sendBodilessUnflushed

function

Source line 913

Sends but does not flush a complete request as only HTTP head, no body.

pub fn sendBodilessUnflushed(r: *Request) Writer.Error!void

Parameters

r: *Request

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Request.sendBody

function

Source line 923

Transfers the HTTP head over the connection and flushes.

See also:

  • sendBodyUnflushed
pub fn sendBody(r: *Request, buffer: []u8) Writer.Error!http.BodyWriter

Parameters

r: *Request
buffer: []u8

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Request.sendBodyComplete

function

Source line 930

Transfers the HTTP head and body over the connection and flushes.

pub fn sendBodyComplete(r: *Request, body: []u8) Writer.Error!void

Parameters

r: *Request
body: []u8

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Request.sendBodyUnflushed

function

Source line 943

Transfers the HTTP head over the connection, which is not flushed until BodyWriter.flush or BodyWriter.end is called.

See also:

  • sendBody
pub fn sendBodyUnflushed(r: *Request, buffer: []u8) Writer.Error!http.BodyWriter

Parameters

r: *Request
buffer: []u8

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Request.sendHead

function

Source line 985

Sends HTTP headers without flushing.

fn sendHead(r: *Request) Writer.Error!void

Parameters

r: *Request

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.http.Client.Request.TransferEncoding

container

Source line 834

Fields

content_length: u64
chunked: void
none: void

std.http.Client.RequestError

error-set

Source line 1629

Errors

AccessDenied BindError

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported BindError

The address is not valid for the address family of socket.

AddressInUse BindError

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable BindError

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

CertificateBundleLoadFailure
ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

Failed to open or read "/etc/hosts" or "/etc/resolv.conf".

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
InvalidHostName
NameServerFailure LookupError
NetworkDown BindError

The local network interface used to reach the destination is offline.

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

One of the BindOptions is not supported by the Io implementation.

OutOfMemory Error
ProcessFdQuotaExceeded BindError

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

System-wide limit on the total number of open files has been reached.

SystemResources BindError

Insufficient memory or other resource internal to the operating system.

Timeout ConnectError
TlsInitializationFailed ConnectTcpError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownHostName LookupError
UnsupportedUriScheme
UriMissingHost
WouldBlock ConnectError

Non-blocking was requested and the operation cannot return immediately.

std.http.Client.RequestOptions

container

Source line 1636

Fields

version: http.Version = .@"HTTP/1.1"
handle_continue: bool = true

Automatically ignore 100 Continue responses. This assumes you don't care, and will have sent the body before you wait for the response.

If this is not the case AND you know the server will send a 100 Continue, set this to false and wait for a response before sending the body. If you wait AND the server does not send a 100 Continue before you finish the request, then the request will deadlock.

keep_alive: bool = true

If false, close the connection after the one request. If true, participate in the client connection pool.

redirect_behavior: Request.RedirectBehavior = @fromBackingInt(@intCast(3))

This field specifies whether to automatically follow redirects, and if so, how many redirects to follow before returning an error.

This will only follow redirects for repeatable requests (ie. with no payload or the server has acknowledged the payload).

connection: ?*Connection = null

Must be an already acquired connection.

headers: Request.Headers = .{}

Standard headers that have default, but overridable, behavior.

extra_headers: []const http.Header = &.{}

These headers are kept including when following a redirect to a different domain. Externally-owned; must outlive the Request.

privileged_headers: []const http.Header = &.{}

These headers are stripped when following a redirect to a different domain. Externally-owned; must outlive the Request.

std.http.Client.Response

container

Source line 483

Fields

request: *Request
head: Head

Pointers in this struct are invalidated when the response body stream is initialized.

std.http.Client.Response.bodyErr

function

Source line 769

After receiving error.ReadFailed from the Reader returned by reader or readerDecompressing, this function accesses the more specific error code.

pub fn bodyErr(response: *const Response) ?http.Reader.BodyError

Parameters

response: *const Response

std.http.Client.Response.Head

container

Source line 489

Fields

bytes: []const u8
version: http.Version
status: http.Status
reason: []const u8
location: ?[]const u8 = null
content_type: ?[]const u8 = null
content_disposition: ?[]const u8 = null
keep_alive: bool
content_length: ?u64 = null

If present, the number of bytes in the response body.

transfer_encoding: http.TransferEncoding = .none
content_encoding: http.ContentEncoding = .identity

std.http.Client.Response.Head.int64

function

Source line 693

inline fn int64(array: *const [8]u8) u64

Parameters

array: *const [8]u8

std.http.Client.Response.Head.invalidateStrings

function

Source line 713

Help the programmer avoid bugs by calling this when the string memory of Head becomes invalidated.

fn invalidateStrings(h: *Head) void

Parameters

h: *Head

std.http.Client.Response.Head.iterateHeaders

function

Source line 639

pub fn iterateHeaders(h: Head) http.HeaderIterator

Parameters

h: Head

Example usage

test iterateHeaders {
    const response_bytes = "HTTP/1.1 200 OK\r\n" ++
        "LOcation:url\r\n" ++
        "content-tYpe: text/plain\r\n" ++
        "content-disposition:attachment; filename=example.txt \r\n" ++
        "content-Length:10\r\n" ++
        "TRansfer-encoding:\tdeflate, chunked \r\n" ++
        "connectioN:\t keep-alive \r\n\r\n";

    const head = try Head.parse(response_bytes);
    var it = head.iterateHeaders();
    {
        const header = it.next().?;
        try testing.expectEqualStrings("LOcation", header.name);
        try testing.expectEqualStrings("url", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("content-tYpe", header.name);
        try testing.expectEqualStrings("text/plain", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("content-disposition", header.name);
        try testing.expectEqualStrings("attachment; filename=example.txt", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("content-Length", header.name);
        try testing.expectEqualStrings("10", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("TRansfer-encoding", header.name);
        try testing.expectEqualStrings("deflate, chunked", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("connectioN", header.name);
        try testing.expectEqualStrings("keep-alive", header.value);
        try testing.expect(!it.is_trailer);
    }
    try testing.expectEqual(null, it.next());
}

std.http.Client.Response.Head.parse

function

Source line 515

pub fn parse(bytes: []const u8) ParseError!Head

Parameters

bytes: []const u8

Errors

HttpConnectionHeaderUnsupported
HttpContentEncodingUnsupported
HttpHeaderContinuationsUnsupported
HttpHeadersInvalid
HttpTransferEncodingUnsupported
InvalidContentLength

Example usage

test parse {
    const response_bytes = "HTTP/1.1 200 OK\r\n" ++
        "LOcation:url\r\n" ++
        "content-tYpe: text/plain\r\n" ++
        "content-disposition:attachment; filename=example.txt \r\n" ++
        "content-Length:10\r\n" ++
        "TRansfer-encoding:\tdeflate, chunked \r\n" ++
        "connectioN:\t keep-alive \r\n\r\n";

    const head = try Head.parse(response_bytes);

    try testing.expectEqual(.@"HTTP/1.1", head.version);
    try testing.expectEqualStrings("OK", head.reason);
    try testing.expectEqual(.ok, head.status);

    try testing.expectEqualStrings("url", head.location.?);
    try testing.expectEqualStrings("text/plain", head.content_type.?);
    try testing.expectEqualStrings("attachment; filename=example.txt", head.content_disposition.?);

    try testing.expectEqual(true, head.keep_alive);
    try testing.expectEqual(10, head.content_length.?);
    try testing.expectEqual(.chunked, head.transfer_encoding);
    try testing.expectEqual(.deflate, head.content_encoding);
}

std.http.Client.Response.Head.ParseError

error-set

Source line 506

Errors

HttpConnectionHeaderUnsupported
HttpContentEncodingUnsupported
HttpHeaderContinuationsUnsupported
HttpHeadersInvalid
HttpTransferEncodingUnsupported
InvalidContentLength

std.http.Client.Response.Head.parseInt3

function

Source line 697

fn parseInt3(text: *const [3]u8) u10

Parameters

text: *const [3]u8

Example usage

test parseInt3 {
    const expectEqual = testing.expectEqual;
    try expectEqual(@as(u10, 0), parseInt3("000"));
    try expectEqual(@as(u10, 418), parseInt3("418"));
    try expectEqual(@as(u10, 999), parseInt3("999"));
}

std.http.Client.Response.iterateTrailers

function

Source line 773

pub fn iterateTrailers(response: *const Response) http.HeaderIterator

Parameters

response: *const Response

std.http.Client.Response.reader

function

Source line 731

If compressed body has been negotiated this will return compressed bytes.

If the returned Reader returns error.ReadFailed the error is available via bodyErr.

Asserts that this function is only called once.

See also:

  • readerDecompressing
pub fn reader(response: *Response, transfer_buffer: []u8) *Reader

Parameters

response: *Response
transfer_buffer: []u8

std.http.Client.Response.readerDecompressing

function

Source line 748

If compressed body has been negotiated this will return decompressed bytes.

If the returned Reader returns error.ReadFailed the error is available via bodyErr.

Asserts that this function is only called once.

See also:

  • reader
pub fn readerDecompressing( response: *Response, transfer_buffer: []u8, decompress: *http.Decompress, decompress_buffer: []u8, ) *Reader

Parameters

response: *Response
transfer_buffer: []u8
decompress: *http.Decompress
decompress_buffer: []u8

std.http.Client.std

alias

Source line 11

Alias of std

std.http.Client.testing

alias

Source line 13

Alias of std.testing

std.http.Client.Uri

alias

Source line 16

Alias of std.Uri

std.http.Client.uriPort

function

Source line 1674

fn uriPort(uri: Uri, protocol: Protocol) u16

Parameters

uri: Uri
protocol: Protocol

std.http.Client.Writer

alias

Source line 19

Alias of std.Io.Writer

Source code

std/http/Client.zig

//! HTTP(S) Client implementation.
//!
//! Connections are opened in a thread-safe manner, but individual Requests are not.
//!
//! TLS support may be disabled via `std.options.http_disable_tls`.
//!
const Client = @This();

const builtin = @import("builtin");

const std = @import("../std.zig");
const Io = std.Io;
const testing = std.testing;
const http = std.http;
const mem = std.mem;
const Uri = std.Uri;
const Allocator = std.mem.Allocator;
const assert = std.debug.assert;
const Writer = std.Io.Writer;
const Reader = std.Io.Reader;
const HostName = std.Io.net.HostName;

pub const disable_tls = std.options.http_disable_tls;

/// Used for all client allocations. Must be thread-safe.
allocator: Allocator,
/// Used for opening TCP connections.
io: Io,

ca_bundle_lock: if (disable_tls) void else Io.RwLock = if (disable_tls) {} else .init,
ca_bundle: if (disable_tls) void else std.crypto.Certificate.Bundle = if (disable_tls) {} else .empty,
/// Used both for the reader and writer buffers.
tls_buffer_size: if (disable_tls) u0 else usize = if (disable_tls) 0 else std.crypto.tls.Client.min_buffer_len,
/// If non-null, ssl secrets are logged to a stream. Creating such a stream
/// allows other processes with access to that stream to decrypt all
/// traffic over connections created with this `Client`.
ssl_key_log: ?*std.crypto.tls.Client.SslKeyLog = null,

/// The time used to decide whether certificates are expired.
///
/// When this is `null`, the next time this client performs an HTTPS request,
/// it will first check the time and rescan the system for root certificates.
now: ?Io.Timestamp = null,

/// The pool of connections that can be reused (and currently in use).
connection_pool: ConnectionPool = .{},
/// Each `Connection` allocates this amount for the reader buffer.
///
/// If the entire HTTP header cannot fit in this amount of bytes,
/// `error.HttpHeadersOversize` will be returned from `Request.wait`.
read_buffer_size: usize = 8192,
/// Each `Connection` allocates this amount for the writer buffer.
write_buffer_size: usize = 1024,

/// If populated, all http traffic travels through this third party.
/// This field cannot be modified while the client has active connections.
/// Pointer to externally-owned memory.
http_proxy: ?*Proxy = null,
/// If populated, all https traffic travels through this third party.
/// This field cannot be modified while the client has active connections.
/// Pointer to externally-owned memory.
https_proxy: ?*Proxy = null,

/// A Least-Recently-Used cache of open connections to be reused.
pub const ConnectionPool = struct {
    mutex: Io.Mutex = .init,
    /// Open connections that are currently in use.
    used: std.DoublyLinkedList = .{},
    /// Open connections that are not currently in use.
    free: std.DoublyLinkedList = .{},
    free_len: usize = 0,
    free_size: usize = 32,

    /// The criteria for a connection to be considered a match.
    pub const Criteria = struct {
        host: HostName,
        port: u16,
        protocol: Protocol,
    };

    /// Finds and acquires a connection from the connection pool matching the criteria.
    /// If no connection is found, null is returned.
    ///
    /// Threadsafe.
    pub fn findConnection(pool: *ConnectionPool, io: Io, criteria: Criteria) Io.Cancelable!?*Connection {
        try pool.mutex.lock(io);
        defer pool.mutex.unlock(io);

        var next = pool.free.last;
        while (next) |node| : (next = node.prev) {
            const connection: *Connection = @alignCast(@fieldParentPtr("pool_node", node));
            if (connection.protocol != criteria.protocol) continue;
            if (connection.port != criteria.port) continue;

            // Domain names are case-insensitive (RFC 5890, Section 2.3.2.4)
            if (!connection.host().eql(criteria.host)) continue;

            pool.acquireUnsafe(connection);
            return connection;
        }

        return null;
    }

    /// Acquires an existing connection from the connection pool. This function is not threadsafe.
    pub fn acquireUnsafe(pool: *ConnectionPool, connection: *Connection) void {
        pool.free.remove(&connection.pool_node);
        pool.free_len -= 1;

        pool.used.append(&connection.pool_node);
    }

    /// Acquires an existing connection from the connection pool. This function is threadsafe.
    pub fn acquire(pool: *ConnectionPool, io: Io, connection: *Connection) Io.Cancelable!void {
        try pool.mutex.lock(io);
        defer pool.mutex.unlock(io);

        return pool.acquireUnsafe(connection);
    }

    /// Tries to release a connection back to the connection pool.
    /// If the connection is marked as closing, it will be closed instead.
    ///
    /// Threadsafe.
    pub fn release(pool: *ConnectionPool, connection: *Connection, io: Io) void {
        pool.mutex.lockUncancelable(io);
        defer pool.mutex.unlock(io);

        pool.used.remove(&connection.pool_node);

        if (connection.closing or pool.free_size == 0) return connection.destroy(io);

        if (pool.free_len >= pool.free_size) {
            const popped: *Connection = @alignCast(@fieldParentPtr("pool_node", pool.free.popFirst().?));
            pool.free_len -= 1;

            popped.destroy(io);
        }

        if (connection.proxied) {
            // proxied connections go to the end of the queue, always try direct connections first
            pool.free.prepend(&connection.pool_node);
        } else {
            pool.free.append(&connection.pool_node);
        }

        pool.free_len += 1;
    }

    /// Adds a newly created node to the pool of used connections. This function is threadsafe.
    pub fn addUsed(pool: *ConnectionPool, io: Io, connection: *Connection) Io.Cancelable!void {
        try pool.mutex.lock(io);
        defer pool.mutex.unlock(io);

        pool.used.append(&connection.pool_node);
    }

    /// Resizes the connection pool.
    ///
    /// If the new size is smaller than the current size, then idle connections will be closed until the pool is the new size.
    ///
    /// Threadsafe.
    pub fn resize(pool: *ConnectionPool, io: Io, new_size: usize) Io.Cancelable!void {
        try pool.mutex.lock(io);
        defer pool.mutex.unlock(io);

        while (pool.free_len > new_size) {
            const popped: *Connection = @alignCast(@fieldParentPtr("pool_node", pool.free.popFirst().?));
            pool.free_len -= 1;

            popped.destroy(io);
        }

        pool.free_size = new_size;
    }

    /// Frees the connection pool and closes all connections within.
    ///
    /// All future operations on the connection pool will deadlock.
    ///
    /// Threadsafe.
    pub fn deinit(pool: *ConnectionPool, io: Io) void {
        pool.mutex.lockUncancelable(io);

        var next = pool.free.first;
        while (next) |node| {
            const connection: *Connection = @alignCast(@fieldParentPtr("pool_node", node));
            next = node.next;
            connection.destroy(io);
        }

        next = pool.used.first;
        while (next) |node| {
            const connection: *Connection = @alignCast(@fieldParentPtr("pool_node", node));
            next = node.next;
            connection.destroy(io);
        }

        pool.* = undefined;
    }
};

pub const Protocol = enum {
    plain,
    tls,

    fn port(protocol: Protocol) u16 {
        return switch (protocol) {
            .plain => 80,
            .tls => 443,
        };
    }

    pub fn fromScheme(scheme: []const u8) ?Protocol {
        const protocol_map = std.StaticStringMap(Protocol).initComptime(.{
            .{ "http", .plain },
            .{ "ws", .plain },
            .{ "https", .tls },
            .{ "wss", .tls },
        });
        return protocol_map.get(scheme);
    }

    pub fn fromUri(uri: Uri) ?Protocol {
        return fromScheme(uri.scheme);
    }
};

pub const Connection = struct {
    client: *Client,
    stream_writer: Io.net.Stream.Writer,
    stream_reader: Io.net.Stream.Reader,
    /// Entry in `ConnectionPool.used` or `ConnectionPool.free`.
    pool_node: std.DoublyLinkedList.Node,
    port: u16,
    host_len: u8,
    proxied: bool,
    closing: bool,
    protocol: Protocol,

    const Plain = struct {
        connection: Connection,

        fn create(
            client: *Client,
            remote_host: HostName,
            port: u16,
            stream: Io.net.Stream,
        ) error{OutOfMemory}!*Plain {
            const io = client.io;
            const gpa = client.allocator;
            const alloc_len = allocLen(client, remote_host.bytes.len);
            const base = try gpa.alignedAlloc(u8, .of(Plain), alloc_len);
            errdefer gpa.free(base);
            const host_buffer = base[@sizeOf(Plain)..][0..remote_host.bytes.len];
            const socket_read_buffer = host_buffer.ptr[host_buffer.len..][0..client.read_buffer_size];
            const socket_write_buffer = socket_read_buffer.ptr[socket_read_buffer.len..][0..client.write_buffer_size];
            assert(base.ptr + alloc_len == socket_write_buffer.ptr + socket_write_buffer.len);
            @memcpy(host_buffer, remote_host.bytes);
            const plain: *Plain = @ptrCast(base);
            plain.* = .{
                .connection = .{
                    .client = client,
                    .stream_writer = stream.writer(io, socket_write_buffer),
                    .stream_reader = stream.reader(io, socket_read_buffer),
                    .pool_node = .{},
                    .port = port,
                    .host_len = @intCast(remote_host.bytes.len),
                    .proxied = false,
                    .closing = false,
                    .protocol = .plain,
                },
            };
            return plain;
        }

        fn destroy(plain: *Plain) void {
            const c = &plain.connection;
            const gpa = c.client.allocator;
            const base: [*]align(@alignOf(Plain)) u8 = @ptrCast(plain);
            gpa.free(base[0..allocLen(c.client, c.host_len)]);
        }

        fn allocLen(client: *Client, host_len: usize) usize {
            return @sizeOf(Plain) + host_len + client.read_buffer_size + client.write_buffer_size;
        }

        fn host(plain: *Plain) HostName {
            const base: [*]u8 = @ptrCast(plain);
            return .{ .bytes = base[@sizeOf(Plain)..][0..plain.connection.host_len] };
        }
    };

    const Tls = struct {
        client: std.crypto.tls.Client,
        connection: Connection,

        /// Asserts that `client.now` is non-null.
        fn create(
            client: *Client,
            remote_host: HostName,
            port: u16,
            stream: Io.net.Stream,
        ) !*Tls {
            const io = client.io;
            const gpa = client.allocator;
            const alloc_len = allocLen(client, remote_host.bytes.len);
            const base = try gpa.alignedAlloc(u8, .of(Tls), alloc_len);
            errdefer gpa.free(base);
            const host_buffer = base[@sizeOf(Tls)..][0..remote_host.bytes.len];
            // The TLS client wants enough buffer for the max encrypted frame
            // size, and the HTTP body reader wants enough buffer for the
            // entire HTTP header. This means we need a combined upper bound.
            const tls_read_buffer_len = client.tls_buffer_size + client.read_buffer_size;
            const tls_read_buffer = host_buffer.ptr[host_buffer.len..][0..tls_read_buffer_len];
            const tls_write_buffer = tls_read_buffer.ptr[tls_read_buffer.len..][0..client.tls_buffer_size];
            const socket_write_buffer = tls_write_buffer.ptr[tls_write_buffer.len..][0..client.write_buffer_size];
            const socket_read_buffer = socket_write_buffer.ptr[socket_write_buffer.len..][0..client.tls_buffer_size];
            assert(base.ptr + alloc_len == socket_read_buffer.ptr + socket_read_buffer.len);
            @memcpy(host_buffer, remote_host.bytes);
            const tls: *Tls = @ptrCast(base);
            var random_buffer: [std.crypto.tls.Client.Options.entropy_len]u8 = undefined;
            io.random(&random_buffer);
            tls.* = .{
                .connection = .{
                    .client = client,
                    .stream_writer = stream.writer(io, tls_write_buffer),
                    .stream_reader = stream.reader(io, socket_read_buffer),
                    .pool_node = .{},
                    .port = port,
                    .host_len = @intCast(remote_host.bytes.len),
                    .proxied = false,
                    .closing = false,
                    .protocol = .tls,
                },
                // TODO data race here on ca_bundle if the user sets `now` to null
                .client = std.crypto.tls.Client.init(
                    &tls.connection.stream_reader.interface,
                    &tls.connection.stream_writer.interface,
                    .{
                        .host = .{ .explicit = remote_host.bytes },
                        .ca = .{ .bundle = .{
                            .gpa = client.allocator,
                            .io = client.io,
                            .lock = &client.ca_bundle_lock,
                            .bundle = &client.ca_bundle,
                        } },
                        .ssl_key_log = client.ssl_key_log,
                        .read_buffer = tls_read_buffer,
                        .write_buffer = socket_write_buffer,
                        .entropy = &random_buffer,
                        .realtime_now = client.now.?,
                        // This is appropriate for HTTPS because the HTTP headers contain
                        // the content length which is used to detect truncation attacks.
                        .allow_truncation_attacks = true,
                    },
                ) catch |err| switch (err) {
                    error.WriteFailed => return tls.connection.stream_writer.err.?,
                    error.ReadFailed => return tls.connection.stream_reader.err.?,
                    else => |e| return e,
                },
            };
            return tls;
        }

        fn destroy(tls: *Tls) void {
            const c = &tls.connection;
            const gpa = c.client.allocator;
            const base: [*]align(@alignOf(Tls)) u8 = @ptrCast(tls);
            gpa.free(base[0..allocLen(c.client, c.host_len)]);
        }

        fn allocLen(client: *Client, host_len: usize) usize {
            const tls_read_buffer_len = client.tls_buffer_size + client.read_buffer_size;
            return @sizeOf(Tls) + host_len + tls_read_buffer_len + client.tls_buffer_size +
                client.write_buffer_size + client.tls_buffer_size;
        }

        fn host(tls: *Tls) HostName {
            const base: [*]u8 = @ptrCast(tls);
            return .{ .bytes = base[@sizeOf(Tls)..][0..tls.connection.host_len] };
        }
    };

    pub const ReadError = std.crypto.tls.Client.ReadError || Io.net.Stream.Reader.Error;

    pub fn getReadError(c: *const Connection) ?ReadError {
        return switch (c.protocol) {
            .tls => {
                if (disable_tls) unreachable;
                const tls: *const Tls = @alignCast(@fieldParentPtr("connection", c));
                return tls.client.read_err orelse c.stream_reader.err.?;
            },
            .plain => {
                return c.stream_reader.err.?;
            },
        };
    }

    fn getStream(c: *Connection) Io.net.Stream {
        return c.stream_reader.stream;
    }

    pub fn host(c: *Connection) HostName {
        return switch (c.protocol) {
            .tls => {
                if (disable_tls) unreachable;
                const tls: *Tls = @alignCast(@fieldParentPtr("connection", c));
                return tls.host();
            },
            .plain => {
                const plain: *Plain = @alignCast(@fieldParentPtr("connection", c));
                return plain.host();
            },
        };
    }

    /// If this is called without calling `flush` or `end`, data will be
    /// dropped unsent.
    pub fn destroy(c: *Connection, io: Io) void {
        c.stream_reader.stream.close(io);
        switch (c.protocol) {
            .tls => {
                if (disable_tls) unreachable;
                const tls: *Tls = @alignCast(@fieldParentPtr("connection", c));
                tls.destroy();
            },
            .plain => {
                const plain: *Plain = @alignCast(@fieldParentPtr("connection", c));
                plain.destroy();
            },
        }
    }

    /// HTTP protocol from client to server.
    /// This either goes directly to `stream_writer`, or to a TLS client.
    pub fn writer(c: *Connection) *Writer {
        return switch (c.protocol) {
            .tls => {
                if (disable_tls) unreachable;
                const tls: *Tls = @alignCast(@fieldParentPtr("connection", c));
                return &tls.client.writer;
            },
            .plain => &c.stream_writer.interface,
        };
    }

    /// HTTP protocol from server to client.
    /// This either comes directly from `stream_reader`, or from a TLS client.
    pub fn reader(c: *Connection) *Reader {
        return switch (c.protocol) {
            .tls => {
                if (disable_tls) unreachable;
                const tls: *Tls = @alignCast(@fieldParentPtr("connection", c));
                return &tls.client.reader;
            },
            .plain => &c.stream_reader.interface,
        };
    }

    pub fn flush(c: *Connection) Writer.Error!void {
        if (c.protocol == .tls) {
            if (disable_tls) unreachable;
            const tls: *Tls = @alignCast(@fieldParentPtr("connection", c));
            try tls.client.writer.flush();
        }
        try c.stream_writer.interface.flush();
    }

    /// If the connection is a TLS connection, sends the close_notify alert.
    ///
    /// Flushes all buffers.
    pub fn end(c: *Connection) Writer.Error!void {
        if (c.protocol == .tls) {
            if (disable_tls) unreachable;
            const tls: *Tls = @alignCast(@fieldParentPtr("connection", c));
            try tls.client.end();
        }
        try c.stream_writer.interface.flush();
    }
};

pub const Response = struct {
    request: *Request,
    /// Pointers in this struct are invalidated when the response body stream
    /// is initialized.
    head: Head,

    pub const Head = struct {
        bytes: []const u8,
        version: http.Version,
        status: http.Status,
        reason: []const u8,
        location: ?[]const u8 = null,
        content_type: ?[]const u8 = null,
        content_disposition: ?[]const u8 = null,

        keep_alive: bool,

        /// If present, the number of bytes in the response body.
        content_length: ?u64 = null,

        transfer_encoding: http.TransferEncoding = .none,
        content_encoding: http.ContentEncoding = .identity,

        pub const ParseError = error{
            HttpConnectionHeaderUnsupported,
            HttpContentEncodingUnsupported,
            HttpHeaderContinuationsUnsupported,
            HttpHeadersInvalid,
            HttpTransferEncodingUnsupported,
            InvalidContentLength,
        };

        pub fn parse(bytes: []const u8) ParseError!Head {
            var res: Head = .{
                .bytes = bytes,
                .status = undefined,
                .reason = undefined,
                .version = undefined,
                .keep_alive = false,
            };
            var it = mem.splitSequence(u8, bytes, "\r\n");

            const first_line = it.first();
            if (first_line.len < 12) return error.HttpHeadersInvalid;

            const version: http.Version = switch (int64(first_line[0..8])) {
                int64("HTTP/1.0") => .@"HTTP/1.0",
                int64("HTTP/1.1") => .@"HTTP/1.1",
                else => return error.HttpHeadersInvalid,
            };
            if (first_line[8] != ' ') return error.HttpHeadersInvalid;
            const status: http.Status = @fromBackingInt(@intCast(parseInt3(first_line[9..12])));
            const reason = mem.trimStart(u8, first_line[12..], " ");

            res.version = version;
            res.status = status;
            res.reason = reason;
            res.keep_alive = switch (version) {
                .@"HTTP/1.0" => false,
                .@"HTTP/1.1" => true,
            };

            while (it.next()) |line| {
                if (line.len == 0) return res;
                switch (line[0]) {
                    ' ', '\t' => return error.HttpHeaderContinuationsUnsupported,
                    else => {},
                }

                var line_it = mem.splitScalar(u8, line, ':');
                const header_name = line_it.next().?;
                const header_value = mem.trim(u8, line_it.rest(), " \t");
                if (header_name.len == 0) return error.HttpHeadersInvalid;

                if (std.ascii.eqlIgnoreCase(header_name, "connection")) {
                    res.keep_alive = !std.ascii.eqlIgnoreCase(header_value, "close");
                } else if (std.ascii.eqlIgnoreCase(header_name, "content-type")) {
                    res.content_type = header_value;
                } else if (std.ascii.eqlIgnoreCase(header_name, "location")) {
                    res.location = header_value;
                } else if (std.ascii.eqlIgnoreCase(header_name, "content-disposition")) {
                    res.content_disposition = header_value;
                } else if (std.ascii.eqlIgnoreCase(header_name, "transfer-encoding")) {
                    // Transfer-Encoding: second, first
                    // Transfer-Encoding: deflate, chunked
                    var iter = mem.splitBackwardsScalar(u8, header_value, ',');

                    const first = iter.first();
                    const trimmed_first = mem.trim(u8, first, " ");

                    var next: ?[]const u8 = first;
                    if (std.meta.stringToEnum(http.TransferEncoding, trimmed_first)) |transfer| {
                        if (res.transfer_encoding != .none) return error.HttpHeadersInvalid; // we already have a transfer encoding
                        res.transfer_encoding = transfer;

                        next = iter.next();
                    }

                    if (next) |second| {
                        const trimmed_second = mem.trim(u8, second, " ");

                        if (http.ContentEncoding.fromString(trimmed_second)) |transfer| {
                            if (res.content_encoding != .identity) return error.HttpHeadersInvalid; // double compression is not supported
                            res.content_encoding = transfer;
                        } else {
                            return error.HttpTransferEncodingUnsupported;
                        }
                    }

                    if (iter.next()) |_| return error.HttpTransferEncodingUnsupported;
                } else if (std.ascii.eqlIgnoreCase(header_name, "content-length")) {
                    const content_length = std.fmt.parseInt(u64, header_value, 10) catch return error.InvalidContentLength;

                    if (res.content_length != null and res.content_length != content_length) return error.HttpHeadersInvalid;

                    res.content_length = content_length;
                } else if (std.ascii.eqlIgnoreCase(header_name, "content-encoding")) {
                    if (res.content_encoding != .identity) return error.HttpHeadersInvalid;

                    const trimmed = mem.trim(u8, header_value, " ");

                    if (http.ContentEncoding.fromString(trimmed)) |ce| {
                        res.content_encoding = ce;
                    } else {
                        return error.HttpContentEncodingUnsupported;
                    }
                }
            }
            return error.HttpHeadersInvalid; // missing empty line
        }

        test parse {
            const response_bytes = "HTTP/1.1 200 OK\r\n" ++
                "LOcation:url\r\n" ++
                "content-tYpe: text/plain\r\n" ++
                "content-disposition:attachment; filename=example.txt \r\n" ++
                "content-Length:10\r\n" ++
                "TRansfer-encoding:\tdeflate, chunked \r\n" ++
                "connectioN:\t keep-alive \r\n\r\n";

            const head = try Head.parse(response_bytes);

            try testing.expectEqual(.@"HTTP/1.1", head.version);
            try testing.expectEqualStrings("OK", head.reason);
            try testing.expectEqual(.ok, head.status);

            try testing.expectEqualStrings("url", head.location.?);
            try testing.expectEqualStrings("text/plain", head.content_type.?);
            try testing.expectEqualStrings("attachment; filename=example.txt", head.content_disposition.?);

            try testing.expectEqual(true, head.keep_alive);
            try testing.expectEqual(10, head.content_length.?);
            try testing.expectEqual(.chunked, head.transfer_encoding);
            try testing.expectEqual(.deflate, head.content_encoding);
        }

        pub fn iterateHeaders(h: Head) http.HeaderIterator {
            return .init(h.bytes);
        }

        test iterateHeaders {
            const response_bytes = "HTTP/1.1 200 OK\r\n" ++
                "LOcation:url\r\n" ++
                "content-tYpe: text/plain\r\n" ++
                "content-disposition:attachment; filename=example.txt \r\n" ++
                "content-Length:10\r\n" ++
                "TRansfer-encoding:\tdeflate, chunked \r\n" ++
                "connectioN:\t keep-alive \r\n\r\n";

            const head = try Head.parse(response_bytes);
            var it = head.iterateHeaders();
            {
                const header = it.next().?;
                try testing.expectEqualStrings("LOcation", header.name);
                try testing.expectEqualStrings("url", header.value);
                try testing.expect(!it.is_trailer);
            }
            {
                const header = it.next().?;
                try testing.expectEqualStrings("content-tYpe", header.name);
                try testing.expectEqualStrings("text/plain", header.value);
                try testing.expect(!it.is_trailer);
            }
            {
                const header = it.next().?;
                try testing.expectEqualStrings("content-disposition", header.name);
                try testing.expectEqualStrings("attachment; filename=example.txt", header.value);
                try testing.expect(!it.is_trailer);
            }
            {
                const header = it.next().?;
                try testing.expectEqualStrings("content-Length", header.name);
                try testing.expectEqualStrings("10", header.value);
                try testing.expect(!it.is_trailer);
            }
            {
                const header = it.next().?;
                try testing.expectEqualStrings("TRansfer-encoding", header.name);
                try testing.expectEqualStrings("deflate, chunked", header.value);
                try testing.expect(!it.is_trailer);
            }
            {
                const header = it.next().?;
                try testing.expectEqualStrings("connectioN", header.name);
                try testing.expectEqualStrings("keep-alive", header.value);
                try testing.expect(!it.is_trailer);
            }
            try testing.expectEqual(null, it.next());
        }

        inline fn int64(array: *const [8]u8) u64 {
            return @bitCast(array.*);
        }

        fn parseInt3(text: *const [3]u8) u10 {
            const nnn: @Vector(3, u8) = text.*;
            const zero: @Vector(3, u8) = .{ '0', '0', '0' };
            const mmm: @Vector(3, u10) = .{ 100, 10, 1 };
            return @reduce(.Add, (nnn -% zero) *% mmm);
        }

        test parseInt3 {
            const expectEqual = testing.expectEqual;
            try expectEqual(@as(u10, 0), parseInt3("000"));
            try expectEqual(@as(u10, 418), parseInt3("418"));
            try expectEqual(@as(u10, 999), parseInt3("999"));
        }

        /// Help the programmer avoid bugs by calling this when the string
        /// memory of `Head` becomes invalidated.
        fn invalidateStrings(h: *Head) void {
            h.bytes = undefined;
            h.reason = undefined;
            if (h.location) |*s| s.* = undefined;
            if (h.content_type) |*s| s.* = undefined;
            if (h.content_disposition) |*s| s.* = undefined;
        }
    };

    /// If compressed body has been negotiated this will return compressed bytes.
    ///
    /// If the returned `Reader` returns `error.ReadFailed` the error is
    /// available via `bodyErr`.
    ///
    /// Asserts that this function is only called once.
    ///
    /// See also:
    /// * `readerDecompressing`
    pub fn reader(response: *Response, transfer_buffer: []u8) *Reader {
        response.head.invalidateStrings();
        const req = response.request;
        if (!req.method.responseHasBody()) return .ending;
        const head = &response.head;
        return req.reader.bodyReader(transfer_buffer, head.transfer_encoding, head.content_length);
    }

    /// If compressed body has been negotiated this will return decompressed bytes.
    ///
    /// If the returned `Reader` returns `error.ReadFailed` the error is
    /// available via `bodyErr`.
    ///
    /// Asserts that this function is only called once.
    ///
    /// See also:
    /// * `reader`
    pub fn readerDecompressing(
        response: *Response,
        transfer_buffer: []u8,
        decompress: *http.Decompress,
        decompress_buffer: []u8,
    ) *Reader {
        response.head.invalidateStrings();
        const head = &response.head;
        return response.request.reader.bodyReaderDecompressing(
            transfer_buffer,
            head.transfer_encoding,
            head.content_length,
            head.content_encoding,
            decompress,
            decompress_buffer,
        );
    }

    /// After receiving `error.ReadFailed` from the `Reader` returned by
    /// `reader` or `readerDecompressing`, this function accesses the
    /// more specific error code.
    pub fn bodyErr(response: *const Response) ?http.Reader.BodyError {
        return response.request.reader.body_err;
    }

    pub fn iterateTrailers(response: *const Response) http.HeaderIterator {
        const r = &response.request.reader;
        assert(r.state == .ready);
        return .{
            .bytes = r.trailers,
            .index = 0,
            .is_trailer = true,
        };
    }
};

pub const Request = struct {
    /// This field is provided so that clients can observe redirected URIs.
    ///
    /// Its backing memory is externally provided by API users when creating a
    /// request, and then again provided externally via `redirect_buffer` to
    /// `receiveHead`.
    uri: Uri,
    client: *Client,
    /// This is null when the connection is released.
    connection: ?*Connection,
    reader: http.Reader,
    keep_alive: bool,

    method: http.Method,
    version: http.Version = .@"HTTP/1.1",
    transfer_encoding: TransferEncoding,
    redirect_behavior: RedirectBehavior,
    accept_encoding: @TypeOf(default_accept_encoding) = default_accept_encoding,

    /// Whether the request should handle a 100-continue response before sending the request body.
    handle_continue: bool,

    /// Standard headers that have default, but overridable, behavior.
    headers: Headers,

    /// Populated in `receiveHead`; used in `deinit` to determine whether to
    /// discard the body to reuse the connection.
    response_content_length: ?u64 = null,
    /// Populated in `receiveHead`; used in `deinit` to determine whether to
    /// discard the body to reuse the connection.
    response_transfer_encoding: http.TransferEncoding = .none,

    /// These headers are kept including when following a redirect to a
    /// different domain.
    /// Externally-owned; must outlive the Request.
    extra_headers: []const http.Header,

    /// These headers are stripped when following a redirect to a different
    /// domain.
    /// Externally-owned; must outlive the Request.
    privileged_headers: []const http.Header,

    pub const default_accept_encoding: [@typeInfo(http.ContentEncoding).@"enum".field_names.len]bool = b: {
        var result: [@typeInfo(http.ContentEncoding).@"enum".field_names.len]bool = @splat(false);
        result[@backingInt(http.ContentEncoding.gzip)] = true;
        result[@backingInt(http.ContentEncoding.deflate)] = true;
        result[@backingInt(http.ContentEncoding.identity)] = true;
        break :b result;
    };

    pub const TransferEncoding = union(enum) {
        content_length: u64,
        chunked: void,
        none: void,
    };

    pub const Headers = struct {
        host: Value = .default,
        authorization: Value = .default,
        user_agent: Value = .default,
        connection: Value = .default,
        accept_encoding: Value = .default,
        content_type: Value = .default,

        pub const Value = union(enum) {
            default,
            omit,
            override: []const u8,
        };
    };

    /// Any value other than `not_allowed` or `unhandled` means that integer represents
    /// how many remaining redirects are allowed.
    pub const RedirectBehavior = enum(u16) {
        /// The next redirect will cause an error.
        not_allowed = 0,
        /// Redirects are passed to the client to analyze the redirect response
        /// directly.
        unhandled = std.math.maxInt(u16),
        _,

        pub fn init(n: u16) RedirectBehavior {
            assert(n != std.math.maxInt(u16));
            return @fromBackingInt(@intCast(n));
        }

        pub fn subtractOne(rb: *RedirectBehavior) void {
            switch (rb.*) {
                .not_allowed => unreachable,
                .unhandled => unreachable,
                _ => rb.* = @fromBackingInt(@intCast(@backingInt(rb.*) - 1)),
            }
        }

        pub fn remaining(rb: RedirectBehavior) u16 {
            assert(rb != .unhandled);
            return @backingInt(rb);
        }
    };

    /// Returns the request's `Connection` back to the pool of the `Client`.
    pub fn deinit(r: *Request) void {
        const io = r.client.io;
        if (r.connection) |connection| {
            connection.closing = connection.closing or switch (r.reader.state) {
                .ready => false,
                .received_head => c: {
                    if (r.method.requestHasBody()) break :c true;
                    if (!r.method.responseHasBody()) break :c false;
                    const reader = r.reader.bodyReader(&.{}, r.response_transfer_encoding, r.response_content_length);
                    _ = reader.discardRemaining() catch |err| switch (err) {
                        error.ReadFailed => break :c true,
                    };
                    break :c r.reader.state != .ready;
                },
                else => true,
            };
            r.client.connection_pool.release(connection, io);
        }
        r.* = undefined;
    }

    /// Sends and flushes a complete request as only HTTP head, no body.
    pub fn sendBodiless(r: *Request) Writer.Error!void {
        try sendBodilessUnflushed(r);
        try r.connection.?.flush();
    }

    /// Sends but does not flush a complete request as only HTTP head, no body.
    pub fn sendBodilessUnflushed(r: *Request) Writer.Error!void {
        assert(r.transfer_encoding == .none);
        assert(!r.method.requestHasBody());
        try sendHead(r);
    }

    /// Transfers the HTTP head over the connection and flushes.
    ///
    /// See also:
    /// * `sendBodyUnflushed`
    pub fn sendBody(r: *Request, buffer: []u8) Writer.Error!http.BodyWriter {
        const result = try sendBodyUnflushed(r, buffer);
        try r.connection.?.flush();
        return result;
    }

    /// Transfers the HTTP head and body over the connection and flushes.
    pub fn sendBodyComplete(r: *Request, body: []u8) Writer.Error!void {
        r.transfer_encoding = .{ .content_length = body.len };
        var bw = try sendBodyUnflushed(r, body);
        bw.writer.end = body.len;
        try bw.end();
        try r.connection.?.flush();
    }

    /// Transfers the HTTP head over the connection, which is not flushed until
    /// `BodyWriter.flush` or `BodyWriter.end` is called.
    ///
    /// See also:
    /// * `sendBody`
    pub fn sendBodyUnflushed(r: *Request, buffer: []u8) Writer.Error!http.BodyWriter {
        assert(r.method.requestHasBody());
        try sendHead(r);
        const http_protocol_output = r.connection.?.writer();
        return switch (r.transfer_encoding) {
            .chunked => .{
                .http_protocol_output = http_protocol_output,
                .state = .init_chunked,
                .writer = .{
                    .buffer = buffer,
                    .vtable = &.{
                        .drain = http.BodyWriter.chunkedDrain,
                        .sendFile = http.BodyWriter.chunkedSendFile,
                    },
                },
            },
            .content_length => |len| .{
                .http_protocol_output = http_protocol_output,
                .state = .{ .content_length = len },
                .writer = .{
                    .buffer = buffer,
                    .vtable = &.{
                        .drain = http.BodyWriter.contentLengthDrain,
                        .sendFile = http.BodyWriter.contentLengthSendFile,
                    },
                },
            },
            .none => .{
                .http_protocol_output = http_protocol_output,
                .state = .none,
                .writer = .{
                    .buffer = buffer,
                    .vtable = &.{
                        .drain = http.BodyWriter.noneDrain,
                        .sendFile = http.BodyWriter.noneSendFile,
                    },
                },
            },
        };
    }

    /// Sends HTTP headers without flushing.
    fn sendHead(r: *Request) Writer.Error!void {
        const uri = r.uri;
        const connection = r.connection.?;
        const w = connection.writer();

        try w.writeAll(@tagName(r.method));
        try w.writeByte(' ');

        if (r.method == .CONNECT) {
            try uri.writeToStream(w, .{ .authority = true });
        } else {
            try uri.writeToStream(w, .{
                .scheme = connection.proxied,
                .authentication = connection.proxied,
                .authority = connection.proxied,
                .path = true,
                .query = true,
            });
        }
        try w.writeByte(' ');
        try w.writeAll(@tagName(r.version));
        try w.writeAll("\r\n");

        if (try emitOverridableHeader("host: ", r.headers.host, w)) {
            try w.writeAll("host: ");
            try uri.writeToStream(w, .{ .authority = true });
            try w.writeAll("\r\n");
        }

        if (try emitOverridableHeader("authorization: ", r.headers.authorization, w)) {
            if (uri.user != null or uri.password != null) {
                try w.writeAll("authorization: ");
                try basic_authorization.write(uri, w);
                try w.writeAll("\r\n");
            }
        }

        if (try emitOverridableHeader("user-agent: ", r.headers.user_agent, w)) {
            try w.writeAll("user-agent: zig/");
            try w.writeAll(builtin.zig_version_string);
            try w.writeAll(" (std.http)\r\n");
        }

        if (try emitOverridableHeader("connection: ", r.headers.connection, w)) {
            if (r.keep_alive) {
                try w.writeAll("connection: keep-alive\r\n");
            } else {
                try w.writeAll("connection: close\r\n");
            }
        }

        if (try emitOverridableHeader("accept-encoding: ", r.headers.accept_encoding, w)) {
            try w.writeAll("accept-encoding: ");
            for (r.accept_encoding, 0..) |enabled, i| {
                if (!enabled) continue;
                const tag: http.ContentEncoding = @fromBackingInt(@intCast(i));
                if (tag == .identity) continue;
                const tag_name = @tagName(tag);
                try w.ensureUnusedCapacity(tag_name.len + 2);
                try w.writeAll(tag_name);
                try w.writeAll(", ");
            }
            w.undo(2);
            try w.writeAll("\r\n");
        }

        switch (r.transfer_encoding) {
            .chunked => try w.writeAll("transfer-encoding: chunked\r\n"),
            .content_length => |len| try w.print("content-length: {d}\r\n", .{len}),
            .none => {},
        }

        if (try emitOverridableHeader("content-type: ", r.headers.content_type, w)) {
            // The default is to omit content-type if not provided because
            // "application/octet-stream" is redundant.
        }

        for (r.extra_headers) |header| {
            assert(header.name.len != 0);

            try w.writeAll(header.name);
            try w.writeAll(": ");
            try w.writeAll(header.value);
            try w.writeAll("\r\n");
        }

        if (connection.proxied) proxy: {
            const proxy = switch (connection.protocol) {
                .plain => r.client.http_proxy,
                .tls => r.client.https_proxy,
            } orelse break :proxy;

            const authorization = proxy.authorization orelse break :proxy;
            try w.writeAll("proxy-authorization: ");
            try w.writeAll(authorization);
            try w.writeAll("\r\n");
        }

        try w.writeAll("\r\n");
    }

    pub const ReceiveHeadError = http.Reader.HeadError || ConnectError || error{
        /// Server sent headers that did not conform to the HTTP protocol.
        ///
        /// To find out more detailed diagnostics, `http.Reader.head_buffer` can be
        /// passed directly to `Request.Head.parse`.
        HttpHeadersInvalid,
        TooManyHttpRedirects,
        /// This can be avoided by calling `receiveHead` before sending the
        /// request body.
        RedirectRequiresResend,
        HttpRedirectLocationMissing,
        HttpRedirectLocationOversize,
        HttpRedirectLocationInvalid,
        HttpContentEncodingUnsupported,
        HttpChunkInvalid,
        HttpChunkTruncated,
        HttpHeadersOversize,
        UnsupportedUriScheme,

        /// Sending the request failed. Error code can be found on the
        /// `Connection` object.
        WriteFailed,
    };

    /// If handling redirects and the request has no payload, then this
    /// function will automatically follow redirects.
    ///
    /// If a request payload is present, then this function will error with
    /// `error.RedirectRequiresResend`.
    ///
    /// This function takes an auxiliary buffer to store the arbitrarily large
    /// URI which may need to be merged with the previous URI, and that data
    /// needs to survive across different connections, which is where the input
    /// buffer lives.
    ///
    /// `redirect_buffer` must outlive accesses to `Request.uri`. If this
    /// buffer capacity would be exceeded, `error.HttpRedirectLocationOversize`
    /// is returned instead. This buffer may be empty if no redirects are to be
    /// handled. RFC 9110 recommends making this at least 8000 bytes.
    ///
    /// If this fails with `error.ReadFailed` then the `Connection.getReadError`
    /// method of `r.connection` can be used to get more detailed information.
    pub fn receiveHead(r: *Request, redirect_buffer: []u8) ReceiveHeadError!Response {
        var aux_buf = redirect_buffer;
        while (true) {
            // This while loop is for handling redirects, which means the request's
            // connection may be different than the previous iteration. However, it
            // is still guaranteed to be non-null with each iteration of this loop.
            const connection = r.connection.?;

            const head_buffer = r.reader.receiveHead() catch |err| {
                // Failure here means the connection can no longer be reused.
                connection.closing = true;
                return err;
            };
            const response: Response = .{
                .request = r,
                .head = Response.Head.parse(head_buffer) catch return error.HttpHeadersInvalid,
            };
            const head = &response.head;

            if (head.status == .@"continue") {
                if (r.handle_continue) continue;
                r.response_transfer_encoding = head.transfer_encoding;
                r.response_content_length = head.content_length;
                return response; // we're not handling the 100-continue
            }

            if (r.method == .CONNECT and head.status.class() == .success) {
                // This connection is no longer doing HTTP.
                connection.closing = false;
                r.response_transfer_encoding = head.transfer_encoding;
                r.response_content_length = head.content_length;
                return response;
            }

            connection.closing = !head.keep_alive or !r.keep_alive;

            // Any response to a HEAD request and any response with a 1xx
            // (Informational), 204 (No Content), or 304 (Not Modified) status
            // code is always terminated by the first empty line after the
            // header fields, regardless of the header fields present in the
            // message.
            if (r.method == .HEAD or head.status.class() == .informational or
                head.status == .no_content or head.status == .not_modified)
            {
                r.response_transfer_encoding = head.transfer_encoding;
                r.response_content_length = head.content_length;
                return response;
            }

            if (head.status.class() == .redirect and r.redirect_behavior != .unhandled) {
                if (r.redirect_behavior == .not_allowed) {
                    // Connection can still be reused by skipping the body.
                    const reader = r.reader.bodyReader(&.{}, head.transfer_encoding, head.content_length);
                    _ = reader.discardRemaining() catch |err| switch (err) {
                        error.ReadFailed => connection.closing = true,
                    };
                    return error.TooManyHttpRedirects;
                }
                try r.redirect(head, &aux_buf);
                try r.sendBodiless();
                continue;
            }

            if (!r.accept_encoding[@backingInt(head.content_encoding)])
                return error.HttpContentEncodingUnsupported;

            r.response_transfer_encoding = head.transfer_encoding;
            r.response_content_length = head.content_length;
            return response;
        }
    }

    /// This function takes an auxiliary buffer to store the arbitrarily large
    /// URI which may need to be merged with the previous URI, and that data
    /// needs to survive across different connections, which is where the input
    /// buffer lives.
    ///
    /// `aux_buf` must outlive accesses to `Request.uri`.
    fn redirect(r: *Request, head: *const Response.Head, aux_buf: *[]u8) !void {
        const io = r.client.io;
        const new_location = head.location orelse return error.HttpRedirectLocationMissing;
        if (new_location.len > aux_buf.*.len) return error.HttpRedirectLocationOversize;
        const location = aux_buf.*[0..new_location.len];
        @memcpy(location, new_location);
        {
            // Skip the body of the redirect response to leave the connection in
            // the correct state. This causes `new_location` to be invalidated.
            const reader = r.reader.bodyReader(&.{}, head.transfer_encoding, head.content_length);
            _ = reader.discardRemaining() catch |err| switch (err) {
                error.ReadFailed => return r.reader.body_err.?,
            };
        }
        const new_uri = r.uri.resolveInPlace(location.len, aux_buf) catch |err| switch (err) {
            error.UnexpectedCharacter => return error.HttpRedirectLocationInvalid,
            error.InvalidFormat => return error.HttpRedirectLocationInvalid,
            error.InvalidPort => return error.HttpRedirectLocationInvalid,
            error.InvalidHostName => return error.HttpRedirectLocationInvalid,
            error.NoSpaceLeft => return error.HttpRedirectLocationOversize,
        };

        const protocol = Protocol.fromUri(new_uri) orelse return error.UnsupportedUriScheme;
        const old_connection = r.connection.?;
        const old_host = old_connection.host();
        var new_host_name_buffer: [HostName.max_len]u8 = undefined;
        const new_host = HostName.fromUri(new_uri, &new_host_name_buffer) catch |err| switch (err) {
            error.UriMissingHost => return error.HttpRedirectLocationInvalid,
            error.InvalidHostName => return error.HttpRedirectLocationInvalid,
            error.NameTooLong => return error.HttpRedirectLocationOversize,
        };
        const keep_privileged_headers =
            std.ascii.eqlIgnoreCase(r.uri.scheme, new_uri.scheme) and
            old_host.sameParentDomain(new_host);

        r.client.connection_pool.release(old_connection, io);
        r.connection = null;

        if (!keep_privileged_headers) {
            // When redirecting to a different domain, strip privileged headers.
            r.privileged_headers = &.{};
        }

        if (switch (head.status) {
            .see_other => true,
            .moved_permanently, .found => r.method == .POST,
            else => false,
        }) {
            // A redirect to a GET must change the method and remove the body.
            r.method = .GET;
            r.transfer_encoding = .none;
            r.headers.content_type = .omit;
        }

        if (r.transfer_encoding != .none) {
            // The request body has already been sent. The request is
            // still in a valid state, but the redirect must be handled
            // manually.
            return error.RedirectRequiresResend;
        }

        const new_connection = try r.client.connect(new_host, uriPort(new_uri, protocol), protocol);
        r.uri = new_uri;
        r.connection = new_connection;
        r.reader = .{
            .in = new_connection.reader(),
            .state = .ready,
            // Populated when `http.Reader.bodyReader` is called.
            .interface = undefined,
            .max_head_len = r.client.read_buffer_size,
        };
        r.redirect_behavior.subtractOne();
    }

    /// Returns true if the default behavior is required, otherwise handles
    /// writing (or not writing) the header.
    fn emitOverridableHeader(prefix: []const u8, v: Headers.Value, bw: *Writer) Writer.Error!bool {
        switch (v) {
            .default => return true,
            .omit => return false,
            .override => |x| {
                var vecs: [3][]const u8 = .{ prefix, x, "\r\n" };
                try bw.writeVecAll(&vecs);
                return false;
            },
        }
    }
};

pub const Proxy = struct {
    protocol: Protocol,
    host: HostName,
    authorization: ?[]const u8,
    port: u16,
    supports_connect: bool,
};

/// Release all associated resources with the client.
///
/// All pending requests must be de-initialized and all active connections released
/// before calling this function.
pub fn deinit(client: *Client) void {
    const io = client.io;
    assert(client.connection_pool.used.first == null); // There are still active requests.

    client.connection_pool.deinit(io);
    if (!disable_tls) client.ca_bundle.deinit(client.allocator);

    client.* = undefined;
}

/// Populates `http_proxy` and `https_proxy` via standard proxy environment variables.
/// Asserts the client has no active connections.
/// Uses `arena` for a few small allocations that must outlive the client, or
/// at least until those fields are set to different values.
pub fn initDefaultProxies(client: *Client, arena: Allocator, environ_map: *const std.process.Environ.Map) !void {
    const io = client.io;

    // Prevent any new connections from being created.
    try client.connection_pool.mutex.lock(io);
    defer client.connection_pool.mutex.unlock(io);

    assert(client.connection_pool.used.first == null); // There are active requests.

    if (client.http_proxy == null) {
        client.http_proxy = try createProxyFromEnvVar(arena, environ_map, &.{
            "http_proxy", "HTTP_PROXY", "all_proxy", "ALL_PROXY",
        });
    }

    if (client.https_proxy == null) {
        client.https_proxy = try createProxyFromEnvVar(arena, environ_map, &.{
            "https_proxy", "HTTPS_PROXY", "all_proxy", "ALL_PROXY",
        });
    }
}

fn createProxyFromEnvVar(
    arena: Allocator,
    environ_map: *const std.process.Environ.Map,
    env_var_names: []const []const u8,
) !?*Proxy {
    const content = for (env_var_names) |name| {
        const content = environ_map.get(name) orelse continue;
        if (content.len == 0) continue;
        break content;
    } else return null;

    const uri = Uri.parse(content) catch try Uri.parseAfterScheme("http", content);
    const protocol = Protocol.fromUri(uri) orelse return null;
    var host_buf: [HostName.max_len]u8 = undefined;
    const raw_host = try HostName.fromUri(uri, &host_buf);

    const authorization: ?[]const u8 = if (uri.user != null or uri.password != null) a: {
        const authorization = try arena.alloc(u8, basic_authorization.valueLengthFromUri(uri));
        assert(basic_authorization.value(uri, authorization).len == authorization.len);
        break :a authorization;
    } else null;

    const proxy = try arena.create(Proxy);
    proxy.* = .{
        .protocol = protocol,
        .host = .{ .bytes = try arena.dupe(u8, raw_host.bytes) },
        .authorization = authorization,
        .port = uriPort(uri, protocol),
        .supports_connect = true,
    };
    return proxy;
}

pub const basic_authorization = struct {
    pub const max_user_len = 255;
    pub const max_password_len = 255;
    pub const max_value_len = valueLength(max_user_len, max_password_len);

    pub fn valueLength(user_len: usize, password_len: usize) usize {
        return "Basic ".len + std.base64.standard.Encoder.calcSize(user_len + 1 + password_len);
    }

    pub fn valueLengthFromUri(uri: Uri) usize {
        const user: Uri.Component = uri.user orelse .empty;
        const password: Uri.Component = uri.password orelse .empty;

        var dw: Writer.Discarding = .init(&.{});
        user.formatUser(&dw.writer) catch unreachable; // discarding
        const user_len = dw.count + dw.writer.end;

        dw.count = 0;
        dw.writer.end = 0;
        password.formatPassword(&dw.writer) catch unreachable; // discarding
        const password_len = dw.count + dw.writer.end;

        return valueLength(@intCast(user_len), @intCast(password_len));
    }

    pub fn value(uri: Uri, out: []u8) []u8 {
        var bw: Writer = .fixed(out);
        write(uri, &bw) catch unreachable;
        return bw.buffered();
    }

    pub fn write(uri: Uri, out: *Writer) Writer.Error!void {
        var buf: [max_user_len + 1 + max_password_len]u8 = undefined;
        var w: Writer = .fixed(&buf);
        const user: Uri.Component = uri.user orelse .empty;
        const password: Uri.Component = uri.password orelse .empty;
        user.formatUser(&w) catch unreachable;
        w.writeByte(':') catch unreachable;
        password.formatPassword(&w) catch unreachable;
        try out.print("Basic {b64}", .{w.buffered()});
    }
};

pub const ConnectTcpError = error{
    TlsInitializationFailed,
} || Allocator.Error || HostName.ConnectError || Io.Cancelable;

/// Reuses a `Connection` if one matching `host` and `port` is already open.
///
/// Threadsafe.
pub fn connectTcp(
    client: *Client,
    host: HostName,
    port: u16,
    protocol: Protocol,
) ConnectTcpError!*Connection {
    return connectTcpOptions(client, .{ .host = host, .port = port, .protocol = protocol });
}

pub const ConnectTcpOptions = struct {
    host: HostName,
    port: u16,
    protocol: Protocol,

    proxied_host: ?HostName = null,
    proxied_port: ?u16 = null,
    timeout: Io.Timeout = .none,
};

pub fn connectTcpOptions(client: *Client, options: ConnectTcpOptions) ConnectTcpError!*Connection {
    const io = client.io;
    const host = options.host;
    const port = options.port;
    const protocol = options.protocol;

    const proxied_host = options.proxied_host orelse host;
    const proxied_port = options.proxied_port orelse port;

    if (try client.connection_pool.findConnection(io, .{
        .host = proxied_host,
        .port = proxied_port,
        .protocol = protocol,
    })) |conn| return conn;

    var stream = try host.connect(io, port, .{ .mode = .stream });
    errdefer stream.close(io);

    switch (protocol) {
        .tls => {
            if (disable_tls) return error.TlsInitializationFailed;
            const tc = Connection.Tls.create(client, proxied_host, proxied_port, stream) catch |err| switch (err) {
                error.OutOfMemory => |e| return e,
                error.Unexpected => |e| return e,
                error.Canceled => |e| return e,
                else => return error.TlsInitializationFailed,
            };
            errdefer tc.destroy();
            try client.connection_pool.addUsed(io, &tc.connection);
            return &tc.connection;
        },
        .plain => {
            const pc = try Connection.Plain.create(client, proxied_host, proxied_port, stream);
            errdefer pc.destroy();
            try client.connection_pool.addUsed(io, &pc.connection);
            return &pc.connection;
        },
    }
}

pub const ConnectUnixError = Allocator.Error || std.posix.SocketError || error{NameTooLong} || std.posix.ConnectError || Io.Cancelable;

/// Connect to `path` as a unix domain socket. This will reuse a connection if one is already open.
///
/// This function is threadsafe.
pub fn connectUnix(client: *Client, path: []const u8) ConnectUnixError!*Connection {
    const io = client.io;

    if (try client.connection_pool.findConnection(io, .{
        .host = path,
        .port = 0,
        .protocol = .plain,
    })) |node|
        return node;

    const conn = try client.allocator.create(ConnectionPool.Node);
    errdefer client.allocator.destroy(conn);
    conn.* = .{ .data = undefined };

    const stream = try Io.net.connectUnixSocket(path);
    errdefer stream.close(io);

    conn.data = .{
        .stream = stream,
        .tls_client = undefined,
        .protocol = .plain,

        .host = try client.allocator.dupe(u8, path),
        .port = 0,
    };
    errdefer client.allocator.free(conn.data.host);

    try client.connection_pool.addUsed(conn);

    return &conn.data;
}

/// Connect to `proxied_host:proxied_port` using the specified proxy with HTTP
/// CONNECT. This will reuse a connection if one is already open.
///
/// This function is threadsafe.
pub fn connectProxied(
    client: *Client,
    proxy: *Proxy,
    proxied_host: HostName,
    proxied_port: u16,
) !*Connection {
    const io = client.io;
    if (!proxy.supports_connect) return error.TunnelNotSupported;

    if (try client.connection_pool.findConnection(io, .{
        .host = proxied_host,
        .port = proxied_port,
        .protocol = proxy.protocol,
    })) |node| return node;

    var maybe_valid = false;
    (tunnel: {
        const connection = try client.connectTcpOptions(.{
            .host = proxy.host,
            .port = proxy.port,
            .protocol = proxy.protocol,
            .proxied_host = proxied_host,
            .proxied_port = proxied_port,
        });
        errdefer {
            connection.closing = true;
            client.connection_pool.release(connection, io);
        }

        var req = client.request(.CONNECT, .{
            .scheme = "http",
            .host = .{ .raw = proxied_host.bytes },
            .port = proxied_port,
        }, .{
            .redirect_behavior = .unhandled,
            .connection = connection,
        }) catch |err| {
            break :tunnel err;
        };
        defer req.deinit();

        req.sendBodiless() catch |err| break :tunnel err;
        const response = req.receiveHead(&.{}) catch |err| break :tunnel err;

        if (response.head.status.class() == .server_error) {
            maybe_valid = true;
            break :tunnel error.ServerError;
        }

        if (response.head.status != .ok) break :tunnel error.ConnectionRefused;

        // this connection is now a tunnel, so we can't use it for anything
        // else, it will only be released when the client is de-initialized.
        req.connection = null;

        connection.closing = false;

        return connection;
    }) catch {
        // something went wrong with the tunnel
        proxy.supports_connect = maybe_valid;
        return error.TunnelNotSupported;
    };
}

pub const ConnectError = ConnectTcpError || RequestError;

/// Connect to `host:port` using the specified protocol. This will reuse a
/// connection if one is already open.
///
/// If a proxy is configured for the client, then the proxy will be used to
/// connect to the host.
///
/// This function is threadsafe.
pub fn connect(
    client: *Client,
    host: HostName,
    port: u16,
    protocol: Protocol,
) ConnectError!*Connection {
    const proxy = switch (protocol) {
        .plain => client.http_proxy,
        .tls => client.https_proxy,
    } orelse return client.connectTcp(host, port, protocol);

    // Prevent proxying through itself.
    if (proxy.host.eql(host) and proxy.port == port and proxy.protocol == protocol) {
        return client.connectTcp(host, port, protocol);
    }

    if (proxy.supports_connect) tunnel: {
        return connectProxied(client, proxy, host, port) catch |err| switch (err) {
            error.TunnelNotSupported => break :tunnel,
            else => |e| return e,
        };
    }

    // fall back to using the proxy as a normal http proxy
    const connection = try client.connectTcp(proxy.host, proxy.port, proxy.protocol);
    connection.proxied = true;
    return connection;
}

pub const RequestError = ConnectTcpError || error{
    UnsupportedUriScheme,
    UriMissingHost,
    InvalidHostName,
    CertificateBundleLoadFailure,
};

pub const RequestOptions = struct {
    version: http.Version = .@"HTTP/1.1",

    /// Automatically ignore 100 Continue responses. This assumes you don't
    /// care, and will have sent the body before you wait for the response.
    ///
    /// If this is not the case AND you know the server will send a 100
    /// Continue, set this to false and wait for a response before sending the
    /// body. If you wait AND the server does not send a 100 Continue before
    /// you finish the request, then the request *will* deadlock.
    handle_continue: bool = true,

    /// If false, close the connection after the one request. If true,
    /// participate in the client connection pool.
    keep_alive: bool = true,

    /// This field specifies whether to automatically follow redirects, and if
    /// so, how many redirects to follow before returning an error.
    ///
    /// This will only follow redirects for repeatable requests (ie. with no
    /// payload or the server has acknowledged the payload).
    redirect_behavior: Request.RedirectBehavior = @fromBackingInt(@intCast(3)),

    /// Must be an already acquired connection.
    connection: ?*Connection = null,

    /// Standard headers that have default, but overridable, behavior.
    headers: Request.Headers = .{},
    /// These headers are kept including when following a redirect to a
    /// different domain.
    /// Externally-owned; must outlive the Request.
    extra_headers: []const http.Header = &.{},
    /// These headers are stripped when following a redirect to a different
    /// domain.
    /// Externally-owned; must outlive the Request.
    privileged_headers: []const http.Header = &.{},
};

fn uriPort(uri: Uri, protocol: Protocol) u16 {
    return uri.port orelse protocol.port();
}

/// Open a connection to the host specified by `uri` and prepare to send a HTTP request.
///
/// The caller is responsible for calling `deinit()` on the `Request`.
/// This function is threadsafe.
///
/// Asserts that "\r\n" does not occur in any header name or value.
pub fn request(
    client: *Client,
    method: http.Method,
    uri: Uri,
    options: RequestOptions,
) RequestError!Request {
    const io = client.io;

    if (std.debug.runtime_safety) {
        for (options.extra_headers) |header| {
            assert(header.name.len != 0);
            assert(std.mem.findScalar(u8, header.name, ':') == null);
            assert(std.mem.findPosLinear(u8, header.name, 0, "\r\n") == null);
            assert(std.mem.findPosLinear(u8, header.value, 0, "\r\n") == null);
        }
        for (options.privileged_headers) |header| {
            assert(header.name.len != 0);
            assert(std.mem.findPosLinear(u8, header.name, 0, "\r\n") == null);
            assert(std.mem.findPosLinear(u8, header.value, 0, "\r\n") == null);
        }
    }

    const protocol = Protocol.fromUri(uri) orelse return error.UnsupportedUriScheme;

    if (protocol == .tls) tls: {
        if (disable_tls) unreachable;
        {
            try client.ca_bundle_lock.lockShared(io);
            defer client.ca_bundle_lock.unlockShared(io);
            if (client.now != null) break :tls;
        }
        var bundle: std.crypto.Certificate.Bundle = .empty;
        defer bundle.deinit(client.allocator);
        const now = Io.Clock.real.now(io);
        bundle.rescan(client.allocator, io, now) catch |err| switch (err) {
            error.Canceled => |e| return e,
            else => return error.CertificateBundleLoadFailure,
        };
        try client.ca_bundle_lock.lock(io);
        defer client.ca_bundle_lock.unlock(io);
        client.now = now;
        std.mem.swap(std.crypto.Certificate.Bundle, &client.ca_bundle, &bundle);
    }

    const connection = options.connection orelse c: {
        var host_name_buffer: [HostName.max_len]u8 = undefined;
        const host_name = HostName.fromUri(uri, &host_name_buffer) catch |err| switch (err) {
            error.UriMissingHost => |e| return e,
            error.NameTooLong, error.InvalidHostName => return error.InvalidHostName,
        };
        break :c try client.connect(host_name, uriPort(uri, protocol), protocol);
    };

    return .{
        .uri = uri,
        .client = client,
        .connection = connection,
        .reader = .{
            .in = connection.reader(),
            .state = .ready,
            // Populated when `http.Reader.bodyReader` is called.
            .interface = undefined,
            .max_head_len = client.read_buffer_size,
        },
        .keep_alive = options.keep_alive,
        .method = method,
        .version = options.version,
        .transfer_encoding = .none,
        .redirect_behavior = options.redirect_behavior,
        .handle_continue = options.handle_continue,
        .headers = options.headers,
        .extra_headers = options.extra_headers,
        .privileged_headers = options.privileged_headers,
    };
}

pub const FetchOptions = struct {
    /// `null` means it will be heap-allocated. RFC 9110 recommends at least
    /// 8000 bytes.
    redirect_buffer: ?[]u8 = null,
    /// `null` means it will be heap-allocated.
    decompress_buffer: ?[]u8 = null,
    redirect_behavior: ?Request.RedirectBehavior = null,
    /// If the server sends a body, it will be written here.
    response_writer: ?*Writer = null,

    location: Location,
    method: ?http.Method = null,
    payload: ?[]const u8 = null,
    raw_uri: bool = false,
    keep_alive: bool = true,

    /// Standard headers that have default, but overridable, behavior.
    headers: Request.Headers = .{},
    /// These headers are kept including when following a redirect to a
    /// different domain.
    /// Externally-owned; must outlive the Request.
    extra_headers: []const http.Header = &.{},
    /// These headers are stripped when following a redirect to a different
    /// domain.
    /// Externally-owned; must outlive the Request.
    privileged_headers: []const http.Header = &.{},

    pub const Location = union(enum) {
        url: []const u8,
        uri: Uri,
    };
};

pub const FetchResult = struct {
    status: http.Status,
};

pub const FetchError = Uri.ParseError || RequestError || Request.ReceiveHeadError || error{
    StreamTooLong,
    /// TODO provide optional diagnostics when this occurs or break into more error codes
    WriteFailed,
    UnsupportedCompressionMethod,
};

/// Perform a one-shot HTTP request with the provided options.
///
/// This function is threadsafe.
pub fn fetch(client: *Client, options: FetchOptions) FetchError!FetchResult {
    const uri = switch (options.location) {
        .url => |u| try Uri.parse(u),
        .uri => |u| u,
    };
    const method: http.Method = options.method orelse
        if (options.payload != null) .POST else .GET;

    const redirect_behavior: Request.RedirectBehavior = options.redirect_behavior orelse
        if (options.payload == null) @fromBackingInt(@intCast(3)) else .unhandled;

    var req = try request(client, method, uri, .{
        .redirect_behavior = redirect_behavior,
        .headers = options.headers,
        .extra_headers = options.extra_headers,
        .privileged_headers = options.privileged_headers,
        .keep_alive = options.keep_alive,
    });
    defer req.deinit();

    if (options.payload) |payload| {
        req.transfer_encoding = .{ .content_length = payload.len };
        var body = try req.sendBodyUnflushed(&.{});
        try body.writer.writeAll(payload);
        try body.end();
        try req.connection.?.flush();
    } else {
        try req.sendBodiless();
    }

    const redirect_buffer: []u8 = if (redirect_behavior == .unhandled) &.{} else options.redirect_buffer orelse
        try client.allocator.alloc(u8, 8 * 1024);
    defer if (options.redirect_buffer == null) client.allocator.free(redirect_buffer);

    var response = try req.receiveHead(redirect_buffer);

    const response_writer = options.response_writer orelse {
        const reader = response.reader(&.{});
        _ = reader.discardRemaining() catch |err| switch (err) {
            error.ReadFailed => return response.bodyErr().?,
        };
        return .{ .status = response.head.status };
    };

    const decompress_buffer: []u8 = switch (response.head.content_encoding) {
        .identity => &.{},
        .zstd => options.decompress_buffer orelse try client.allocator.alloc(u8, std.compress.zstd.default_window_len),
        .deflate, .gzip => options.decompress_buffer orelse try client.allocator.alloc(u8, std.compress.flate.max_window_len),
        .compress => return error.UnsupportedCompressionMethod,
    };
    defer if (options.decompress_buffer == null) client.allocator.free(decompress_buffer);

    var transfer_buffer: [64]u8 = undefined;
    var decompress: http.Decompress = undefined;
    const reader = response.readerDecompressing(&transfer_buffer, &decompress, decompress_buffer);

    _ = reader.streamRemaining(response_writer) catch |err| switch (err) {
        error.ReadFailed => return response.bodyErr().?,
        else => |e| return e,
    };

    return .{ .status = response.head.status };
}

test {
    _ = Response;
}