Home / Docs / Specification / 31. HTTP servers
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.
-
The text form. In
--grant(spec/13 §5):serve:<scheme>://<address>:<port>, then items as suffixes;<item>.<scheme>ishttporhttps, 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.0and[::]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 withIPV6_V6ONLYreceives 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 (
0alone where the range allows it).
-
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/onceexchanges delivered and not yet answered 256 1 to 2^31 − 1 N/second,N/minute,N/hourexchanges delivered per period, a token bucket none 1 to 2^31 − 1 waiting=Nrequests read and waiting to be delivered 1024 0 to 2^31 − 1 connections=Nopen connections 1024 1 to 1,048,576 peer=Nopen connections from one peer max(16, connections / 16)1 to 1,048,576, or nonehandshakes=NTLS handshakes started per second; one peer may start max(4, N / 16)512 1 to 2^31 − 1 requests=Nrequests on one connection 1000 1 to 2^31 − 1 line=Kthe request line, in KiB 8 1 to 64 headers=Nheader lines of a request, trailers included 100 1 to 1000 header=Kthe header section, trailers included, in KiB 16 1 to 256 body=Ka request's body, in KiB 1024 0 to 1,048,576 buffers=Mbytes of request bodies held for the grant, in MiB 64 1 to 65,536 peer_buffers=Mthe share of buffersof one peer, in MiBmax(1, buffers / 64)1 to 65,536, or nonereplies=Mbytes of replies not yet written, in MiB 64 1 to 65,536 peer_replies=Mthe share of repliesof one peer under pressure, in MiBmax(1, replies / 64)1 to 65,536, or nonedelivered=Mbytes of the requests of open exchanges, in MiB 256 1 to 65,536 idle=Sseconds a connection waits for a request's first byte 5 1 to 3600 read=Sseconds to read a whole request 20 1 to 3600 write=Sseconds to write a whole reply 30 1 to 3600 answer=Sseconds from the end of a request to the start of its reply 30 1 to 86,400 hosts=a,bthe names Hostmay carry (rule 5)IP literals and localhostnames, or *certificate=F,key=Fthe certificate chain and the private key, PEM files none httpsonly, and required theretls12also accept TLS 1.2 off httpsonlyA derived default is computed from the values the grant gives, so
connections=4096makes the defaultpeer256. Sizes and counts are compared in unsigned 64-bit arithmetic that never wraps. Every default is settled: a later release may only tighten one. -
The
ita.unaform. Underrun grants,serve "<scheme>://<address>:<port>", then one item per line below it, each the item of rule 2 it names:ebnfserve_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 ;unarun 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.
-
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,keyortls12on anhttpgrant, an empty path or a path with;, and ahostsline of rule 5's errors; at the grant's line, an invalid scheme, address or port, anhttpsgrant withoutcertificateorkey, and an overlap (rule 6). - With
--grant, each is a usage error, exit code 2, before anything runs; so is aserve:grant for a single file or a package of an edition before0.4. - In
una.toml, aserve:grant is U7002 in every edition: before0.4there is no server, and from0.4the grants are read fromita.una. - A grant allows all three operations of
HttpServer.
- In
-
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 with0x, asHostwrites 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 theHostread by §3 rule 5:- without
hosts, on every grant whatever its address, the name MUST belocalhostor an IP literal, else421; - with
hosts, the name MUST equal a listed name or match a*.name, else421; an IP literal matches no name.
- without
-
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[::]:pand0.0.0.0:pdo not overlap. Inita.unathe later of two grants that overlap is U7008; among the grants of a run, manifest and flags together, an overlap is a usage error. -
Before
main. After the checks of spec/13 §5 and beforemainstarts, the host, in this order:- raises the run's limit of open descriptors to the sum of
connectionsover the grants, plus 64, within the hard limit; a run that cannot is a usage error; - for each
httpsgrant, opens the key file and then the certificate file, once each, checks each open descriptor, and reads each from that descriptor (rule 8); - binds one listening socket per grant, without
SO_REUSEPORT, withIPV6_V6ONLYon IPv6, so no other process shares its connections; an address that cannot be bound is a usage error that names it. The socket setsSO_REUSEADDR, so a server restarts while connections of its previous run are inTIME_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.0or[::]), and then receives the connections to that address. The defense is a grant that names a specific address rather than the wildcard. - for a program that serves, starts its serve threads over those listeners, which accept nothing until its first server operation (§6 rule 14).
- raises the run's limit of open descriptors to the sum of
-
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
CERTIFICATEblocks, 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, ALPNhttp/1.1only, 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
httpsgrant loads and checks its files and binds, as every grant does, and nothing accepts on any listener. - Other platforms. An
httpsgrant 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.
- Opening. Each file is opened once, following symbolic links, without blocking on a FIFO, and checked on the open descriptor with