@gjsify/http2-native 0.4.0 → 0.4.3

package/package.json

@@ -1,57 +1,57 @@
 {
-  "name": "@gjsify/http2-native",
-  "version": "0.4.0",
-  "description": "Optional Vala/GObject bridge providing nghttp2 primitives unreachable through libsoup's high-level GIR API: HPACK header-block encoding (for PUSH_PROMISE / DATA frames), server-side push stream-ID allocation, and a thin nghttp2_session wrapper for future cleartext HTTP/2 (h2c) support. Used by @gjsify/http2 to back ServerHttp2Stream.pushStream() / respondWithFD() / respondWithFile() and enable createServer() over plain TCP once the full Soup ↔ nghttp2 boundary is in place.",
-  "type": "module",
-  "main": "lib/esm/index.js",
-  "module": "lib/esm/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/esm/index.js"
+    "name": "@gjsify/http2-native",
+    "version": "0.4.3",
+    "description": "Optional Vala/GObject bridge providing nghttp2 primitives unreachable through libsoup's high-level GIR API: HPACK header-block encoding (for PUSH_PROMISE / DATA frames), server-side push stream-ID allocation, and a thin nghttp2_session wrapper for future cleartext HTTP/2 (h2c) support. Used by @gjsify/http2 to back ServerHttp2Stream.pushStream() / respondWithFD() / respondWithFile() and enable createServer() over plain TCP once the full Soup ↔ nghttp2 boundary is in place.",
+    "type": "module",
+    "main": "lib/esm/index.js",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "prebuilds",
+        "meson.build",
+        "src/vala"
+    ],
+    "gjsify": {
+        "prebuilds": "prebuilds"
+    },
+    "scripts": {
+        "clear": "rm -rf lib build tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo || exit 0",
+        "check": "tsc --noEmit",
+        "init:meson": "meson setup build .",
+        "init:meson:wipe": "gjsify run init:meson --wipe",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}'",
+        "build:meson": "gjsify run init:meson && meson compile -C build",
+        "build:types": "tsc",
+        "build:prebuilds": "gjsify run build:meson && mkdir -p prebuilds/linux-x86_64 && cp build/libgjsifyhttp2.so build/GjsifyHttp2-1.0.gir build/GjsifyHttp2-1.0.typelib prebuilds/linux-x86_64/",
+        "build:gir-types": "ts-for-gir generate --externalDeps --allowMissingDeps --girDirectories=./prebuilds/linux-x86_64 --girDirectories=/usr/share/gir-1.0 --modules=GjsifyHttp2-1.0 --outdir=src/ts --npmScope=@girs --package=false --ignoreVersionConflicts=true"
+    },
+    "keywords": [
+        "gjs",
+        "http2",
+        "nghttp2",
+        "hpack",
+        "push-promise",
+        "h2c",
+        "vala",
+        "native"
+    ],
+    "dependencies": {
+        "@girs/gjs": "4.0.0-rc.15",
+        "@girs/glib-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/gobject-2.0": "2.88.0-4.0.0-rc.15"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "workspace:^",
+        "@ts-for-gir/cli": "^4.0.0-rc.15",
+        "@types/node": "^25.6.2",
+        "typescript": "^6.0.3"
     }
-  },
-  "files": [
-    "lib",
-    "prebuilds",
-    "meson.build",
-    "src/vala"
-  ],
-  "gjsify": {
-    "prebuilds": "prebuilds"
-  },
-  "scripts": {
-    "clear": "rm -rf lib build tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo || exit 0",
-    "check": "tsc --noEmit",
-    "init:meson": "meson setup build .",
-    "init:meson:wipe": "yarn init:meson --wipe",
-    "build": "yarn build:gjsify && yarn build:types",
-    "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}'",
-    "build:meson": "yarn init:meson && meson compile -C build",
-    "build:types": "tsc",
-    "build:prebuilds": "yarn build:meson && mkdir -p prebuilds/linux-x86_64 && cp build/libgjsifyhttp2.so build/GjsifyHttp2-1.0.gir build/GjsifyHttp2-1.0.typelib prebuilds/linux-x86_64/",
-    "build:gir-types": "ts-for-gir generate --externalDeps --allowMissingDeps --girDirectories=./prebuilds/linux-x86_64 --girDirectories=/usr/share/gir-1.0 --modules=GjsifyHttp2-1.0 --outdir=src/ts --npmScope=@girs --package=false --ignoreVersionConflicts=true"
-  },
-  "keywords": [
-    "gjs",
-    "http2",
-    "nghttp2",
-    "hpack",
-    "push-promise",
-    "h2c",
-    "vala",
-    "native"
-  ],
-  "dependencies": {
-    "@girs/gjs": "4.0.0-rc.15",
-    "@girs/glib-2.0": "2.88.0-4.0.0-rc.15",
-    "@girs/gobject-2.0": "2.88.0-4.0.0-rc.15"
-  },
-  "devDependencies": {
-    "@gjsify/cli": "^0.4.0",
-    "@ts-for-gir/cli": "^4.0.0-rc.15",
-    "@types/node": "^25.6.2",
-    "typescript": "^6.0.3"
-  }
-}
+}

