Home / Docs / Specification
24. HTTP
Status: Normative, v0.2 (ADR 0074 and its amendment of 2026-10-07).
The host capability Http sends HTTP/1.1 requests to the origins that grants allow, and returns their responses.
Editions. The constructs of this chapter exist only in packages of edition 0.2 and later (spec/13 §7). In edition 0.1, Http, Header, Response and HttpError are ordinary names.
1. The capability
-
Declarations.
std.hostdeclares, in the prelude (spec/14 §3):unapub kind Header name: Text value: internal Text pub kind Response status: Int headers: List[Header] body: Text pub kind HttpError = Denied | BadUrl | BadRequest | Unreachable | TimedOut | TooLarge | Tls | Protocol pub capability Http op get(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response fails HttpError accepts internal op post(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response fails HttpError accepts internal op put(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response fails HttpError accepts internal op delete(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response fails HttpError accepts internal -
Names. A user kind or capability named
Http,Header,ResponseorHttpErroris U1002 in edition 0.2. A module MAY import the four names fromstd.host, asimport std.host (Http, Response)(spec/10 §11 rule 10, #307). -
Statuses. Every HTTP response is a
Response, whatever its status. A request fails only when it gets no response it may return:Denied: no grant allows the URL's origin with the method, orkey_namenames no key of the grants;BadUrl: the URL is not an absolutehttporhttpsURL, or it has user info;BadRequest: a header's name is not a token, or it namesHost,Content-Length,Transfer-EncodingorConnection, which the client sets itself; or the request names a key bykey_nameand also has anAuthorizationheader, or the key has a control character other than a tab;Unreachable: name resolution or the connection failed;TimedOut: the request passed its deadline (§4 rule 2);TooLarge: the response passed a limit of §4 rule 1;Tls: the TLS handshake or the certificate failed;Protocol: the response is not valid HTTP/1.1 as §3 reads it, or its body is not UTF-8.- (Edition 0.4 preview, ADR 0116 rule 12.)
Interrupted, a ninth variant afterProtocol, in edition0.4and later only: a host stop request came while the operation waited, or before it started, in the body of afor ever(spec/26 §6). The request may or may not have reached its server. - (Edition 0.4, ADR 0117 rule 8.)
RateLimited, a tenth variant afterInterrupted, in edition0.4and later only: the request had to wait at a limit of a grant whose queue was full (spec/27 §9). It was not sent.
A header value with a control character other than a tab is no failure: the run aborts with U6004 at the operation, before anything is sent. A header's value is
internal(§5), so a failure the program could handle would reveal whether it holds one; an abort is outside the noninterference model (spec/07 §1).
2. Grants
- Syntax.
http:<origin>orhttp:<origin>:<methods>, in[run] grantsand in--grant(spec/13 §5):<origin>ishttp://orhttps://, a host, and an optional:<port>; an IPv6 host is in brackets, ashttp://[::1]:8080;- the host's leftmost label MAY be
*, which matches exactly one label; <methods>is a comma-separated list ofget,post,putanddelete, by defaultget.
- Deny by default. A request is allowed when a grant matches its scheme, its host and its port (the scheme's default when absent), and allows its method. Otherwise it fails with
Denied, before any connection. - Redirects. For
301,302,303,307and308, the client follows theLocationwhen the method isget, or the status is303(which it follows asget), and a grant allows the target with that method. It follows at most 5 redirects in a row. Otherwise the redirect response is returned. - Checks.
una checkanduna runreport ausesof anHttpoperation that no grant allows as U3012, as for every host capability. - Limits (edition
0.4, ADR 0117 rule 8). A grant MAY carry limits on the rate of its requests, on how many are in flight at once, and on how many wait, as limit lines under it inita.unaor suffixes of its spec, as inhttp:https://api.example.com:get;100/minute;8/once;waiting=1000(spec/27 §9). A request is charged to every grant that allows it, and each redirect to the grants that allow its target; one over a limit waits, and fails withRateLimitedwhen the queue it must join is full.
3. Requests and responses
- HTTP/1.1, directly. The client speaks HTTP/1.1 to the origin of each request, with no proxy. It MUST ignore
HTTP_PROXY,HTTPS_PROXY,ALL_PROXYandNO_PROXY, in any letter case. - Requests. A request carries the method, the URL's path and query,
Host,Content-Lengthfor a body,Accept-Encoding: identity,Connection: close, and the program's headers in order. Withkey_name: Some(n)it also carriesAuthorization: Bearer <key>, with the key namednof thekeys:grants (spec/13 §5), to the origin of the request only. A redirect to another origin carries neither that header nor the program'sAuthorization,CookieandProxy-Authorizationheaders, in any letter case; its other headers follow. Once a redirect has left the request's origin, those credentials stay dropped for the rest of the chain, even at a later redirect back to that origin. - Responses.
- The client reads the status line and the headers.
- It reads the body by
Content-Length, bychunkedtransfer coding (trailers are read and dropped), or to the end of the connection when neither is present. A chunk size is hex digits alone, with no whitespace around them, elseProtocol. - Over
https, the end of the connection ends a body only when the server sends TLS'sclose_notifyfirst; a connection that closes without it isProtocol(#1822: a TCP close may be an on-path attacker's, RFC 8446 §6.1, RFC 9112 §9.8). A body delimited byContent-Lengthor by its last chunk is complete when it is read, so a close withoutclose_notifyafter it changes nothing. Plainhttphas no such signal and takes the close as the end. - A
204or304response has no body, whatever its headers say. - At most 10
1xxresponses MAY precede the final one; one more, or a101, isProtocol. - Header names are kept as received, in order.
- TLS verifies the server's certificate chain against the Mozilla root store that the implementation compiles in, and the host name. There is no option to skip verification.
- Settings up front (ADR 0116 amendment, P8, #1148). In edition
0.4, a run whose grants includeHttpbuilds its TLS client settings, the root store included, beforemainstarts, in both engines, and a run without such a grant never builds them. Built at the firsthttpsrequest instead, they would be state left by earlier code: a request after earliersecretcode that made one would save the time of building them, which a deadline could turn into a value.
- Settings up front (ADR 0116 amendment, P8, #1148). In edition
4. Limits and time
- Size. A response's headers are at most 100, and at most 64 KiB together, else
Protocol. Its body is at most--max-response <MiB>(default 16), elseTooLarge, and the client reads no further. - Time. Each request has one deadline,
--http-timeout <seconds>(default 30, at most 86400, a day): the total wall-clock time of the request, covering name resolution, connecting, the TLS handshake, writing and reading, across its redirects, and in edition0.4its waits at the limits of grants (spec/27 §9). Past it the request fails withTimedOut. Name resolution and the TCP connection run on two bounded pools of threads, since the host's resolver has no timeout of its own, nothing in the process can cut a lookup, and a connection attempt cannot be woken without code of its own (#1148): the request hands each to its pool and waits only until its deadline, an instant, or until its task's cancellation abandons it, and then fails withTimedOutorInterruptedwhatever the step does; the step in progress runs to its end on the pool's thread, which closes the connection, if one came, without using it. In the interpreter, a request made on a helper thread in a run that serves live peers is not abandoned by its task's cancellation: it runs to its deadline, and its result is dropped (spec/27 §8 rule 2).- The lookup pool has
max(2, --io-threads / 4)threads (64 helpers give 16): a lookup normally takes milliseconds against an exchange's tens to hundreds, so a quarter of the helpers serve their lookups without a queue, and lookups that hang hold at most that many threads, the requests of one name that wait at the same time one thread (below). An address literal is not looked up and skips this pool. - The connect pool has
--io-threadsthreads, one per helper, so connecting is never capped below what the helpers could do themselves. A connection job looks at its request only between two addresses: an attempt in progress runs until it connects or the request's deadline passes. - Up front. Every thread of both pools starts before
mainin a run whose grants include anyHttpgrant, in every edition and in both engines, and none in another run (ADR 0116 amendment, P8); their stacks, 256 KiB each, are reserved and committed only as they are used. A thread that cannot start stops the run beforemainwith U6003, and a request made without the pools fails withUnreachable. With the helpers, a run'sHttprequests take at most2 × --io-threads + max(2, --io-threads / 4)threads, and the run as a whole that number,--workersand--file-threads, all started beforemain. The pools are not capped below that, so a large--io-threadscan pass the system's limit on a process's threads: at 4096, about 9,200 threads with the defaults, beyond macOS's usual limit (kern.num_taskthreads, often 8192) and many containers' limit on processes and threads. The run then stops beforemainwith U6003, exit code 1, no position and the messagethe lookup and connect threads of this run's requests could not be made, or that of spec/27 §1 rule 4 when the helpers are the ones refused; a smaller--io-threadsruns. - One lookup per name (#1265, ADR 0117 slice S7, review R7-10). A request for a name whose lookup is queued or running joins it while another request still waits for it, names compared without case, and waits for its answer until its own deadline: the requests of one name that wait at the same time share one thread of the lookup pool, whatever their rate. A lookup whose requests all gave up takes no new one: if it has not started it never runs, and else it runs to its end unseen, while a later request of the name starts a lookup of its own on a free thread. So a lookup left by earlier requests never answers a later one, and delays one only when the pool is full. A request that joins a lookup another request still waits for takes a time that request shaped, shorter as well as longer: only requests in flight at the same time join, which is the timing of their tasks or races. Residue is bounded by the pool's size and by the host resolver's own time, not per name: requests made one after another, each cut by a deadline before the resolver answers, each leave a lookup running, and the names of one zone are not bounded together. A bound per zone, which would count the residue of a zone's steps against a share of each pool, is not taken here (#1717): counting residue would let a deadline's cut delay a later request on a pool that is not full, a channel that
L_resdoes not cover (spec/26 §7 rule 5). - The hand-off. Each step costs one push and one pop under its pool's mutex, the wake of one pool thread and a reply on the request's own channel, and a lookup, on average, O(1) operations on a hash map keyed by its name (linear in the name's length): about two thread wakes, against the milliseconds the step takes.
- Hangs. When every thread of a pool holds a step that hangs, new steps queue, and each of their requests still fails at its own deadline; a step still queued when its request gives up never runs. A pool's line is pruned of the steps whose requests gave up once it has doubled since it was last pruned, so it holds at most twice the steps it kept at its last prune, or 32, and a pool O(peak waiting requests + threads) steps and names however long its steps hang, at an amortized O(1) per step. A step that panics fails its request at once with
Unreachable, and its thread serves on. A lookup or a connection left running after its request gave up, its task canceled or its deadline passed, is residue that the timing labelL_rescovers (spec/26 §7 rule 5), at most the pools' sizes. The reactor of ADR 0117 step 6 replaces both pools. - Out of model (ADR 0116 amendment, P12). The host's resolver may keep state of its own across lookups: glibc's name service switch loads its modules and reads its configuration at the process's first lookup, which can cost a few milliseconds once, and its caches, like the host's, keep answers of earlier lookups. Which lookups earlier code made can so change how long a later one takes. That state is the host's, as the processor's caches are, and stays out of model; a lookup's time reaches a value only through a deadline, whose label covers the request's operation.
- The lookup pool has
- Complexity. A request takes time and space linear in the URL, headers and body it sends. A response takes time and space linear in what it reads, which rule 1 bounds.
- Tasks. A request blocks only its task's thread (spec/19 §8). In native code, from edition
0.4, it parks its task while it runs on a helper thread (spec/27 §2), where it also waits at the limits of its grants (spec/27 §9).
5. Information flow
- Every argument of every operation is a sink with
accepts internal(spec/07 §7 rule 4): asecretURL, header, body or key name is U4003. - Every response is
internal. - Failures (S-15, ADR 0085). Whether an operation fails, and how, is labeled by every argument: the URL, the key name, the headers with their values, and the body (spec/07 §7 rule 4). The server receives them all and may decide the failure by them, as
TooLarge,ProtocolandTimedOutare. SinceHeaderdeclares its valueinternal, the failure of every request isinternal, as its response is. Soattemptgives aninternalResult, andif error passandif error failare U4002. - A key sent by
key_namenever becomes a value of the program, so it has no label in it. It appears in no trace, outcome or diagnostic.
6. Traces
An operation of Http is a trace event of spec/11 §5, with instance host:Http and op the method's name. Its arguments are written and redacted as any operation's are, and so is its outcome, by the label of the binder of its result.
7. Examples and determinism
- Examples cannot use
Http(U3014). A program's tests install handlers for it (spec/05 §5). - The network is outside the model: two runs MAY get different responses. Grants, redirects, the limits of §4 rule 1 and the requests the client writes are deterministic. Whether a request waits at, or is refused by, a limit of a grant (spec/27 §9) depends on the timing of the run's requests, which is outside the model;
RateLimitedcarries the label of that timing. - Both engines use one client, and give the same requests, responses and failures for the same server (spec/16 §5).