nish/net/http2-tls

HTTP/2 over TLS 1.3 on TCP: a pool of Http2Connections, one beside each slot of a TlsTcpServer, for a program that owns its readiness loop. Slot 0's connection is built with the server, so a bad Http2Config is refused there; every other slot's is built on the first accept into it.

import {
  H2_ALPN,
  Http2TlsServer,
} from "nish/net/http2-tls";
import { Secret } from "nish:secret";
import { pollAdd, pollModify, tcpListen } from "nish:net";
import { H2_ERROR, H2_NEED_MORE, H2_REQUEST, Http2Config, Http2Connection } from "nish/net/http2";
import { Http2TlsServer } from "nish/net/http2-tls";
import { TlsServerConfig } from "nish/net/tls";
import { TLS_RECORD_DONE, TLS_RECORD_SIGN } from "nish/net/tls/record-server";

// `tlsConfig.alpn` holds `H2_ALPN`; `loop` is the program's, from `pollCreate`.
const LISTENER: i32 = 64; // past every slot's token
const start = (loop: i32, tlsConfig: TlsServerConfig): Http2TlsServer => {
  const listener: i32 = tcpListen("0.0.0.0", 8443, 128);
  pollAdd(loop, listener, 1, LISTENER);
  return new Http2TlsServer(tlsConfig, new Http2Config(), listener, 64);
};
// When the listener's token comes back:
const admit = (loop: i32, server: Http2TlsServer, random: u8[], key: u8[]): void => {
  crypto.getRandomValues(random);
  crypto.getRandomValues(key);
  const slot: i32 = server.accept(random, key);
  if (slot >= 0) { pollAdd(loop, server.fd(slot), 1, slot); }
};
// When a slot's token comes back with `events`:
const serve = (loop: i32, server: Http2TlsServer, slot: i32, events: i32, key: Secret<u8[]>): void => {
  let wants: i32 = (events & 5) !== 0 ? server.readable(slot) : server.writable(slot);
  if ((wants & TLS_RECORD_SIGN) !== 0) { wants = server.signP256(slot, key); }
  const none: u8[][] = [];
  let event: i32 = server.next(slot);
  while (event !== H2_NEED_MORE && event !== H2_ERROR) {
    const conn: Http2Connection = server.connection(slot);
    if (event === H2_REQUEST) { conn.respond(conn.stream, 200, none, none, true); }
    event = server.next(slot);
  }
  wants = server.flush(slot);
  if ((wants & TLS_RECORD_DONE) !== 0) { server.close(slot); }
  else { pollModify(loop, server.fd(slot), wants & 3, slot); }
};

It is nish/net/tls-tcp's loop with one step added: next moves what TLS has decrypted into the slot's connection and answers the connection's next event, and flush moves what the connection wrote into TLS and on to the socket. Every call answers the TLS slot's interest, whose low two bits are the events pollModify takes. A connection whose input buffer is full stops reading TLS, TLS then stops asking for the socket to be read, and the peer's TCP window closes: back-pressure goes all the way down.

ALPN

RFC 9113 §3.2 runs HTTP/2 over TLS only when ALPN chose h2. A slot whose handshake ends with any other protocol, or none, is shut down with TLS's close_notify and never reaches its connection; the program's configuration offers h2 (and may offer http/1.1 beside it, for a program that serves both and calls alpn(slot) itself).

Slots, a cap; buffers, borrowed. The constructor makes the TLS pool and slot 0's connection, but no other slot's and no frame buffer: a slot's connection is made by the first accept into it and kept, so a pool sized for its peak costs at start-up only what does not depend on the size, and holds at most size connections once the peak has come.

A connection borrows its input, output and header-block buffers from the server's Http2Pools when it first needs each, and gives each back once it is empty and when the slot closes, so a free or idle slot holds none. A slot whose handshake is not done holds one output buffer, its SETTINGS written and waiting on TLS, until the handshake ends or the slot closes: one client that stalls its handshake keeps one buffer, as it kept a whole slot before (docs/security/tls.md, TLS-4). Each pool's ceiling is the slot count, so a borrow never fails.