package/src/vala/frame-encoder.vala

@@ -0,0 +1,141 @@
+/*
+ * Http2FrameEncoder — HPACK + frame-builder bridge backed by libnghttp2.
+ *
+ * Why this exists
+ * ───────────────
+ * libsoup ≥ 3 speaks HTTP/2 internally, but its high-level GIR API
+ * (`Soup.Server` / `Soup.ServerMessage`) does not expose the underlying
+ * nghttp2 session — so things like PUSH_PROMISE frames, fine-grained
+ * flow-control window updates, and explicit stream-IDs are unreachable
+ * from JS. nghttp2 itself has no Vala VAPI, and its callback-driven
+ * session API is awkward to bind directly.
+ *
+ * This bridge wraps just the pieces JS-side `@gjsify/http2` needs:
+ *   • encode_headers()   — HPACK-deflate a flat name/value pair array
+ *   • build_data_frame() — wrap arbitrary bytes in a DATA frame
+ *   • build_push_promise() — emit a complete PUSH_PROMISE frame
+ *
+ * All buffer ownership stays C-side via `GLib.Bytes` to keep the
+ * SpiderMonkey GC out of nghttp2's allocations — same pattern as
+ * `@gjsify/http-soup-bridge` and `@gjsify/webrtc-native`.
+ */
+
+namespace GjsifyHttp2 {
+
+    [CCode (cname = "gjsify_http2_hpack_encode",
+            cheader_filename = "nghttp2-helpers.h")]
+    private extern GLib.Bytes? _hpack_encode (
+        [CCode (array_length = false, array_null_terminated = false)]
+        string[] names,
+        [CCode (array_length = false, array_null_terminated = false)]
+        string[] values,
+        size_t n_pairs);
+
+    [CCode (cname = "gjsify_http2_pack_frame",
+            cheader_filename = "nghttp2-helpers.h")]
+    private extern GLib.Bytes _pack_frame (uint8 type,
+                                           uint8 flags,
+                                           uint32 stream_id,
+                                           GLib.Bytes payload);
+
+    [CCode (cname = "gjsify_http2_pack_push_promise",
+            cheader_filename = "nghttp2-helpers.h")]
+    private extern GLib.Bytes _pack_push_promise (uint32 associated_stream_id,
+                                                  uint32 promised_stream_id,
+                                                  GLib.Bytes header_block);
+
+    [CCode (cname = "gjsify_http2_nghttp2_version",
+            cheader_filename = "nghttp2-helpers.h")]
+    private extern unowned string _nghttp2_version ();
+
+    /**
+     * FrameEncoder — stateless HPACK / frame builder.
+     *
+     * Each call constructs a fresh nghttp2 deflater (4 KiB dynamic table)
+     * for the header block, so callers don't need to track encoder state
+     * across multiple pushes. This trades a few microseconds of HPACK
+     * setup for simplicity — server-push is not a hot path.
+     */
+    public class FrameEncoder : GLib.Object {
+
+        /* Frame types (RFC 7540 §11.2) — exposed as constants so JS
+         * code doesn't have to hard-code magic numbers. */
+        public const uint8 TYPE_DATA          = 0x00;
+        public const uint8 TYPE_HEADERS       = 0x01;
+        public const uint8 TYPE_PUSH_PROMISE  = 0x05;
+        public const uint8 TYPE_GOAWAY        = 0x07;
+        public const uint8 TYPE_WINDOW_UPDATE = 0x08;
+
+        public const uint8 FLAG_END_STREAM  = 0x01;
+        public const uint8 FLAG_END_HEADERS = 0x04;
+
+        /**
+         * encode_headers:
+         * @names:  array of header names (must already be HTTP/2-lowercase)
+         * @values: array of header values, same length as @names
+         *
+         * HPACK-encode the given name/value pairs. Returns the encoded
+         * header block as a #GLib.Bytes, or %NULL on error.
+         */
+        public GLib.Bytes? encode_headers (string[] names, string[] values) {
+            if (names.length != values.length) return null;
+            return _hpack_encode (names, values, names.length);
+        }
+
+        /**
+         * build_data_frame:
+         * @stream_id:  stream this DATA frame belongs to
+         * @end_stream: %TRUE to set END_STREAM flag (last DATA on the stream)
+         * @payload:    payload bytes (caller must keep ≤ remote MAX_FRAME_SIZE)
+         */
+        public GLib.Bytes build_data_frame (uint32 stream_id,
+                                            bool end_stream,
+                                            GLib.Bytes payload) {
+            uint8 flags = end_stream ? FLAG_END_STREAM : 0;
+            return _pack_frame (TYPE_DATA, flags, stream_id, payload);
+        }
+
+        /**
+         * build_headers_frame:
+         * @stream_id:    target stream id
+         * @end_stream:   set END_STREAM (response with empty body)
+         * @end_headers:  set END_HEADERS (single-frame header block)
+         * @header_block: HPACK-encoded headers from encode_headers()
+         */
+        public GLib.Bytes build_headers_frame (uint32 stream_id,
+                                               bool end_stream,
+                                               bool end_headers,
+                                               GLib.Bytes header_block) {
+            uint8 flags = 0;
+            if (end_stream)  flags |= FLAG_END_STREAM;
+            if (end_headers) flags |= FLAG_END_HEADERS;
+            return _pack_frame (TYPE_HEADERS, flags, stream_id, header_block);
+        }
+
+        /**
+         * build_push_promise:
+         * @associated_stream_id: the request stream this push is associated with
+         * @promised_stream_id:   the new even-numbered server stream-id (use
+         *                        StreamIdAllocator.next_promised())
+         * @header_block:         HPACK-encoded request pseudo-headers for the push
+         *                        (`:method`, `:scheme`, `:authority`, `:path` etc.)
+         *
+         * Builds a complete PUSH_PROMISE frame with END_HEADERS set.
+         */
+        public GLib.Bytes build_push_promise (uint32 associated_stream_id,
+                                              uint32 promised_stream_id,
+                                              GLib.Bytes header_block) {
+            return _pack_push_promise (associated_stream_id, promised_stream_id, header_block);
+        }
+
+        /**
+         * nghttp2_version:
+         *
+         * Returns the libnghttp2 version string the bridge is linked against.
+         * Useful for diagnostics + version pinning in error messages.
+         */
+        public unowned string nghttp2_version () {
+            return _nghttp2_version ();
+        }
+    }
+}

