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
}
}
}
HandlerLimits
What an HttpHandler holds and refuses past.
HttpHandler
The HTTP/1.1 server: a carrier, its readiness loop, a router and a pool of requests.
HttpRequest
One request, whole: its head copied out of the carrier and its body.
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.

