@amritk/nish-aarch64-darwin 0.35.0 → 0.37.0

package/std/net/handler.ts

@@ -162,7 +162,10 @@ export class HandlerLimits {
   http: Http1Config
   /** The most connections at once. */
   slots: i32 = 256
-  /** The JSON scratch buffer's size: the largest body `json` and `problem` can write. */
+  /**
+   * 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.
+   */
   jsonBytes: i32 = 65536
   /** The most readiness events one `wait` takes. */
   maxEvents: i32 = 256
@@ -176,6 +179,11 @@ export class HandlerLimits {
    */
   bodyTimeout: i32 = 30000
 
+  /**
+   * 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.
+   */
   constructor() {
     this.http = new Http1Config()
     this.http.maxBody = HANDLER_ONE_MIB
@@ -190,37 +198,85 @@ export class HandlerLimits {
 export class HttpRequest {
   /** The method, the target and the header section, as the parser kept them (field names lowercased). */
   head: u8[]
-  /** Four per field, into `head`: name start and end, value start and end. */
+  /**
+   * Four per field, into `head`: name start and end, value start and end.
+   * @internal Filled by `HttpHandler` in this module when it copies the head, and read by `header`, `valueStart` and `valueEnd`.
+   */
   spans: i32[]
-  /** The route parameters as `[start, end)` pairs into `head`, in the pattern's order. */
+  /**
+   * The route parameters as `[start, end)` pairs into `head`, in the pattern's order.
+   * @internal Filled by `HttpHandler` in this module from `Router.match`; programs read them through `paramStart`, `param` and the rest.
+   */
   params: i32[]
   /** The body, `body[0 .. bodyLength)`. */
   body: u8[]
-  /** What the carrier had no room for yet: `pending[pendingStart .. pendingEnd)`. */
+  /**
+   * What the carrier had no room for yet: `pending[pendingStart .. pendingEnd)`.
+   * @internal Written and flushed by `HttpHandler` in this module while it streams the response.
+   */
   pending: u8[]
-  /** When the head was read, as the handler's turn saw it (`monotonicNanos`); `bodyTimeout` runs from here. */
+  /**
+   * When the head was read, as the handler's turn saw it (`monotonicNanos`); `bodyTimeout` runs from here.
+   * @internal Stamped and checked by `HttpHandler` in this module to close a connection whose body trickles past `bodyTimeout`.
+   */
   since: i64 = 0
   /** The index `Router.add` answered for the route, or a negative `ROUTER_*` code. */
   route: i32 = 0
-  /** How many parameter pairs `params` holds. */
+  /**
+   * How many parameter pairs `params` holds.
+   * @internal Set by `HttpHandler` in this module after routing; the param accessors check `k` against it.
+   */
   paramCount: i32 = 0
+  /** Where the method starts in `head`; the method is `head[methodStart .. methodEnd)`, for a log line or a `Router.match`. */
   methodStart: i32 = 0
+  /** Where the method ends in `head`, one past its last byte. */
   methodEnd: i32 = 0
+  /** Where the request target (path and query) starts in `head`; the target is `head[targetStart .. targetEnd)`. */
   targetStart: i32 = 0
+  /** Where the request target ends in `head`, one past its last byte. */
   targetEnd: i32 = 0
-  /** Where the path ends: the target's first `?`, or its end. */
+  /**
+   * Where the path ends: the target's first `?`, or its end.
+   * @internal Set by `HttpHandler` in this module when it copies the head, and read by `pathIs` and `queryIndex`.
+   */
   pathEnd: i32 = 0
+  /**
+   * How many fields `spans` describes.
+   * @internal Set by `HttpHandler` in this module when it copies the head, and read by `header`.
+   */
   headerCount: i32 = 0
+  /** How many bytes of `body` are the request's body, 0 for none; read the body as `body[0 .. bodyLength)`. */
   bodyLength: i32 = 0
   /** The connection's slot, and its generation when this request was read. */
   slot: i32 = 0
+  /**
+   * The slot's generation when this request was read.
+   * @internal Read by `HttpHandler` in this module, which drops a reply to a slot that has since closed and been reused.
+   */
   gen: i32 = 0
   /** Its index in the handler's pool. */
   index: i32 = 0
+  /**
+   * Where the request is in its life, one of the module's private `HANDLER_*` states.
+   * @internal Moved by `HttpHandler` in this module from the free list through reading, queued, held and streaming, and back.
+   */
   state: i32 = 0
+  /**
+   * Where the unsent bytes in `pending` start.
+   * @internal Advanced by `HttpHandler` in this module as the carrier takes pending bytes.
+   */
   pendingStart: i32 = 0
+  /**
+   * Where the unsent bytes in `pending` end.
+   * @internal Advanced by `HttpHandler` in this module as `write` keeps what the carrier had no room for.
+   */
   pendingEnd: i32 = 0
 
+  /**
+   * An empty request for the handler's pool; its buffers grow to the first
+   * request it holds and are kept for the ones after.
+   * @param index its place in the handler's pool, which the free list and the queue name it by
+   */
   constructor(index: i32) {
     this.index = index
     this.head = []
@@ -230,29 +286,50 @@ export class HttpRequest {
     this.pending = []
   }
 
-  /** Whether the method is exactly `method` (methods are case-sensitive, RFC 9110 §9.1). */
+  /**
+   * Whether the method is exactly `method` (methods are case-sensitive, RFC 9110 §9.1).
+   * @param method the method name to compare with, such as `"GET"`
+   * @returns true when the request's method is byte for byte `method`
+   */
   methodIs(method: string): boolean {
     return handlerSpanIs(this.head, this.methodStart, this.methodEnd, method)
   }
 
-  /** Whether the path, the target up to its `?`, is exactly `path`. */
+  /**
+   * Whether the path, the target up to its `?`, is exactly `path`.
+   * @param path the raw path to compare with, still percent-encoded as it came on the wire
+   * @returns true when the target's path, without its query, is byte for byte `path`
+   */
   pathIs(path: string): boolean {
     return handlerSpanIs(this.head, this.targetStart, this.pathEnd, path)
   }
 
-  /** Where parameter `k` starts in `head`. Panics on a parameter the route does not have. */
+  /**
+   * Where parameter `k` starts in `head`. Panics on a parameter the route does not have.
+   * @param k the parameter's position in the route pattern, from 0
+   * @returns the byte offset in `head` of the parameter's first raw byte
+   */
   paramStart(k: i32): i32 {
     this.checkParam(k)
     return this.params[2 * k]
   }
 
-  /** Where parameter `k` ends in `head`. */
+  /**
+   * Where parameter `k` ends in `head`.
+   * @param k the parameter's position in the route pattern, from 0
+   * @returns the byte offset in `head` just past the parameter's last raw byte
+   */
   paramEnd(k: i32): i32 {
     this.checkParam(k)
     return this.params[2 * k + 1]
   }
 
-  /** Whether parameter `k`, raw, is exactly `text`. */
+  /**
+   * Whether parameter `k`, raw, is exactly `text`.
+   * @param k the parameter's position in the route pattern, from 0
+   * @param text the value to compare with, as it would appear still percent-encoded
+   * @returns true when the raw parameter bytes are exactly `text`
+   */
   paramIs(k: i32, text: string): boolean {
     this.checkParam(k)
     return handlerSpanIs(this.head, this.params[2 * k], this.params[2 * k + 1], text)
@@ -262,19 +339,26 @@ export class HttpRequest {
    * 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.
+   * @param k the parameter's position in the route pattern, from 0
+   * @param out where the decoded bytes go, from index 0; the caller's buffer
+   * @returns how many decoded bytes were written, or a negative `ROUTER_*` code
    */
   param(k: i32, out: u8[]): i32 {
     this.checkParam(k)
     return routerDecode(this.head, this.params[2 * k], this.params[2 * k + 1], out)
   }
 
-  /** Parameter `k` read as a decimal number that is not negative and fits an `i32`, or -1. */
+  /**
+   * Parameter `k` read as a decimal number that is not negative and fits an `i32`, or -1.
+   * @param k the parameter's position in the route pattern, from 0
+   * @returns the number the parameter's digits spell, or -1 when it is empty, holds a non-digit or overflows
+   */
   paramDecimal(k: i32): i32 {
     this.checkParam(k)
     return handlerDecimal(this.head, this.params[2 * k], this.params[2 * k + 1])
   }
 
-  checkParam(k: i32): void {
+  private checkParam(k: i32): void {
     if (k < 0 || k >= this.paramCount) {
       panic(`HttpRequest.param: the route has ${this.paramCount} parameter(s), not one at ${k}`)
     }
@@ -287,6 +371,9 @@ export class HttpRequest {
    * 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.
+   * @param name the parameter name to look for, compared with each name after decoding
+   * @param out where the decoded value goes, from index 0; the caller's buffer
+   * @returns how many decoded bytes were written, or `HANDLER_ABSENT` or a negative `ROUTER_*` code
    */
   query(name: string, out: u8[]): i32 {
     const at: i32 = this.queryIndex(name)
@@ -296,16 +383,25 @@ export class HttpRequest {
     return handlerFormDecode(this.head, this.queryValueStart, this.queryValueEnd, out)
   }
 
-  /** Whether the query holds a parameter named `name`. */
+  /**
+   * Whether the query holds a parameter named `name`.
+   * @param name the parameter name to look for, compared with each name after decoding
+   * @returns true when some pair in the query has that name, even with an empty value
+   */
   hasQuery(name: string): boolean {
     return this.queryIndex(name) >= 0
   }
 
   /** The span `queryIndex` found, raw. */
   queryValueStart: i32 = 0
+  /** Where the raw value `queryIndex` found ends in `head`, one past its last byte; it starts at `queryValueStart`. */
   queryValueEnd: i32 = 0
 
-  /** Finds the first parameter named `name`: where its pair starts, or -1; its raw value goes to `queryValue...`. */
+  /**
+   * Finds the first parameter named `name`: where its pair starts, or -1; its raw value goes to `queryValue...`.
+   * @param name the parameter name to look for, compared with each name after decoding
+   * @returns the byte offset in `head` where the matching `name=value` pair starts, or -1 when none matches
+   */
   queryIndex(name: string): i32 {
     let at: i32 = this.pathEnd + 1
     const end: i32 = this.targetEnd
@@ -328,7 +424,11 @@ export class HttpRequest {
     return -1
   }
 
-  /** The index of the first field named `name`, which is lowercase, or `HANDLER_ABSENT`. */
+  /**
+   * The index of the first field named `name`, which is lowercase, or `HANDLER_ABSENT`.
+   * @param name the field name in lowercase, since the parser lowercased every name it kept
+   * @returns the field's index for `valueStart` and `valueEnd`, or `HANDLER_ABSENT` when no field has the name
+   */
   header(name: string): i32 {
     for (let i: i32 = 0; i < this.headerCount; i++) {
       if (handlerSpanIs(this.head, this.spans[4 * i], this.spans[4 * i + 1], name)) {
@@ -338,17 +438,30 @@ export class HttpRequest {
     return HANDLER_ABSENT
   }
 
-  /** Where field `i`'s value starts in `head`. */
+  /**
+   * Where field `i`'s value starts in `head`.
+   * @param i a field index, as `header` answered it
+   * @returns the byte offset in `head` of the value's first byte
+   */
   valueStart(i: i32): i32 {
     return this.spans[4 * i + 2]
   }
 
-  /** Where field `i`'s value ends in `head`. */
+  /**
+   * Where field `i`'s value ends in `head`.
+   * @param i a field index, as `header` answered it
+   * @returns the byte offset in `head` just past the value's last byte
+   */
   valueEnd(i: i32): i32 {
     return this.spans[4 * i + 3]
   }
 
-  /** Whether the first field named `name` (lowercase) has exactly the value `value`. */
+  /**
+   * Whether the first field named `name` (lowercase) has exactly the value `value`.
+   * @param name the field name in lowercase
+   * @param value the value to compare with, byte for byte and case-sensitive
+   * @returns true when the field is present and its first occurrence has exactly that value
+   */
   headerIs(name: string, value: string): boolean {
     const i: i32 = this.header(name)
     return i >= 0 && handlerSpanIs(this.head, this.spans[4 * i + 2], this.spans[4 * i + 3], value)
@@ -360,64 +473,85 @@ export class HttpRequest {
  * requests. One per thread; nothing in it is shared.
  */
 export class HttpHandler {
+  /**
+   * The HTTP/1.1 carrier the handler drives.
+   * @internal Read only by this class, which accepts, reads, flushes and closes connections through it.
+   */
   server: Http1Server
-  router: Router
+  private router: Router
   /** Every request the pool has made, and the indices of the free ones. */
-  requests: HttpRequest[]
-  free: i32[]
+  private requests: HttpRequest[]
+  private free: i32[]
   /** Whole requests waiting for `take`, a ring of `queue.length` with `queueCount` from `queueStart`. */
-  queue: i32[]
+  private queue: i32[]
   /** Per slot: its generation, its request (-1 for none), and whether it holds a connection. */
-  slotGen: i32[]
-  current: i32[]
-  open: boolean[]
+  private slotGen: i32[]
+  private current: i32[]
+  private open: boolean[]
   /** `pollWait`'s output. */
-  readyFds: i32[]
+  private readyFds: i32[]
   /** Per watched id: whether its descriptor was ready in the last `wait`. */
-  watchedFired: boolean[]
+  private watchedFired: boolean[]
   /** `json` and `problem` write here. */
   scratch: u8[]
+  /**
+   * The JSON writer over `scratch`.
+   * @internal Read only by this class; programs get it from `json`.
+   */
   writer: JsonWriter
   /** `refuse`'s scratch for `Router.match`. */
-  probe: i32[]
+  private probe: i32[]
   /** One field for `send`; two for a 405. */
-  typeName: u8[][]
-  typeValue: u8[][]
-  allowNames: u8[][]
-  allowValues: u8[][]
+  private typeName: u8[][]
+  private typeValue: u8[][]
+  private allowNames: u8[][]
+  private allowValues: u8[][]
   /** Each `Allow` value made, by the bit mask of the methods it lists: made once a mask and kept. */
-  allowMasks: i64[]
-  allowBytes: u8[][]
-  jsonType: u8[]
-  problemType: u8[]
-  noFields: u8[][]
+  private allowMasks: i64[]
+  private allowBytes: u8[][]
+  private jsonType: u8[]
+  private problemType: u8[]
+  private noFields: u8[][]
   /**
    * When an accept failed for want of a resource (EMFILE, ENFILE, ENOMEM):
    * the listener is out of the loop until then, which it would otherwise wake
    * every turn while its connection waits. 0 while it is in the loop.
    */
-  acceptRestUntil: i64 = 0
+  private acceptRestUntil: i64 = 0
   /** `bodyTimeout` in nanoseconds. */
-  bodyTimeout: i64 = 0
-  /** When the current turn's sockets were ready (`monotonicNanos`): a head read in it is stamped with this. */
+  private bodyTimeout: i64 = 0
+  /**
+   * When the current turn's sockets were ready (`monotonicNanos`): a head read in it is stamped with this.
+   * @internal Read by std/net/upstream.ts, whose `pump` compares it with the last turn it saw to run once per handler turn.
+   */
   turnAt: i64 = 0
   /** When `wait` next looks for a body past `bodyTimeout`. */
-  bodyCheckAt: i64 = 0
-  listener: i32 = 0
+  private bodyCheckAt: i64 = 0
+  private listener: i32 = 0
+  /**
+   * The readiness loop's descriptor, from `pollCreate`.
+   * @internal Read by std/net/upstream.ts to add its upstream sockets to the same loop, so one `wait` serves both.
+   */
   loop: i32 = 0
-  queueStart: i32 = 0
-  queueCount: i32 = 0
-  outputSize: i32 = 0
+  private queueStart: i32 = 0
+  private queueCount: i32 = 0
+  private outputSize: i32 = 0
   /** Set by `drain`: accept nothing more and close each connection once it is idle. */
-  draining: boolean = false
+  private draining: boolean = false
   /** Whether `json` gave out the writer for a value `sendJson` has not yet sent. */
-  jsonBegun: boolean = false
+  private jsonBegun: boolean = false
 
   /**
    * 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`.
+   * @param limits the caps and timeouts. `slots`, `jsonBytes`, `maxEvents`
+   *   and `bodyTimeout` are read once here, so changing them later has no
+   *   effect; `http` is kept by the carrier, which reads its timeouts and
+   *   caps live
+   * @param listener the listening socket's descriptor, still the program's to close
+   * @param router the routes, which the handler keeps and consults at each request head
    */
   constructor(limits: HandlerLimits, listener: i32, router: Router) {
     if (limits.slots < 1 || limits.jsonBytes < 256 || limits.maxEvents < 1 || limits.bodyTimeout < 1) {
@@ -469,6 +603,8 @@ export class HttpHandler {
    * `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.
+   * @param fd the program's descriptor to watch for reading; it stays the program's to read and close
+   * @param id the name `fired` asks about it by, from 0 to `HANDLER_MAX_WATCHED - 1`
    */
   watch(fd: i32, id: i32): void {
     if (id < 0 || id >= HANDLER_MAX_WATCHED) {
@@ -477,7 +613,11 @@ export class HttpHandler {
     pollAdd(this.loop, fd, H1_WANT_READ, -2 - id)
   }
 
-  /** Whether watched descriptor `id` was ready in the last `wait`. */
+  /**
+   * Whether watched descriptor `id` was ready in the last `wait`.
+   * @param id the name the descriptor was given to `watch`
+   * @returns true when it was readable in the last turn; false for an id outside the range
+   */
   fired(id: i32): boolean {
     return id >= 0 && id < HANDLER_MAX_WATCHED && this.watchedFired[id]
   }
@@ -487,6 +627,8 @@ export class HttpHandler {
    * 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`.
+   * @param timeoutMs the longest to block, in milliseconds, or -1 to block until something is ready
+   * @returns how many whole requests are queued for `take` after this turn
    */
   wait(timeoutMs: i32): i32 {
     for (let id: i32 = 0; id < HANDLER_MAX_WATCHED; id++) {
@@ -569,7 +711,7 @@ export class HttpHandler {
   }
 
   /** Takes every waiting connection. */
-  acceptAll(): void {
+  private acceptAll(): void {
     if (this.draining) {
       return
     }
@@ -594,7 +736,7 @@ export class HttpHandler {
    * Takes `slot`'s events until it needs the socket again, then sends what it
    * holds and re-arms it, or closes it once it is over.
    */
-  drive(slot: i32): void {
+  private drive(slot: i32): void {
     const conn: Http1Connection = this.server.connection(slot)
     let event: i32 = this.server.next(slot)
     while (event !== H1_NEED_MORE && event !== H1_ERROR) {
@@ -633,12 +775,12 @@ export class HttpHandler {
   }
 
   /** Whether `conn`'s output holds at most half its size unsent, so a response head fits behind it. */
-  roomy(conn: Http1Connection): boolean {
+  private roomy(conn: Http1Connection): boolean {
     return (conn.outputEnd - conn.outputStart) * 2 <= this.outputSize
   }
 
   /** A head: a request from the free list, the head copied into it, and its route. */
-  begin(slot: i32, conn: Http1Connection): void {
+  private begin(slot: i32, conn: Http1Connection): void {
     if (this.draining) {
       // A head read during the drain is the connection's last.
       conn.closeAfter = true
@@ -683,7 +825,7 @@ export class HttpHandler {
    * that route, since a GET resource answers HEAD (RFC 9110 §9.3.2) and the
    * carrier sends no body for it.
    */
-  route(r: HttpRequest): void {
+  private route(r: HttpRequest): void {
     const params: i32[] = r.params
     let route: i32 = this.router.match(
       r.head,
@@ -716,7 +858,7 @@ export class HttpHandler {
   }
 
   /** Body bytes: appended to the request's body, which the carrier's cap bounds. */
-  gather(slot: i32, conn: Http1Connection): void {
+  private gather(slot: i32, conn: Http1Connection): void {
     const at: i32 = this.current[slot]
     if (at < 0) {
       return
@@ -734,7 +876,7 @@ export class HttpHandler {
   }
 
   /** The request is whole: queued for `take`, or parked while the response before it is still mostly unsent. */
-  whole(slot: i32, conn: Http1Connection): void {
+  private whole(slot: i32, conn: Http1Connection): void {
     const at: i32 = this.current[slot]
     if (at < 0) {
       return
@@ -747,7 +889,7 @@ export class HttpHandler {
     }
   }
 
-  enqueue(r: HttpRequest): void {
+  private enqueue(r: HttpRequest): void {
     r.state = HANDLER_QUEUED
     const size: i32 = toI32(this.queue.length)
     if (this.queueCount === size) {
@@ -763,7 +905,7 @@ export class HttpHandler {
   }
 
   /** `H1_WRITE`: the carrier has room again for the response under way. */
-  resume(slot: i32, conn: Http1Connection): void {
+  private resume(slot: i32, conn: Http1Connection): void {
     const at: i32 = this.current[slot]
     if (at < 0) {
       return
@@ -779,7 +921,7 @@ export class HttpHandler {
   }
 
   /** Hands the carrier as much of `r`'s pending bytes as it takes. */
-  pushPending(r: HttpRequest, conn: Http1Connection): void {
+  private pushPending(r: HttpRequest, conn: Http1Connection): void {
     const left: i32 = r.pendingEnd - r.pendingStart
     if (left === 0) {
       return
@@ -795,7 +937,7 @@ export class HttpHandler {
   }
 
   /** Ends `r`'s response once nothing is pending, and hands `r` back; otherwise leaves it flushing. */
-  finish(r: HttpRequest, conn: Http1Connection): void {
+  private finish(r: HttpRequest, conn: Http1Connection): void {
     r.state = HANDLER_FLUSHING
     if (r.pendingEnd > r.pendingStart) {
       return
@@ -809,7 +951,7 @@ export class HttpHandler {
   }
 
   /** A free request, or a new one. */
-  obtain(): HttpRequest {
+  private obtain(): HttpRequest {
     const count: i32 = toI32(this.free.length)
     if (count > 0) {
       const at: i32 = this.free[count - 1]
@@ -822,7 +964,7 @@ export class HttpHandler {
     return r
   }
 
-  release(r: HttpRequest): void {
+  private release(r: HttpRequest): void {
     if (r.state === HANDLER_FREE) {
       return
     }
@@ -831,7 +973,7 @@ export class HttpHandler {
   }
 
   /** Hands back the request `slot` was reading when the carrier refused it. */
-  releaseReading(slot: i32): void {
+  private releaseReading(slot: i32): void {
     const at: i32 = this.current[slot]
     if (at >= 0 && this.requests[at].state === HANDLER_READING) {
       this.current[slot] = -1
@@ -844,13 +986,13 @@ export class HttpHandler {
    * dropped. A request the handler alone holds goes back now; one queued or
    * taken goes back when `ready` passes it or the program answers it.
    */
-  closeSlot(slot: i32): void {
+  private closeSlot(slot: i32): void {
     this.server.close(slot)
     this.forget(slot)
   }
 
   /** The bookkeeping of a slot the carrier has closed. */
-  forget(slot: i32): void {
+  private forget(slot: i32): void {
     this.open[slot] = false
     this.slotGen[slot] = this.slotGen[slot] + 1
     const at: i32 = this.current[slot]
@@ -864,7 +1006,7 @@ export class HttpHandler {
   }
 
   /** Closes every connection whose request has been reading its body for longer than `bodyTimeout` at `now`. */
-  expireBodies(now: i64): void {
+  private expireBodies(now: i64): void {
     for (let s: i32 = 0; s < toI32(this.current.length) && s < toI32(this.open.length); s++) {
       const at: i32 = this.current[s]
       if (this.open[s] && at >= 0 && at < toI32(this.requests.length)) {
@@ -877,7 +1019,7 @@ export class HttpHandler {
   }
 
   /** Every slot the carrier's `expire` closed. */
-  sweep(): void {
+  private sweep(): void {
     for (let s: i32 = 0; s < toI32(this.open.length); s++) {
       if (this.open[s] && !this.server.holds(s)) {
         this.forget(s)
@@ -887,7 +1029,10 @@ export class HttpHandler {
 
   // ---- Requests -------------------------------------------------------------------
 
-  /** Whether a whole request is waiting for `take`. Requests whose connection closed while queued are handed back here. */
+  /**
+   * Whether a whole request is waiting for `take`. Requests whose connection closed while queued are handed back here.
+   * @returns true when `take` will give out a request whose connection is still open
+   */
   ready(): boolean {
     while (this.queueCount > 0) {
       const r: HttpRequest = this.requests[this.queue[this.queueStart]]
@@ -901,7 +1046,10 @@ export class HttpHandler {
     return false
   }
 
-  /** The next whole request, which the program now owes an answer. Panics when none is `ready`. */
+  /**
+   * The next whole request, which the program now owes an answer. Panics when none is `ready`.
+   * @returns the oldest queued request, the program's until it answers it
+   */
   take(): HttpRequest {
     if (!this.ready()) {
       panic("HttpHandler.take: no request is ready")
@@ -914,16 +1062,22 @@ export class HttpHandler {
   }
 
   /** Whether `r`'s connection is the one it was read on, still open. */
-  live(r: HttpRequest): boolean {
+  private live(r: HttpRequest): boolean {
     return this.server.holds(r.slot) && this.slotGen[r.slot] === r.gen
   }
 
-  /** How many requests the pool has made: the most ever in flight at once. */
+  /**
+   * How many requests the pool has made: the most ever in flight at once.
+   * @returns the pool's size, which only grows, so a flat count shows nothing leaks
+   */
   pooled(): i32 {
     return toI32(this.requests.length)
   }
 
-  /** How many connections are open. */
+  /**
+   * How many connections are open.
+   * @returns the number of carrier slots holding a connection, which falls to 0 after `drain`
+   */
   connections(): i32 {
     return this.server.busy()
   }
@@ -936,6 +1090,14 @@ export class HttpHandler {
    * `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.
+   * @param r a request taken and not yet answered
+   * @param status the response status, from 200 to 599
+   * @param names the field names, as bytes, beside `values`
+   * @param values each field's value, `values[k]` for `names[k]`
+   * @param bodyLength how many body bytes will follow, or `HTTP1_CHUNKED` for a body of unknown length
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed
+   *   first, or when the carrier's output was too full to take the head and
+   *   the connection was closed for it
    */
   start(r: HttpRequest, status: i32, names: u8[][], values: u8[][], bodyLength: i32): i32 {
     if (r.state !== HANDLER_HELD) {
@@ -974,6 +1136,11 @@ export class HttpHandler {
    * 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`.
+   * @param r a request whose response `start` began
+   * @param buf the bytes to send from; the caller's again on return
+   * @param off where in `buf` the body bytes start
+   * @param len how many bytes to send
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed first
    */
   write(r: HttpRequest, buf: u8[], off: i32, len: i32): i32 {
     if (r.state !== HANDLER_STREAMING) {
@@ -1013,7 +1180,7 @@ export class HttpHandler {
   }
 
   /** Appends bytes to `r`'s pending buffer, growing it once to the largest response it has held. */
-  keep(r: HttpRequest, buf: u8[], off: i32, len: i32): void {
+  private keep(r: HttpRequest, buf: u8[], off: i32, len: i32): void {
     const live: i32 = r.pendingEnd - r.pendingStart
     if (toI32(r.pending.length) - r.pendingEnd < len) {
       if (r.pendingStart > 0 || toI32(r.pending.length) < live + len) {
@@ -1035,6 +1202,8 @@ export class HttpHandler {
    * 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`.
+   * @param r a request whose response `start` began; the handler's again after this call
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed first
    */
   end(r: HttpRequest): i32 {
     if (r.state !== HANDLER_STREAMING) {
@@ -1055,13 +1224,36 @@ export class HttpHandler {
     return HANDLER_SENT
   }
 
-  /** Answers `r` with `status`, a `Content-Type` of `contentType` and the body `body[off .. off + len)`, in one call. */
+  /**
+   * Answers `r` with `status`, a `Content-Type` of `contentType` and the body `body[off .. off + len)`, in one call.
+   * @param r a request taken and not yet answered; the handler's again after this call
+   * @param status the response status, from 200 to 599
+   * @param contentType the `Content-Type` value, as bytes
+   * @param body the buffer holding the body; the caller's again on return
+   * @param off where in `body` the body bytes start
+   * @param len how many body bytes to send
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed
+   *   first, or when the carrier's output was too full to take the head and
+   *   the connection was closed for it
+   */
   send(r: HttpRequest, status: i32, contentType: u8[], body: u8[], off: i32, len: i32): i32 {
     this.typeValue[0] = contentType
     return this.sendFields(r, status, this.typeName, this.typeValue, body, off, len)
   }
 
-  /** Answers `r` with `status`, the fields `names[k]`: `values[k]` and the body `body[off .. off + len)`, in one call. */
+  /**
+   * Answers `r` with `status`, the fields `names[k]`: `values[k]` and the body `body[off .. off + len)`, in one call.
+   * @param r a request taken and not yet answered; the handler's again after this call
+   * @param status the response status, from 200 to 599
+   * @param names the field names, as bytes, beside `values`
+   * @param values each field's value, `values[k]` for `names[k]`
+   * @param body the buffer holding the body; the caller's again on return
+   * @param off where in `body` the body bytes start
+   * @param len how many body bytes to send
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed
+   *   first, or when the carrier's output was too full to take the head and
+   *   the connection was closed for it
+   */
   sendFields(
     r: HttpRequest,
     status: i32,
@@ -1082,7 +1274,14 @@ export class HttpHandler {
     return this.end(r)
   }
 
-  /** Answers `r` with `status` and no body: a 204, or a status whose meaning is all there is to say. */
+  /**
+   * Answers `r` with `status` and no body: a 204, or a status whose meaning is all there is to say.
+   * @param r a request taken and not yet answered; the handler's again after this call
+   * @param status the response status, from 200 to 599
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed
+   *   first, or when the carrier's output was too full to take the head and
+   *   the connection was closed for it
+   */
   empty(r: HttpRequest, status: i32): i32 {
     return this.sendFields(r, status, this.noFields, this.noFields, this.scratch, HANDLER_ZERO, HANDLER_ZERO)
   }
@@ -1091,6 +1290,7 @@ export class HttpHandler {
    * 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.
+   * @returns the handler's own writer, empty, valid until the next `json`, `sendJson` or `problem`
    */
   json(): JsonWriter {
     this.writer.reset(this.scratch, HANDLER_ZERO)
@@ -1102,6 +1302,11 @@ export class HttpHandler {
    * 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.
+   * @param r a request taken and not yet answered; the handler's again after this call
+   * @param status the response status for a value that fit, from 200 to 599
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed
+   *   first, or when the carrier's output was too full to take the head and
+   *   the connection was closed for it
    */
   sendJson(r: HttpRequest, status: i32): i32 {
     if (!this.jsonBegun) {
@@ -1120,6 +1325,13 @@ export class HttpHandler {
    * `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.
+   * @param r a request taken and not yet answered; the handler's again after this call
+   * @param status the response status, from 200 to 599, also written into the object
+   * @param title the status's reason phrase, or empty to leave it out
+   * @param detail a sentence for a person about this occurrence, or empty to leave it out
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed
+   *   first, or when the carrier's output was too full to take the head and
+   *   the connection was closed for it
    */
   problem(r: HttpRequest, status: i32, title: string, detail: string): i32 {
     const length: i32 = this.writeProblem(status, title, detail)
@@ -1131,7 +1343,7 @@ export class HttpHandler {
    * One too large for it is written without its detail, and then without its
    * title, which leaves room enough in the least `jsonBytes`.
    */
-  writeProblem(status: i32, title: string, detail: string): i32 {
+  private writeProblem(status: i32, title: string, detail: string): i32 {
     let length: i32 = this.writeProblemObject(status, title, detail)
     if (length < 0) {
       length = this.writeProblemObject(status, title, "")
@@ -1144,7 +1356,7 @@ export class HttpHandler {
   }
 
   /** `writeProblem`'s one try: the object's length, or -1 when it did not fit. */
-  writeProblemObject(status: i32, title: string, detail: string): i32 {
+  private writeProblemObject(status: i32, title: string, detail: string): i32 {
     const w: JsonWriter = this.json()
     w.beginObject()
     w.key("type")
@@ -1168,6 +1380,10 @@ export class HttpHandler {
    * 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.
+   * @param r a request whose `route` is negative, taken and not yet answered; the handler's again after this call
+   * @returns `HANDLER_SENT`, or `HANDLER_DROPPED` when the connection closed
+   *   first, or when the carrier's output was too full to take the head and
+   *   the connection was closed for it
    */
   refuse(r: HttpRequest): i32 {
     if (r.route === ROUTER_METHOD_NOT_ALLOWED) {
@@ -1191,7 +1407,7 @@ export class HttpHandler {
    * HEAD wherever GET is, since a GET route answers HEAD too. Made once for
    * each set of methods.
    */
-  allowFor(r: HttpRequest): u8[] {
+  private allowFor(r: HttpRequest): u8[] {
     const router: Router = this.router
     const methods: i32 = toI32(router.methodStart.length)
     let mask: i64 = 0