package/src/vala/nghttp2-helpers.c

@@ -0,0 +1,133 @@
+/*
+ * Tiny C shim around libnghttp2's HPACK encoder + frame helpers.
+ * See nghttp2-helpers.h for the rationale + per-function docs.
+ */
+
+#include "nghttp2-helpers.h"
+
+#include <string.h>
+#include <stdlib.h>
+
+GBytes *
+gjsify_http2_hpack_encode (char **names,
+                           char **values,
+                           gsize  n_pairs)
+{
+    if (n_pairs == 0) {
+        return g_bytes_new (NULL, 0);
+    }
+    if (names == NULL || values == NULL) {
+        return NULL;
+    }
+
+    nghttp2_nv *nva = g_new0 (nghttp2_nv, n_pairs);
+    for (gsize i = 0; i < n_pairs; i++) {
+        const char *n = names[i] ? names[i] : "";
+        const char *v = values[i] ? values[i] : "";
+        nva[i].name     = (uint8_t *) n;
+        nva[i].value    = (uint8_t *) v;
+        nva[i].namelen  = strlen (n);
+        nva[i].valuelen = strlen (v);
+        nva[i].flags    = NGHTTP2_NV_FLAG_NONE;
+    }
+
+    nghttp2_hd_deflater *def = NULL;
+    int rv = nghttp2_hd_deflate_new (&def, 4096);
+    if (rv != 0 || def == NULL) {
+        g_free (nva);
+        return NULL;
+    }
+
+    size_t bound = nghttp2_hd_deflate_bound (def, nva, n_pairs);
+    guint8 *buf = g_malloc (bound);
+    ssize_t produced = nghttp2_hd_deflate_hd (def, buf, bound, nva, n_pairs);
+
+    nghttp2_hd_deflate_del (def);
+    g_free (nva);
+
+    if (produced < 0) {
+        g_free (buf);
+        return NULL;
+    }
+
+    /* GBytes takes ownership of buf via g_free destroy notify. */
+    return g_bytes_new_with_free_func (buf, (gsize) produced, g_free, buf);
+}
+
+GBytes *
+gjsify_http2_pack_frame (guint8   type,
+                         guint8   flags,
+                         guint32  stream_id,
+                         GBytes  *payload)
+{
+    gsize plen = 0;
+    const guint8 *pdata = payload ? g_bytes_get_data (payload, &plen) : NULL;
+
+    /* Frame header is 9 bytes:
+     *   length    : 24-bit big-endian
+     *   type      : 8-bit
+     *   flags     : 8-bit
+     *   stream_id : 31-bit big-endian (high bit reserved, must be 0)
+     */
+    gsize total = 9 + plen;
+    guint8 *buf = g_malloc (total);
+
+    buf[0] = (guint8) ((plen >> 16) & 0xff);
+    buf[1] = (guint8) ((plen >>  8) & 0xff);
+    buf[2] = (guint8) ((plen      ) & 0xff);
+    buf[3] = type;
+    buf[4] = flags;
+
+    guint32 sid = stream_id & 0x7fffffffu;
+    buf[5] = (guint8) ((sid >> 24) & 0xff);
+    buf[6] = (guint8) ((sid >> 16) & 0xff);
+    buf[7] = (guint8) ((sid >>  8) & 0xff);
+    buf[8] = (guint8) ((sid      ) & 0xff);
+
+    if (plen > 0 && pdata != NULL) {
+        memcpy (buf + 9, pdata, plen);
+    }
+
+    return g_bytes_new_with_free_func (buf, total, g_free, buf);
+}
+
+GBytes *
+gjsify_http2_pack_push_promise (guint32  associated_stream_id,
+                                guint32  promised_stream_id,
+                                GBytes  *header_block)
+{
+    gsize hlen = 0;
+    const guint8 *hdata = header_block ? g_bytes_get_data (header_block, &hlen) : NULL;
+
+    /* PUSH_PROMISE payload = 4-byte promised-stream-id (R + 31-bit id)
+     *                        || HPACK header block. */
+    gsize plen = 4 + hlen;
+    guint8 *payload = g_malloc (plen);
+
+    guint32 pid = promised_stream_id & 0x7fffffffu;
+    payload[0] = (guint8) ((pid >> 24) & 0xff);
+    payload[1] = (guint8) ((pid >> 16) & 0xff);
+    payload[2] = (guint8) ((pid >>  8) & 0xff);
+    payload[3] = (guint8) ((pid      ) & 0xff);
+
+    if (hlen > 0 && hdata != NULL) {
+        memcpy (payload + 4, hdata, hlen);
+    }
+
+    GBytes *payload_bytes = g_bytes_new_with_free_func (payload, plen, g_free, payload);
+    GBytes *frame = gjsify_http2_pack_frame (
+        NGHTTP2_PUSH_PROMISE,
+        NGHTTP2_FLAG_END_HEADERS,
+        associated_stream_id,
+        payload_bytes
+    );
+    g_bytes_unref (payload_bytes);
+    return frame;
+}
+
+const char *
+gjsify_http2_nghttp2_version (void)
+{
+    nghttp2_info *info = nghttp2_version (0);
+    return info ? info->version_str : "unknown";
+}

