@amritk/nish-x86_64-linux 0.18.0 → 0.20.0

package/std/net/http3-server.ts

@@ -9,6 +9,7 @@
  *     // quicConfig.alpn is ["h3"]; pollAdd(loop, fd, 1, 0)
  *     // each time round the loop, with `now` in milliseconds:
  *     pollWait(loop, ready, server.timeout(now));
+ *     server.clock(micros);                      // the same instant in microseconds, for the pacer
  *     server.receive(now, key);                  // every datagram waiting; signs handshakes with `key`
  *     server.tick(now);                          // the connections' timers
  *     let slot: i32 = server.ready();
@@ -19,6 +20,8 @@
  *       slot = server.ready();
  *     }
  *     server.flush(now);                         // what every touched slot has to send
+ *     // at shutdown:
+ *     server.stop();                             // releases every slot, wipes the static keys
  *
  * **Routing.** A datagram goes to the slot that owns its first packet's
  * Destination Connection ID, found through a hash index of every slot's
@@ -38,6 +41,10 @@
  * **Sending.** `flush` writes each touched slot's datagrams with
  * `quicListenerTakeFlight`, a paced flight at a time in one `udpSendTo` with
  * GSO where the platform has it and one datagram at a time where it does not.
+ * The pacer counts the microseconds `clock` gives it, so on a path whose
+ * round trip is under a millisecond it neither waits for the next
+ * millisecond to earn credit nor holds a slot back for a whole one; without
+ * `clock` it counts whole milliseconds.
  * A slot whose HTTP/3 side sent GOAWAY and whose requests have all finished,
  * every byte acknowledged, is closed with H3_NO_ERROR; a closed slot is freed
  * once its CONNECTION_CLOSE is out.
@@ -51,11 +58,21 @@
  *
  * **Caps, fixed at start-up**: the slots, and inside each the QUIC
  * configuration's streams and buffers and the `Http3Config`'s field section,
- * body chunk and DATA frame. The constructor makes every slot's connections;
+ * body chunk and DATA frame. A slot's connections and address are built on
+ * the first Initial accepted into it and kept, so a pool sized for its peak
+ * costs at start-up only its per-slot tables (the index, the wheel, the
+ * queues), and holds at most `size` connections once the peak has come;
  * a datagram an established connection reads, and every datagram it sends,
  * allocates nothing; nor does a datagram no slot owns, which the listener
- * reads where it lies and answers into scratch made once, nor a handshake,
- * whose state is the slot's — `docs/security/http3.md` (H3-1, H3-3).
+ * reads where it lies and answers into scratch made once, nor a handshake
+ * into a slot built before, whose state is the slot's —
+ * `docs/security/http3.md` (H3-1, H3-3).
+ *
+ * **The Date.** Every response carries one `date` field (RFC 9110 §6.6.1)
+ * from the pool's `HttpDate`, which formats the IMF-fixdate at most once a
+ * second for every slot; trailers carry none, and a program that sends its
+ * own `date` sends that one instead. `server.date.pin(unixMs)` fixes it, for
+ * a test that compares bytes.
  *
  * Written from RFC 9114 §3 and RFC 9000 §5.2, not ported from another
  * implementation. Private names carry the `http3Server` prefix
@@ -63,6 +80,8 @@
  */
 import { udpRecvFrom, udpSendTo } from "nish:net"
 import { Secret } from "nish:secret"
