@volter/twin-temporal 0.1.0

package/dist/src/temporal-h2.js

@@ -0,0 +1,644 @@
+import hpack from './generated/hpack.json' with { type: 'json' };
+const PREFACE = Buffer.from('PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n', 'latin1');
+const FRAME = { DATA: 0, HEADERS: 1, PRIORITY: 2, RST_STREAM: 3, SETTINGS: 4, PUSH_PROMISE: 5, PING: 6, GOAWAY: 7, WINDOW_UPDATE: 8, CONTINUATION: 9 };
+const FLAG = { END_STREAM: 0x1, ACK: 0x1, END_HEADERS: 0x4, PADDED: 0x8, PRIORITY: 0x20 };
+const ERROR = { NO_ERROR: 0, PROTOCOL_ERROR: 1, INTERNAL_ERROR: 2, FLOW_CONTROL_ERROR: 3, STREAM_CLOSED: 5, FRAME_SIZE_ERROR: 6, REFUSED_STREAM: 7, CANCEL: 8, COMPRESSION_ERROR: 9 };
+const DEFAULT_WINDOW = 65_535;
+/** what this server grants each stream and the connection to receive */
+const RECEIVE_WINDOW = 16 * 1024 * 1024;
+const MAX_CONCURRENT_STREAMS = 1000;
+/** a request body larger than this resets its stream: a memory bound, not Temporal's message limit (the
+ *  SDKs' gRPC default is 4 MiB; this server does not enforce that one) */
+const MAX_REQUEST_BYTES = 64 * 1024 * 1024;
+/** a header block (HEADERS + CONTINUATION) larger than this closes the connection */
+const MAX_HEADER_BLOCK = 256 * 1024;
+// ---- HPACK ------------------------------------------------------------------------------------
+const STATIC_TABLE = hpack.staticTable;
+const HUFFMAN_ROOT = (() => {
+    const root = {};
+    hpack.huffman.forEach(([code, length], symbol) => {
+        let node = root;
+        for (let bit = length - 1; bit >= 0; bit -= 1) {
+            const key = (code >>> bit) & 1 ? 'one' : 'zero';
+            node = node[key] ??= {};
+        }
+        node.symbol = symbol;
+    });
+    return root;
+})();
+export class HpackError extends Error {
+}
+export function huffmanDecode(bytes) {
+    const out = [];
+    let node = HUFFMAN_ROOT;
+    let pending = 0; // bits consumed since the last symbol
+    let allOnes = true;
+    for (const byte of bytes) {
+        for (let bit = 7; bit >= 0; bit -= 1) {
+            const one = (byte >> bit) & 1;
+            const next = one ? node.one : node.zero;
+            if (!next)
+                throw new HpackError('invalid huffman code');
+            pending += 1;
+            allOnes &&= one === 1;
+            if (next.symbol !== undefined) {
+                if (next.symbol === 256)
+                    throw new HpackError('EOS symbol inside a huffman string'); // §5.2
+                out.push(next.symbol);
+                node = HUFFMAN_ROOT;
+                pending = 0;
+                allOnes = true;
+            }
+            else {
+                node = next;
+            }
+        }
+    }
+    // §5.2: padding is at most 7 bits and is the most significant bits of EOS (all ones)
+    if (pending > 7 || !allOnes)
+        throw new HpackError('invalid huffman padding');
+    return Buffer.from(out).toString('latin1');
+}
+export class HpackDecoder {
+    table = [];
+    size = 0;
+    maxSize;
+    /** the SETTINGS_HEADER_TABLE_SIZE this endpoint advertised (the decoder's ceiling; 4096 is the
+     *  protocol default, which this server never changes) */
+    limit;
+    constructor(headerTableSize = 4096) {
+        this.maxSize = headerTableSize;
+        this.limit = headerTableSize;
+    }
+    decode(block) {
+        const headers = [];
+        let offset = 0;
+        const integer = (prefixBits) => {
+            const mask = (1 << prefixBits) - 1;
+            let value = block[offset] & mask;
+            offset += 1;
+            if (value < mask)
+                return value;
+            let shift = 0;
+            for (;;) {
+                if (offset >= block.length)
+                    throw new HpackError('truncated integer');
+                const byte = block[offset];
+                offset += 1;
+                value += (byte & 0x7f) * 2 ** shift;
+                shift += 7;
+                if ((byte & 0x80) === 0)
+                    return value;
+                if (shift > 28)
+                    throw new HpackError('integer overflow');
+            }
+        };
+        const string = () => {
+            if (offset >= block.length)
+                throw new HpackError('truncated string');
+            const huffman = (block[offset] & 0x80) !== 0;
+            const length = integer(7);
+            if (offset + length > block.length)
+                throw new HpackError('truncated string');
+            const bytes = block.subarray(offset, offset + length);
+            offset += length;
+            return huffman ? huffmanDecode(bytes) : Buffer.from(bytes).toString('latin1');
+        };
+        const entry = (index) => {
+            if (index <= 0)
+                throw new HpackError('index 0');
+            if (index <= STATIC_TABLE.length)
+                return STATIC_TABLE[index - 1];
+            const dynamic = this.table[index - STATIC_TABLE.length - 1];
+            if (!dynamic)
+                throw new HpackError(`index ${index} is beyond the dynamic table`);
+            return dynamic;
+        };
+        while (offset < block.length) {
+            const byte = block[offset];
+            if (byte & 0x80) { // §6.1 indexed
+                headers.push(entry(integer(7)));
+            }
+            else if (byte & 0x40) { // §6.2.1 literal with incremental indexing
+                const index = integer(6);
+                const name = index === 0 ? string() : entry(index)[0];
+                const value = string();
+                headers.push([name, value]);
+                this.insert(name, value);
+            }
+            else if (byte & 0x20) { // §6.3 dynamic table size update
+                const size = integer(5);
+                if (size > this.limit)
+                    throw new HpackError('table size update above the advertised limit');
+                this.maxSize = size;
+                this.evict();
+            }
+            else { // §6.2.2 without indexing / §6.2.3 never indexed
+                const index = integer(4);
+                const name = index === 0 ? string() : entry(index)[0];
+                headers.push([name, string()]);
+            }
+        }
+        return headers;
+    }
+    insert(name, value) {
+        this.table.unshift([name, value]);
+        this.size += name.length + value.length + 32;
+        this.evict();
+    }
+    evict() {
+        while (this.size > this.maxSize && this.table.length > 0) {
+            const [name, value] = this.table.pop();
+            this.size -= name.length + value.length + 32;
+        }
+    }
+}
+function hpackInteger(value, prefixBits, firstByte) {
+    const mask = (1 << prefixBits) - 1;
+    if (value < mask)
+        return [firstByte | value];
+    const out = [firstByte | mask];
+    let rest = value - mask;
+    while (rest >= 128) {
+        out.push((rest % 128) + 128);
+        rest = Math.floor(rest / 128);
+    }
+    out.push(rest);
+    return out;
+}
+/** Every header as a literal without indexing, new name, no huffman (RFC 7541 §6.2.2). */
+export function hpackEncode(headers) {
+    const out = [];
+    for (const [name, value] of headers) {
+        const nameBytes = Buffer.from(name.toLowerCase(), 'latin1');
+        const valueBytes = Buffer.from(value, 'latin1');
+        out.push(0x00, ...hpackInteger(nameBytes.length, 7, 0), ...nameBytes, ...hpackInteger(valueBytes.length, 7, 0), ...valueBytes);
+    }
+    return Uint8Array.from(out);
+}
+function frameHeader(length, type, flags, streamId) {
+    const header = Buffer.alloc(9);
+    header.writeUIntBE(length, 0, 3);
+    header[3] = type;
+    header[4] = flags;
+    header.writeUInt32BE(streamId & 0x7fffffff, 5);
+    return header;
+}
+class H2Connection {
+    buffer = Buffer.alloc(0);
+    prefaceSeen = false;
+    decoder = new HpackDecoder();
+    streams = new Map();
+    continuing = null;
+    lastStreamId = 0;
+    peerInitialWindow = DEFAULT_WINDOW;
+    peerMaxFrame = 16_384;
+    connectionSendWindow = DEFAULT_WINDOW;
+    dead = false;
+    socket;
+    handler;
+    http1;
+    http1Mode = false;
+    constructor(socket, handler, http1) {
+        this.socket = socket;
+        this.handler = handler;
+        this.http1 = http1;
+        socket.on('data', (chunk) => this.receive(chunk));
+        socket.on('close', () => this.teardown());
+        socket.on('error', () => this.teardown());
+    }
+    /** The server's connection preface (§3.4), sent once the client's has arrived: no push, a stream
+     *  ceiling and a large receive window. Waiting for the client's is what lets an HTTP/1 request on
+     *  the same port be answered as one instead of receiving binary frames first. */
+    sendPreface() {
+        const settings = Buffer.alloc(18);
+        settings.writeUInt16BE(0x2, 0);
+        settings.writeUInt32BE(0, 2); // ENABLE_PUSH
+        settings.writeUInt16BE(0x3, 6);
+        settings.writeUInt32BE(MAX_CONCURRENT_STREAMS, 8);
+        settings.writeUInt16BE(0x4, 12);
+        settings.writeUInt32BE(RECEIVE_WINDOW, 14);
+        this.write(FRAME.SETTINGS, 0, 0, settings);
+        this.windowUpdate(0, RECEIVE_WINDOW - DEFAULT_WINDOW);
+    }
+    /** An HTTP/1.1 request on this port (a World's door probe, a curl of the HTTP API): read one
+     *  request, answer it through the fetch handler, close. */
+    receiveHttp1() {
+        const end = this.buffer.indexOf('\r\n\r\n');
+        if (end < 0) {
+            if (this.buffer.length > 64 * 1024)
+                this.teardown();
+            return;
+        }
+        const head = this.buffer.subarray(0, end).toString('latin1').split('\r\n');
+        const [method, target] = head[0].split(' ');
+        const headers = new Headers();
+        try {
+            for (const line of head.slice(1)) {
+                const colon = line.indexOf(':');
+                if (colon > 0)
+                    headers.append(line.slice(0, colon).trim(), line.slice(colon + 1).trim());
+            }
+        }
+        catch {
+            this.respondHttp1(new Response('bad header', { status: 400 }));
+            return;
+        }
+        if (headers.get('transfer-encoding')) {
+            this.respondHttp1(new Response('chunked request bodies are not accepted', { status: 411 }));
+            return;
+        }
+        const length = Number(headers.get('content-length') ?? 0);
+        if (!Number.isFinite(length) || length < 0 || length > MAX_REQUEST_BYTES) {
+            this.respondHttp1(new Response('bad content-length', { status: 400 }));
+            return;
+        }
+        if (this.buffer.length < end + 4 + length)
+            return;
+        const body = this.buffer.subarray(end + 4, end + 4 + length);
+        this.buffer = Buffer.alloc(0);
+        this.socket.removeAllListeners('data');
+        let request;
+        try {
+            // the URL is built on loopback, never on the client's Host header
+            if (!target?.startsWith('/'))
+                throw new Error('request target must be origin-form');
+            request = new Request(`http://127.0.0.1${target}`, {
+                method: method, headers, ...(method === 'GET' || method === 'HEAD' ? {} : { body: new Uint8Array(body) }),
+            });
+        }
+        catch {
+            this.respondHttp1(new Response('bad request', { status: 400 }));
+            return;
+        }
+        void Promise.resolve().then(() => this.http1(request)).then((response) => this.respondHttp1(response), () => this.respondHttp1(new Response('internal error', { status: 500 })));
+    }
+    respondHttp1(response) {
+        void response.arrayBuffer().then((bytes) => {
+            if (this.dead)
+                return;
+            const lines = [`HTTP/1.1 ${response.status} ${response.statusText || 'OK'}`];
+            response.headers.forEach((value, key) => { if (key !== 'content-length' && key !== 'connection')
+                lines.push(`${key}: ${value}`); });
+            lines.push(`content-length: ${bytes.byteLength}`, 'connection: close', '', '');
+            this.socket.end(Buffer.concat([Buffer.from(lines.join('\r\n'), 'latin1'), Buffer.from(bytes)]));
+        });
+    }
+    write(type, flags, streamId, payload = new Uint8Array(0)) {
+        if (this.dead)
+            return;
+        this.socket.write(Buffer.concat([frameHeader(payload.length, type, flags, streamId), payload]));
+    }
+    windowUpdate(streamId, increment) {
+        if (increment <= 0)
+            return;
+        const payload = Buffer.alloc(4);
+        payload.writeUInt32BE(increment & 0x7fffffff, 0);
+        this.write(FRAME.WINDOW_UPDATE, 0, streamId, payload);
+    }
+    goaway(code, message) {
+        const payload = Buffer.concat([Buffer.alloc(8), Buffer.from(message, 'utf8')]);
+        payload.writeUInt32BE(this.lastStreamId & 0x7fffffff, 0);
+        payload.writeUInt32BE(code, 4);
+        this.write(FRAME.GOAWAY, 0, 0, payload);
+        // end, not destroy: the GOAWAY frame is flushed before the socket closes
+        this.dead = true;
+        for (const stream of this.streams.values())
+            stream.abort.abort();
+        this.streams.clear();
+        this.socket.end();
+        // a peer that never closes its half is cut off after a grace
+        setTimeout(() => this.socket.destroy(), 1000).unref?.();
+    }
+    resetStream(stream, code) {
+        const payload = Buffer.alloc(4);
+        payload.writeUInt32BE(code, 0);
+        this.write(FRAME.RST_STREAM, 0, stream.id, payload);
+        this.closeStream(stream);
+    }
+    closeStream(stream) {
+        stream.localClosed = true;
+        stream.remoteClosed = true;
+        stream.outbound = [];
+        stream.abort.abort();
+        this.streams.delete(stream.id);
+    }
+    teardown() {
+        if (this.dead) {
+            this.socket.destroy();
+            return;
+        }
+        this.dead = true;
+        for (const stream of this.streams.values())
+            stream.abort.abort();
+        this.streams.clear();
+        this.socket.destroy();
+    }
+    receive(chunk) {
+        if (this.dead)
+            return;
+        this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;
+        if (this.http1Mode) {
+            this.receiveHttp1();
+            return;
+        }
+        if (!this.prefaceSeen) {
+            const seen = this.buffer.subarray(0, Math.min(this.buffer.length, PREFACE.length));
+            if (!PREFACE.subarray(0, seen.length).equals(seen)) {
+                // not HTTP/2: an HTTP/1 request line is answered by the fetch handler, anything else refused
+                const start = this.buffer.subarray(0, 8).toString('latin1');
+                if (this.http1 && this.buffer.length < 8 && /^[A-Z]+$/.test(start))
+                    return; // a method still arriving
+                if (this.http1 && /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS) /.test(start)) {
+                    this.http1Mode = true;
+                    this.receiveHttp1();
+                    return;
+                }
+                this.socket.end();
+                this.teardown();
+                return;
+            }
+            if (this.buffer.length < PREFACE.length)
+                return;
+            this.prefaceSeen = true;
+            this.buffer = this.buffer.subarray(PREFACE.length);
+            this.sendPreface();
+        }
+        while (!this.dead && this.buffer.length >= 9) {
+            const length = this.buffer.readUIntBE(0, 3);
+            if (length > 16_384) {
+                this.goaway(ERROR.FRAME_SIZE_ERROR, 'frame larger than SETTINGS_MAX_FRAME_SIZE');
+                return;
+            }
+            if (this.buffer.length < 9 + length)
+                return;
+            const type = this.buffer[3];
+            const flags = this.buffer[4];
+            const streamId = this.buffer.readUInt32BE(5) & 0x7fffffff;
+            const payload = this.buffer.subarray(9, 9 + length);
+            this.buffer = this.buffer.subarray(9 + length);
+            try {
+                this.frame(type, flags, streamId, payload);
+            }
+            catch (error) {
+                this.goaway(error instanceof HpackError ? ERROR.COMPRESSION_ERROR : ERROR.PROTOCOL_ERROR, error.message);
+                return;
+            }
+        }
+    }
+    frame(type, flags, streamId, payload) {
+        if (this.continuing && type !== FRAME.CONTINUATION)
+            throw new Error('expected CONTINUATION'); // §6.10
+        switch (type) {
+            case FRAME.SETTINGS: {
+                if (streamId !== 0)
+                    throw new Error('SETTINGS on a stream');
+                if (flags & FLAG.ACK)
+                    return;
+                if (payload.length % 6 !== 0)
+                    throw new Error('SETTINGS length');
+                for (let i = 0; i < payload.length; i += 6) {
+                    const id = payload.readUInt16BE(i);
+                    const value = payload.readUInt32BE(i + 2);
+                    if (id === 0x4) {
+                        if (value > 0x7fffffff)
+                            throw new Error('SETTINGS_INITIAL_WINDOW_SIZE too large');
+                        const delta = value - this.peerInitialWindow;
+                        this.peerInitialWindow = value;
+                        for (const stream of this.streams.values())
+                            stream.sendWindow += delta;
+                    }
+                    else if (id === 0x5) {
+                        if (value < 16_384 || value > 16_777_215)
+                            throw new Error('SETTINGS_MAX_FRAME_SIZE out of range');
+                        this.peerMaxFrame = value;
+                    }
+                    // HEADER_TABLE_SIZE governs the peer's decoder of OUR blocks, which never index; the
+                    // rest (push, concurrency, header list size) bound what this server already never does
+                }
+                this.write(FRAME.SETTINGS, FLAG.ACK, 0);
+                this.flush();
+                return;
+            }
+            case FRAME.PING: {
+                if (payload.length !== 8)
+                    throw new Error('PING length');
+                if (!(flags & FLAG.ACK))
+                    this.write(FRAME.PING, FLAG.ACK, 0, payload);
+                return;
+            }
+            case FRAME.GOAWAY: {
+                this.socket.end();
+                this.teardown();
+                return;
+            }
+            case FRAME.WINDOW_UPDATE: {
+                if (payload.length !== 4)
+                    throw new Error('WINDOW_UPDATE length');
+                const increment = payload.readUInt32BE(0) & 0x7fffffff;
+                if (streamId === 0) {
+                    if (increment === 0)
+                        throw new Error('WINDOW_UPDATE of 0');
+                    this.connectionSendWindow += increment;
+                }
+                else {
+                    const stream = this.streams.get(streamId);
+                    if (stream)
+                        stream.sendWindow += increment;
+                }
+                this.flush();
+                return;
+            }
+            case FRAME.RST_STREAM: {
+                const stream = this.streams.get(streamId);
+                if (stream)
+                    this.closeStream(stream);
+                return;
+            }
+            case FRAME.PRIORITY:
+                return;
+            case FRAME.PUSH_PROMISE:
+                throw new Error('a client never sends PUSH_PROMISE');
+            case FRAME.HEADERS: {
+                if (streamId === 0 || streamId % 2 === 0)
+                    throw new Error('HEADERS on an invalid stream id');
+                let body = payload;
+                let pad = 0;
+                if (flags & FLAG.PADDED) {
+                    pad = body[0];
+                    body = body.subarray(1);
+                }
+                if (flags & FLAG.PRIORITY)
+                    body = body.subarray(5);
+                if (pad > body.length)
+                    throw new Error('padding exceeds HEADERS payload');
+                body = body.subarray(0, body.length - pad);
+                let stream = this.streams.get(streamId);
+                if (!stream) {
+                    if (streamId <= this.lastStreamId)
+                        throw new Error('stream id reused'); // §5.1.1
+                    this.lastStreamId = streamId;
+                    stream = {
+                        id: streamId, headerBlock: [], headers: {}, body: [], bodyBytes: 0, remoteClosed: false, localClosed: false,
+                        sendWindow: this.peerInitialWindow, outbound: [], abort: new AbortController(),
+                    };
+                    this.streams.set(streamId, stream);
+                }
+                else {
+                    // trailers from the client: this server's methods carry none, but the block must still
+                    // be decoded to keep the HPACK table in step
+                    stream.headerBlock = [];
+                }
+                stream.headerBlock.push(body);
+                if (stream.dispatched)
+                    stream.late = true; // decoded for the HPACK table, then refused
+                if (flags & FLAG.END_STREAM)
+                    stream.remoteClosed = true;
+                if (flags & FLAG.END_HEADERS)
+                    this.headersDone(stream);
+                else
+                    this.continuing = stream;
+                return;
+            }
+            case FRAME.CONTINUATION: {
+                const stream = this.continuing;
+                if (!stream || stream.id !== streamId)
+                    throw new Error('CONTINUATION without HEADERS');
+                stream.headerBlock.push(payload);
+                if (stream.headerBlock.reduce((n, part) => n + part.length, 0) > MAX_HEADER_BLOCK)
+                    throw new Error('header block too large');
+                if (flags & FLAG.END_HEADERS) {
+                    this.continuing = null;
+                    this.headersDone(stream);
+                }
+                return;
+            }
+            case FRAME.DATA: {
+                let body = payload;
+                if (flags & FLAG.PADDED) {
+                    const pad = body[0];
+                    if (pad >= body.length)
+                        throw new Error('padding exceeds DATA payload');
+                    body = body.subarray(1, body.length - pad);
+                }
+                // replenish what the frame consumed (padding included), connection and stream
+                this.windowUpdate(0, payload.length);
+                const stream = this.streams.get(streamId);
+                if (!stream || stream.remoteClosed) {
+                    if (streamId > this.lastStreamId)
+                        throw new Error('DATA on an idle stream');
+                    return; // a stream this server already closed or reset
+                }
+                if (!(flags & FLAG.END_STREAM))
+                    this.windowUpdate(streamId, payload.length);
+                stream.body.push(Buffer.from(body));
+                stream.bodyBytes += body.length;
+                if (stream.bodyBytes > MAX_REQUEST_BYTES) {
+                    this.resetStream(stream, ERROR.REFUSED_STREAM);
+                    return;
+                }
+                if (flags & FLAG.END_STREAM) {
+                    stream.remoteClosed = true;
+                    this.dispatch(stream);
+                }
+                return;
+            }
+            default:
+                return; // §4.1: unknown frame types are ignored
+        }
+    }
+    headersDone(stream) {
+        const block = Buffer.concat(stream.headerBlock);
+        stream.headerBlock = null;
+        const decoded = this.decoder.decode(block);
+        // the decoded list is bounded too: indexed references re-emit dynamic entries, so a small block
+        // can decode to far more than it carries (SETTINGS_MAX_HEADER_LIST_SIZE's concern, RFC 9113 §6.5.2)
+        if (decoded.reduce((n, [name, value]) => n + name.length + value.length + 32, 0) > MAX_HEADER_BLOCK)
+            throw new HpackError('decoded header list too large');
+        // a header block on a stream this server already answers is a stream error (RFC 9113 §5.1,
+        // half-closed (remote)): it is never dispatched a second time
+        if (stream.late) {
+            this.resetStream(stream, ERROR.STREAM_CLOSED);
+            return;
+        }
+        const first = Object.keys(stream.headers).length === 0;
+        if (first)
+            for (const [name, value] of decoded)
+                stream.headers[name] = stream.headers[name] === undefined ? value : `${stream.headers[name]}, ${value}`;
+        if (this.streams.size > MAX_CONCURRENT_STREAMS) {
+            this.resetStream(stream, ERROR.REFUSED_STREAM);
+            return;
+        }
+        if (stream.remoteClosed)
+            this.dispatch(stream);
+    }
+    dispatch(stream) {
+        if (stream.dispatched)
+            return;
+        stream.dispatched = true;
+        const response = {
+            headers: (headers, end = false) => this.enqueue(stream, { kind: 'headers', block: hpackEncode(headers), end }),
+            data: (bytes) => this.enqueue(stream, { kind: 'data', bytes, offset: 0 }),
+            trailers: (headers) => this.enqueue(stream, { kind: 'headers', block: hpackEncode(headers), end: true }),
+            get closed() { return stream.localClosed; },
+        };
+        try {
+            this.handler({ headers: stream.headers, body: Buffer.concat(stream.body), signal: stream.abort.signal }, response);
+        }
+        catch {
+            this.resetStream(stream, ERROR.INTERNAL_ERROR);
+        }
+    }
+    enqueue(stream, item) {
+        if (stream.localClosed || this.dead)
+            return;
+        stream.outbound.push(item);
+        if (item.kind === 'headers' && item.end)
+            stream.localClosed = true;
+        this.flush();
+    }
+    flush() {
+        for (const stream of [...this.streams.values()]) {
+            while (stream.outbound.length > 0 && !this.dead) {
+                const item = stream.outbound[0];
+                if (item.kind === 'headers') {
+                    // one HEADERS frame, CONTINUATION for a block larger than the peer's frame size
+                    let offset = 0;
+                    const block = item.block;
+                    const firstLength = Math.min(block.length, this.peerMaxFrame);
+                    const last = firstLength === block.length;
+                    this.write(FRAME.HEADERS, (item.end ? FLAG.END_STREAM : 0) | (last ? FLAG.END_HEADERS : 0), stream.id, block.subarray(0, firstLength));
+                    offset = firstLength;
+                    while (offset < block.length) {
+                        const length = Math.min(block.length - offset, this.peerMaxFrame);
+                        this.write(FRAME.CONTINUATION, offset + length === block.length ? FLAG.END_HEADERS : 0, stream.id, block.subarray(offset, offset + length));
+                        offset += length;
+                    }
+                    stream.outbound.shift();
+                    if (item.end) {
+                        this.streams.delete(stream.id);
+                        break;
+                    }
+                    continue;
+                }
+                const remaining = item.bytes.length - item.offset;
+                const allowance = Math.min(remaining, this.peerMaxFrame, this.connectionSendWindow, stream.sendWindow);
+                if (remaining > 0 && allowance <= 0)
+                    break; // wait for WINDOW_UPDATE
+                const chunk = item.bytes.subarray(item.offset, item.offset + allowance);
+                this.write(FRAME.DATA, 0, stream.id, chunk);
+                item.offset += allowance;
+                this.connectionSendWindow -= allowance;
+                stream.sendWindow -= allowance;
+                if (item.offset >= item.bytes.length)
+                    stream.outbound.shift();
+            }
+        }
+    }
+}
+/** Speak HTTP/2 (h2c with prior knowledge) on an accepted socket; an HTTP/1 request line is handed to
+ *  `http1` when given. The listener that accepts sockets is the server module's (temporal-server.ts). */
+export function acceptH2Connection(socket, handler, http1) {
+    socket.setNoDelay(true);
+    return new H2Connection(socket, handler, http1);
+}

