nish/net/serve
An HTTP/1.1 server for an async program: one task and one region per request, answers in request order.
import {
Request,
Response,
ServeLimits,
ServeStats,
refuse,
serve,
serveOn,
} from "nish/net/serve";
import { Request, Response, ServeLimits, refuse, serve } from "nish/net/serve"
import { Router, RouterLimits } from "nish/net/router"
import { sleep } from "nish:async"
const HOME: i32 = 0 // module constants, in the order the routes are added
const USER: i32 = 1
const handle = async (req: Request): Promise<Response> => {
switch (req.route) {
case HOME: return new Response(200).text("hello\n")
case USER: {
await sleep(5) // a database, another service: the loop runs on
return new Response(200).json(`{"id":"${req.param(0)}"}`)
}
default: return refuse(req) // 404, or 405 with its Allow
}
}
export const main = async (): Promise<i32> => {
const router = new Router(new RouterLimits())
router.add("GET", "/")
router.add("GET", "/users/:id")
return await serve(8080, router, new ServeLimits(), handle)
}
refuse
The answer for a request the router refused: 405 with an Allow field naming the methods the path has, and 404 for anything else.
serve
Serves HTTP/1.1 on port on every address, handing each request to handle in a task of its own, until limits.maxRequests are answered (for good when it is 0).
serveOn
serve on a listening socket the program made — tcpListen on port 0 in a test, or tcpListenFlags with SO_REUSEPORT for a worker — filling stats as it runs.
Request
A request, as handle reads it: the task's own copy of the head and body, valid for as long as the task runs.
Response
The answer handle gives: a status, a content type and a body.
ServeLimits
The caps a server holds every request and connection to; each field is read once, by serve.
ServeStats
What a server did, for a log line or a test; serveOn fills it as it runs.
serve drives nish/net/http1-server's connections from a readiness loop
of its own, as an async function: it awaits the loop's descriptor, so
the program's other tasks run while no socket is ready. It routes each
request at its head, gathers its body, and hands the whole request to
handle in a task of its own, spawned with the request's slot; the
task's allocations — the request it reads, the response it builds,
whatever handle makes on the way — live in the task's region and go
when it ends.
The task reads its own copy
Until it is answered, a request's head is
the connection parser's own buffer, read in place. The task copies the
head and body into its own memory before handle runs, as spawn runs it
that far at once,
and when handle answers it writes the status, the content type and the
body back into the slot's fixed buffers, in bulk, and wakes the
loop. The loop then sends the answer and frees the slot. Nothing the task
allocated outlives it, and the loop's arena does not grow per request once
its slots are warm: tests/link/net_serve_pipelined_flat pins
Arena.used() flat over thousands of pipelined requests. What the runtime
allocates outside the arena for a task and its region is not measured.
Answers keep request order
The server reads a connection's next request only once the one before it is answered, so at most one request per connection is in flight, and pipelined requests are answered in the order they came: a later request's task starts only after the earlier one is answered, so it can never finish first.
A pipelined burst goes out in one write
The loop answers what the
tasks wrote and takes what the connections queued until neither moves, so
a handle that answers without waiting serves a whole burst in one turn.
The loop holds each answer's send while the next request on its
connection is queued and the output has room, and the loop flushes once
before it parks: one write per connection per turn, and no wake byte for a
task that answers while the loop runs.
Every cap answers. ServeLimits bounds the connections, the requests
in flight (503 past it), a request's header section (431) and body (413),
and the response a task may write (500 past it). docs/security/serve.md
is the record.
readable is refused under --emit-ts (NL4017), so a program that serves
is native only.
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.
Functions
refuse
The answer for a request the router refused: 405 with an Allow field
naming the methods the path has, and 404 for anything else.
const refuse: (req: Request) => Response
reqRequestrequiredthe request to refuse; the loop answers it from the request it holds
returnsResponsea response the server answers with 404, or 405 and an Allow field naming the methods its path has
serve
Serves HTTP/1.1 on port on every address, handing each request to
handle in a task of its own, until limits.maxRequests are answered (for
good when it is 0).
const serve: (
port: i32,
router: Router,
limits: ServeLimits,
handle: (req: Request) => Promise<Response>,
) => Promise<i32>
porti32requiredthe TCP port to listen on
routerRouterrequiredthe routes, added before the call; a request's route is the index Router.add answered
limitsServeLimitsrequiredthe caps; see ServeLimits
handle(req: Request) => Promise<Response>requiredthe program's answer to a request, run as its own task
returnsPromise<i32>0 once stopped, or the negative error tcpListen answered
serveOn
serve on a listening socket the program made — tcpListen on port 0 in
a test, or tcpListenFlags with SO_REUSEPORT for a worker — filling
stats as it runs.
const serveOn: (
listener: i32,
router: Router,
limits: ServeLimits,
handle: (req: Request) => Promise<Response>,
stats: ServeStats,
) => Promise<i32>
listeneri32requiredthe listening socket, still the program's to close
routerRouterrequiredthe routes, added before the call
limitsServeLimitsrequiredthe caps; see ServeLimits
handle(req: Request) => Promise<Response>requiredthe program's answer to a request, run as its own task
statsServeStatsrequiredwhere the server counts what it did, the caller's
returnsPromise<i32>0 once stopped
Classes
Request
A request, as handle reads it: the task's own copy of the head and body,
valid for as long as the task runs.
class Request
| Member | |
|---|---|
new Request(raw: HttpRequest) |
A request over raw, which it keeps. |
raw: HttpRequest |
The request as the server parsed it, copied into the task: its spans, its head and its body. |
route: i32 |
The index Router.add answered for the route, or a negative ROUTER_* code. |
header(name: string): string |
The value of the first header field named name. |
method(): string |
The method. |
param(k: i32): string |
Route parameter k, percent-decoded. Panics when the request's route has no parameter k. |
paramMalformed(k: i32): boolean |
Whether route parameter k holds a malformed percent escape, which a program answers 400. Panics when the request's route has no parameter k. |
paramNumber(k: i32): i32 |
Route parameter k read as a decimal number that is not negative and fits an i32. Panics when the request's route has no parameter k. |
path(): string |
The path: the target up to its ?, still percent-encoded. |
query(name: string): string |
The first query parameter named name, form-decoded (+ as a space, %XX as its byte). |
text(): string |
The body as text. |
Response
The answer handle gives: a status, a content type and a body. Build it
with new Response(status) and one of text, json or bytes, or with
refuse.
class Response
| Member | |
|---|---|
new Response(status: i32) |
An answer with status and no body yet. |
body: u8[] |
The body, body[0 .. length). |
length: i32 |
How many bytes of body are the body. |
status: i32 |
The status, from 200 to 599; any other is answered 500. |
type: string |
The Content-Type value; empty sends none, and the body goes without one. |
bytes(type: string, buf: u8[], off: i32, len: i32): Response |
Sets a body of bytes with a content type. |
json(s: string): Response |
Sets a JSON body the program wrote. |
text(s: string): Response |
Sets a plain-text body. |
ServeLimits
The caps a server holds every request and connection to; each field is read once, by serve.
class ServeLimits
| Member | |
|---|---|
new ServeLimits() |
|
bodyBytes: i32 |
The most bytes a request body may have; past it the request is answered 413 and its connection ends. |
connections: i32 |
The most connections open at once; a connection past it is accepted and closed at once, and its client sees the connection reset. |
deadline: i32 |
Milliseconds a request's task may run, from its start to its answer; past it the task is cancelled: each await it is parked on, and each it makes later, answers false at once, so it runs to its end and its slot is freed. 0 or less sets no limit. |
headerBytes: i32 |
The most bytes a request's header section may have; past it the request is answered 431 and its connection ends. |
headTimeout: i32 |
Milliseconds a connection may take to send a whole request head, from its first byte; past it the connection is closed. The bound on a client that trickles its head (slowloris): it holds a connection this long, no longer. |
idleTimeout: i32 |
Milliseconds a connection may go without a byte read or written, as a keep-alive connection does between requests; past it the connection is closed, freeing its slot. |
inFlight: i32 |
The most requests in flight — handed to a task and not yet answered — at once; past it a request is answered 503. |
maxRequests: i32 |
How many requests to answer before stopping: the server then stops accepting, finishes what it holds and returns. 0, the default, serves for good. |
responseBytes: i32 |
The most bytes a response body may have; a task that answers more is answered 500 instead. |
server: string |
The Server field written into the head of every answer a task writes, as server: <value>; "", the default, writes none. The answers the server writes itself carry none: a refuse (404, or 405 with its Allow) and 400, 413, 431, 500 and 503. Made into bytes once, when the server starts, so it costs no work per request. A control byte in it panics as the server starts. |
ServeStats
What a server did, for a log line or a test; serveOn fills it as it runs.
class ServeStats
| Member | |
|---|---|
new ServeStats() |
|
answered: i32 |
Requests answered, by a task or by the server itself. |
busy: i32 |
Requests answered 503 because inFlight tasks were already running. |
failed: i32 |
Answers a task wrote that broke a cap or a rule, answered 500 instead. |
sends: i64 |
The writes the server began to send answers, counted at the end of each loop turn: a pipelined burst that fits the output is one. |
slots: i32 |
How many slots the server made: the most requests ever in flight at once. |
usedEnd: i64 |
Arena.used() in the server's loop once maxRequests were answered, before draining. |
usedWarm: i64 |
Arena.used() in the server's loop once warmAfter requests were answered. |
warmAfter: i32 |
After how many answers to read usedWarm; 0 reads it never. |

