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)
}

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
reqRequestrequired

the request to refuse; the loop answers it from the request it holds

returnsResponse

a 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>
porti32required

the TCP port to listen on

routerRouterrequired

the routes, added before the call; a request's route is the index Router.add answered

limitsServeLimitsrequired

the caps; see ServeLimits

handle(req: Request) => Promise<Response>required

the 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>
listeneri32required

the listening socket, still the program's to close

routerRouterrequired

the routes, added before the call

limitsServeLimitsrequired

the caps; see ServeLimits

handle(req: Request) => Promise<Response>required

the program's answer to a request, run as its own task

statsServeStatsrequired

where 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.