// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! A client that takes a URL and works out the rest. //! //! `http1.client` and `http2.client` are drivers: each is handed a //! `transport.Connection` and speaks one version down it, and deciding which //! version, and dialling the connection, is left to whoever holds them. This //! is that whoever. It is shaped like `std.http.Client.fetch` on purpose -- //! a location, a method, an optional payload, a writer for the body, and a //! status back -- so that a caller who knows one knows the other. //! //! ```zig //! var client: http_io.Client = .{ .io = io, .gpa = gpa }; //! defer client.deinit(); //! //! var body: std.Io.Writer.Allocating = .init(gpa); //! defer body.deinit(); //! var result = try client.fetch(.{ //! .location = .{ .url = "https://example.com/" }, //! .response_writer = &body.writer, //! }); //! defer result.deinit(); //! // result.status, result.version, result.headers.get("content-type"), //! // body.written() //! ``` //! //! ## What it negotiates //! //! **The version, by ALPN.** An `https` URL is dialled offering `h2` ahead of //! `http/1.1`, and whichever the server selects is the driver that speaks. //! §3.2 of RFC 9113 makes ALPN the only way HTTP/2 over TLS is ever agreed. //! §3.1 of RFC 7301 says a server "MAY" answer the offer, so a handshake that //! selects nothing is a server that does not do ALPN at all -- and an `https` //! server that does not negotiate is speaking what an `https` URL meant before //! there was anything to negotiate, which is HTTP/1.1. An `http` URL has no //! handshake to negotiate in, and §3.1 of RFC 9113 deprecated the `Upgrade` //! that used to stand in for one, so cleartext is HTTP/1.1 unless the caller //! says the server speaks HTTP/2 -- `http2_prior_knowledge`, which is §3.3's //! "prior knowledge" and the only way left. //! //! **The address, from the name.** A host name is resolved through //! `std.Io.net.HostName.lookup`, or through whatever `Client.resolver` names //! in its place, and each address is tried in the order the resolver gave, until one //! answers -- see `tcp.connectAny`. An address literal is dialled as it is. //! //! **Redirects**, as `std.http.Client` does them: up to three for a request //! without a payload, and none for one with, since resending a body to //! wherever a server points is a decision for the caller. `Location` is //! resolved against the URL that was fetched, by RFC 3986 §5's algorithm, //! which is zig-uri's `Uri.click`. //! //! ## What it does not do //! //! **No connection is kept.** Every `fetch` dials, sends, reads and closes, //! so a redirect to the same origin opens a second connection, and HTTP/2's //! multiplexing is not used across calls. A caller that wants several //! requests on one connection uses the drivers directly, which is what they //! are for. //! //! **HTTP/3 when asked, or when advertised.** `http3 = .only` or `.prefer` //! fetches an `https` URL over QUIC, the second falling back to TCP when no //! handshake completes; `.advertised` uses it where the origin has said so //! with `Alt-Svc` (RFC 7838), which is remembered in an `AltSvc` cache that //! several clients may share. //! //! **No Unicode host names**: `HostName` holds letters, digits //! and hyphens, so an internationalised name has to arrive in its `xn--` //! form. zig-uri's `Uri.toUri` produces that when it is built with Unicode //! support. //! //! **Not thread-safe**, unlike `std.http.Client`: two tasks fetching at once //! want a `Client` each. It holds a random number generator and a lazily //! loaded certificate bundle, and nothing else, so one is cheap. const std = @import("std"); const Io = std.Io; const net = Io.net; const Allocator = std.mem.Allocator; const http = @import("http"); const uri = @import("uri"); const tcp = @import("tcp.zig"); const tls = @import("tls.zig"); const proxy = @import("proxy.zig"); const http3_io = @import("http3.zig"); const AltSvc = @import("AltSvc.zig"); const protocol = http.protocol; const transport = http.transport; const coding = protocol.coding; const Field = protocol.Field; const Headers = protocol.Headers; const Method = protocol.Method; const Version = protocol.Version; const Request = http.client.Request; const Client = @This(); io: Io, gpa: Allocator, /// What a server's certificate chain is checked against. Borrowed, and never /// freed here. /// /// Null means the system's store, which is loaded the first time an `https` /// URL is fetched and kept for the client's life. That is the opposite /// default from `tls.ClientOptions.root_ca`, which trusts nothing until told, /// and deliberately so: that is a dialler, handed an address by a caller who /// has already decided what it is talking to, and this is the thing a caller /// reaches for when it has a URL and wants what is at the other end of it -- /// which is exactly the case the system store exists for. root_ca: ?tls.CertBundle = null, /// For a test, and named so that it cannot be set by accident. insecure_skip_verify: bool = false, /// Whether to offer `h2` over TLS. Off, only `http/1.1` is offered. http2: bool = true, /// Whether an `https` URL is fetched over HTTP/3. /// /// TCP has ALPN to choose a version inside the one handshake; QUIC is a /// different transport on a different protocol, so trying it is a decision /// made before anything is sent, and this is where it is made. See `Http3`. /// /// Never for an `http` URL -- §3.1 of RFC 9114 gives HTTP/3 no cleartext /// form -- and never through a proxy, since reaching one over HTTP/3 would be /// RFC 9298's CONNECT-UDP, which is not implemented. Both of those are /// fetched over TCP whatever this says. http3: Http3 = .off, /// How long a QUIC handshake to one address may take before it is given up /// on: the next address is tried, and after the last, `.prefer` falls back to /// TCP. Shorter than a TCP connect is allowed to take, because the usual /// reason for no answer is UDP blocked somewhere on the way, which is silence /// rather than a refusal and costs this whole wait. http3_handshake_timeout: Io.Duration = .fromSeconds(3), /// Passed to the HTTP/3 driver, apart from `accept_encodings`. Its /// `max_body_len` bounds a response over HTTP/3, which is gathered whole. http3_config: http.http3.client.Config = .{}, /// Whether an `http` URL is spoken to in HTTP/2 from the first octet. /// /// §3.3 of RFC 9113: a client that knows a server speaks HTTP/2 may start /// with the preface, and one that does not know must not -- an HTTP/1.1 /// server reads `PRI * HTTP/2.0` as a request for a method it has never heard /// of. Nothing about a URL says which a server is, so this is the caller /// saying it. http2_prior_knowledge: bool = false, /// Whether a redirect from an `https` URL to an `http` one is refused with /// `error.InsecureRedirect` rather than followed. /// /// Off by default, which is what browsers, curl and `std.http.Client` all do. /// On, it is the difference between a request that was made over TLS and one /// that merely started that way: whatever follows a downgrade -- the next /// request, its target, its cookies if a caller sends them, and the answer /// -- crosses the network in cleartext, where anybody on the path can read /// it and anybody on the path can have caused it. §4.2.2 of RFC 9110 makes /// `https` a promise that the exchange is secured, and a server's redirect /// is not the caller's consent to have that promise withdrawn. /// /// Refused before anything is sent to the `http` URL, so nothing leaks. refuse_insecure_redirects: bool = false, /// How long a `fetch` may take, all of it: the name lookup, the connection, /// the TLS handshake, every redirect and the whole body. `.none` waits for as /// long as the server does. `std.Io.Timeout`, so a duration or a deadline: /// /// ```zig /// .timeout = .{ .duration = .{ .raw = .fromSeconds(30), .clock = .awake } }, /// ``` /// /// One budget for the whole exchange rather than one per read, because that /// is the only kind a caller can plan around -- a server trickling a byte a /// second never trips a per-read timeout -- and because it is the only kind /// the standard library can give portably: Zig 0.17 times a socket read only /// on `Io.Threaded` and panics on the others, and its timeout on `connect` is /// a `@panic("TODO")`. So the fetch runs as a task of its own, a second task /// sleeps until the deadline, and whichever finishes first cancels the other; /// a cancelled fetch closes its connection on the way out like any other /// failure. That needs an `Io` that can run two tasks at /// once, and without one a timed fetch is `error.ConcurrencyUnavailable` /// rather than an untimed one. /// /// A `.deadline` is absolute, so one set once bounds every fetch made before /// it passes, together. timeout: Io.Timeout = .none, /// Content codings to ask for, and to undo. Empty asks for none; see /// `http1.client.Config.accept_encodings` for what asking costs. /// /// Set here rather than in the two driver configurations below, whose own /// `accept_encodings` this replaces: a caller cannot know in advance which /// driver a server will select, and two answers to one question is a client /// that decodes over one version and not the other. accept_encodings: []const coding.Coding = &.{}, /// Passed to the HTTP/1.x driver, apart from `accept_encodings`. http1_config: http.http1.client.Config = .{}, /// Passed to the HTTP/2 driver, apart from `accept_encodings`. /// /// Its `max_body_len` bounds what a `fetch` will read over HTTP/2, because /// that driver gathers a body before handing it over; over HTTP/1.1 the body /// streams into the writer and nothing here bounds it. http2_config: http.http2.client.Config = .{}, /// The socket underneath, for both versions. tcp_options: transport.Listener.Options = .{}, /// How a host name becomes addresses: `std.Io.net.HostName.lookup`, or any /// function with its signature. /// /// The same signature, so that the standard library's is simply the default /// and anything written to stand in for it anywhere stands in for it here. /// The contract is that function's: addresses go into `resolved` carrying /// `options.port`, the queue is closed before returning even on error, and /// with a queue of sixteen -- which is what this passes -- it must not block, /// so a replacement stops at sixteen addresses. There is no context pointer, /// so a replacement that needs configuration finds it at container level. /// /// Replaceable because the standard library's is one of several reasonable /// answers -- a stub resolver with DNS over TLS or HTTPS behind it is another /// -- and a program that wants one should not have to fork this client to /// get it. resolver: *const fn ( host_name: net.HostName, io: Io, resolved: *Io.Queue(net.HostName.LookupResult), options: net.HostName.LookupOptions, ) net.HostName.LookupError!void = net.HostName.lookup, /// The proxy `http` URLs are fetched through, or null to fetch them directly. /// /// The request is *forwarded*: it goes to the proxy with its target in /// absolute form, as §3.2.2 of RFC 9112 has a request to a proxy carry it, /// and the proxy makes the request itself. So it is always HTTP/1.1 to the /// proxy, and `http2_prior_knowledge` does not apply -- what the proxy knows /// about the origin is its own business. http_proxy: ?proxy.Proxy = null, /// The proxy `https` URLs are fetched through, or null to fetch them directly. /// /// The request is *tunnelled*: `CONNECT` asks the proxy for a byte stream to /// the origin, and the TLS handshake runs inside it -- so the certificate /// checked is the origin's, the proxy sees nothing but ciphertext, and ALPN /// chooses the version exactly as it does without a proxy. https_proxy: ?proxy.Proxy = null, /// Hosts fetched directly whatever the two proxies say. See `proxy.bypasses` /// for how an entry matches. Borrowed. no_proxy: []const []const u8 = &.{}, /// Where `.advertised` asks DNS for an origin's HTTPS records (RFC 9460), or /// null not to. `std.Io.net.HostName.lookup`'s shape, as `resolver` is, for /// the same reasons -- it streams, closes `resolved` on return, and must not /// block on a queue of sixteen -- and for the same reason a hook: the standard /// library cannot ask for record type 65, and zig-dns-client, which can, /// cannot be a dependency of this module. See `Service` for the division of /// labour and `doc/https-records.md` for the whole plan. services: ?*const fn ( host_name: net.HostName, io: Io, resolved: *Io.Queue(Service), options: ServiceLookupOptions, ) ServiceLookupError!void = null, /// Whether an `http` URL whose origin has an HTTPS record is fetched as /// `https` instead, which §9.5 of RFC 9460 asks for: the record "directs the /// client to communicate with this host only over a secure transport, similar /// to HSTS". On by default, since a record is the origin saying so; off /// fetches an `http` URL as it is written. Only with `.advertised` and /// `services`. https_record_upgrade: bool = true, /// Where `.advertised` remembers what origins have said. Borrowed, so that /// several `Client`s -- on several tasks, which the cache's lock is for -- can /// share what any of them learns. Null uses one of this client's own. alt_svc: ?*AltSvc = null, own_alt_svc: AltSvc = .{}, /// The system's store, once it has been loaded. Owned. system_ca: ?tls.CertBundle = null, /// Randomness for TLS handshakes, seeded from the `Io` on first use. /// /// A CSPRNG and not `DefaultPrng`, because what the handshake draws from it /// are key shares and a predictable generator is a predictable key. csprng: ?std.Random.DefaultCsprng = null, /// Frees the system's certificate store, if a fetch loaded it. Everything /// else a client holds is borrowed or inline. pub fn deinit(c: *Client) void { if (c.system_ca) |*bundle| bundle.deinit(c.gpa); c.* = undefined; } test deinit { var client: Client = .{ .io = testing.io, .gpa = testing.allocator }; client.deinit(); } /// Sets `http_proxy`, `https_proxy` and `no_proxy` from the environment, the /// way curl and `std.http.Client.initDefaultProxies` read it: `http_proxy`, /// then `HTTP_PROXY`, then `all_proxy` and `ALL_PROXY` for the first; /// `https_proxy` and `HTTPS_PROXY` before the same two for the second; and /// `no_proxy` or `NO_PROXY` for the list. Only fields still at their defaults /// are set, so a proxy configured by hand wins. /// /// What it sets is allocated in `arena`, which has to outlive the client. pub fn initDefaultProxies( c: *Client, arena: Allocator, environ_map: *const std.process.Environ.Map, ) proxy.Proxy.ParseError!void { if (c.http_proxy == null) { if (firstSet(environ_map, &.{ "http_proxy", "HTTP_PROXY", "all_proxy", "ALL_PROXY" })) |value| { c.http_proxy = try .parse(arena, value); } } if (c.https_proxy == null) { if (firstSet(environ_map, &.{ "https_proxy", "HTTPS_PROXY", "all_proxy", "ALL_PROXY" })) |value| { c.https_proxy = try .parse(arena, value); } } if (c.no_proxy.len == 0) { if (firstSet(environ_map, &.{ "no_proxy", "NO_PROXY" })) |value| { c.no_proxy = try proxy.splitNoProxy(arena, value); } } } test initDefaultProxies { const gpa = testing.allocator; var environ: std.process.Environ.Map = .init(gpa); defer environ.deinit(); try environ.put("http_proxy", "proxy.example:3128"); try environ.put("HTTPS_PROXY", "https://secure-proxy.example"); try environ.put("no_proxy", "localhost, .internal"); var arena_state: std.heap.ArenaAllocator = .init(gpa); defer arena_state.deinit(); var client: Client = .{ .io = testing.io, .gpa = gpa }; defer client.deinit(); try client.initDefaultProxies(arena_state.allocator(), &environ); try testing.expectEqualStrings("proxy.example", client.http_proxy.?.host); try testing.expectEqual(@as(u16, 3128), client.http_proxy.?.port); try testing.expect(client.https_proxy.?.secure); try testing.expectEqual(@as(u16, 443), client.https_proxy.?.port); try testing.expectEqual(@as(usize, 2), client.no_proxy.len); // A proxy already configured is left as it is. var configured: Client = .{ .io = testing.io, .gpa = gpa, .http_proxy = .{ .host = "mine.example", .port = 8080 }, }; defer configured.deinit(); try configured.initDefaultProxies(arena_state.allocator(), &environ); try testing.expectEqualStrings("mine.example", configured.http_proxy.?.host); } /// The first of `names` that is set to something, since an empty variable is /// how a shell unsets a proxy for one command. fn firstSet(environ_map: *const std.process.Environ.Map, names: []const []const u8) ?[]const u8 { for (names) |name| { const value = environ_map.get(name) orelse continue; if (value.len > 0) return value; } return null; } pub const FetchOptions = struct { location: Location, /// Null is `GET`, or `POST` when there is a payload -- which is what /// `std.http.Client.fetch` does. method: ?Method = null, /// The request content. Sent with a `Content-Length`, as §8.6 of RFC 9110 /// asks of a client that knows the length, and it always does here. payload: ?[]const u8 = null, /// Or the request content read as it is sent, for a body too large to /// hold -- a container layer, a disk image. Not with `payload`. /// /// `length` is declared as the `Content-Length` before anything is read, /// and exactly that many octets are then streamed from `reader` into the /// connection, with nothing buffered beyond the connection's own buffers: /// over HTTP/1.1 as the body after the head, over HTTP/2 as DATA frames /// sized by flow control. A reader that ends sooner is /// `error.RequestBodyShort`, never a shorter body, and one that fails is /// `error.RequestBodyReadFailed`. /// /// A reader is read once, so a redirect that would send the body again -- /// a `307` or `308`, or a `301` or `302` to anything but a `POST` -- is /// `error.StreamedPayloadRedirected` rather than a request sent with /// whatever is left in the reader. `redirects = .auto` does not follow /// at all when there is one, as it does not for `payload`. payload_reader: ?PayloadReader = null, /// Where the response body goes. Null discards it. /// /// Every body goes here, whatever its status: a `404`'s error page as /// much as a `200`'s content. `response_writer_for` is the way to tell /// them apart before either is written. /// /// Not flushed: it is the caller's writer, and when it is flushed is the /// caller's decision. response_writer: ?*Io.Writer = null, /// Or the response body's writer, chosen once the head of the response /// that will be handed back has arrived and before any of its body is /// read -- so that a download goes into its file only when it is a `2xx`, /// and an error page stays out of it. Asked once per fetch, after any /// redirects that were followed, whose bodies go nowhere. Not with /// `response_writer`. response_writer_for: ?ResponseWriterFor = null, redirects: Redirects = .auto, /// Sent on every request, including those that follow a redirect to /// another origin. extra_headers: []const Field = &.{}, /// Sent until a redirect leads to another origin, and not after. /// /// This is where an `Authorization` or a `Cookie` goes. §15.4 of RFC 9110 /// lets a server send a client anywhere, and a credential that followed /// would be handed to whoever the server named. privileged_headers: []const Field = &.{}, /// Told of each interim response as it arrives -- see /// `client.Request.interim`, which this is handed to. /// /// On every hop: a redirect that is followed is a request of its own, and /// its interim responses are told as they come, with nothing to say which /// hop they belong to. Holding them back until it is known which hop is /// the last would defeat the point of a `103 Early Hints`. A caller that /// has to tell them apart takes `redirects = .unhandled` and follows the /// redirects itself. /// /// Not told of anything a proxy says in answer to a `CONNECT`, which is /// about the tunnel and not about this request. interim: ?Request.InterimHook = null, /// When to send the payload with a 100-continue expectation, holding it /// back until the server asks for it -- see `client.Request.expect_continue`. /// /// A server that refuses the request -- a `401`, a `413` -- then does so /// before any of the payload is sent; a redirect that arrives before it is /// sent is followed with a `payload_reader` that has not been read; and a /// `417 Expectation Failed` is answered by sending the request once more /// without the expectation, which §15.5.18 of RFC 9110 suggests. /// /// Off by default, because nothing times the wait for the server's answer /// but `timeout`: a server or intermediary that ignores the expectation /// leaves the request waiting until that runs out, or for ever without /// one. `.{ .above = 1 << 20 }` with a `timeout` set is curl's policy. expect_continue: ExpectContinue = .never, pub const Location = union(enum) { url: []const u8, /// Borrowed; `fetch` copies what it needs. uri: uri.Uri, }; }; pub const ResponseWriterFor = struct { context: *anyopaque, /// The writer for `head`'s body, or null to discard it. An error is what /// `fetch` fails with, before any of the body is read: a file that could /// not be opened, say, with whatever went wrong kept in `context`. choose: *const fn (context: *anyopaque, head: ResponseHead) Io.Writer.Error!?*Io.Writer, }; /// What `ResponseWriterFor.choose` is shown of a response. pub const ResponseHead = struct { status: protocol.Status, version: Version, /// Valid only for the duration of the call; `FetchResult.headers` is the /// same list, kept. headers: *const Headers, }; /// Where a response body goes, as `FetchOptions` says. const Sink = struct { writer: ?*Io.Writer = null, chooser: ?ResponseWriterFor = null, fn pick(s: Sink, status: u16, version: Version, headers: *const Headers) FetchError!?*Io.Writer { const chooser = s.chooser orelse return s.writer; return chooser.choose(chooser.context, .{ .status = toStatus(status) orelse return error.MalformedResponse, .version = version, .headers = headers, }); } }; /// Three digits by the time either driver hands a status over, so this is /// null for nothing that was parsed; a status that somehow is not is a /// response that is not one. fn toStatus(status: u16) ?protocol.Status { const code = std.math.cast(u10, status) orelse return null; return @fromBackingInt(code); } pub const Http3 = enum { /// HTTP/1.1 and HTTP/2 over TCP, as ALPN decides. off, /// HTTP/3 or nothing: a server that does not complete a QUIC handshake is /// the error that handshake failed with. only, /// HTTP/3 when the server answers over QUIC, and TCP when it does not. /// The fallback happens only before anything was sent, so a request is /// never sent twice; once a request has gone out over QUIC, a failure is /// that failure. prefer, /// HTTP/3 where the origin has said, with `Alt-Svc`, that it speaks it, /// and TCP everywhere else -- which is how a browser does it (RFC 7838). /// /// The first fetch to an origin goes over TCP, because nothing has been /// said yet; what its response advertises goes into `alt_svc`, and later /// fetches go to the alternative it named until that stops being fresh. /// An alternative that fails is left alone for `AltSvc.broken_for_s` and /// the origin reached over TCP instead, with the same no-resend rule as /// `.prefer`. advertised, }; /// One endpoint of an origin, from its HTTPS records, after SVCB resolution. /// /// RFC 9460 splits the work, and so does this. The hook does §3's /// resolution: the query name (§9.1: the host itself for port 443, /// `_._https.` otherwise), following AliasMode records and CNAMEs /// with a limit, appending the alias chain's final name as an endpoint of its /// own as §3 requires, and dropping any record with a `mandatory` key it does /// not understand (§8) -- `ech` among them, which nothing here implements. /// What it hands over is ServiceMode endpoints. `Client` does the rest: /// which transports an endpoint's ALPN set allows (§7.1.2), the connection, /// and falling back. pub const Service = struct { /// §2.4.1: lower is preferred. `Client` sorts by it, stably. priority: u16 = 1, target_buf: [255]u8 = undefined, target_len: u8 = 0, /// Null for the origin's own port. port: ?u16 = null, /// The `alpn` key: the protocols this endpoint offers. alpn: Alpn = .{}, /// The `no-default-alpn` key: whether §9's default, `http/1.1`, is /// withdrawn -- which is what an endpoint that is QUIC and nothing else /// says. no_default_alpn: bool = false, /// `ipv4hint` and `ipv6hint`, used only if the target's own addresses /// cannot be had. Their ports are ignored. hints_buf: [8]net.IpAddress = undefined, hints_len: u8 = 0, pub const Alpn = struct { http_1_1: bool = false, h2: bool = false, h3: bool = false, }; /// The name to connect to. Empty for §2.5.2's ".", which is the name the /// lookup was for. pub fn target(s: *const Service) []const u8 { return s.target_buf[0..s.target_len]; } test target { // A new `Service` is §2.5.2's ".": the name that was looked up. const same: Service = .{}; try testing.expectEqualStrings("", same.target()); var elsewhere: Service = .{}; try elsewhere.setTarget("svc.example.net"); try testing.expectEqualStrings("svc.example.net", elsewhere.target()); } /// Sets the name to connect to, copied in. Empty is §2.5.2's ".", the /// name the lookup was for; longer than a DNS name may be (255 octets) is /// `error.NameTooLong`. pub fn setTarget(s: *Service, name: []const u8) error{NameTooLong}!void { if (name.len > s.target_buf.len) return error.NameTooLong; @memcpy(s.target_buf[0..name.len], name); s.target_len = @intCast(name.len); } test setTarget { var s: Service = .{ .priority = 1 }; try s.setTarget("svc.example.net"); try testing.expectEqualStrings("svc.example.net", s.target()); try testing.expectError(error.NameTooLong, s.setTarget(&@as([256]u8, @splat('a')))); } /// The `ipv4hint` and `ipv6hint` addresses, in the order they were added. pub fn hints(s: *const Service) []const net.IpAddress { return s.hints_buf[0..s.hints_len]; } test hints { var s: Service = .{}; try testing.expectEqual(@as(usize, 0), s.hints().len); s.addHint(.{ .ip4 = .loopback(0) }); try testing.expectEqual(@as(usize, 1), s.hints().len); try testing.expect(s.hints()[0].eql(&.{ .ip4 = .loopback(0) })); } /// Adds an address hint, dropping it when there is no room for more than /// eight. pub fn addHint(s: *Service, address: net.IpAddress) void { if (s.hints_len == s.hints_buf.len) return; s.hints_buf[s.hints_len] = address; s.hints_len += 1; } test addHint { var s: Service = .{}; for (0..10) |i| s.addHint(.{ .ip4 = .loopback(@intCast(i)) }); // Eight are kept; the rest are dropped rather than failing. try testing.expectEqual(@as(usize, 8), s.hints().len); } /// Whether TLS over TCP may be tried at this endpoint: an `h2` or /// `http/1.1` in its set, or the default still standing. pub fn allowsTcp(s: *const Service) bool { return s.alpn.h2 or s.alpn.http_1_1 or !s.no_default_alpn; } test allowsTcp { // §9: `http/1.1` is in every set unless `no-default-alpn` withdraws it. const default: Service = .{ .alpn = .{ .h3 = true } }; try testing.expect(default.allowsTcp()); const quic_only: Service = .{ .alpn = .{ .h3 = true }, .no_default_alpn = true }; try testing.expect(!quic_only.allowsTcp()); const h2: Service = .{ .alpn = .{ .h2 = true, .h3 = true }, .no_default_alpn = true }; try testing.expect(h2.allowsTcp()); } }; pub const ServiceLookupOptions = struct { /// The `https` port the origin is being reached on, which decides the /// query name: §9.1 prefixes `_._https.` to anything but 443. port: u16, }; pub const ServiceLookupError = error{ /// §3.1: SVCB resolution failed -- SERVFAIL, a transport error, a timeout /// -- over DNS that was cryptographically protected (DNSSEC, DoT, DoH). /// The fetch is abandoned rather than carried on without the records, /// since otherwise "an active attacker could mount a downgrade attack by /// denying the user access to the SvcParams". Only the hook knows whether /// its channel was protected; over plain DNS it reports a failure as no /// records at all, which §3.1 also allows. ProtectedResolutionFailed, } || Io.Cancelable; /// When `fetch` sends a payload with a 100-continue expectation. pub const ExpectContinue = union(enum) { never, /// Whenever there is a payload. always, /// When the payload is longer than this many octets. above: u64, }; pub const PayloadReader = struct { reader: *Io.Reader, /// Octets to send, which is also what `Content-Length` says. length: u64, }; pub const Redirects = union(enum) { /// Follow up to three when there is no payload, and none when there is. auto, /// Hand a redirect back as the response, body and all. unhandled, /// Follow up to this many, and fail with `error.TooManyRedirects` at the /// next. A payload is resent to a `307` or a `308`, which §15.4.8 and /// §15.4.9 require keep the method and the content. follow: u16, }; pub const FetchResult = struct { /// The status of the last response, which is the one that was not /// followed. `std.http.Status`, as `std.http.Client.FetchResult` has it: /// non-exhaustive, so a code nothing has a name for still arrives, and /// `class()` is what §15 of RFC 9110 has a client act on for one. status: protocol.Status, /// The version that response arrived in, which is what the negotiation /// settled on. version: Version, /// That response's fields, in the order they arrived and with the names /// as they were sent -- lowercase over HTTP/2, which §8.2.1 of RFC 9113 /// requires, and however the server wrote them over HTTP/1.1. `get` and /// `values` compare names without case, so neither is a caller's concern. /// /// Copied, since the connection they arrived on is closed before `fetch` /// returns, and owned by this result: `deinit` frees them. headers: Headers, arena: std.heap.ArenaAllocator, /// Frees `headers` and everything else the result owns. The body is not /// among them: it went to the caller's writer. pub fn deinit(r: *FetchResult) void { r.arena.deinit(); r.* = undefined; } // Named by string rather than `test deinit`, which Zig refuses here as an // ambiguous reference: `Client.deinit` is in scope as well. test "FetchResult.deinit" { var example: Example = undefined; try example.start(); defer example.stop(); var client: Client = .{ .io = testing.io, .gpa = testing.allocator }; defer client.deinit(); var buffer: [64]u8 = undefined; var result = try client.fetch(.{ .location = .{ .url = try example.url(&buffer, "/") } }); // The fields are the result's own, and good until this. defer result.deinit(); try testing.expectEqualStrings("5", result.headers.get("content-length").?); } }; pub const FetchError = uri.parse.Error || http.http1.client.Error || http.http2.client.Error || tls.ConnectError || net.HostName.LookupError || Headers.AppendError || Io.RandomSecureError || Io.ConcurrentError || proxy.TunnelError || tls.ConnectOverError || http.http3.client.Error || error{ /// No QUIC handshake completed in `http3_handshake_timeout`, with /// `http3 = .only`. HandshakeTimeout, /// The UDP socket would not send or receive, with `http3 = .only`. NetworkFailed, /// The server's certificate was refused during a QUIC handshake. Not /// retried at another address or over TCP, for the reason /// `tls.connectAny` gives. BadCertificate, /// Neither `http` nor `https`. UnsupportedUriScheme, /// The URL names no host to connect to. UriMissingHost, /// §4.2.4 of RFC 9110: userinfo in an `http` or `https` URI is /// deprecated, and "a recipient SHOULD parse for userinfo and treat /// its presence as an error". A credential belongs in /// `privileged_headers`, where a redirect cannot carry it off. UserinfoInUri, /// Not a host name `HostName` will take, and not an address literal. InvalidHostName, TooManyRedirects, /// See `ServiceLookupError`. ProtectedResolutionFailed, /// A redirect that would send `payload_reader` again, which cannot be /// done: what it held has been read. Hand the redirect back with /// `redirects = .unhandled` and start again from the new location. StreamedPayloadRedirected, /// `timeout` passed before the fetch was done. Timeout, /// A redirect from `https` to `http`, with /// `refuse_insecure_redirects` set. InsecureRedirect, /// The system's certificate store could not be read. CertificateBundleLoadFailure, /// The server selected an ALPN protocol this client did not offer. /// §3.2 of RFC 7301 has a server "only select a protocol if the /// client supports it", so this is a server not following it. UnexpectedProtocol, /// A field in `extra_headers` or `privileged_headers` is one the /// driver sets itself; see `client.Request.reserved`. ReservedField, }; /// Fetches a URL, following redirects as `options.redirects` says, and writes /// the last response's body to `options.response_writer`, or to the writer /// `options.response_writer_for` chooses for it. pub fn fetch(c: *Client, options: FetchOptions) FetchError!FetchResult { // Fixed now, so that a `.duration` is measured from the call and not from // whenever the task that sleeps on it happens to start. const deadline = c.timeout.toDeadline(c.io); if (deadline == .none) return c.fetchUntimed(options); const Race = union(enum) { fetched: FetchError!FetchResult, expired: Io.Cancelable!void, }; // Room for both, which `cancel` needs: a task it cancels still has to put // its result somewhere, and a full queue is a deadlock. var results: [2]Race = undefined; var race: Io.Select(Race) = .init(c.io, &results); try race.concurrent(.fetched, fetchUntimed, .{ c, options }); race.concurrent(.expired, Io.Timeout.sleep, .{ deadline, c.io }) catch |err| { discard(&race); return err; }; const first = race.await() catch |err| { // Cancelled from outside, which is the caller's to hear about. discard(&race); return err; }; switch (first) { .fetched => |outcome| { discard(&race); return outcome; }, .expired => { // The fetch may have finished in the same instant. If it did, what // it fetched is the answer: throwing away a response that arrived // in time would be the timeout's own race lost to itself. while (race.cancel()) |late| switch (late) { .fetched => |outcome| if (outcome) |result| { discard(&race); return result; } else |_| {}, .expired => {}, }; return error.Timeout; }, } } test fetch { var example: Example = undefined; try example.start(); defer example.stop(); var client: Client = .{ .io = testing.io, .gpa = testing.allocator }; defer client.deinit(); var body: Io.Writer.Allocating = .init(testing.allocator); defer body.deinit(); var buffer: [64]u8 = undefined; var result = try client.fetch(.{ .location = .{ .url = try example.url(&buffer, "/") }, .response_writer = &body.writer, }); defer result.deinit(); try testing.expectEqual(.ok, result.status); // An `http` URL is HTTP/1.1, there being nothing to negotiate in. try testing.expectEqual(Version.http_1_1, result.version); try testing.expectEqualStrings("hello", body.written()); } /// Cancels whatever is left in the race and frees anything it had already /// fetched, since a `FetchResult` owns memory that nobody else will free. fn discard(race: anytype) void { while (race.cancel()) |late| switch (late) { .fetched => |outcome| if (outcome) |result| { var owned = result; owned.deinit(); } else |_| {}, .expired => {}, }; } fn fetchUntimed(c: *Client, options: FetchOptions) FetchError!FetchResult { var current: uri.Uri = switch (options.location) { .url => |text| try uri.Uri.parse(c.gpa, text), .uri => |u| try u.clone(c.gpa), }; defer current.deinit(); // The target as it was written, hop by hop; see `writtenTarget`. var targets: std.heap.ArenaAllocator = .init(c.gpa); defer targets.deinit(); var target: ?[]const u8 = switch (options.location) { .url => |text| try c.writtenTarget(targets.allocator(), null, text, current), .uri => null, }; // One body, not two; and one place for the response's. if (options.payload != null and options.payload_reader != null) return error.InvalidRequest; if (options.response_writer != null and options.response_writer_for != null) return error.InvalidRequest; var method = options.method orelse if (options.payload != null or options.payload_reader != null) Method.post else Method.get; var payload = options.payload; var streamed = options.payload_reader; const follow = switch (options.redirects) { .auto => payload == null and streamed == null, .unhandled => false, .follow => true, }; var remaining: u16 = switch (options.redirects) { .auto => 3, .unhandled => 0, .follow => |n| n, }; var privileged = true; var expectation_refused = false; while (true) { // Before the exchange rather than inside it, because an `http` URL // with an HTTPS record becomes an `https` one (RFC 9460 §9.5) and a // relative `Location` in what comes back has to resolve against that. var service_buffer: [8]Service = undefined; const endpoints = try c.serviceEndpoints(¤t, &service_buffer); const outcome = try c.exchange(current, target, method, payload, streamed, options, privileged, follow, endpoints, !expectation_refused); if (outcome.expectation_refused) { // §15.5.18 of RFC 9110: "the client... MAY repeat the request // without the expectation", and nothing of it was sent, so a // `payload_reader` is still unread. Once: a second `417` to a // request without one is a response like any other. expectation_refused = true; continue; } const location = outcome.location orelse { var kept = outcome.kept.?; const status = toStatus(outcome.status) orelse { kept.arena.deinit(); return error.MalformedResponse; }; return .{ .status = status, .version = outcome.version, .headers = kept.headers, .arena = kept.arena, }; }; defer c.gpa.free(location); if (remaining == 0) return error.TooManyRedirects; remaining -= 1; // §10.2.2 of RFC 9110: `Location` is a URI-reference, so a relative // one is resolved against the URI that was requested -- RFC 3986 §5. const next = try current.click(c.gpa, location); if (c.refuse_insecure_redirects and isDowngrade(current, next)) { next.deinit(); return error.InsecureRedirect; } if (!sameOrigin(current, next)) privileged = false; current.deinit(); current = next; target = try c.writtenTarget(targets.allocator(), target, location, current); switch (outcome.status) { // §15.4.4: a 303 is answered with a GET, whatever was asked -- // except a HEAD, which is still a HEAD. 303 => if (!method.eql(Method.head)) { method = Method.get; payload = null; streamed = null; }, // §15.4.2 and §15.4.3: "a user agent MAY change the request // method from POST to GET", and every browser does, so a server // sending one expects it. 301, 302 => if (method.eql(Method.post)) { method = Method.get; payload = null; streamed = null; }, else => {}, } // Still carrying a body that has already been read. Not one that was // held back for a 100 Continue that never came, which is still // unread and goes to wherever the redirect leads. if (streamed != null and outcome.content_sent) return error.StreamedPayloadRedirected; } } const Outcome = struct { status: u16, version: Version, /// Whether the request's content went out; see `client.Response`. content_sent: bool = true, /// A `417` to a request carrying a 100-continue expectation, which is /// to be sent again without one. Neither `location` nor `kept` is set. expectation_refused: bool = false, /// Set only when the response is a redirect that is to be followed. /// Owned by the caller. location: ?[]u8 = null, /// Set only when it is not: the response `fetch` hands back. kept: ?Kept = null, }; /// A response's fields, copied out of the connection that is about to close. const Kept = struct { headers: Headers, arena: std.heap.ArenaAllocator, }; /// One allocation for the strings and one for the list, both in an arena, so /// that a response with a hundred fields costs two calls rather than two /// hundred and frees in one. fn keep(gpa: Allocator, from: Headers) Allocator.Error!Kept { var arena: std.heap.ArenaAllocator = .init(gpa); errdefer arena.deinit(); const a = arena.allocator(); var total: usize = 0; for (from.fields.items) |field| total += field.name.len + field.value.len; const bytes = try a.alloc(u8, total); var fields = try std.ArrayList(Field).initCapacity(a, from.fields.items.len); var at: usize = 0; for (from.fields.items) |field| { const name = bytes[at..][0..field.name.len]; @memcpy(name, field.name); at += name.len; const value = bytes[at..][0..field.value.len]; @memcpy(value, field.value); at += value.len; fields.appendAssumeCapacity(.{ .name = name, .value = value }); } return .{ .headers = .{ .fields = fields }, .arena = arena }; } /// Whether following `from` to `to` gives up TLS. Only `https` to `http`: a /// scheme that is neither is refused later as unsupported, whatever this says. fn isDowngrade(from: uri.Uri, to: uri.Uri) bool { const from_scheme = from.scheme orelse return false; const to_scheme = to.scheme orelse return false; return std.ascii.eqlIgnoreCase(from_scheme, "https") and std.ascii.eqlIgnoreCase(to_scheme, "http"); } fn isRedirect(status: u16) bool { return switch (status) { // §15.4: 300 offers a choice rather than naming one, 304 is about a // cache, and 305 and 306 are deprecated and reserved. 301, 302, 303, 307, 308 => true, else => false, }; } /// One request and one response, over a connection dialled for it. fn exchange( c: *Client, u: uri.Uri, written: ?[]const u8, method: Method, payload: ?[]const u8, streamed: ?PayloadReader, options: FetchOptions, privileged: bool, follow: bool, endpoints: ?[]const Service, expect: bool, ) FetchError!Outcome { const scheme = u.scheme orelse return error.UnsupportedUriScheme; const secure = if (std.ascii.eqlIgnoreCase(scheme, "https")) true else if (std.ascii.eqlIgnoreCase(scheme, "http")) false else return error.UnsupportedUriScheme; if (u.username != null or u.password != null) return error.UserinfoInUri; const host = u.host orelse return error.UriMissingHost; if (host.text().len == 0) return error.UriMissingHost; const port: u16 = u.port orelse if (secure) http.default_tls_port else http.default_port; var arena_state: std.heap.ArenaAllocator = .init(c.gpa); defer arena_state.deinit(); const arena = arena_state.allocator(); var request: Request = .{ .method = method, .target = written orelse try originForm(arena, u), // §7.2 of RFC 9110: the authority as the URI gave it, which carries // the port only when one was written. .host = try u.authority(arena, .{}), .body = if (payload) |p| .{ .exact = p.len } else if (streamed) |s| .{ .exact = s.length } else .none, .content = payload, .source = if (streamed) |s| s.reader else null, .interim = options.interim, .expect_continue = expect and switch (options.expect_continue) { .never => false, .always => true, .above => |threshold| (if (payload) |p| p.len else if (streamed) |s| s.length else 0) > threshold, }, }; defer request.deinit(c.gpa); const sink: Sink = .{ .writer = options.response_writer, .chooser = options.response_writer_for }; for (options.extra_headers) |field| try request.setHeader(c.gpa, field.name, field.value); if (privileged) { for (options.privileged_headers) |field| try request.setHeader(c.gpa, field.name, field.value); } const via = c.proxyFor(secure, host.text()); if (!secure) { if (via) |forwarder| { // §3.2.2 of RFC 9112: to a proxy, the whole URI. `Host` still // goes, and has to agree with it, which it does by construction. request.target = try std.mem.concat(arena, u8, &.{ "http://", request.host, request.target }); if (forwarder.authorization) |value| { try request.setHeader(c.gpa, "Proxy-Authorization", value); } const conn = try c.dialProxy(forwarder); return c.overHttp1(conn, request, sink, follow, null); } var address_buffer: [16]net.IpAddress = undefined; const addresses = try c.resolve(host, port, &address_buffer); const conn = try tcp.connectAny(c.io, c.gpa, addresses, c.tcp_options); return if (c.http2_prior_knowledge) c.overHttp2(conn, request, sink, follow, null) else c.overHttp1(conn, request, sink, follow, null); } const tls_options = try c.tlsOptions(host.text()); // What a response may teach about this origin's HTTP/3, when anything // will listen: only in `.advertised`, and only for a request made // directly, since §2.1 wants the assurance a TLS connection to the origin // gives and a proxy's relay does not. const learn: ?Origin = if (via == null and c.http3 == .advertised) .{ .host = host.text(), .port = port } else null; // Resolved once for whichever transport ends up used, so that a fallback // does not look the name up a second time. var address_buffer: [16]net.IpAddress = undefined; const addresses: []const net.IpAddress = if (via == null) try c.resolve(host, port, &address_buffer) else &.{}; if (via == null) switch (c.http3) { .off => {}, .only, .prefer => { if (try c.overHttp3(host.text(), addresses, request, sink, follow, null, c.http3 == .prefer)) |outcome| { return outcome; } // `.prefer`, and no QUIC handshake completed: TCP, below. }, .advertised => { // What the origin said over HTTP first, since it was said to this // client and is the more specific; its DNS records next, which is // what makes a first request to an origin able to use HTTP/3. if (c.altSvc().lookup(c.io, host.text(), port)) |target| { if (try c.overAlternative(host.text(), addresses, target, request, sink, follow, learn)) |outcome| { return outcome; } // §2.4: "if the connection to the alternative service fails // or is unresponsive, the client MAY fall back to using the // origin", and leaves it alone for a while so that the next // fetch does not pay for finding out again. c.altSvc().markBroken(c.io, host.text(), port); } if (endpoints) |list| { if (try c.overEndpoints(host.text(), port, list, request, sink, follow, learn)) |outcome| { return outcome; } // RFC 9460 §3: "If the client is SVCB-optional and connecting // using this list of endpoints has failed, the client now // attempts to use non-SVCB connection modes" -- the origin, // below. } }, }; const conn = if (via) |tunneller| tunnelled: { // The origin's name is the proxy's to resolve, which is the point of // asking it for the authority rather than for an address: the proxy // may see names this machine cannot. var authority_buffer: [net.HostName.max_len + 8]u8 = undefined; const authority = proxy.formatAuthority(&authority_buffer, host.text(), port) catch return error.InvalidHostName; const to_proxy = try c.dialProxy(tunneller); const through = try proxy.tunnel(c.io, c.gpa, to_proxy, authority, tunneller.authorization); break :tunnelled try tls.connectOver(c.io, c.gpa, through, tls_options); } else try tls.connectAny(c.io, c.gpa, addresses, tls_options); return c.overTls(conn, request, sink, follow, learn); } /// Whichever driver ALPN chose on a TLS connection. fn overTls( c: *Client, conn: transport.Connection, request: Request, sink: Sink, follow: bool, learn: ?Origin, ) FetchError!Outcome { const selected = conn.info.alpn orelse "http/1.1"; if (std.mem.eql(u8, selected, "h2") and c.http2) { return c.overHttp2(conn, request, sink, follow, learn); } if (std.mem.eql(u8, selected, "http/1.1")) { return c.overHttp1(conn, request, sink, follow, learn); } var owned = conn; owned.close(c.io, c.gpa); return error.UnexpectedProtocol; } /// What a TLS connection to an origin offers and checks. The name is the /// origin's wherever the connection goes -- an `Alt-Svc` alternative's host, /// an HTTPS record's TargetName -- since the certificate that makes either one /// trustworthy is the origin's. fn tlsOptions(c: *Client, origin_host: []const u8) FetchError!tls.ClientOptions { return .{ .host = origin_host, .root_ca = try c.trust(), .insecure_skip_verify = c.insecure_skip_verify, .alpn_protocols = if (c.http2) &.{ "h2", "http/1.1" } else &.{"http/1.1"}, .rng = try c.random(), .tcp = c.tcp_options, }; } /// The proxy a request to this host goes through, if any. fn proxyFor(c: *const Client, secure: bool, host: []const u8) ?proxy.Proxy { if (proxy.bypasses(c.no_proxy, host)) return null; return if (secure) c.https_proxy else c.http_proxy; } /// An origin's HTTPS-record endpoints, sorted by priority, or null when there /// are none to use -- and, for an `http` URL whose origin has some, `current` /// rewritten to the `https` URL RFC 9460 §9.5 has the client fetch instead. fn serviceEndpoints(c: *Client, current: *uri.Uri, buffer: []Service) FetchError!?[]const Service { if (c.http3 != .advertised) return null; const lookup = c.services orelse return null; const scheme = current.scheme orelse return null; const secure = std.ascii.eqlIgnoreCase(scheme, "https"); const plain = std.ascii.eqlIgnoreCase(scheme, "http"); if (!secure and !plain) return null; if (plain and !c.https_record_upgrade) return null; const host = current.host orelse return null; // An address literal has no records to ask for, and a name `HostName` // will not take is `exchange`'s to report. if (host != .hostname) return null; const name = net.HostName.init(host.text()) catch return null; // §3.2: with a proxy carrying the request by name, and nothing private to // ask SVCB of, an SVCB-optional client "MUST disable SVCB resolution // entirely" -- asking here would tell a second party where the request is // going. For an `http` URL both proxies count: the one it would use now, // and the one the `https` URL would. if (c.proxyFor(secure, host.text()) != null) return null; if (plain and c.proxyFor(true, host.text()) != null) return null; // §9.5's construction of the `https` URL: "If the 'http' URL explicitly // specifies port 80, specify port 443", and change nothing else. const explicit_port: ?u16 = if (plain and current.port == 80) 443 else current.port; const port = explicit_port orelse http.default_tls_port; var results: [16]Service = undefined; var queue: Io.Queue(Service) = .init(&results); lookup(name, c.io, &queue, .{ .port = port }) catch |err| switch (err) { error.Canceled => |e| return e, error.ProtectedResolutionFailed => |e| return e, }; var n: usize = 0; while (queue.getOne(c.io)) |service| { if (n < buffer.len) { buffer[n] = service; n += 1; } } else |err| switch (err) { error.Closed => {}, error.Canceled => |e| return e, } if (n == 0) return null; std.sort.insertion(Service, buffer[0..n], {}, struct { fn lessThan(_: void, a: Service, b: Service) bool { return a.priority < b.priority; } }.lessThan); if (plain) { // §9.5: "the client SHOULD behave as if it has received an HTTP 307 // (Temporary Redirect) status code with this 'https' URL in the // 'Location' field" -- a redirect nothing was sent for, so none of the // caller's budget for redirects is spent on it, and nothing sent in // cleartext for a privileged header to have leaked through. const upgraded = try current.replace(c.gpa, .{ .scheme = "https", .port = if (explicit_port) |p| @as(?u16, p) else null, }); current.deinit(); current.* = upgraded; } return buffer[0..n]; } /// An exchange with the first of an origin's HTTPS-record endpoints that can /// be reached, in priority order, or null when none could. fn overEndpoints( c: *Client, origin_host: []const u8, origin_port: u16, endpoints: []const Service, request: Request, sink: Sink, follow: bool, learn: ?Origin, ) FetchError!?Outcome { for (endpoints) |*endpoint| { const name = if (endpoint.target().len == 0) origin_host else endpoint.target(); const port = endpoint.port orelse origin_port; var address_buffer: [16]net.IpAddress = undefined; const addresses = c.resolveText(name, port, &address_buffer) catch |err| switch (err) { error.Canceled, error.OutOfMemory => |e| return e, // The target's own addresses cannot be had: the hints are what // they are for. else => hinted: { const n = @min(endpoint.hints().len, address_buffer.len); for (endpoint.hints()[0..n], address_buffer[0..n]) |from, *to| { to.* = from; to.setPort(port); } break :hinted address_buffer[0..n]; }, }; if (addresses.len == 0) continue; // §7.1.2: QUIC if the set holds `h3`, TLS over TCP if it holds // anything that runs there -- offering, over each, everything this // client speaks on that transport "without regard to the SVCB ALPN // set", so that ALPN inside the handshake still has the last word. if (endpoint.alpn.h3) { const outcome = c.overHttp3(origin_host, addresses, request, sink, follow, learn, true) catch |err| switch (err) { // A certificate that is not the origin's, at an endpoint: // this endpoint failed, and the next -- or the origin, over // TLS the ordinary way -- is still to be tried. error.BadCertificate => null, else => |e| return e, }; if (outcome) |o| return o; } if (endpoint.allowsTcp()) { const conn = tls.connectAny(c.io, c.gpa, addresses, try c.tlsOptions(origin_host)) catch |err| switch (err) { error.Canceled, error.OutOfMemory => |e| return e, else => continue, }; return try c.overTls(conn, request, sink, follow, learn); } } return null; } /// A name or an address literal, to the addresses to try. fn resolveText(c: *Client, text: []const u8, port: u16, buffer: []net.IpAddress) FetchError![]const net.IpAddress { if (net.IpAddress.resolve(c.io, text, port)) |literal| { buffer[0] = literal; return buffer[0..1]; } else |_| return c.resolveName(text, port, buffer); } /// An exchange over HTTP/3, or null when no QUIC handshake completed and /// `http3 = .prefer` leaves TCP to try. /// /// Each address in turn, as `tcp.connectAny` does, since an address that /// drops UDP is the ordinary case and not the exceptional one. fn overHttp3( c: *Client, host: []const u8, addresses: []const net.IpAddress, request: Request, sink: Sink, follow: bool, learn: ?Origin, fallback: bool, ) FetchError!?Outcome { var failure: FetchError = error.HandshakeTimeout; for (addresses) |address| { if (try c.attemptHttp3(host, address, request, sink, follow, learn, &failure)) |outcome| { return outcome; } } return if (fallback) null else failure; } /// One address: a UDP socket, a QUIC handshake, and an exchange. Null, with /// `failure` saying why, when the handshake did not complete and another /// address or TCP may do better; an error for anything that happened after /// the request began, which is not retried anywhere. /// /// The socket, the dialer and the task pumping it live in this frame and /// nowhere else, which is why it is a function of its own: the dialer must /// not move once connected, and all three end together when it returns. fn attemptHttp3( c: *Client, host: []const u8, address: net.IpAddress, request: Request, sink: Sink, follow: bool, learn: ?Origin, failure: *FetchError, ) FetchError!?Outcome { // The unspecified address of the family being dialled: a socket bound to // one family cannot reach the other. const local: net.IpAddress = switch (address) { .ip4 => .{ .ip4 = .unspecified(0) }, .ip6 => .{ .ip6 = .unspecified(0) }, }; var socket = local.bind(c.io, .{ .mode = .dgram }) catch { failure.* = error.NetworkFailed; return null; }; defer socket.close(c.io); var dialer: http3_io.Dialer = undefined; dialer.connect(c.io, c.gpa, &socket, address, .{ .host = host, .root_ca = try c.trust(), .insecure_skip_verify = c.insecure_skip_verify, .rng = try c.random(), .handshake_timeout_ns = @intCast(@max(0, c.http3_handshake_timeout.nanoseconds)), }) catch |err| switch (err) { error.OutOfMemory, error.Canceled => |e| return e, // An answer about the name, not the address, and so not one to ask // again elsewhere -- the same judgement `tls.connectAny` makes. error.BadCertificate => return error.BadCertificate, error.HandshakeTimeout, error.NetworkFailed, error.HandshakeFailed => |e| { failure.* = e; return null; }, }; defer dialer.deinit(); // A stream read waits for a datagram and this is what makes one arrive, // so it has to run beside the exchange rather than inside it. var pump: Io.Group = .init; defer pump.cancel(c.io); try pump.concurrent(c.io, runDialer, .{&dialer}); defer dialer.stop(); var config = c.http3_config; config.accept_encodings = c.accept_encodings; var h3: http.http3.client.Connection = .init(c.gpa, dialer.session(), config); try h3.start(); // What the server's own streams say, read beside the exchange for the // same reason the pump is: the control stream does not end while the // connection lasts. Cancelled with the pump, before `h3` goes away. try pump.concurrent(c.io, http.http3.client.Connection.run, .{ &h3, c.io }); var answered = try h3.send(request); defer answered.deinit(c.gpa); const res = answered.response; c.noteAltSvc(learn, &res.headers); // §15.5.18 of RFC 9110: the expectation itself was refused, and nothing // of the content went. `fetch` sends it again without one; this // response's body is not the caller's to see. if (request.expect_continue and res.status == 417 and !res.content_sent) { return .{ .status = res.status, .version = res.version, .expectation_refused = true }; } if (follow and isRedirect(res.status)) { if (res.header("location")) |location| return .{ .status = res.status, .version = res.version, .content_sent = res.content_sent, .location = try c.gpa.dupe(u8, location), }; } if (try sink.pick(res.status, res.version, &res.headers)) |w| w.writeAll(answered.body()) catch return error.WriteFailed; return .{ .status = res.status, .version = res.version, .content_sent = res.content_sent, .kept = try keep(c.gpa, res.headers) }; } /// An origin, as `AltSvc` keys it. const Origin = struct { host: []const u8, port: u16 }; fn altSvc(c: *Client) *AltSvc { return c.alt_svc orelse &c.own_alt_svc; } fn noteAltSvc(c: *Client, origin: ?Origin, headers: *const Headers) void { const o = origin orelse return; c.altSvc().learn(c.io, o.host, o.port, headers); } /// An exchange with an origin's advertised HTTP/3 alternative, or null when it /// could not be reached and the origin should be tried over TCP. /// /// §2.1 and §2.3 of RFC 7838 between them: the connection goes to the /// alternative's host and port, but the name sent in SNI and checked against /// the certificate is the *origin's* -- "reasonable assurances that the /// alternative service is under control of and valid for the whole origin" /// are exactly a certificate for the origin -- and so is the request's /// `:authority`, which `request` already carries. fn overAlternative( c: *Client, origin_host: []const u8, origin_addresses: []const net.IpAddress, target: AltSvc.Target, request: Request, sink: Sink, follow: bool, learn: ?Origin, ) FetchError!?Outcome { var address_buffer: [16]net.IpAddress = undefined; const addresses: []const net.IpAddress = if (target.host().len == 0) same: { // The same host on another port: the addresses already resolved, // pointed at the alternative's port. const n = @min(origin_addresses.len, address_buffer.len); for (origin_addresses[0..n], address_buffer[0..n]) |from, *to| { to.* = from; to.setPort(target.port); } break :same address_buffer[0..n]; } else if (net.IpAddress.resolve(c.io, target.host(), target.port)) |literal| literal: { address_buffer[0] = literal; break :literal address_buffer[0..1]; } else |_| c.resolveName(target.host(), target.port, &address_buffer) catch |err| switch (err) { error.Canceled, error.OutOfMemory => |e| return e, // A name nobody can find is an alternative that failed. else => return null, }; return c.overHttp3(origin_host, addresses, request, sink, follow, learn, true) catch |err| switch (err) { // Unlike `.only` and `.prefer`, which dial the origin itself: an // alternative whose certificate is not the origin's is an alternative // that failed, and the origin is still there over TCP to be verified // the ordinary way. §2.4 has the client "fall back to using the // origin", and TLS over TCP gives up nothing a failed QUIC handshake // had. error.BadCertificate => null, else => |e| e, }; } fn runDialer(dialer: *http3_io.Dialer) void { dialer.run() catch {}; } /// A connection to a proxy, with buffers large enough for a TLS handshake to /// run inside whatever tunnel it is about to carry. fn dialProxy(c: *Client, p: proxy.Proxy) FetchError!transport.Connection { var address_buffer: [16]net.IpAddress = undefined; const addresses = try c.resolveText(p.host, p.port, &address_buffer); var options = c.tcp_options; options.read_buffer_len = @max(options.read_buffer_len, tls.min_read_buffer_len); options.write_buffer_len = @max(options.write_buffer_len, tls.min_write_buffer_len); if (!p.secure) return tcp.connectAny(c.io, c.gpa, addresses, options); // An `https://` proxy: TLS to the proxy itself, checked against the same // trust as an origin. `http/1.1` alone, because what is spoken to it is a // `CONNECT` or a forwarded request, and both are HTTP/1.1. return tls.connectAny(c.io, c.gpa, addresses, .{ .host = p.host, .root_ca = try c.trust(), .insecure_skip_verify = c.insecure_skip_verify, .alpn_protocols = &.{"http/1.1"}, .rng = try c.random(), .tcp = options, }); } fn overHttp1( c: *Client, conn: transport.Connection, request: Request, sink: Sink, follow: bool, learn: ?Origin, ) FetchError!Outcome { var config = c.http1_config; config.accept_encodings = c.accept_encodings; var h1 = http.http1.client.Connection.init(c.io, c.gpa, conn, config) catch |err| { var owned = conn; owned.close(c.io, c.gpa); return err; }; defer h1.deinit(); const res = try h1.send(request); c.noteAltSvc(learn, &res.headers); // §15.5.18 of RFC 9110: the expectation itself was refused, and nothing // of the content went. `fetch` sends it again without one; this // response's body is not the caller's to see. if (request.expect_continue and res.status == 417 and !res.content_sent) { return .{ .status = res.status, .version = res.version, .expectation_refused = true }; } if (follow and isRedirect(res.status)) { // A redirect's body is not read: the connection is about to close, // so nothing after it needs to find the start of another response. if (res.header("location")) |location| return .{ .status = res.status, .version = res.version, .content_sent = res.content_sent, .location = try c.gpa.dupe(u8, location), }; } const response_writer = try sink.pick(res.status, res.version, &res.headers); if (res.body.present) { if (response_writer) |w| { _ = res.body.reader.streamRemaining(w) catch |err| return switch (err) { error.ReadFailed => error.ReadFailed, error.WriteFailed => error.WriteFailed, }; } else { _ = res.body.reader.discardRemaining() catch return error.ReadFailed; } } // After the body, so that nothing is left to free if reading it failed. // The fields are still there: they are in the head buffer, and the body // was read through a buffer of its own. return .{ .status = res.status, .version = res.version, .content_sent = res.content_sent, .kept = try keep(c.gpa, res.headers) }; } fn overHttp2( c: *Client, conn: transport.Connection, request: Request, sink: Sink, follow: bool, learn: ?Origin, ) FetchError!Outcome { var config = c.http2_config; config.accept_encodings = c.accept_encodings; var h2 = http.http2.client.Connection.init(c.io, c.gpa, conn, config) catch |err| { var owned = conn; owned.close(c.io, c.gpa); return err; }; defer h2.deinit(); try h2.handshake(); const handle = try h2.begin(request); defer h2.finish(handle); const res = try h2.await(handle); c.noteAltSvc(learn, &res.headers); // §15.5.18 of RFC 9110: the expectation itself was refused, and nothing // of the content went. `fetch` sends it again without one; this // response's body is not the caller's to see. if (request.expect_continue and res.status == 417 and !res.content_sent) { return .{ .status = res.status, .version = res.version, .expectation_refused = true }; } if (follow and isRedirect(res.status)) { if (res.header("location")) |location| return .{ .status = res.status, .version = res.version, .content_sent = res.content_sent, .location = try c.gpa.dupe(u8, location), }; } if (try sink.pick(res.status, res.version, &res.headers)) |w| w.writeAll(h2.body(handle)) catch return error.WriteFailed; // Before `finish` gives the stream's slot back, which is where they live. return .{ .status = res.status, .version = res.version, .content_sent = res.content_sent, .kept = try keep(c.gpa, res.headers) }; } /// The request target in origin form exactly as `text` wrote it, when that /// can be recovered and says what `resolved` says; null to have `originForm` /// encode it again from `resolved` instead. /// /// `text` is the URL `fetch` was given, or a `Location` that was resolved /// against the target in `base` to give `resolved`. /// /// zig-uri keeps a path and a query decoded, and decoding forgets which /// reserved characters were escaped: `a%2Bb` and `a+b` both come back as /// `a+b`. §2.2 of RFC 3986 says those are different URIs, and a server /// reading the query as a form takes the bare `+` for a space -- so writing /// the decoded query out again would search for "a b" when "a+b" was asked. /// What was written is what is sent. It is checked against `resolved` rather /// than trusted, which catches whatever resolution changed that this does not /// redo -- a dot segment removed, say -- and leaves those to be encoded again. fn writtenTarget( c: *Client, arena: Allocator, base: ?[]const u8, text: []const u8, resolved: uri.Uri, ) Allocator.Error!?[]const u8 { const written = try resolveWritten(arena, base, text) orelse return null; const target = if (std.mem.startsWith(u8, written, "/")) written else try std.mem.concat(arena, u8, &.{ "/", written }); if (!isTargetText(target)) return null; // Read back as the path and query of an `http` URI, which is what a // server will make of it. The authority keeps a target starting `//` // from being read as one. const as_uri = try std.mem.concat(c.gpa, u8, &.{ "http://h", target }); defer c.gpa.free(as_uri); const read = uri.Uri.parse(c.gpa, as_uri) catch |err| switch (err) { error.OutOfMemory => |e| return e, else => return null, }; defer read.deinit(); if (!samePath(read, resolved)) return null; if (read.query.len != resolved.query.len) return null; for (read.query, resolved.query) |a, b| if (!a.eql(b)) return null; // A copy, since `text` may be a `Location` that is freed before the // next hop is resolved against this. return try arena.dupe(u8, target); } /// §5.2.2 of RFC 3986 on the text of a path and a query, without the dot /// segment removal that `writtenTarget` leaves to its check. Null when there /// is no text to resolve against. fn resolveWritten(arena: Allocator, base: ?[]const u8, text: []const u8) Allocator.Error!?[]const u8 { const ref = text[0 .. std.mem.findScalar(u8, text, '#') orelse text.len]; const after_scheme = if (schemeEnd(ref)) |end| ref[end + 1 ..] else ref; if (std.mem.startsWith(u8, after_scheme, "//")) { const authority = after_scheme[2..]; const end = std.mem.findAny(u8, authority, "/?") orelse authority.len; return authority[end..]; } // `http:a` has a scheme and no authority, which is nothing to send. if (after_scheme.len != ref.len) return null; if (std.mem.startsWith(u8, ref, "/")) return ref; const b = base orelse return null; const base_path = b[0 .. std.mem.findScalar(u8, b, '?') orelse b.len]; if (ref.len == 0) return b; if (ref[0] == '?') return try std.mem.concat(arena, u8, &.{ base_path, ref }); // §5.2.3: everything of the base path up to its last `/`, then the // reference. const directory = base_path[0..if (std.mem.findScalarLast(u8, base_path, '/')) |i| i + 1 else 0]; return try std.mem.concat(arena, u8, &.{ directory, ref }); } /// Where the `:` ending `ref`'s scheme is, if it has one (§3.1 of RFC 3986). fn schemeEnd(ref: []const u8) ?usize { if (ref.len == 0 or !std.ascii.isAlphabetic(ref[0])) return null; for (ref[1..], 1..) |octet, i| switch (octet) { ':' => return i, 'a'...'z', 'A'...'Z', '0'...'9', '+', '-', '.' => {}, else => return null, }; return null; } /// Whether `target` is made only of what §3.3 and §3.4 of RFC 3986 allow in /// a path and a query, with every `%` starting an escape. A URL given with a /// space in it, or written as an IRI, is not, and is encoded again instead. fn isTargetText(target: []const u8) bool { var i: usize = 0; while (i < target.len) : (i += 1) switch (target[i]) { 'a'...'z', 'A'...'Z', '0'...'9', '-', '.', '_', '~' => {}, '!', '$', '&', '\'', '(', ')', '*', '+', ',', ';', '=' => {}, ':', '@', '/', '?' => {}, '%' => { if (i + 2 >= target.len) return false; if (!std.ascii.isHex(target[i + 1]) or !std.ascii.isHex(target[i + 2])) return false; i += 2; }, else => return false, }; return true; } /// Whether two paths are one request target's: equal, or empty against a /// lone `/`, both of which `writeTarget` sends as `/`. fn samePath(a: uri.Uri, b: uri.Uri) bool { const a_root = isRoot(a); const b_root = isRoot(b); if (a_root or b_root) return a_root and b_root; if (a.rooted != b.rooted or a.path.len != b.path.len) return false; for (a.path, b.path) |x, y| if (!std.mem.eql(u8, x, y)) return false; return true; } fn isRoot(u: uri.Uri) bool { return u.path.len == 0 or (u.path.len == 1 and u.path[0].len == 0); } /// The request target in origin form: §3.2.1 of RFC 9112, the path and the /// query and nothing else. The fragment is the client's own business and /// never travels -- §4.2.5 of RFC 9110. fn originForm(arena: Allocator, u: uri.Uri) Allocator.Error![]const u8 { var out: Io.Writer.Allocating = .init(arena); const w = &out.writer; const path_only: uri.Components = .{ .rooted = u.rooted, .path = u.path }; const query_only: uri.Components = .{ .query = u.query }; writeTarget(w, path_only, query_only) catch return error.OutOfMemory; return out.written(); } fn writeTarget(w: *Io.Writer, path: uri.Components, query: uri.Components) Io.Writer.Error!void { // §4.2.3 of RFC 9110: an empty path is `/` for an `http` URI -- and it is // not optional, because §3.2.1 of RFC 9112 has no empty target. if (path.path.len == 0) { try w.writeByte('/'); } else { // With no authority in front of it, a path starting `//` would be // written with a `/.` ahead of it so as not to be read back as one. // A request target is never read that way, so it goes out as given. if (path.rooted) try w.writeByte('/'); for (path.path, 0..) |segment, i| { if (i > 0) try w.writeByte('/'); try uri.percent.encode(w, segment, &uri.percent.segment); } } if (query.query.len > 0) { try w.writeByte('?'); try uri.format.writeQuery(w, query, .uri); } } /// §4.3.1 of RFC 9110: an origin is the scheme, the host and the port, with /// the first two compared without case and the third defaulted by the scheme. /// It is what "another origin" means for `privileged_headers`. fn sameOrigin(a: uri.Uri, b: uri.Uri) bool { const a_scheme = a.scheme orelse return false; const b_scheme = b.scheme orelse return false; if (!std.ascii.eqlIgnoreCase(a_scheme, b_scheme)) return false; const a_host = a.host orelse return false; const b_host = b.host orelse return false; if (std.meta.activeTag(a_host) != std.meta.activeTag(b_host)) return false; if (!std.ascii.eqlIgnoreCase(a_host.text(), b_host.text())) return false; return a.effectivePort() == b.effectivePort(); } fn resolve( c: *Client, host: uri.Host, port: u16, buffer: []net.IpAddress, ) FetchError![]const net.IpAddress { switch (host) { .ipv4, .ipv6 => |literal| { // `resolve` rather than `parse` for the IPv6 zone identifier, // which names an interface -- the only thing "resolve" means here. buffer[0] = net.IpAddress.resolve(c.io, literal, port) catch return error.InvalidHostName; return buffer[0..1]; }, .hostname => |text| return c.resolveName(text, port, buffer), } } fn resolveName( c: *Client, text: []const u8, port: u16, buffer: []net.IpAddress, ) FetchError![]const net.IpAddress { const name = net.HostName.init(text) catch return error.InvalidHostName; // Sixteen is what `lookup` promises not to block on, which matters // because nothing is draining the queue while it runs. var results: [16]net.HostName.LookupResult = undefined; var queue: Io.Queue(net.HostName.LookupResult) = .init(&results); try c.resolver(name, c.io, &queue, .{ .port = port }); var n: usize = 0; while (queue.getOne(c.io)) |result| switch (result) { .address => |address| if (n < buffer.len) { buffer[n] = address; n += 1; }, .canonical_name => {}, } else |err| switch (err) { error.Closed => {}, error.Canceled => |e| return e, } if (n == 0) return error.NoAddressReturned; return buffer[0..n]; } fn trust(c: *Client) FetchError!tls.CertBundle { if (c.root_ca) |bundle| return bundle; // Nothing is checked, so there is no reason to read the store. if (c.insecure_skip_verify) return .empty; if (c.system_ca == null) { var bundle: tls.CertBundle = .empty; // A rescan that stops part way, canceled or failed, has already // loaded some of the store, and nothing else will free it. bundle.rescan(c.gpa, c.io, Io.Clock.real.now(c.io)) catch |err| { bundle.deinit(c.gpa); return switch (err) { error.Canceled => |e| e, else => error.CertificateBundleLoadFailure, }; }; c.system_ca = bundle; } return c.system_ca.?; } fn random(c: *Client) Io.RandomSecureError!std.Random { if (c.csprng == null) { var seed: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined; try Io.randomSecure(c.io, &seed); c.csprng = .init(seed); } return c.csprng.?.random(); } const testing = std.testing; test { // So that the examples on `Service` and `FetchResult` are compiled: a // nested type's tests are reached only when something refers to the type // itself. testing.refAllDecls(@This()); } /// A server on a loopback port for the examples, answering every request /// with `hello`. Must not move once started: the task serving it holds a /// pointer to the server, which holds one to the listener. const Example = struct { listener: tcp.Listener, server: http.server.Server, tasks: Io.Group, fn start(e: *Example) !void { const io = testing.io; e.listener = try .listen(io, .{ .ip4 = .loopback(0) }, .{}); errdefer e.listener.deinit(io); e.server = .init(io, testing.allocator, e.listener.listener(), .initStateless(hello), .{}); e.tasks = .init; // Without a second task the accept and the connect deadlock. e.tasks.concurrent(io, serve, .{&e.server}) catch return error.SkipZigTest; } fn serve(server: *http.server.Server) void { server.serve() catch {}; } fn hello(_: *http.server.Request, res: *http.server.Response) anyerror!void { try res.send("hello"); } fn stop(e: *Example) void { e.server.shutdown(); e.tasks.await(testing.io) catch {}; e.listener.deinit(testing.io); } fn url(e: *const Example, buffer: []u8, path: []const u8) ![]const u8 { return std.fmt.bufPrint(buffer, "http://127.0.0.1:{d}{s}", .{ e.listener.localAddress().getPort(), path }); } }; fn expectTarget(expected: []const u8, text: []const u8) !void { const u = try uri.Uri.parse(testing.allocator, text); defer u.deinit(); var arena: std.heap.ArenaAllocator = .init(testing.allocator); defer arena.deinit(); try testing.expectEqualStrings(expected, try originForm(arena.allocator(), u)); } test "the target is the path and the query, and never the fragment" { try expectTarget("/", "http://example.com"); try expectTarget("/", "http://example.com/"); try expectTarget("/a/b/", "http://example.com/a/b/"); try expectTarget("/?q=1", "http://example.com?q=1"); try expectTarget("/a?q=1&r", "http://example.com/a?q=1&r#frag"); // Stored decoded and written encoded again, so an escaped slash stays // inside its segment rather than becoming a separator. try expectTarget("/a%2Fb/c", "http://example.com/a%2Fb/c"); // The one place `uri.format.write` would differ: with no authority ahead // of it, a leading `//` is guarded. A request target is never read that // way. try expectTarget("//a", "http://example.com//a"); } fn expectWritten(expected: ?[]const u8, base: ?[]const u8, text: []const u8, resolved_text: []const u8) !void { const resolved = try uri.Uri.parse(testing.allocator, resolved_text); defer resolved.deinit(); var arena: std.heap.ArenaAllocator = .init(testing.allocator); defer arena.deinit(); var client: Client = .{ .io = testing.io, .gpa = testing.allocator }; defer client.deinit(); const got = try client.writtenTarget(arena.allocator(), base, text, resolved); if (expected) |e| { try testing.expectEqualStrings(e, got orelse return error.TestExpectedEqual); } else { try testing.expectEqual(@as(?[]const u8, null), got); } } test "RFC 3986 2.2: the target is sent as it was written" { // What decoding would lose: each of these is a different URI from the // one with the character bare. try expectWritten("/a%2Bb/c?q=a%2Bb%26c%3Dd%2Fe%3A%2C", null, "http://h/a%2Bb/c?q=a%2Bb%26c%3Dd%2Fe%3A%2C#f", "http://h/a%2Bb/c?q=a%2Bb%26c%3Dd%2Fe%3A%2C"); try expectWritten("/?q=%2B", null, "https://h:8443?q=%2B", "https://h:8443?q=%2B"); try expectWritten("/", null, "http://h", "http://h"); // A Location, resolved against the target before it (§5.2). try expectWritten("/x/y?q=%2B", "/a/b?z", "http://other/x/y?q=%2B", "http://other/x/y?q=%2B"); try expectWritten("/x?q=%2B", "/a/b?z", "//other/x?q=%2B", "http://other/x?q=%2B"); try expectWritten("/x?q=%2B", "/a/b?z", "/x?q=%2B", "http://h/x?q=%2B"); try expectWritten("/a/c?q=%2B", "/a/b?z", "c?q=%2B", "http://h/a/c?q=%2B"); try expectWritten("/a/b?q=%2B", "/a/b?z", "?q=%2B", "http://h/a/b?q=%2B"); try expectWritten("/a/b?z=%2B", "/a/b?z=%2B", "", "http://h/a/b?z=%2B"); try expectWritten("/c", "?q", "c", "http://h/c"); } test "a target that cannot be sent as written is encoded again" { // Not target text: a space, an IRI, a broken escape. try expectWritten(null, null, "http://h/a b", "http://h/a%20b"); try expectWritten(null, null, "http://h/\xc3\xa9", "http://h/%C3%A9"); try expectWritten(null, null, "http://h/%2", "http://h/"); // A dot segment that resolution removed, which the check catches. try expectWritten(null, "/a/b", "../c", "http://h/c"); // Nothing to resolve against. try expectWritten(null, null, "c", "http://h/c"); } test "an origin is the scheme, the host and the port" { const gpa = testing.allocator; const base = try uri.Uri.parse(gpa, "https://example.com/a"); defer base.deinit(); const same = try uri.Uri.parse(gpa, "HTTPS://EXAMPLE.com:443/b?c"); defer same.deinit(); try testing.expect(sameOrigin(base, same)); const other_port = try uri.Uri.parse(gpa, "https://example.com:8443/a"); defer other_port.deinit(); try testing.expect(!sameOrigin(base, other_port)); const downgraded = try uri.Uri.parse(gpa, "http://example.com/a"); defer downgraded.deinit(); try testing.expect(!sameOrigin(base, downgraded)); const elsewhere = try uri.Uri.parse(gpa, "https://example.net/a"); defer elsewhere.deinit(); try testing.expect(!sameOrigin(base, elsewhere)); } test "the fields a result keeps are its own" { // Copied out of storage that is then overwritten, which is what happens to // a connection's head buffer after `fetch` returns. var name_storage = "Content-Type".*; var value_storage = "text/plain".*; var fields = [_]Field{ .{ .name = &name_storage, .value = &value_storage }, .{ .name = "x-empty", .value = "" }, }; var kept = try keep(testing.allocator, .initBorrowed(&fields)); defer kept.arena.deinit(); @memset(&name_storage, 'X'); @memset(&value_storage, 'X'); try testing.expectEqual(@as(usize, 2), kept.headers.fields.items.len); try testing.expectEqualStrings("text/plain", kept.headers.get("content-type").?); try testing.expectEqualStrings("", kept.headers.get("x-empty").?); } test "a downgrade is https to http and nothing else" { const gpa = testing.allocator; const secure = try uri.Uri.parse(gpa, "https://example.com/"); defer secure.deinit(); const plain = try uri.Uri.parse(gpa, "HTTP://example.com/"); defer plain.deinit(); const elsewhere = try uri.Uri.parse(gpa, "https://example.net/"); defer elsewhere.deinit(); try testing.expect(isDowngrade(secure, plain)); try testing.expect(!isDowngrade(secure, elsewhere)); // Upgrading is not giving anything up. try testing.expect(!isDowngrade(plain, secure)); try testing.expect(!isDowngrade(plain, plain)); } test "the statuses that are followed" { for ([_]u16{ 301, 302, 303, 307, 308 }) |status| try testing.expect(isRedirect(status)); for ([_]u16{ 200, 300, 304, 305, 306, 309 }) |status| try testing.expect(!isRedirect(status)); }