nish/net/handler

Complete requests and their responses over the HTTP/1.1 carrier, so that a server answers requests instead of driving Http1Server's events by hand.

import {
  HANDLER_ABSENT,
  HANDLER_DROPPED,
  HANDLER_MAX_WATCHED,
  HANDLER_SENT,
  HandlerLimits,
  HttpHandler,
  HttpRequest,
} from "nish/net/handler";
const HOME: i32 = 0   // module constants, in the order the routes are added
const USER: i32 = 1
const router = new Router(new RouterLimits())
router.add("GET", "/")          // answers HOME
router.add("GET", "/users/:id") // answers USER
const h = new HttpHandler(new HandlerLimits(), tcpListen("0.0.0.0", 8080, 1024), router)
while (true) {
  h.wait(1000)
  while (h.ready()) {
    const req = h.take()
    switch (req.route) {
      case HOME: h.send(req, 200, TEXT, hello, 0, hello.length); break
      case USER: { const w = h.json(); ...; h.sendJson(req, 200); break }
      default: h.refuse(req)   // 404, or 405 with its Allow
    }
  }
}

The handler owns the readiness loop, the carrier and everything between a request's first byte and its last response byte: it accepts, routes each request at its head, gathers its body up to the cap, and hands the program the request once it is whole. Keep-alive and pipelining are the carrier's: a connection's next request is read only once the one before it is answered and handed over, so answers go out in request order.

There are no function values

There are no function values, so the program pulls: wait runs one turn of the loop, ready and take give out the whole requests it made, and the program dispatches on req.route — the index Router.add answered, or a negative ROUTER_* code — with a switch on module constants, as nish/net/router describes.

A request may be answered later

A request the program has taken stays its own until it answers it, in the same turn or in a later one (after a database answers, say). Every request taken is answered exactly once, by send, sendFields, sendJson, problem, refuse or start ... end, and once answered the request object is the handler's again: it goes back to a free list and serves a later request, so the program keeps no reference to it.

An answer that comes too late is dropped

Each slot carries a generation, bumped whenever its connection closes, and a request remembers the generation it was read under. An answer for a request whose connection has closed in the meantime — the peer left, the idle timeout passed — answers HANDLER_DROPPED and sends nothing, even when a new connection has taken the slot since. The answer still hands the request back, so nothing leaks.

Nothing is allocated per request once warm

A request's method, target and header section are copied out of the carrier's head into the request's own buffer at H1_REQUEST (the parser reuses its own for the next request), and everything the program reads is a span into that copy or into the body buffer. Those buffers, the free list and the queue grow to the largest request seen and are kept; JSON is written into one scratch buffer the handler owns. tests/link/net_handler pins Arena.used() flat over thousands of requests.

The body cap is the carrier's maxBody, which HandlerLimits sets to one MiB: a declared length over it, or a chunked body that grows past it, is answered 413 by the carrier and the connection ends. A request's body buffer grows to the body it holds, so a handler holds at most its slots times the cap in bodies. docs/security/handler.md is the record.

Misuse — a status outside 200 to 599, a reserved field (Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive), more body than the length said, a second start — panics: it is a bug in the program, never something a peer can cause. What a peer can cause answers a code the program may ignore, so no answer needs its result bound.

Private helpers share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e), which is why each one carries the module's name.

Written from RFC 9110, RFC 9112 and RFC 9457, not ported from another implementation.

Classes

HandlerLimits

What an HttpHandler holds and refuses past. http is the carrier's own configuration, made here with its body cap lowered to one MiB because the handler holds a body whole; raise http.maxBody for a server that takes larger bodies, knowing each slot may keep a buffer that large.

class HandlerLimits
Member
new HandlerLimits() The defaults: 256 slots, a 64 KiB JSON buffer, 256 events a turn, a 30 second body timeout, and the carrier's own defaults with the body cap lowered to one MiB. Change a field after construction to tune one.
bodyTimeout: i32 Milliseconds from a request's head to the end of its body. A request still reading its body past it has its connection closed: the carrier's idleTimeout is refreshed by every byte, so a body trickled a byte at a time would otherwise hold its slot for good (HANDLER-5). It is checked each wait, at most once a second, so a connection may outlive it by up to a second, or until wait returns.
http: Http1Config The carrier's caps and timeouts; http.maxBody is the body cap, past which a request is answered 413.
jsonBytes: i32 Bytes in the JSON scratch buffer: the largest body json and problem can write. A value past it makes sendJson answer 500. At least 256.
maxEvents: i32 The most readiness events one wait takes.
ring: boolean Whether listen opens its listener with NET_LISTEN_RING, so each connection is accepted into an io_uring slot rather than a descriptor. Off by default. Where the kernel refuses rings, the listener serves descriptors and netRingState says why. A connection is then a slot handle, which sendFd and a C library through nish:ffi cannot take.
slots: i32 The most connections at once. It is the handler's own cap, not RLIMIT_NOFILE: with ring set the connections live in io_uring slots and may outnumber the descriptor limit. Past it a connection is accepted and closed at once.
listen(host: string, port: i32, backlog: i32, flags: i32): i32 Opens a TCP listener for an HttpHandler with these limits: tcpListenFlags with flags, plus NET_LISTEN_RING when ring is set.