+import { BufferPool } from "nish/net/buffer-pool"
+import { HttpDate } from "nish/net/http1-server"
 import { Http3Config, Http3Connection } from "nish/net/http3"
 import { H3_NO_ERROR, h3Count } from "nish/net/http3-frame"
 import {
@@ -70,10 +89,13 @@ import {
   QUIC_CONN_DATAGRAM_SIZE,
   QUIC_CONN_ENTROPY_SIZE,
   QUIC_CONN_LOCAL_CIDS,
+  QUIC_CONN_MAX_STREAM_DATA,
+  QUIC_CONN_MAX_STREAMS,
   QuicConnection,
   QuicServerConfig,
 } from "nish/net/quic"
 import { QUIC_MAX_CID_LENGTH } from "nish/net/quic-packet"
+import { QuicStreamPools, quicStreamGrowFree } from "nish/net/quic-stream"
 import {
   QUIC_LISTEN_ACCEPT,
   QUIC_LISTENER_ANSWER_SIZE,
@@ -82,7 +104,7 @@ import {
   QuicFlight,
   QuicListener,
   QuicListenerAnswer,
-  quicListenerPaceTime,
+  quicListenerFlightTime,
   quicListenerTakeFlight,
 } from "nish/net/quic-listener"
 import { TlsP256Signer } from "nish/net/tls"
@@ -397,14 +419,29 @@ export class Http3Wheel {
  */
 export class Http3Server {
   quicConfig: QuicServerConfig
+  /** The HTTP/3 configuration each slot's `Http3Connection` is built with. */
+  config: Http3Config
   listener: QuicListener
   /** What the listener answers into, made once: its reply and IDs are refilled in their own room. */
   answer: QuicListenerAnswer
+  /** The slots built so far, 0 up: each built on the first Initial accepted into it, or the first ask for it. */
   quics: QuicConnection[]
   conns: Http3Connection[]
+  /**
+   * The `date` every slot's responses carry, formatted once a second for all
+   * of them: each slot's `Http3Connection.date` is its bytes, refreshed by
+   * `connection` and `ready`. `date.pin` fixes its clock.
+   */
+  date: HttpDate
   index: Http3CidIndex
   wheel: Http3Wheel
-  /** Each slot's client address, as its first datagram came from. */
+  /**
+   * Each slot's client address, as its first datagram came from. Not
+   * validated until `quic(slot).addressValidated` is set (RFC 9000 §8.1): a
+   * Retry token the listener checked, with `retry` on, or a Handshake packet
+   * from the client. Before then it is the source of one UDP datagram, which
+   * anyone can forge, so a cap or an allow-list keyed on it waits for that.
+   */
   addresses: u8[][]
   /** What `receive` reads into, and where `flush` writes a flight. */
   rx: u8[]
@@ -421,17 +458,25 @@ export class Http3Server {
   /** The slots with datagrams for the program, a ring, and the slots with something to send, a stack. */
   readyRing: i32[]
   dirtyStack: i32[]
-  /** Free slots, a stack. */
+  /** Released slots, a stack: a slot never built is taken from `used` instead. */
   free: i32[]
   /** Per slot: 1 while on the ready ring, 2 while on the dirty stack. */
   queued: i32[]
   /** When the answer budget was last topped up, -1 before the first answer. */
   answerRefilled: i64 = -1
+  /** The caller's clock in microseconds, from `clock`, or -1: what each connection's pacer counts. */
+  micros: i64 = -1
   fd: i32 = -1
   readyHead: i32 = 0
   readyCount: i32 = 0
   dirtyCount: i32 = 0
   freeCount: i32 = 0
+  /** How many slots the pool may hold, which `size` answers. */
+  slots: i32 = 1
+  /** The slots ever accepted into, 0 up: one past it has never held a connection, so is free without being on `free`. */
+  used: i32 = 0
+  /** Set by `stop`: a slot built after it is released as it is made, so it holds no keys. */
+  stopped: boolean = false
   /** What is left of the answer budget (see `answerRefilled`). */
   answerBudget: i32 = 0
   /** Counters for a log or a test, saturating: connections accepted, Initials dropped for want of a slot, datagrams past the answer budget, sends that failed. */
@@ -439,34 +484,75 @@ export class Http3Server {
   refused: i32 = 0
   limited: i32 = 0
   sendErrors: i32 = 0
+  /**
+   * The stream buffers every slot's connection borrows from, made by the
+   * constructor for the stream table `quicConfig` gives every slot: `null`
+   * when its streams have none. Each pool makes a buffer only when a stream
+   * first needs one, so an idle server holds none (QUIC-3). It is made even
+   * for a configuration `quicConnConfigFits` refuses; `build` shares it only
+   * with a connection whose stream buffers are its size.
+   */
+  streamPools: QuicStreamPools | null = null
+  /** The `bodyChunk`-byte read buffers every slot's `Http3Connection` borrows, one at most each. */
+  dataPool: BufferPool
+  /** The `maxFieldSectionSize`-byte HEADERS buffers every slot's `Http3Connection` borrows around a decode. */
+  sectionPool: BufferPool
 
   /**
    * A pool of `size` slots serving HTTP/3 under `config` over QUIC under
    * `quicConfig` on the UDP socket `fd`. `listenerEntropy` is the
    * listener's `QUIC_LISTENER_ENTROPY_SIZE` random bytes, whose first eight
    * also key the connection-ID index (wiped in the caller's array, as the
-   * listener does). Every slot's connections are made here.
+   * listener does). No slot's connections are made here: each slot's are
+   * built on the first Initial accepted into it. From here on
+   * `quicConfig`'s `statelessResetKey` and `retryTokenKey` are the server's:
+   * `stop` wipes them, so the configuration is this server's alone.
    */
   constructor(quicConfig: QuicServerConfig, config: Http3Config, fd: i32, size: i32, listenerEntropy: u8[]) {
     if (size < 1 || size > 65536) {
       panic(`Http3Server: ${size} slots, outside 1 to 65536`)
     }
     this.quicConfig = quicConfig
+    this.config = config
     this.fd = fd
+    this.slots = size
     this.index = new Http3CidIndex(size, listenerEntropy)
     this.listener = new QuicListener(quicConfig, listenerEntropy)
     this.answer = new QuicListenerAnswer(QUIC_LISTENER_ANSWER_SIZE)
     this.wheel = new Http3Wheel(size)
     this.quics = []
     this.conns = []
+    this.date = new HttpDate()
+    // Formatted once now, so no slot ever sends the bytes before a first format.
+    this.date.current()
     this.addresses = []
     this.entropy = new Array<u8>(QUIC_CONN_ENTROPY_SIZE)
-    for (let k: i32 = 0; k < size; k++) {
-      crypto.getRandomValues(this.entropy)
-      const quic = new QuicConnection(quicConfig, this.entropy)
-      this.quics.push(quic)
-      this.conns.push(new Http3Connection(config, quic))
-      this.addresses.push(new Array<u8>(H3_SERVER_ADDRESS))
+    this.dataPool = new BufferPool("Http3Server.data", config.bodyChunk, size)
+    this.sectionPool = new BufferPool("Http3Server.section", config.maxFieldSectionSize, size)
+    // Room for every buffer each pool can lend, so that giving one back never grows the arena.
+    const none: u8[] = []
+    quicStreamGrowFree(this.dataPool.free, size, none)
+    quicStreamGrowFree(this.sectionPool.free, size, none)
+    // The stream table every slot's connection will have, read from the
+    // configuration as `QuicConnection` reads it: a shape outside its bounds
+    // gets no pools, and a connection whose configuration does not fit has no
+    // table to share them with.
+    const streamData: i64 = quicConfig.maxStreamData
+    const bidi: i64 = quicConfig.maxStreamsBidi
+    const uni: i64 = quicConfig.maxStreamsUni
+    const local: i64 = quicConfig.localStreams
+    if (
+      streamData >= 1 &&
+      streamData <= QUIC_CONN_MAX_STREAM_DATA &&
+      bidi >= 0 &&
+      bidi <= QUIC_CONN_MAX_STREAMS &&
+      uni >= 0 &&
+      uni <= QUIC_CONN_MAX_STREAMS &&
+      local >= 0 &&
+      local <= QUIC_CONN_MAX_STREAMS &&
+      bidi + uni + local > 0
+    ) {
+      this.streamPools = new QuicStreamPools(toI32(streamData), toI32(bidi + uni + local), size)
     }
     this.rx = new Array<u8>(H3_SERVER_RECEIVE_SIZE)
     this.tx = new Array<u8>(QUIC_LISTENER_FLIGHT_MAX * QUIC_CONN_DATAGRAM_SIZE)
@@ -478,22 +564,57 @@ export class Http3Server {
     this.state = new Array<i32>(size)
     this.readyRing = new Array<i32>(size)
     this.dirtyStack = new Array<i32>(size)
+    // Released slots only: one never used is taken at `used`.
     this.free = new Array<i32>(size)
     this.queued = new Array<i32>(size)
-    for (let k: i32 = size - 1; k >= 0; k--) {
-      this.free[this.freeCount] = k
-      this.freeCount = this.freeCount + 1
+  }
+
+  /**
+   * Builds the next slot, `quics.length`: its QUIC connection under fresh
+   * entropy, sharing `streamPools` when its stream table is the one they
+   * were made for, its HTTP/3 connection on the pool's buffers and `date`,
+   * and its address.
+   */
+  build(): void {
+    crypto.getRandomValues(this.entropy)
+    const quic = new QuicConnection(this.quicConfig, this.entropy)
+    this.quics.push(quic)
+    const pools: QuicStreamPools | null = this.streamPools
+    if (pools !== null && pools.data.size === quic.streams.bufferSize && quic.streams.slots.length > 0) {
+      quic.streams.share(pools)
+    }
+    const conn: Http3Connection = new Http3Connection(this.config, quic)
+    conn.share(this.dataPool, this.sectionPool)
+    conn.date = this.date.current()
+    this.conns.push(conn)
+    this.addresses.push(new Array<u8>(H3_SERVER_ADDRESS))
+    if (this.stopped) {
+      conn.release()
     }
   }
 
-  /** How many slots the pool has. */
+  /** `slot` when it is one of the pool's, built with every slot before it if it was not; 0 when it is out of range. */
+  slotAt(slot: i32): i32 {
+    const at: i32 = slot >= 0 && slot < this.slots ? slot : H3_SERVER_ZERO
+    while (toI32(this.quics.length) <= at) {
+      this.build()
+    }
+    return at
+  }
+
+  /** Whether every slot holds a connection: none released, and none left never used. */
+  full(): boolean {
+    return this.freeCount <= 0 && this.used >= this.slots
+  }
+
+  /** How many slots the pool has, built or not. */
   size(): i32 {
-    return toI32(this.quics.length)
+    return this.slots
   }
 
   /** How many slots hold a connection. */
   busy(): i32 {
-    return this.size() - this.freeCount
+    return this.used - this.freeCount
   }
 
   /** Whether `slot` holds a connection. */
@@ -501,16 +622,20 @@ export class Http3Server {
     return slot >= 0 && slot < toI32(this.state.length) && this.state[slot] === H3_SERVER_BUSY
   }
 
-  /** The HTTP/3 connection of `slot`; a slot out of range names the first. */
+  /**
+   * The HTTP/3 connection of `slot`, its `date` brought up to now; a slot out
+   * of range names the first. A slot not built yet is built here, with every
+   * slot before it, so a program that binds something to each slot's
+   * connection up front gets the one its slot keeps.
+   */
   connection(slot: i32): Http3Connection {
-    const at: i32 = slot >= 0 && slot < toI32(this.conns.length) ? slot : H3_SERVER_ZERO
-    return this.conns[at]
+    this.date.current()
+    return this.conns[this.slotAt(slot)]
   }
 
-  /** The QUIC connection of `slot`; a slot out of range names the first. */
+  /** The QUIC connection of `slot`, built as `connection` builds it; a slot out of range names the first. */
   quic(slot: i32): QuicConnection {
-    const at: i32 = slot >= 0 && slot < toI32(this.quics.length) ? slot : H3_SERVER_ZERO
-    return this.quics[at]
+    return this.quics[this.slotAt(slot)]
   }
 
   /** Puts `slot` on the ready ring and the dirty stack, unless it is on them. */
@@ -538,6 +663,7 @@ export class Http3Server {
 
   /** The next slot with news for the program, or -1: call its connection's `next` until it has none. */
   ready(): i32 {
+    this.date.current()
     while (this.readyCount > 0) {
       const slot: i32 = this.readyRing[this.readyHead]
       this.readyHead = (this.readyHead + 1) % toI32(this.readyRing.length)
@@ -629,11 +755,19 @@ export class Http3Server {
       }
       return
     }
-    if (this.freeCount <= 0) {
+    // A slot released before is taken first, then the next never used, so the
+    // first accepts take slots 0, 1, 2 ... and a pool that never fills never
+    // builds its last slots.
+    let slot: i32 = 0
+    if (this.freeCount > 0) {
+      this.freeCount = this.freeCount - 1
+      slot = this.free[this.freeCount]
+    } else if (this.used < this.slots) {
+      slot = this.slotAt(this.used)
+      this.used = this.used + 1
+    } else {
       return
     }
-    this.freeCount = this.freeCount - 1
-    const slot: i32 = this.free[this.freeCount]
     crypto.getRandomValues(this.entropy)
     const quic: QuicConnection = this.quics[slot]
     quic.reset(this.entropy)
@@ -680,7 +814,7 @@ export class Http3Server {
     if ((first & 0x30) !== 0 || toI32(buf[at + 5]) < 8) {
       return false
     }
-    if (this.freeCount <= 0) {
+    if (this.full()) {
       this.refused = h3Count(this.refused)
       return false
     }
@@ -713,9 +847,21 @@ export class Http3Server {
     return true
   }
 
+  /**
+   * Gives the server the caller's monotonic clock in microseconds: the
+   * instant the `now` of the calls that follow names, `monotonicNanos() /
+   * 1000` where `now` is `monotonicNanos() / 1000000`. The pacer counts it;
+   * every timer still counts `now`. One that is not inside `now`'s
+   * millisecond is not read.
+   */
+  clock(micros: i64): void {
+    this.micros = micros
+  }
+
   /** Hands `slot`'s connection a datagram, signs when the handshake asks, and refiles its IDs and timer. */
   serve(slot: i32, buf: u8[], at: i32, len: i32, now: i64, key: Secret<u8[]>): void {
     const quic: QuicConnection = this.quics[slot]
+    quic.recovery.micros = this.micros
     quic.receiveWindow(buf, at, len, now)
     const input: u8[] | null = quic.signatureInput()
     if (input !== null) {
@@ -801,6 +947,7 @@ export class Http3Server {
   /** `flush` of one slot. */
   flushSlot(slot: i32, now: i64): void {
     const quic: QuicConnection = this.quics[slot]
+    quic.recovery.micros = this.micros
     if (this.conns[slot].isDone() && !quic.closed()) {
       quic.close(H3_NO_ERROR)
     }
@@ -843,7 +990,7 @@ export class Http3Server {
     // The pacer answers a time, not a delay: the slot wakes at it when it
     // comes before the connection's own deadline.
     let due: i64 = quic.deadline()
-    const paced: i64 = quicListenerPaceTime(quic, now)
+    const paced: i64 = quicListenerFlightTime(quic, now)
     if (paced > now && (due < 0 || paced < due)) {
       due = paced
     }
@@ -862,7 +1009,7 @@ export class Http3Server {
   release(slot: i32): void {
     this.unindex(slot)
     this.wheel.unfile(slot)
-    this.quics[slot].release()
+    this.conns[slot].release()
     this.state[slot] = H3_SERVER_FREE
     if (this.freeCount < toI32(this.free.length)) {
       this.free[this.freeCount] = slot
@@ -870,6 +1017,39 @@ export class Http3Server {
     }
   }
 
+  /**
+   * Stops the server for good and wipes the keys it holds: every built slot's
+   * connection is released (`QuicConnection.release`, which sends nothing),
+   * as is one built after, by `connection` or `quic`; the listener is
+   * released; and the configuration's `statelessResetKey` and
+   * `retryTokenKey`, the index's salt, the connections' entropy scratch
+   * and the listener's last answer (a Retry's or a reset's token) are
+   * zeroed. From then on every datagram is dropped and no connection is
+   * accepted. The configuration's two keys are the server's once it is made
+   * with them: a program that keeps a copy of either, to start the next
+   * server with, wipes its own copy. The keys are zeroed in place, so give
+   * each server a `QuicServerConfig` of its own: any other listener,
+   * connection or server made with the same one would go on MACing Retry
+   * tokens and deriving stateless reset tokens under an all-zero key, which
+   * anyone can forge.
+   */
+  stop(): void {
+    this.stopped = true
+    for (let slot: i32 = 0; slot < toI32(this.quics.length); slot++) {
+      if (this.holds(slot)) {
+        this.release(slot)
+      } else {
+        this.conns[slot].release()
+      }
+    }
+    this.listener.release()
+    secureZero(this.quicConfig.statelessResetKey)
+    secureZero(this.quicConfig.retryTokenKey)
+    secureZero(this.index.salt)
+    secureZero(this.entropy)
+    this.answer.wipe()
+  }
+
   /** Runs the timers due by `now`, and marks each slot it ran for `flush`. */
   tick(now: i64): void {
     const wheel: Http3Wheel = this.wheel