---
title: "31.2 Grants"
url: https://una-lang.org/en/docs/spec/31-http-servers/2-grants/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/31-http-servers.md
---

# 31.2 Grants

A `serve:` grant lets a run accept connections on one address and port, with limits that every server has whether its grant writes them or not (ADR 0123 rules 6 to 9). The limits named in §3, `line`, `headers`, `header` and `body`, are items of this section.

1. **The text form.** In `--grant` (`spec/13 §5`): `serve:<scheme>://<address>:<port>`, then items as suffixes `;<item>`.
   - `<scheme>` is `http` or `https`, in lower case.
   - `<address>` is an IPv4 address in dotted-quad form, or an IPv6 address in brackets, written in its canonical form (RFC 5952: lower case, the longest run of zero groups compressed, no leading zeros), so one address has one spelling. `0.0.0.0` and `[::]` mean every interface. A host name, a zone, an IPv4-mapped IPv6 address (`[::ffff:127.0.0.1]`, written as the IPv4 address instead) and a multicast address are refused: nothing resolves a grant, and a socket bound with `IPV6_V6ONLY` receives no IPv4 connection. A link-local IPv6 address (`fe80::/10`) is unsupported: without a zone it cannot be bound, so the run fails closed with the usage error of rule 7.
   - `<port>` is from 1 to 65535, always written, with no leading zero. Nothing follows it but items.
   - A number in an item is decimal digits with no sign and no leading zero (`0` alone where the range allows it).
2. **Items.** Each item has a default, and each is given at most once; one rate at most, of any period, since a grant keeps one token bucket.

   | Item | Meaning | Default | Range |
   | --- | --- | --- | --- |
   | `N/once` | exchanges delivered and not yet answered | 256 | 1 to 2^31 − 1 |
   | `N/second`, `N/minute`, `N/hour` | exchanges delivered per period, a token bucket | none | 1 to 2^31 − 1 |
   | `waiting=N` | requests read and waiting to be delivered | 1024 | 0 to 2^31 − 1 |
   | `connections=N` | open connections | 1024 | 1 to 1,048,576 |
   | `peer=N` | open connections from one peer | `max(16, connections / 16)` | 1 to 1,048,576, or `none` |
   | `handshakes=N` | TLS handshakes started per second; one peer may start `max(4, N / 16)` | 512 | 1 to 2^31 − 1 |
   | `requests=N` | requests on one connection | 1000 | 1 to 2^31 − 1 |
   | `line=K` | the request line, in KiB | 8 | 1 to 64 |
   | `headers=N` | header lines of a request, trailers included | 100 | 1 to 1000 |
   | `header=K` | the header section, trailers included, in KiB | 16 | 1 to 256 |
   | `body=K` | a request's body, in KiB | 1024 | 0 to 1,048,576 |
   | `buffers=M` | bytes of request bodies held for the grant, in MiB | 64 | 1 to 65,536 |
   | `peer_buffers=M` | the share of `buffers` of one peer, in MiB | `max(1, buffers / 64)` | 1 to 65,536, or `none` |
   | `replies=M` | bytes of replies not yet written, in MiB | 64 | 1 to 65,536 |
   | `peer_replies=M` | the share of `replies` of one peer under pressure, in MiB | `max(1, replies / 64)` | 1 to 65,536, or `none` |
   | `delivered=M` | bytes of the requests of open exchanges, in MiB | 256 | 1 to 65,536 |
   | `idle=S` | seconds a connection waits for a request's first byte | 5 | 1 to 3600 |
   | `read=S` | seconds to read a whole request | 20 | 1 to 3600 |
   | `write=S` | seconds to write a whole reply | 30 | 1 to 3600 |
   | `answer=S` | seconds from the end of a request to the start of its reply | 30 | 1 to 86,400 |
   | `hosts=a,b` | the names `Host` may carry (rule 5) | IP literals and `localhost` | names, or `*` |
   | `certificate=F`, `key=F` | the certificate chain and the private key, PEM files | none | `https` only, and required there |
   | `tls12` | also accept TLS 1.2 | off | `https` only |

   A derived default is computed from the values the grant gives, so `connections=4096` makes the default `peer` 256. Sizes and counts are compared in unsigned 64-bit arithmetic that never wraps. Every default is settled: a later release may only tighten one.
3. **The `ita.una` form.** Under `run grants`, `serve "<scheme>://<address>:<port>"`, then one item per line below it, each the item of rule 2 it names:

   ```ebnf
   serve_grant = "serve" text_lit NEWLINE [ INDENT serve_item { serve_item } DEDENT ] ;
   serve_item  = ( "certificate" text_lit | "key" text_lit | "tls12"
                 | "at" "most" int_lit ( "at" "once" | "per" ( "second" | "minute" | "hour" ) )
                 | ( "waiting" | "connections" | "requests" | "headers" ) "at" "most" int_lit
                 | "peer" ( "at" "most" int_lit | "none" )
                 | "handshakes" "at" "most" int_lit "per" "second"
                 | ( "line" | "header" | "body" ) "at" "most" int_lit "KiB"
                 | ( "buffers" | "replies" | "delivered" ) "at" "most" int_lit "MiB"
                 | ( "peer_buffers" | "peer_replies" ) ( "at" "most" int_lit "MiB" | "none" )
                 | ( "idle" | "read" | "write" | "answer" ) "within" int_lit ( "second" | "seconds" )
                 | "hosts" text_lit { "," text_lit } ) NEWLINE ;
   ```

   ```una
   run
     grants
       serve "https://0.0.0.0:8443"
         certificate "tls/chain.pem"
         key "tls/key.pem"
         at most 256 at once
         at most 6000 per minute
         body at most 64 KiB
         answer within 10 seconds
         hosts "shop.example", "*.shop.example"
   ```

   A unit is written where the table has one, and only that unit, so no line is read in a unit it does not name.
