One server for HTTP/1.1, 2 and 3
nish/net/http-server answers HTTP/1.1, HTTP/2 (over TLS or cleartext) and
HTTP/3 from one loop and one routing switch. You configure a listener for
each version you serve; every request, whichever version carried it, comes out of the same
take with the same fields, and one route body answers all three. Once an
HTTP/3 listener is configured, every HTTP/1.1 and HTTP/2 response carries an
Alt-Svc field naming its port, so a browser moves to HTTP/3 on its own.
It is the pull loop of an API server over several carriers:
wait runs one turn, ready and take hand out the requests it made whole,
and you switch on r.route, the number Router.add
answered. Reach for nish/net/handler when you serve HTTP/1.1 alone and want
its chunked request bodies, or an async server when each
request should run in a task of its own. Like nish:net, this module is
native only.
A first server
import { HttpServer, HttpServerLimits } from "nish/net/http-server";
import { Http1Config } from "nish/net/http1-server";
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 server = new HttpServer(new HttpServerLimits(), router);
server.listenHttp1(listener, new Http1Config(), 256);
const text = bytesOf("text/plain");
const hello = bytesOf("hello\n");
while (true) {
server.wait(1000);
while (server.ready()) {
const r = server.take();
switch (r.route) {
case HELLO:
server.send(r, 200, text, hello, 0, toI32(hello.length));
break;
case USER: {
const id: i32 = r.paramDecimal(0);
if (id < 0) {
server.problem(r, 400, "Bad Request", "the id is a number");
break;
}
const w = server.json();
w.beginObject();
w.key("id");
w.i32(id);
w.endObject();
server.sendJson(r, 200);
break;
}
default:
server.refuse(r); // 404, or 405 with its Allow
}
}
}
};
curl localhost:8080/users/7 answers {"id":7}; a path no route has
answers 404 and a known path with another method 405, both as
RFC 9457 problems.
Adding HTTP/2 and HTTP/3
HTTP/2 is served over TLS (ALPN h2) on a TCP socket, and HTTP/3 over QUIC on
a UDP socket. Each listener takes the socket you made, and stays yours to
close:
server.listenHttp1(tcpFd, new Http1Config(), 256);
server.listenHttp2Tls(tlsFd, tls, new Http2Config(), 64);
server.listenHttp3(udpFd, quic, new Http3Config(), 64, entropy);
for (;;) {
server.waitSigned(1000, key); // signs each handshake with the certificate's key
while (server.ready()) {
answer(server, server.take());
}
}
-
tlsis aTlsServerConfig(nish/net/tls): the certificate chain, leaf first, ALPN["h2"]and the signature scheme of your key. -
quicis aQuicServerConfig(nish/net/quic), andentropythe random bytes the QUIC listener keys its own secrets with (QUIC_LISTENER_ENTROPY_SIZEof them). -
keyis the certificate's P-256 private key, aSecret.waitSignedborrows it for the call; it stays yours to wipe. A server with only HTTP/1.1 and h2c listeners callswait, which takes no key;waitpanics once a TLS or QUIC listener is configured.
The Alt-Svc field reads h3=":<port>"; ma=86400: the UDP socket's own
port, or HttpServerLimits.altSvcPort when a proxy in front of you
publishes another. With altSvcMaxAge 0 every HTTP/1.1 and HTTP/2
over TLS response says alt-svc: clear instead, so clients forget an
earlier advertisement. A
response whose fields already name an alt-svc keeps yours. An HTTP/3
response carries none.
Cleartext HTTP/2
server.listenH2c(fd, new Http2Config(), slots) serves HTTP/2 without TLS on a
TCP listener, to clients that already know it speaks HTTP/2 (prior
knowledge: the client opens with the 24-byte preface). There is no
Upgrade: h2c from HTTP/1.1. Its requests come out of take like the rest,
with r.version 2 and r.secure false, and carry no alt-svc. A
connection that has not sent its preface within prefaceTimeout is closed,
and after the preface idleTimeout applies as on HTTP/2 over TLS.
Nothing on an h2c connection is encrypted or authenticated. Serve it only behind a proxy that ends TLS for you, or on a network you trust.
Reading a request
A request holds the same fields on every version. r.head holds its method,
target and fields, copied once out of the connection; r.body holds
r.bodyLength bytes of body. Both stay valid until you answer it.
r.version is 1, 2 or 3, and r.secure says whether it came over TLS or
QUIC: false on HTTP/1.1 and h2c.
| You want | Call |
|---|---|
| the method or path, compared | r.methodIs("POST"), r.pathIs("/health") |
route parameter k |
r.paramStart(k), r.paramEnd(k) into r.head; r.paramIs(k, "me"); r.param(k, out) percent-decodes into out; r.paramDecimal(k) is the number, or -1 |
| a query value | r.query("name", out) form-decodes into out; r.hasQuery("name"); r.queryIndex("name") sets r.queryValueStart and r.queryValueEnd |
| a field | r.header("content-type") answers its index, or HANDLER_ABSENT; r.valueStart(i), r.valueEnd(i); r.headerIs("accept", "application/json") |
A field name is matched without regard to case on every version. 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, through the server you took it from:
server.send(r, status, contentType, body, off, len)sends a body you hold.-
server.sendFields(r, status, names, values, body, off, len)adds your own fields. server.empty(r, status)sends no body.-
server.json()gives the server's JSON writer, cleared; write one value, thenserver.sendJson(r, status). server.problem(r, status, title, detail)sends an RFC 9457 problem.-
server.refuse(r)answers a request no route took: 404, or 405 withAllow. -
server.start(r, status, names, values, length), thenserver.write(r, buf, off, len)as often as you like, thenserver.end(r), streams a body. A length ofHTTP1_CHUNKEDsends one of unknown length: chunked on HTTP/1.1, plain DATA frames on HTTP/2 and HTTP/3.
Each returns HANDLER_SENT, or HANDLER_DROPPED when the client has gone:
its connection closed, or its HTTP/2 or HTTP/3 stream was reset. Either way
the request goes back to the server's pool, so do not keep it after
answering. server.hungUp(r) asks the same question before you answer, for
a request you hold while another service works. On HTTP/1.1 and HTTP/2 it
is true once the client's side of the connection has ended, which includes a
client that half-closed TCP after sending its request and may still read
the answer; send's result says whether it did.
On HTTP/2 and HTTP/3, field names are lowercase. The server writes the length and connection fields itself. A status outside 200 to 599, more or less body than the length said, a request answered twice, or one answered through another server, panics, as a bug in your program.
Limits
HttpServerLimits holds what the server refuses past. Each listener checks
its carrier's own caps against them when you configure it, and panics on one
that would let in more:
| Field | Default | Past it |
|---|---|---|
requests |
1024 | the pool every version shares is full: see below |
maxBody |
1 MiB | the request is answered 413 |
maxHead |
32 KiB | the request is answered 431 |
maxFields |
100 | the request is answered 431 |
maxResponseFields |
32 | the response is not sent; the request answers HANDLER_DROPPED |
bodyTimeout |
30 000 ms | a body still arriving that long after its head ends its request |
idleTimeout |
60 000 ms | an HTTP/2 connection, over TLS or h2c, with no open stream closes |
prefaceTimeout |
10 000 ms | an h2c connection that has not sent its preface closes |
jsonBytes |
64 KiB | sendJson answers 500 |
An HTTP/1.1 connection is held to its own Http1Config caps as well, which
may be tighter: a target past its maxTarget is answered 414.
With the pool full, an HTTP/1.1 connection stops being read until a request
is free, an HTTP/2 stream is refused with REFUSED_STREAM and an HTTP/3 one
with H3_REQUEST_REJECTED, both of which a client may retry. No one
connection holds more than a quarter of the pool, and never fewer than
one request (so at requests 1 to 3, one each), so one client cannot
starve the rest. Each request keeps a head buffer of maxHead bytes, made
the first time it is used, and holds its body whole. A body grows in steps:
up to T, the smaller of 64 KiB and maxBody, it doubles; past T it moves
once into an array of exactly maxBody. So the bodies a server holds stay
below requests times maxBody + 3T, beside the heads.
Stopping gracefully
server.watch(fd, id) and server.fired(id) add your own descriptors to the
loop, as the API server shows with
signalFd(). Then:
server.drain();
while (server.connections() > 0) {
turn(server, 100); // waitSigned, take, answer
}
drain stops accepting, closes each idle HTTP/1.1 connection at once and
each busy one after its answer, and sends GOAWAY on each HTTP/2 and HTTP/3
connection, which closes once its streams are done. A request already read is
still handed over, so answer what take gives you until connections() is
0.
HttpServer decides this for its own connections. A program that carries
its own HTTP/1.1 bytes drives an Http1Connection from
nish/net/http1-server itself, and its own drain asks each connection
before closing it:
conn.feed(buf, 0, n);
conn.headArrived(monotonicNanos()); // after every feed, so a begun head counts
// ... turn and flush the connection as usual ...
if (draining && conn.betweenRequests()) {
close(fd); // nothing read is unanswered, nothing owed is unsent
}
betweenRequests() is true while the connection speaks HTTP (not upgraded to
a WebSocket, not closing), no request is open, no next head has begun to
arrive, and every byte of the last response has been sent. A head has begun
only once headArrived has seen its bytes, so a program that feeds the
connection itself calls headArrived after each feed; skip it and
betweenRequests() can answer true while a head waits unread. When it is
false, keep turning the connection and ask again after the next flush; one
that is closing is yours to close once isDone() says everything is sent.
The library reference lists every declaration:
nish/net/http-server. What the
module was reviewed for is its
security record.