accept resets the slot's connection, and once the pools are warm nothing a connection does allocates but a header block's HPACK decoding (docs/security/http2.md, H2-1). The caps are the Http2Config's, one for every slot, so a program sets them once.

The Date

Every final 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; a 1xx and 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 9113 §3 and §9.2, not ported from another implementation.

Classes

Http2TlsServer

A pool of HTTP/2 connections over TLS on one listening socket. slots are TlsTcpServer's, and connection(slot) is the HTTP/2 side of each.

class Http2TlsServer
Member
new Http2TlsServer(tlsConfig: TlsServerConfig, config: Http2Config, listener: i32, size: i32) A pool of size slots, at least one, serving HTTP/2 under config over TLS under tlsConfig on listener. Only slot 0's connection is made here, so a config it refuses panics now, with its words; every other slot's is made by the first accept into it and kept. Frame buffers are borrowed from pools as a connection needs them.
connections: Http2Connection[] The connections made so far, slot k's at k: slot 0's, made by the constructor, and one for each slot accepted into since.
date: HttpDate The date every slot's responses carry, formatted once a second for all of them: each slot's Http2Connection.date is its bytes, refreshed by connection and next. date.pin fixes its clock.
readonly pools: Http2Pools The frame buffers every slot's connection borrows: one of each per slot at most, none made up front.
tls: TlsTcpServer The TLS pool under this server, slot for slot, for what this class does not wrap, such as session tickets (enableTickets, issue, resume). Accept through this class's accept: a slot accepted on tls itself gets no fresh HTTP/2 connection, so next and flush may treat it as free or run it on the state of the slot's last peer.
accept(serverRandom: u8[], ephemeralPrivate: u8[]): i32 Accepts the next waiting connection into a free slot, as TlsTcpServer.accept does, and gives it a fresh HTTP/2 connection whose SETTINGS go out once the handshake is done: the slot's own, restarted, or one made now if this is the first accept into it. Answers the slot, or what TlsTcpServer.accept answers.
alpn(slot: i32): string The ALPN protocol slot's handshake chose.
busy(): i32 How many slots hold a connection.
close(slot: i32): void Ends slot's connection and frees the slot at once, as TlsTcpServer.close does; the connection gives back every buffer it holds.
connection(slot: i32): Http2Connection The HTTP/2 connection of slot, its date brought up to now. A slot never accepted into, or out of range, names slot 0's, which may be live.
expire(now: i64): i32 Ends every slot whose connection has outlived a timeout at now: a client that has not acknowledged the server's SETTINGS within settingsTimeout of its accept, the TLS handshake included, is sent GOAWAY SETTINGS_TIMEOUT (RFC 9113 §6.5.3) once its handshake is done, and one with nothing moved for idleTimeout, mid-stream or lingering after its close_notify, GOAWAY NO_ERROR; each frame goes as far as the socket takes it now, and the slot is closed. A program calls it from its loop, with pollWait's timeout no longer than the shorter of the two.
fd(slot: i32): i32 The descriptor of slot, for pollAdd.
flush(slot: i32): i32 Writes what slot's connection holds into TLS, as far as TLS takes it, and sends it; shuts TLS down once the connection is over (everything is sent, and it failed, or no stream is left after a GOAWAY or after the peer's byte stream ended), or ALPN chose another protocol. Answers the interest, with the write bit while the connection still holds bytes.
holds(slot: i32): boolean Whether slot holds a connection.
next(slot: i32): i32 Moves what TLS has decrypted for slot into its connection, as far as the connection has room, and answers the connection's next event. A free slot, or one whose ALPN was not h2, answers H2_ERROR.
readable(slot: i32): i32 The socket of slot is readable: TLS reads it, and what HTTP/2 has to send goes after.
rest(slot: i32): void Gives back the buffers slot's connection holds and has emptied, so an idle slot holds none.
signP256(slot: i32, key: Secret<u8[]>): i32 Signs slot's CertificateVerify with key, as TlsTcpServer.signP256 does.
size(): i32 How many slots the pool has, made or not.
writable(slot: i32): i32 The socket of slot is writable: what TLS and HTTP/2 hold goes out.

Constants

"h2"

H2_ALPN: string

The ALPN protocol identifier of HTTP/2 over TLS (RFC 9113 §3.2).