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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034// 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 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,/// `_<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]; }
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 `_<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;
/// 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));}