package/dist/src/temporal-history.d.ts

@@ -0,0 +1,27 @@
+export declare const TEMPORAL_SERVICE = "temporal";
+/** A history event in the engine's plain form (temporal-proto.ts `OBJECT`): `eventId`, `eventTime`,
+ *  `eventType` and one `<kind>EventAttributes`. */
+export type HistoryEvent = Record<string, unknown> & {
+    eventId: number;
+    eventType: string;
+};
+/** A stored subject: its fields as written (the kernel's `id`/`type`/`updatedAt` are its own). */
+export type Stored = Record<string, unknown> & {
+    id: string;
+};
+export declare class TemporalStore {
+    readonly root: string | undefined;
+    constructor(root?: string);
+    /** Every subject of one type, as its own fields. READ-ONLY: the kernel's memoized tree and parsed
+     *  log rows share nested objects with what this hands out, so a caller that changes a subject
+     *  copies it first (the engine's RunTx does, deeply) — editing one in place corrupts the log the
+     *  kernel digests. */
+    list(type: string): Stored[];
+    get(type: string, id: string): Stored | undefined;
+    /** Write one subject (all of its fields) under `operation`, the RPC or the server act that moved it. */
+    put(type: string, id: string, fields: Record<string, unknown>, operation: string, input?: Record<string, unknown>): Promise<void>;
+    /** Store a run's new events as one chunk; answers the chunk's key for the subject to name. */
+    appendChunk(events: HistoryEvent[]): Promise<string>;
+    /** A run's events, in order, from the chunks its subject names. */
+    readChunks(keys: string[]): Promise<HistoryEvent[]>;
+}