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