package/src/vala/nghttp2-helpers.h

@@ -0,0 +1,82 @@
+/*
+ * Tiny C shim around libnghttp2's HPACK encoder + frame helpers.
+ *
+ * Vala can bind nghttp2 directly, but the calling conventions for opaque
+ * out-pointer constructors (nghttp2_hd_deflate_new) and pointer-array
+ * structs (nghttp2_nv) are awkward to express across a VAPI we have to
+ * maintain by hand. Wrapping them in plain C functions returning GBytes
+ * is far simpler — and keeps every pointer hand-off inside C, which is
+ * exactly the pattern @gjsify/http-soup-bridge / @gjsify/webrtc-native
+ * use to keep SpiderMonkey GC out of the libnghttp2 boxed lifecycle.
+ *
+ * Reference: nghttp2/nghttp2.h (libnghttp2 ≥ 1.40).
+ */
+
+#ifndef GJSIFY_HTTP2_NGHTTP2_HELPERS_H
+#define GJSIFY_HTTP2_NGHTTP2_HELPERS_H
+
+#include <glib.h>
+#include <nghttp2/nghttp2.h>
+
+G_BEGIN_DECLS
+
+/**
+ * gjsify_http2_hpack_encode:
+ * @names:      flat name array  (length = n_pairs)
+ * @values:     flat value array (length = n_pairs)
+ * @n_pairs:    number of header pairs
+ *
+ * HPACK-encode @n_pairs name/value strings using a fresh nghttp2 deflater
+ * (default 4096-byte dynamic table). Returns a freshly-allocated #GBytes
+ * containing the encoded header block, or %NULL on error.
+ *
+ * Lower-cases nothing — caller is responsible for HTTP/2 lowercase rules.
+ */
+GBytes *gjsify_http2_hpack_encode (char **names,
+                                   char **values,
+                                   gsize  n_pairs);
+
+/**
+ * gjsify_http2_pack_frame:
+ * @type:        nghttp2 frame type (1=HEADERS, 5=PUSH_PROMISE, 0=DATA, ...)
+ * @flags:       frame flags (END_STREAM=0x01, END_HEADERS=0x04, ...)
+ * @stream_id:   stream identifier (31-bit)
+ * @payload:     frame payload bytes (already HPACK-encoded for header frames,
+ *               raw bytes for DATA / PUSH_PROMISE-with-promised-id-prefix)
+ *
+ * Builds a complete HTTP/2 frame: 9-byte fixed header (length, type, flags,
+ * stream-id) followed by @payload. Returns a freshly-allocated #GBytes.
+ *
+ * Caller is responsible for splitting payloads larger than 16384 bytes
+ * across CONTINUATION frames if needed (this helper does NOT segment).
+ */
+GBytes *gjsify_http2_pack_frame (guint8       type,
+                                 guint8       flags,
+                                 guint32      stream_id,
+                                 GBytes      *payload);
+
+/**
+ * gjsify_http2_pack_push_promise:
+ * @associated_stream_id: the parent stream the push is associated with
+ * @promised_stream_id:   the new even-numbered stream-id the server reserves
+ * @header_block:         HPACK-encoded request headers for the push
+ *
+ * Convenience wrapper combining the 4-byte promised-stream-id prefix that
+ * PUSH_PROMISE requires with @header_block, then frames it. Sets
+ * END_HEADERS flag (single-frame header block — caller must keep
+ * @header_block ≤ remote SETTINGS_MAX_FRAME_SIZE − 4).
+ */
+GBytes *gjsify_http2_pack_push_promise (guint32  associated_stream_id,
+                                        guint32  promised_stream_id,
+                                        GBytes  *header_block);
+
+/**
+ * gjsify_http2_nghttp2_version:
+ *
+ * Returns the libnghttp2 runtime version string ("1.62.0", ...).
+ */
+const char *gjsify_http2_nghttp2_version (void);
+
+G_END_DECLS
+
+#endif /* GJSIFY_HTTP2_NGHTTP2_HELPERS_H */

