---
title: "27.9 Limits on grants"
url: https://una-lang.org/en/docs/spec/27-tasks-and-time/9-limits-on-grants/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/27-tasks-and-time.md
---

# 27.9 Limits on grants

1. **Syntax** (ADR 0117 rule 8). In edition `0.4`, an `http` grant MAY carry limits. In `ita.una` they are lines under the grant (`spec/30 §2`):

   ```ebnf
   limit_line = "at" "most" int_lit ( "per" ( "second" | "minute" | "hour" ) | "at" "once" ) NEWLINE
              | "waiting" "at" "most" int_lit NEWLINE ;
   ```

   ```una
   run
     grants
       http "https://api.payments.example" get, post
         at most 100 per minute
         at most 8 at once
         waiting at most 1000
   ```

   In the text form of a grant spec (`spec/13 §5`), as `--grant` takes it, they are suffixes after the methods, each `;` and one of `<n>/second`, `<n>/minute`, `<n>/hour`, `<n>/once` and `waiting=<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 `--grant` spec 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 than `http`; a kind of limit given twice on one grant, two rates counting as one kind whatever their periods.
   - **Editions.** Limits exist in edition `0.4` and later only: `una.toml` (editions `0.1` to `0.3`) has no form of them, and a limited `--grant` for a package of an earlier edition, or for an executable that embeds no `L_lim` (rule 5), is a usage error, exit code 2, before `main` starts.
2. **Meaning.**
   - **Per period:** at most `n` requests per second, minute or hour, in a burst of up to `n`, then one every period divided by `n`: 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 of `Clock.now`, and the run takes no wall time to wait.
   - **At once:** at most `n` requests of the grant in flight.
   - **Waiting:** at most `n` requests 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 = @y` and `with @x = @y[ops]` stay limited.
   - **Scope.** Limits are per run: several processes, or a restart, each have their own.
3. **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.
4. **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 `waiting` requests, it fails at once with `HttpError.RateLimited`, a variant `HttpError` has in edition `0.4` and later only, after `Interrupted` (`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 its `RateLimited`, 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 a `tasks` statement, 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-timeout` covers the time it waits (`spec/24 §4` rule 2), and so do the deadlines of a `within` (§5) and of a `for ever within` iteration (`spec/26 §7`): past the earliest, it fails with `HttpError.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 `interrupted` and takes it out of the queue, never sent, which a deadline's cut of its `tasks` statement does not: the wait ends at that deadline with its time-out failure (§2 rule 4); a host stop in the body of a `for ever` ends it with `HttpError.Interrupted` (`spec/26 §6`).
5. **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_lim` is the meet of two labels, each of which covers that history:
   - **P10's, over the ancestors:** the join, over every site `s` that performs an operation of `Http`, of `τ⁰` of the body of every node from which the function holding `s` can 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 `τ_conc` at `s` (§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, `τ_conc` never 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 lambda `f` that can reach a request, of the driver's gaps in a driven run (all of `τ⁰(step)`, `Suf(init) ⊔ Pre(step)` and `Pre(on_stop)`), and of `τ_conc` at every site. `Pre(f)`, `Suf(f)` and `Gap(f)` are the labels of the code from `f`'s entry to its first request, from a request to its exit, and between two of its requests, over a control-flow graph of `f`'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 inside `e within d` has an edge to the deadline's cut, loops have their back edges, `start` and 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 its `Gap`. A call that reaches a request adds its callee's `Pre`, `Suf` and `Gap`; 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. `Gap` also joins the label of the failure of every step that can fail, and the whole `τ⁰` of every step inside a `within` with 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, as `let 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_lim` also joins `L_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 the `TimedOut` of a wait at a limit, are labeled with the join of `internal` and `L_lim`, so a program whose grants carry limits MUST have `L_lim` at most `internal`:
   - `una check` reports U4001, when a grant of `run grants` carries limits and `L_lim` is above `internal`, at each `Http` site whose own P10 label is above `internal` in a body whose `Gap` is above it, or at every such site when no body's `Gap` is; 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 `τ_conc` raised it, or the construct whose requests can be left running when `L_res` raised it;
   - `una build` embeds `L_lim` in the executable of an edition `0.4` package;
   - `una run` and the executable refuse a `--grant` with limits when `L_lim` is above `internal`: a usage error, exit code 2, before `main` starts, 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. `τ_conc` at 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 on `public` and `internal` data keeps `L_lim` at `internal`, and its grants can carry limits.
6. **Report.** How long a request waits at a limit is timing, out of model: the report's `out_of_model` list (`spec/13 §6`) holds "waits at limits and at `start`" (§7 rule 8). A full queue becomes a value only through `RateLimited`, which rule 5 labels.
7. **Costs** (ADR 0117 Costs). Finding the grants that allow a request takes O(G) for its `G` grants of `Http`, 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.
