Home / Docs / Specification / 27. Tasks and time
27.9 Limits on grants
-
Syntax (ADR 0117 rule 8). In edition
0.4, anhttpgrant MAY carry limits. Inita.unathey are lines under the grant (spec/30 §2):ebnflimit_line = "at" "most" int_lit ( "per" ( "second" | "minute" | "hour" ) | "at" "once" ) NEWLINE | "waiting" "at" "most" int_lit NEWLINE ;unarun grants http "https://api.payments.example" get, post at most 100 per minute at most 8 at once waiting at most 1000In the text form of a grant spec (spec/13 §5), as
--granttakes it, they are suffixes after the methods, each;and one of<n>/second,<n>/minute,<n>/hour,<n>/onceandwaiting=<n>, in any order:http:https://api.payments.example:get,post;100/minute;8/once;waiting=1000.- Errors. Each of these is U7008 at its line in
ita.una, and makes a--grantspec invalid, a usage error: a limit line of another form, or one with lines below it; a count below 1 or above 2^31 − 1; a limit on a grant other thanhttp; a kind of limit given twice on one grant, two rates counting as one kind whatever their periods. - Editions. Limits exist in edition
0.4and later only:una.toml(editions0.1to0.3) has no form of them, and a limited--grantfor a package of an earlier edition, or for an executable that embeds noL_lim(rule 5), is a usage error, exit code 2, beforemainstarts.
- Errors. Each of these is U7008 at its line in
-
Meaning.
- Per period: at most
nrequests per second, minute or hour, in a burst of up ton, then one every period divided byn: a token bucket kept by GCRA, the generic cell rate algorithm, over the run's clock (spec/26 §8): the monotonic clock from the run's start, or the virtual clock of--virtual-time. A wait for a refill is a wait on time: under virtual time, where a host operation runs without parking, it moves the virtual clock to the refill, or to the request's deadline when that comes first (rule 4), so both engines give the same outcomes and readings ofClock.now, and the run takes no wall time to wait. - At once: at most
nrequests of the grant in flight. - Waiting: at most
nrequests waiting at the grant's limits, 1024 without the line. - Several grants. A request is charged to every grant that allows it (spec/24 §2 rule 2), so a broader grant without limits does not bypass a narrower one with limits. Each hop of a redirect chain (spec/24 §2 rule 3) is a request of its own, charged to the grants that allow its target.
- Below every handler. The limits are enforced in the host layer that both engines share, below every handler and every rebinding: a rebinding shares the instance (spec/11 §2), so
with @x = @yandwith @x = @y[ops]stay limited. - Scope. Limits are per run: several processes, or a restart, each have their own.
- Per period: at most
-
No deadlock.
- A request takes the tokens and slots of every grant that allows its target all at once, or none, holds its slots while it is in flight, and releases them when its response is read, before a redirect asks for its own.
- A request holds nothing while it waits, and a request that holds slots never waits for a limit, so no cycle of waits can form.
- First come, first served. A request that must wait gets a ticket, and is served when, for every limited grant it needs, it has the lowest ticket among that grant's waiters and the grant has a token and a slot free. A new request is served at once only when no request waits at any grant it needs. So the waiter with the lowest ticket waits only for capacity, and no waiter starves.
- A request in a run where a grant carries limits never parks on the reactor: it runs on a helper of the I/O pool (§2 rule 3), and holds its slots until the helper returns, so the count in flight is never understated; and its wait at a limit holds its helper (spec/24 §4 rule 4). An exchange whose task was canceled ends at its next I/O step (§2 rule 4, ADR 0116 amendment P9, ADR 0117 amendment of 2026-10-27), and its helper returns then: its slots are released at that moment, not when the peer would have answered, and a request waiting for them before that still waits.
-
Waiting. A request over a limit waits in the grant's queue, an interruptible wait:
- A full queue. When a queue it must join holds
waitingrequests, it fails at once withHttpError.RateLimited, a variantHttpErrorhas in edition0.4and later only, afterInterrupted(spec/24 §1 rule 3). The interpreter runs started tasks and the branches of a race one at a time, with host operations on its one thread (§1 rule 5, §8 rule 2), and so does native code under--virtual-time(§8 rule 3): there a grant never has two requests in flight or one waiting, so a full queue, and itsRateLimited, occur only natively on the real clock, one of the outcomes the timing allows (§8 rule 4), and in the interpreter in a run that serves live peers and has atasksstatement, whose requests on helper threads and the one on its thread share the run's limits and can wait at them together (§8 rule 2, ADR 0117 amendment of 2026-11-09). - Time.
--http-timeoutcovers the time it waits (spec/24 §4 rule 2), and so do the deadlines of awithin(§5) and of afor ever withiniteration (spec/26 §7): past the earliest, it fails withHttpError.TimedOut, without being sent. - Cancellation and stops. A cancellation of its task that interrupts a waiting operation (§6 rule 7, §7 rule 4) ends it
interruptedand takes it out of the queue, never sent, which a deadline's cut of itstasksstatement does not: the wait ends at that deadline with its time-out failure (§2 rule 4); a host stop in the body of afor everends it withHttpError.Interrupted(spec/26 §6).
- A full queue. When a queue it must join holds
-
Information flow (ADR 0117 IF4). Whether a queue is full depends on when every request on its grant was made. A grant's bucket and slots are shared by every request of the run, so the time between two requests counts too (ADR 0116 P10, P11).
L_limis the meet of two labels, each of which covers that history:- P10's, over the ancestors: the join, over every site
sthat performs an operation ofHttp, ofτ⁰of the body of every node from which the function holdingscan be reached in the call graph of ADR 0116 P1, that function included (functions, the operations of handlers, which a call reaches through an operation of the handler's capability, and every lambda, which a call of a function value reaches), and ofτ_concats(§11). Code that runs between two requests of one task lies in the body of such an ancestor of the later request, or in what it calls. At a site in a function's body,τ_concnever exceeds the ancestors'τ⁰. - P11's, over the code between requests (issue #1155): the join of
Gap(f)over every function, operation of a handler and lambdafthat can reach a request, of the driver's gaps in a driven run (all ofτ⁰(step),Suf(init) ⊔ Pre(step)andPre(on_stop)), and ofτ_concat every site.Pre(f),Suf(f)andGap(f)are the labels of the code fromf's entry to its first request, from a request to its exit, and between two of its requests, over a control-flow graph off's Core IR whose nodes are its steps of evaluation (spec/11): failure edges lead from each step that can fail to its handling clause or to the exit, every step insidee within dhas an edge to the deadline's cut, loops have their back edges,startand the task constructs are calls of their tasks, and a prelude function that applies a function argument takes the summaries of every lambda, withτ⁰of its arguments in itsGap. A call that reaches a request adds its callee'sPre,SufandGap; a loop whose body reaches a request counts its whole body; within one strongly connected component of the call graph every summary isτ⁰of the component's bodies.Gapalso joins the label of the failure of every step that can fail, and the wholeτ⁰of every step inside awithinwith the label its time-out carries, from which a request can be reached, since they decide whether a later request happens. Code before a run's first request that decides nothing, aslet spent = crunch(key), is not counted: every bucket starts full. A type that holds a type parameter, a binding whose label Core IR does not give, or a callee it does not hold counts as⊤, and P10's label then decides.
Both labels are sound, so their meet is. The checker builds Core IR for P11 only when P10's label is above
internal.L_limalso joinsL_res(spec/26 §7 rule 5, item 6), since a request left on a helper by a canceled task holds its slots, and the helper, until its exchange returns.RateLimited, and theTimedOutof a wait at a limit, are labeled with the join ofinternalandL_lim, so a program whose grants carry limits MUST haveL_limat mostinternal:una checkreports U4001, when a grant ofrun grantscarries limits andL_limis aboveinternal, at eachHttpsite whose own P10 label is aboveinternalin a body whoseGapis above it, or at every such site when no body'sGapis; the message names the code between two requests that raised it (in the site's own function when that one did), the driver's gap, the tasks that can run beside it whenτ_concraised it, or the construct whose requests can be left running whenL_resraised it;una buildembedsL_limin the executable of an edition0.4package;una runand the executable refuse a--grantwith limits whenL_limis aboveinternal: a usage error, exit code 2, beforemainstarts, with the message "the grant<spec>has limits, but this program's requests are timed by<label>data".
P10's label is computed in one pass over the strongly connected components of the call graph, linear in the functions, handlers, operations and edges of the package; P11's in one walk per body to build its graph, four searches over it and one pass over the components: O(V + E) in the steps of the package.
τ_concat a request in a function's body is that of §11; at a request in a lambda's body or in a handler's operation it is⊤, as the ancestors of such a request are not one function's (issue #1154). So a server whose requests run in started tasks beside work onpublicandinternaldata keepsL_limatinternal, and its grants can carry limits. - P10's, over the ancestors: the join, over every site
-
Report. How long a request waits at a limit is timing, out of model: the report's
out_of_modellist (spec/13 §6) holds "waits at limits and atstart" (§7 rule 8). A full queue becomes a value only throughRateLimited, which rule 5 labels. -
Costs (ADR 0117 Costs). Finding the grants that allow a request takes O(G) for its
Ggrants ofHttp, as before. Charging it takes O(1) per limited grant that allows it, under one lock per run held for that work only; a request that waits takes one queue entry per such grant, joined in O(1) and left in O(1) amortized. A run without limits pays nothing more.