package/src/vala/session-bridge.vala

@@ -0,0 +1,65 @@
+/*
+ * SessionBridge — placeholder for the future cleartext-HTTP/2 (h2c)
+ * session driver.
+ *
+ * Intent
+ * ──────
+ * Once we wire `nghttp2_session_server_new()` against a `Gio.Socket` we
+ * obtain from a Soup.Server `request-aborted` / raw socket callback (or
+ * directly from `Gio.SocketService` when bypassing Soup entirely), this
+ * class will own:
+ *   • the nghttp2_session pointer
+ *   • a 64 KiB read buffer driven by a `g_socket_create_source(IN)`
+ *     watch on the GLib main context
+ *   • a write queue drained on `OUT` readiness
+ *   • mirror signals (`request_received`, `data_received`, `stream_closed`,
+ *     `goaway_received`) re-emitted on the main context via `GLib.Idle.add`
+ *     — same hop pattern as @gjsify/webrtc-native bridges
+ *
+ * Until that lands, this class only validates the HTTP/2 connection
+ * preface ("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n", 24 bytes) so JS-side code
+ * detecting a prior-knowledge h2c upgrade can route the socket through
+ * a future native session loop.
+ */
+
+namespace GjsifyHttp2 {
+
+    public class SessionBridge : GLib.Object {
+
+        /**
+         * is_client_preface:
+         * @bytes: the first ≥ 24 bytes received on a TCP connection
+         *
+         * Returns %TRUE if @bytes starts with the RFC 7540 §3.5 client
+         * connection preface ("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n").
+         * Used to detect prior-knowledge h2c on a freshly-accepted socket
+         * before deciding whether to dispatch it to Soup (HTTP/1.1) or
+         * the future native nghttp2 session loop.
+         */
+        public static bool is_client_preface (GLib.Bytes? bytes) {
+            if (bytes == null) return false;
+            const uint8 PREFACE[] = {
+                0x50, 0x52, 0x49, 0x20, 0x2a, 0x20, 0x48, 0x54,
+                0x54, 0x50, 0x2f, 0x32, 0x2e, 0x30, 0x0d, 0x0a,
+                0x0d, 0x0a, 0x53, 0x4d, 0x0d, 0x0a, 0x0d, 0x0a
+            };
+            size_t blen;
+            unowned uint8[] data = bytes.get_data ();
+            blen = data.length;
+            if (blen < 24) return false;
+            for (int i = 0; i < 24; i++) {
+                if (data[i] != PREFACE[i]) return false;
+            }
+            return true;
+        }
+
+        /**
+         * preface_length:
+         *
+         * Returns the size of the HTTP/2 client connection preface (24).
+         */
+        public static uint preface_length () {
+            return 24;
+        }
+    }
+}