4. **Errors and editions.**
   - In `ita.una`, each of these is U7008 at its line: a line of another form, an item given twice or a second rate, a value out of range, `certificate`, `key` or `tls12` on an `http` grant, an empty path or a path with `;`, and a `hosts` line of rule 5's errors; at the grant's line, an invalid scheme, address or port, an `https` grant without `certificate` or `key`, and an overlap (rule 6).
   - With `--grant`, each is a usage error, exit code 2, before anything runs; so is a `serve:` grant for a single file or a package of an edition before `0.4`.
   - In `una.toml`, a `serve:` grant is U7002 in every edition: before `0.4` there is no server, and from `0.4` the grants are read from `ita.una`.
   - A grant allows all three operations of `HttpServer`.
5. **`hosts`.** Each name is a registered name of letters, digits, `-`, `_` and `.`, with no empty label and a last label that is neither all digits nor starts with `0x`, as `Host` writes one (§3 rule 5); one trailing `.` is removed and the name is compared in ASCII lower case. A name MAY start with `*.`, which stands for exactly one label (`spec/24 §2`); `*` alone accepts every name of valid syntax and is the only item of its list. An IP literal, a port, an empty name and a name given twice are errors. With the `Host` read by §3 rule 5:
   - without `hosts`, on every grant whatever its address, the name MUST be `localhost` or an IP literal, else `421`;
   - with `hosts`, the name MUST equal a listed name or match a `*.` name, else `421`; an IP literal matches no name.
6. **Overlap.** Each address and port is granted once, and a wildcard address may not share its port with another grant of its family, whatever the schemes. IPv6 sockets are bound with `IPV6_V6ONLY`, so `[::]:p` and `0.0.0.0:p` do not overlap. In `ita.una` the later of two grants that overlap is U7008; among the grants of a run, manifest and flags together, an overlap is a usage error.
7. **Before `main`.** After the checks of `spec/13 §5` and before `main` starts, the host, in this order:
   1. raises the run's limit of open descriptors to the sum of `connections` over the grants, plus 64, within the hard limit; a run that cannot is a usage error;
   2. for each `https` grant, opens the key file and then the certificate file, once each, checks each open descriptor, and reads each from that descriptor (rule 8);
   3. binds one listening socket per grant, without `SO_REUSEPORT`, with `IPV6_V6ONLY` on IPv6, so no other process shares its connections; an address that cannot be bound is a usage error that names it. The socket sets `SO_REUSEADDR`, so a server restarts while connections of its previous run are in `TIME_WAIT`; a second listener on the same address and port is refused. On macOS and the BSDs, another local process can still bind a more specific address on the same port while a grant binds the wildcard (`0.0.0.0` or `[::]`), and then receives the connections to that address. The defense is a grant that names a specific address rather than the wildcard.
   4. for a program that serves, starts its serve threads over those listeners, which accept nothing until its first server operation (§6 rule 14).
8. **TLS files.**
   - **Opening.** Each file is opened once, following symbolic links, without blocking on a FIFO, and checked on the open descriptor with `fstat`, never by its path, so a file swapped between the check and the read is impossible. Each MUST be a regular file of at most 1 MiB. Relative paths resolve as other grants' paths do (`spec/13 §5`).
   - **The key file** MUST also be owned by the run's effective user or by root, have no write bit for its group and no bit for others (`st_mode & 0o027 == 0`), and have its group read bit only when its group is the run's effective group or a supplementary group. A key owned by another user is refused even when the run is root's.
   - **Contents.** The certificate file holds a chain of `CERTIFICATE` blocks, leaf first; the key file a private key in PKCS#8, SEC1 or PKCS#1 form. A file that cannot be read, or that holds no such block, is a usage error.
   - **The key stays in the host.** No operation returns it, and it is in no value, trace, diagnostic or report.
   - **The protocol, pinned.** TLS 1.3 only, unless the grant says `tls12`, which adds TLS 1.2 with the extended master secret required. No renegotiation, no early data, no stateless session tickets (resumption through a bounded in-memory cache only), no key log, ALPN `http/1.1` only, and no client certificates.
   - **Pending.** The check that the key matches the certificate, and the TLS server itself, wait for the decision on the project's TLS provider (#1059); until then a run with an `https` grant loads and checks its files and binds, as every grant does, and nothing accepts on any listener.
   - **Other platforms.** An `https` grant is a usage error on a platform other than macOS and Linux, until a later record defines the check of a file's access list.
