An API server
nish/net/handler answers HTTP/1.1 requests. It owns the readiness loop, the
connections and everything between a request's first byte and its response's
last: it accepts, routes each request through a
Router as soon as its head arrives, gathers its body, and
hands your program the request once it is whole. Your program reads it and
answers it. Keep-alive, pipelining, chunked bodies, HEAD, timeouts and the
body cap are taken care of.
You do not register a callback per route. Your program pulls: wait runs
one turn of the loop, ready and take give out the requests it made whole,
and you dispatch on req.route — the number Router.add answered, or a
negative ROUTER_* code — with a switch. An async program that would rather hand each request to a function
of its own, in a task that may await, uses an async server.
A first server
import { HandlerLimits, HttpHandler } from "nish/net/handler";
import { Router, RouterLimits } from "nish/net/router";
import { tcpListen } from "nish:net";
// The routes, in the order they are added: `add` answers 0, 1.
const HELLO: i32 = 0;
const USER: i32 = 1;
const bytesOf = (text: string): u8[] => {
const out: u8[] = [];
for (let i: i32 = 0; i < toI32(text.length); i++) {
out.push(toU8(text.charCodeAt(i)));
}
return out;
};
export const main = (): i32 => {
const router = new Router(new RouterLimits());
router.add("GET", "/");
router.add("GET", "/users/:id");
const listener: i32 = tcpListen("127.0.0.1", 8080, 1024);
if (listener < 0) {
console.error(`cannot listen: ${listener}`);
return 1;
}
const h = new HttpHandler(new HandlerLimits(), listener, router);
const text = bytesOf("text/plain");
const hello = bytesOf("hello\n");
while (true) {
h.wait(1000);
while (h.ready()) {
const req = h.take();
switch (req.route) {
case HELLO:
h.send(req, 200, text, hello, 0, toI32(hello.length));
break;
case USER: {
const id: i32 = req.paramDecimal(0);
if (id < 0) {
h.problem(req, 400, "Bad Request", "the id is a number");
break;
}
const w = h.json();
w.beginObject();
w.key("id");
w.i32(id);
w.endObject();
h.sendJson(req, 200);
break;
}
default:
h.refuse(req); // 404, or 405 with its Allow
}
}
}
};
curl localhost:8080/users/7 answers {"id":7}; curl -X POST localhost:8080/ answers 405 with Allow: GET, HEAD; any other path a 404.
Both refusals are RFC 9457 problems,
application/problem+json.
Reading a request
Everything a request holds is a range of bytes in its own buffers, req.head
(the request line and the fields) and req.body (req.bodyLength bytes), and
stays valid until you answer it. Nothing is copied unless you ask.
| You want | Call |
|---|---|
| the method or path, compared | req.methodIs("POST"), req.pathIs("/health") |
route parameter k |
req.paramStart(k), req.paramEnd(k) into req.head; req.paramIs(k, "me"); req.param(k, out) percent-decodes into out; req.paramDecimal(k) is the number, or -1 |
| a query value | req.query("name", out) form-decodes into out; req.hasQuery("name"); req.queryIndex("name") sets req.queryValueStart and req.queryValueEnd |
| a field | req.header("content-type") answers its index, or HANDLER_ABSENT; req.valueStart(i), req.valueEnd(i); req.headerIs("accept", "application/json") |
A decoded parameter or query value can hold any byte, /, .. and NUL
among them; check it before you use it as a file name.
Answering
Every request you take is answered exactly once:
h.send(req, status, contentType, body, off, len)sends a body you hold.-
h.sendFields(req, status, names, values, body, off, len)adds your own fields. h.empty(req, status)sends no body (a 204, say).-
h.json()gives the handler's JSON writer, cleared; write one value, thenh.sendJson(req, status). A value that outgrewHandlerLimits.jsonBytesis answered 500 instead. -
h.problem(req, status, title, detail)sends an RFC 9457 problem. One too large forjsonBytesis sent without its detail. h.refuse(req)answers a request no route took: 404, or 405 withAllow.-
h.start(req, status, names, values, length), thenh.write(req, buf, off, len)as often as you like, thenh.end(req), streams a body; a length of -1 sends it chunked.
The handler writes Content-Length, Transfer-Encoding, Connection and
Date itself; naming one of the first four yourself, a status outside 200 to
599, more or less body than the length said, or sendJson with no json()
before it, panics, as a bug in your program.
A request may be answered later, after a database answers, say: keep it
and answer it in a later turn. If its client has gone in the meantime, the
answer returns HANDLER_DROPPED and sends nothing, even when a new connection
has taken the old one's place. Either way the request goes back to the
handler's pool, so do not keep it after answering.
Limits
HandlerLimits holds what the handler refuses past:
| Field | Default | Past it |
|---|---|---|
http.maxBody |
1 MiB | the request is answered 413 and its connection ends |
bodyTimeout |
30 000 ms | a body still arriving that long after its head ends its connection |
slots |
256 | a new connection is accepted and closed at once |
jsonBytes |
64 KiB | sendJson answers 500 |
maxEvents |
256 | readiness events wait for the next turn |
ring |
false | not a limit: open the listener with limits.listen, and on Linux it takes connections into io_uring slots, so slots may pass the descriptor limit; a kernel that refuses rings serves descriptors, and netRingState() says why (networking) |
When the process runs out of descriptors, or a ring listener out of slots, a
waiting connection stays in the listener's backlog: the handler stops
accepting until a connection closes or 100 ms pass, rather than spin.
h.resting() is true while it does.
http is the HTTP/1.1 carrier's own configuration (Http1Config): its head
size and field count caps, its head timeout and its idle timeout. The idle
timeout restarts on every byte, so bodyTimeout is what stops a client that
sends its body one byte at a time. Each slot
keeps a body buffer as large as the largest body it has held, so a server
holds at most slots times http.maxBody in bodies. Once warm, a request
allocates nothing.
Stopping gracefully
h.watch(fd, id) adds one of your own descriptors to the loop, and
h.fired(id) says whether it was ready in the last wait. With
signalFd() from nish:process, SIGINT and SIGTERM become a descriptor:
const signals: i32 = signalFd();
h.watch(signals, 0);
while (!h.fired(0)) {
serve(h, 1000); // wait, take, answer
}
h.drain();
while (h.connections() > 0) {
serve(h, 100);
}
netClose(listener);
drain stops accepting, closes each idle connection at once, and closes each
busy one once the request on it is answered and sent: that answer says
Connection: close, and a request pipelined behind it is not read. A request already read
is still handed over, so answer what take gives you until connections()
is 0. Put a deadline on that second loop if a client may never read its
answer.
A whole example
examples/http-app is a JSON notes API on this page's pieces: command-line
flags, a log line a request, problems for bad input, and the graceful stop
above with a deadline. Build it with nish examples/http-app/main.ts --link http-app and run ./http-app 8080. Copy it and change it: logging and
configuration are left to the example because every server wants them a
little differently.
The handler speaks HTTP/1.1 only. For HTTP/2 and HTTP/3, drive
nish/net/http2-tls and nish/net/http3-server directly, routing with the
same table (HTTP routing).
Http3Server times its own clients: a connection with no request open past
Http3Config.idleTimeout (60 s by default) is closed with H3_NO_ERROR, and
one still sending a request's head past headTimeout (30 s) with
H3_EXCESSIVE_LOAD. A body that trickles after its head is the handler's to
time, as bodyTimeout does for HTTP/1.1.