package/src/vala/stream-id-allocator.vala

@@ -0,0 +1,62 @@
+/*
+ * StreamIdAllocator — server-side HTTP/2 stream-id sequencer.
+ *
+ * Per RFC 7540 §5.1.1:
+ *   • Client-initiated streams use odd ids (1, 3, 5, ...)
+ *   • Server-initiated (push) streams use even ids (2, 4, 6, ...)
+ *
+ * The next-id pointer is monotonically increasing per session and must
+ * never wrap. Once we exhaust the 31-bit id space we MUST send a GOAWAY
+ * with NGHTTP2_NO_ERROR and let a fresh connection take over.
+ *
+ * One allocator instance per ServerHttp2Session.
+ */
+
+namespace GjsifyHttp2 {
+
+    public class StreamIdAllocator : GLib.Object {
+
+        /* Max valid stream id (31-bit). Anything >= this is exhausted. */
+        public const uint32 MAX_STREAM_ID = 0x7fffffffu;
+
+        private uint32 _next_promised = 2;
+        private uint32 _last_client = 0;
+
+        /**
+         * next_promised:
+         *
+         * Returns the next even stream-id to use for a PUSH_PROMISE.
+         * Returns 0 if the id space is exhausted — caller MUST then
+         * send GOAWAY and refuse further pushes.
+         */
+        public uint32 next_promised () {
+            if (_next_promised > MAX_STREAM_ID) return 0;
+            uint32 id = _next_promised;
+            _next_promised += 2;
+            return id;
+        }
+
+        /**
+         * record_client_stream:
+         * @id: client-initiated odd stream-id observed on this session
+         *
+         * Track the highest client stream-id seen — needed for the
+         * `last-stream-id` field of a GOAWAY frame.
+         */
+        public void record_client_stream (uint32 id) {
+            if ((id & 1u) == 1u && id > _last_client) {
+                _last_client = id;
+            }
+        }
+
+        public uint32 last_client_stream_id { get { return _last_client; } }
+
+        /** Number of pushes that can still be issued (count, not id). */
+        public uint32 remaining_pushes {
+            get {
+                if (_next_promised > MAX_STREAM_ID) return 0;
+                return (MAX_STREAM_ID - _next_promised) / 2u + 1u;
+            }
+        }
+    }
+}