// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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), ); }