HttpHandler

The HTTP/1.1 server: a carrier, its readiness loop, a router and a pool of requests. One per thread; nothing in it is shared.

class HttpHandler
Member
new HttpHandler(limits: HandlerLimits, listener: i32, router: Router) A handler over listener, a listening socket the program made (tcpListen, or tcpListenFlags with SO_REUSEPORT for a worker of nish/net/prefork), routing through router, whose routes are added before the first wait. limits.ring acts only through the listener: open it with limits.listen, since a listener from tcpListen stays on descriptors whatever ring says.
scratch: u8[] json and problem write here.
connections(): i32 How many connections are open.
deferSends(): void Lets the handler put a connection's send off until flush, so the answers to a pipelined burst go out in one write. Off by default, so an answer is sent as it ends. A program that turns it on calls flush (or wait, which flushes) after each turn of answers, before it blocks; nish/net/serve does.
drain(): void Begins a graceful stop: the handler accepts no more connections, closes each idle one now, and closes each other one once the request on it is answered and sent, so connections() falls to 0 as the program answers what it holds. A request already read on a draining connection is still handed over and answered. The listener is the program's to close.
empty(r: HttpRequest, status: i32): i32 Answers r with status and no body: a 204, or a status whose meaning is all there is to say.
end(r: HttpRequest): i32 Ends r's response. r is the handler's again: it goes back once the carrier has taken every byte, and the connection's next request is read. Answers HANDLER_SENT or HANDLER_DROPPED. After deferSends the send may be put off so a pipelined burst goes out in one write: call wait or flush after answering, or it waits for the next of them.
fired(id: i32): boolean Whether watched descriptor id was ready in the last wait.
flush(): void Sends every answer whose send was put off, so the connection's answers to a pipelined burst go out in one write. wait calls it before it blocks; a program that blocks elsewhere, as nish/net/serve does, calls it first.
hungUp(r: HttpRequest): boolean Whether the client of r has hung up: its connection is closed or reused, or the peer ended its stream while r is held. A half-close counts, as nginx counts it, so a hung task is cancelled rather than kept for a reader who may be gone.
json(): JsonWriter The JSON writer, reset onto the handler's scratch buffer: write one value with it, then sendJson. One JSON body at a time, since every request shares the buffer.
pooled(): i32 How many requests the pool has made: the most ever in flight at once.
problem(r: HttpRequest, status: i32, title: string, detail: string): i32 Answers r with an RFC 9457 problem: application/problem+json with type about:blank, title (the status's reason, for that type), status and, when not empty, detail, a sentence for a person about this occurrence. Nothing of the request is echoed, so a detail is the program's own words.
ready(): boolean Whether a whole request is waiting for take. Requests whose connection closed while queued are handed back here.
refuse(r: HttpRequest): i32 Answers a request the router refused, by its route: 405 with an Allow field naming the methods the path has (RFC 9110 §15.5.6), and 404 for anything else. A parameter's malformed escape is the program's to refuse, when it decodes the parameter.
resting(): boolean Whether the listener is resting: an accept failed for want of a resource (EMFILE for descriptors, ENFILE for ring slots, ENOMEM), so the handler takes no connection until one closes or the 100 ms rest ends. During drain() a close does not end the rest, so it stays true until the 100 ms pass.
send(r: HttpRequest, status: i32, contentType: u8[], body: u8[], off: i32, len: i32): i32 Answers r with status, a Content-Type of contentType and the body body[off .. off + len), in one call.
sendFields(r: HttpRequest, status: i32, names: u8[][], values: u8[][], body: u8[], off: i32, len: i32): i32 Answers r with status, the fields names[k]: values[k] and the body body[off .. off + len), in one call.
sendJson(r: HttpRequest, status: i32): i32 Answers r with status and the value json's writer holds, as application/json. A value the writer refused or did not finish — it outgrew jsonBytes, say — is answered as a 500 problem instead.
sends(): i64 How many times the handler handed a connection's waiting output to its socket: one per connection per pass, however many answers it holds.
start(r: HttpRequest, status: i32, names: u8[][], values: u8[][], bodyLength: i32): i32 Starts r's response: status (200 to 599), the fields names[k]: values[k], and a body of bodyLength bytes or HTTP1_CHUNKED; then write the body and end. Answers HANDLER_SENT, or HANDLER_DROPPED when r's connection has closed — every later write and end for it then does nothing, and end hands it back.
take(): HttpRequest The next whole request, which the program now owes an answer. Panics when none is ready.
wait(timeoutMs: i32): i32 One turn of the loop: waits up to timeoutMs (-1 for no limit) for a socket to be ready, accepts, reads and writes what is, closes the connections past their timeouts, and answers how many whole requests are waiting for take.
watch(fd: i32, id: i32): void Watches fd for reading beside the handler's sockets, as id (0 to HANDLER_MAX_WATCHED - 1): fired(id) says whether it was ready in the last wait. For a program's own descriptors — signalFd() for a graceful stop, a pipe from another thread.
write(r: HttpRequest, buf: u8[], off: i32, len: i32): i32 Writes buf[off .. off + len) of r's body. What the carrier has no room for is copied and sent as room comes, so buf is the caller's again on return. Answers HANDLER_SENT or HANDLER_DROPPED.

HttpRequest

One request, whole: its head copied out of the carrier and its body. Every position is an offset into head or body, which are the request's own and stay valid until it is answered.

class HttpRequest
Member
new HttpRequest(index: i32) An empty request for the handler's pool; its buffers grow to the first request it holds and are kept for the ones after.
body: u8[] The body, body[0 .. bodyLength).
bodyLength: i32 How many bytes of body are the request's body, 0 for none; read the body as body[0 .. bodyLength).
head: u8[] The method, the target and the header section, as the parser kept them (field names lowercased).
index: i32 Its index in the handler's pool.
methodEnd: i32 Where the method ends in head, one past its last byte.
methodStart: i32 Where the method starts in head; the method is head[methodStart .. methodEnd), for a log line or a Router.match.
queryValueEnd: i32 Where the raw value queryIndex found ends in head, one past its last byte; it starts at queryValueStart.
queryValueStart: i32 The span queryIndex found, raw.
route: i32 The index Router.add answered for the route, or a negative ROUTER_* code.
slot: i32 The connection's slot, and its generation when this request was read.
targetEnd: i32 Where the request target ends in head, one past its last byte.
targetStart: i32 Where the request target (path and query) starts in head; the target is head[targetStart .. targetEnd).
hasQuery(name: string): boolean Whether the query holds a parameter named name.
header(name: string): i32 The index of the first field named name, which is lowercase, or HANDLER_ABSENT.
headerIs(name: string, value: string): boolean Whether the first field named name (lowercase) has exactly the value value.
methodIs(method: string): boolean Whether the method is exactly method (methods are case-sensitive, RFC 9110 §9.1).
param(k: i32, out: u8[]): i32 Parameter k percent-decoded into out from 0 (routerDecode): its length, ROUTER_BAD_ESCAPE for a malformed escape, or ROUTER_NO_ROOM when out is too short. Nothing is written on a code.
paramDecimal(k: i32): i32 Parameter k read as a decimal number that is not negative and fits an i32, or -1.
paramEnd(k: i32): i32 Where parameter k ends in head.
paramIs(k: i32, text: string): boolean Whether parameter k, raw, is exactly text.
paramStart(k: i32): i32 Where parameter k starts in head. Panics on a parameter the route does not have.
pathIs(path: string): boolean Whether the path, the target up to its ?, is exactly path.
query(name: string, out: u8[]): i32 The first query parameter named name, its value decoded into out from 0 — + as a space and %XX as its byte, the form encoding (application/x-www-form-urlencoded) — and its length; a name is compared decoded too. HANDLER_ABSENT when no parameter has the name, ROUTER_BAD_ESCAPE for a malformed escape in its value, ROUTER_NO_ROOM when out is too short. A name with no = has an empty value.
queryIndex(name: string): i32 Finds the first parameter named name: where its pair starts, or -1; its raw value goes to queryValue....
valueEnd(i: i32): i32 Where field i's value ends in head.
valueStart(i: i32): i32 Where field i's value starts in head.

Limits

16

HANDLER_MAX_WATCHED: i32

The most descriptors watch takes beside the handler's own.

Constants

-20

HANDLER_ABSENT: i32

HttpRequest.query and header: no such name.

-21

HANDLER_DROPPED: i32

An answer for a request whose connection closed first: nothing was sent.

0

HANDLER_SENT: i32

An answer sent, or queued to be sent.