Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Reaching a server through an HTTP proxy.//!//! A proxy is used one of two ways, and which one is decided by what is being//! fetched rather than by the proxy://!//! * **Forwarding**, for an `http` URL. The request goes to the proxy with its//! target in absolute form -- `GET http://example.com/a HTTP/1.1`, §3.2.2 of//! RFC 9112 -- and the proxy makes the request itself and relays the answer.//! Nothing here is needed for that beyond the connection to the proxy and a//! `Proxy-Authorization` field: `http1.client` already sends whatever target//! it is given.//! * **Tunnelling**, for an `https` URL, and for anything a caller would rather//! the proxy not read. `CONNECT example.com:443` asks the proxy for a byte//! stream to that authority (§9.3.6 of RFC 9110), and a `2xx` answer means//! everything after it on the connection is that stream. `tunnel` does the//! asking and hands the connection back carrying it, and `tls.connectOver`//! puts TLS on top -- so the certificate checked is the origin's, the proxy//! sees only ciphertext, and ALPN inside the tunnel chooses HTTP/2 exactly as//! it would on a direct connection.//!//! The connection to the proxy is itself either plain or TLS, which is what an//! `https://` proxy URL means, and it is independent of both: an `https` URL//! through an `https://` proxy is TLS inside TLS.//!//! A caller holding the drivers rather than `Client` puts the pieces together//! the same way `Client` does://!//! ```zig//! const to_proxy = try http_io.tcp.connect(io, gpa, proxy_address, .{//! // A TLS handshake is about to run through these buffers.//! .read_buffer_len = http_io.tls.min_read_buffer_len,//! });//! const tunnelled = try http_io.proxy.tunnel(io, gpa, to_proxy, "example.com:443", null);//! const conn = try http_io.tls.connectOver(io, gpa, tunnelled, .{//! .host = "example.com",//! .root_ca = trust,//! .alpn_protocols = &.{"h2"},//! .rng = rng,//! });//! var h2 = try http.http2.client.Connection.init(io, gpa, conn, .{});//! ```
const std = @import("std");const Io = std.Io;const Allocator = std.mem.Allocator;
const http = @import("http");const uri = @import("uri");
const transport = http.transport;const Method = http.protocol.Method;const Request = http.client.Request;
/// Where a proxy is and how to talk to it.pub const Proxy = struct { /// Whether the connection to the proxy is TLS: an `https://` proxy URL. secure: bool = false, /// A name, or an address literal -- an IPv6 one without its brackets. host: []const u8, port: u16, /// The whole `Proxy-Authorization` value, scheme and all, sent to the /// proxy and never further. `parse` builds a `Basic` one out of userinfo. authorization: ?[]const u8 = null,
pub const ParseError = uri.parse.Error || error{ /// Neither `http` nor `https`, which are the only schemes that say how /// to talk to an HTTP proxy. UnsupportedProxyScheme, /// No host to connect to. ProxyMissingHost, };
/// A proxy from the form an environment variable or a command line gives /// it: `http://user:secret@proxy.example:3128`. /// /// A value with no scheme at all -- `proxy.example:3128`, which is how a /// good many environments spell it -- is taken as `http`, which is what /// curl and `std.http.Client` both do. The port defaults to the scheme's, /// and userinfo becomes a `Basic` credential (RFC 7617): the user, a colon /// and the password, base64-encoded, after the percent-encoding the URL /// needed has been undone. /// /// Everything returned is allocated in `arena`. pub fn parse(arena: Allocator, text: []const u8) ParseError!Proxy { const with_scheme = if (std.mem.find(u8, text, "://") == null) try std.mem.concat(arena, u8, &.{ "http://", text }) else text; const u = try uri.Uri.parse(arena, with_scheme); // The `Uri` lives in the arena, so nothing it points at has to be // copied out of it before it is dropped. const scheme = u.scheme orelse return error.UnsupportedProxyScheme; const secure = if (std.ascii.eqlIgnoreCase(scheme, "https")) true else if (std.ascii.eqlIgnoreCase(scheme, "http")) false else return error.UnsupportedProxyScheme; const host = u.host orelse return error.ProxyMissingHost; if (host.text().len == 0) return error.ProxyMissingHost;
const authorization: ?[]const u8 = if (u.username != null or u.password != null) blk: { const credentials = try std.mem.concat(arena, u8, &.{ u.username orelse "", ":", u.password orelse "", }); const encoder = std.base64.standard.Encoder; const value = try arena.alloc(u8, "Basic ".len + encoder.calcSize(credentials.len)); @memcpy(value[0.."Basic ".len], "Basic "); _ = encoder.encode(value["Basic ".len..], credentials); break :blk value; } else null;
return .{ .secure = secure, .host = host.text(), .port = u.port orelse if (secure) http.default_tls_port else http.default_port, .authorization = authorization, }; }
test parse { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator();
const plain = try Proxy.parse(arena, "http://proxy.example:3128"); try testing.expect(!plain.secure); try testing.expectEqualStrings("proxy.example", plain.host); try testing.expectEqual(@as(u16, 3128), plain.port); try testing.expectEqual(@as(?[]const u8, null), plain.authorization);
// No scheme is `http`, and no port is the scheme's. const bare = try Proxy.parse(arena, "proxy.example"); try testing.expect(!bare.secure); try testing.expectEqual(@as(u16, 80), bare.port);
const secure = try Proxy.parse(arena, "https://[2001:db8::1]"); try testing.expect(secure.secure); try testing.expectEqualStrings("2001:db8::1", secure.host); try testing.expectEqual(@as(u16, 443), secure.port);
// RFC 7617 §2's own example, with the space in the password percent- // encoded the way a URL has to carry it. const credentialed = try Proxy.parse(arena, "http://Aladdin:open%20sesame@proxy.example:8080"); try testing.expectEqualStrings("Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==", credentialed.authorization.?);
try testing.expectError(error.UnsupportedProxyScheme, Proxy.parse(arena, "socks5://proxy.example:1080")); }};
/// Whether `host` is one a `no_proxy` list says to reach directly.////// There is no standard for the list, only convention, and this follows/// curl's reading of it, which is the most widely copied: entries are compared/// without case; an entry matches the host itself and every name under it, so/// `example.com` and `.example.com` both cover `www.example.com`; an address/// literal matches only itself; and `*` alone matches everything. Ports are/// not considered, and neither are CIDR ranges.pub fn bypasses(no_proxy: []const []const u8, host: []const u8) bool { for (no_proxy) |raw| { const entry = std.mem.trim(u8, raw, " \t"); if (entry.len == 0) continue; if (std.mem.eql(u8, entry, "*")) return true; const bare = std.mem.trimStart(u8, entry, "."); if (std.ascii.eqlIgnoreCase(host, bare)) return true; if (host.len > bare.len and host[host.len - bare.len - 1] == '.' and std.ascii.endsWithIgnoreCase(host, bare)) { return true; } } return false;}
test bypasses { const list: []const []const u8 = &.{ "example.com", ".internal", "10.0.0.1", " localhost " }; try testing.expect(bypasses(list, "example.com")); try testing.expect(bypasses(list, "WWW.Example.com")); try testing.expect(bypasses(list, "db.internal")); try testing.expect(bypasses(list, "internal")); try testing.expect(bypasses(list, "10.0.0.1")); try testing.expect(bypasses(list, "localhost")); // A suffix that is not at a label boundary is another name. try testing.expect(!bypasses(list, "notexample.com")); try testing.expect(!bypasses(list, "10.0.0.10")); try testing.expect(!bypasses(list, "example.org"));
try testing.expect(bypasses(&.{"*"}, "anything.at.all")); try testing.expect(!bypasses(&.{}, "example.com"));}
/// Splits a `no_proxy` value -- comma-separated, as the environment gives it/// -- into the entries `bypasses` takes. The slices borrow `text`.pub fn splitNoProxy(arena: Allocator, text: []const u8) Allocator.Error![]const []const u8 { var entries: std.ArrayList([]const u8) = .empty; var it = std.mem.tokenizeScalar(u8, text, ','); while (it.next()) |entry| { const trimmed = std.mem.trim(u8, entry, " \t"); if (trimmed.len > 0) try entries.append(arena, trimmed); } return entries.toOwnedSlice(arena);}
test splitNoProxy { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); // Blanks around an entry are dropped, and so are empty entries. const split = try splitNoProxy(arena_state.allocator(), " a.example, ,b.example,"); try testing.expectEqual(@as(usize, 2), split.len); try testing.expectEqualStrings("a.example", split[0]); try testing.expectEqualStrings("b.example", split[1]); try testing.expect(bypasses(split, "www.b.example"));}
pub const TunnelError = http.http1.client.Error || error{ /// The proxy answered `407`: it wants a credential, or did not accept the /// one it was given. ProxyAuthenticationRequired, /// The proxy answered something other than `2xx` or `407` -- it will not /// reach that authority, or could not. ProxyRefused,};
/// Asks the proxy at the other end of `conn` for a tunnel to `authority`, and/// hands the same connection back carrying it.////// `authority` is `host:port` -- §3.2.3 of RFC 9112's authority-form, the only/// target `CONNECT` takes, with an IPv6 literal in brackets. `authorization`/// is a `Proxy-Authorization` value, as `Proxy.authorization` holds one.////// Takes ownership of `conn`: it is closed on any failure, and on success the/// connection returned is the same one and closing it closes the tunnel.pub fn tunnel( io: Io, gpa: Allocator, conn: transport.Connection, authority: []const u8, authorization: ?[]const u8,) TunnelError!transport.Connection { var h1 = http.http1.client.Connection.init(io, gpa, conn, .{}) catch |err| { var owned = conn; owned.close(io, gpa); return err; }; defer h1.deinit();
var request: Request = .{ .method = Method.connect, .target = authority, // §9.3.6 of RFC 9110 and §3.2.3 of RFC 9112: the `Host` of a // `CONNECT` is the authority it is asking for. .host = authority, }; defer request.deinit(gpa); if (authorization) |value| { request.setHeader(gpa, "Proxy-Authorization", value) catch |err| return switch (err) { error.OutOfMemory => error.OutOfMemory, error.ReservedField, error.InvalidField => error.InvalidRequest, }; }
const res = try h1.send(request); switch (res.status) { // §9.3.6: "Any 2xx (Successful) response indicates that the sender // (and all inbound proxies) will switch to tunnel mode immediately // after the response header section". There is no body to read, and // the driver knows it -- `protocol.responseFraming` says `none` for a // 2xx to a `CONNECT` -- so whatever the proxy's read buffer holds past // the head is already the tunnel's. 200...299 => return h1.release(), 407 => return error.ProxyAuthenticationRequired, else => return error.ProxyRefused, }}
test tunnel { // The proxy's whole half of the exchange, scripted: a `200` and then the // first octets of the tunnel in the same read, which is what a proxy that // forwards eagerly produces and what must not be lost with the head. var out: [512]u8 = undefined; var output: Io.Writer = .fixed(&out); var input: Io.Reader = .fixed("HTTP/1.1 200 Connection established\r\n\r\ntunnelled"); const conn: transport.Connection = .borrowed(&input, &output, .{ .peer = null, .local = null, .secure = false, .alpn = null, });
var through = try tunnel(testing.io, testing.allocator, conn, "example.com:443", "Basic eDp5"); defer through.close(testing.io, testing.allocator);
try testing.expectEqualStrings( "CONNECT example.com:443 HTTP/1.1\r\n" ++ "Host: example.com:443\r\n" ++ "Proxy-Authorization: Basic eDp5\r\n" ++ "\r\n", output.buffered(), ); var rest: [16]u8 = undefined; const n = try through.input.readSliceShort(&rest); try testing.expectEqualStrings("tunnelled", rest[0..n]);}
/// `host:port` for a `CONNECT` target or a `Host` field, with an IPv6 literal/// in brackets, which §3.2.2 of RFC 3986 requires of one in an authority.pub fn formatAuthority(buffer: []u8, host: []const u8, port: u16) error{NoSpaceLeft}![]const u8 { const ipv6 = std.mem.findScalar(u8, host, ':') != null; return if (ipv6) std.fmt.bufPrint(buffer, "[{s}]:{d}", .{ host, port }) else std.fmt.bufPrint(buffer, "{s}:{d}", .{ host, port });}
test formatAuthority { var buffer: [64]u8 = undefined; try testing.expectEqualStrings("example.com:443", try formatAuthority(&buffer, "example.com", 443)); try testing.expectEqualStrings("[2001:db8::1]:8443", try formatAuthority(&buffer, "2001:db8::1", 8443));}
const testing = std.testing;
test { // So that `Proxy`'s example is compiled: a nested type's tests are // reached only when something refers to the type itself. testing.refAllDecls(@This());}
test "a proxy that will not tunnel says why" { var out: [512]u8 = undefined; var output: Io.Writer = .fixed(&out); var input: Io.Reader = .fixed("HTTP/1.1 407 Proxy Authentication Required\r\nContent-Length: 0\r\n\r\n"); const conn: transport.Connection = .borrowed(&input, &output, .{ .peer = null, .local = null, .secure = false, .alpn = null, }); try testing.expectError( error.ProxyAuthenticationRequired, tunnel(testing.io, testing.allocator, conn, "example.com:443", null), );
var denied_input: Io.Reader = .fixed("HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\n\r\n"); output = .fixed(&out); const denied: transport.Connection = .borrowed(&denied_input, &output, .{ .peer = null, .local = null, .secure = false, .alpn = null, }); try testing.expectError( error.ProxyRefused, tunnel(testing.io, testing.allocator, denied, "example.com:443", null), );}
test "RFC 9110 15.2: a proxy's interim response comes before its answer, and is not it" { // A proxy may say `100 Continue` or anything else in the 1xx class before // it says whether it will tunnel. Taking the first head for the answer // made that a refusal. var out: [512]u8 = undefined; var output: Io.Writer = .fixed(&out); var input: Io.Reader = .fixed( "HTTP/1.1 100 Continue\r\n\r\nHTTP/1.1 200 Connection established\r\n\r\ntunnelled", ); const conn: transport.Connection = .borrowed(&input, &output, .{ .peer = null, .local = null, .secure = false, .alpn = null, }); var through = try tunnel(testing.io, testing.allocator, conn, "example.com:443", null); defer through.close(testing.io, testing.allocator); var rest: [16]u8 = undefined; const n = try through.input.readSliceShort(&rest); try testing.expectEqualStrings("tunnelled", rest[0..n]);
// And a `101` is not a 2xx. §9.3.6: "Any 2xx (Successful) response // indicates that the sender... will switch to tunnel mode", and nothing // else does. var switching_input: Io.Reader = .fixed("HTTP/1.1 101 Switching Protocols\r\nUpgrade: x\r\n\r\n"); output = .fixed(&out); const switching: transport.Connection = .borrowed(&switching_input, &output, .{ .peer = null, .local = null, .secure = false, .alpn = null, }); try testing.expectError( error.ProxyRefused, tunnel(testing.io, testing.allocator, switching, "example.com:443", null), );}