Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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: 0.16 has no timeout on a socket read, and/// the one 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,
pub fn deinit(c: *Client) void { if (c.system_ca) |*bundle| bundle.deinit(c.gpa); c.* = undefined;}
/// 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); } }}
/// 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. /// /// Not flushed: it is the caller's writer, and when it is flushed is the /// caller's decision. response_writer: ?*Io.Writer = 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 = &.{},
pub const Location = union(enum) { url: []const u8, /// Borrowed; `fetch` copies what it needs. uri: uri.Uri, };};
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,/// `_<port>._https.<host>` 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]; }
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); }
pub fn hints(s: *const Service) []const net.IpAddress { return s.hints_buf[0..s.hints_len]; }
/// Adds an address hint, dropping it when there is no room. 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; }
/// 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; }};
pub const ServiceLookupOptions = struct { /// The `https` port the origin is being reached on, which decides the /// query name: §9.1 prefixes `_<port>._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;
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,
pub fn deinit(r: *FetchResult) void { r.arena.deinit(); r.* = undefined; }};
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`.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; }, }}
/// 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();
// One body, not two. if (options.payload != null and options.payload_reader != 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;
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, method, payload, streamed, options, privileged, follow, endpoints); const location = outcome.location orelse { var kept = outcome.kept.?; // Three digits by the time either driver hands a status over, so // this cannot fail on anything that was parsed; a status that // somehow is not is a response that is not one. const status = std.math.cast(u10, outcome.status) orelse { kept.arena.deinit(); return error.MalformedResponse; }; return .{ .status = @enumFromInt(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;
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. if (streamed != null) return error.StreamedPayloadRedirected; }}
const Outcome = struct { status: u16, version: Version, /// 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, method: Method, payload: ?[]const u8, streamed: ?PayloadReader, options: FetchOptions, privileged: bool, follow: bool, endpoints: ?[]const Service,) 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 = 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, }; defer request.deinit(c.gpa); 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, options.response_writer, 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, options.response_writer, follow, null) else c.overHttp1(conn, request, options.response_writer, 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, options.response_writer, 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, options.response_writer, 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, options.response_writer, 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, options.response_writer, follow, learn);}
/// Whichever driver ALPN chose on a TLS connection.fn overTls( c: *Client, conn: transport.Connection, request: Request, response_writer: ?*Io.Writer, 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, response_writer, follow, learn); } if (std.mem.eql(u8, selected, "http/1.1")) { return c.overHttp1(conn, request, response_writer, 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, response_writer: ?*Io.Writer, 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, response_writer, 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, response_writer, 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, response_writer: ?*Io.Writer, follow: bool, learn: ?Origin, fallback: bool,) FetchError!?Outcome { var failure: FetchError = error.HandshakeTimeout; for (addresses) |address| { if (try c.attemptHttp3(host, address, request, response_writer, 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, response_writer: ?*Io.Writer, 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(); var answered = try h3.send(request); defer answered.deinit(c.gpa); const res = answered.response; c.noteAltSvc(learn, &res.headers);
if (follow and isRedirect(res.status)) { if (res.header("location")) |location| return .{ .status = res.status, .version = res.version, .location = try c.gpa.dupe(u8, location), }; } if (response_writer) |w| w.writeAll(answered.body()) catch return error.WriteFailed; return .{ .status = res.status, .version = res.version, .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, response_writer: ?*Io.Writer, 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, response_writer, 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, response_writer: ?*Io.Writer, 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); 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, .location = try c.gpa.dupe(u8, location), }; }
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, .kept = try keep(c.gpa, res.headers) };}
fn overHttp2( c: *Client, conn: transport.Connection, request: Request, response_writer: ?*Io.Writer, 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);
if (follow and isRedirect(res.status)) { if (res.header("location")) |location| return .{ .status = res.status, .version = res.version, .location = try c.gpa.dupe(u8, location), }; } if (response_writer) |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, .kept = try keep(c.gpa, res.headers) };}
/// 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; bundle.rescan(c.gpa, c.io, Io.Clock.real.now(c.io)) catch |err| switch (err) { error.Canceled => |e| return e, else => { bundle.deinit(c.gpa); return 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;
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");}
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));}