Subtle ordering hazard worth thinking about: the constructor sends initial settings via Http2Settings::send() without pushing to pending_settings_acks. If the user calls session.settings(cb1) before the peer ACKs the constructor's initial settings, the queue is [cb1], then the constructor ACK arrives first and pops cb1 — cb1 is invoked for the wrong settings ACK. The user's actual ACK then finds an empty queue and is silently dropped.

Node's outstanding_settings_ queue handles this by always pushing for every settings submission (including the constructor's, with a noop callback). Either match that pattern, or push a sentinel for the constructor's submission and skip-pop on it.

Addressed in 17992c0. The push now happens before submit in fn settings(cb), and I added an invariant comment on pending_settings_acks documenting that JS routes the constructor's initial settings through the same Http2Session.prototype.settings → submitSettings → kHandle.settings(boundCb) path (with settingsCallback.bind(this, undefined) as the cb), so the queue and outbound SETTINGS frames stay 1:1.

Non-blocking: Vec::remove(0) is O(n). For a session that posts many session.settings(cb) calls without waiting for ACKs, this becomes quadratic. VecDeque<v8::Global<v8::Function>> with pop_front() would be O(1) and is a drop-in replacement here.

Done in 17992c0 — switched to VecDeque<v8::Global<v8::Function>> with push_back / pop_front.

This relies on the thread-local SETTINGS buffer being zero-initialized at the count slot whenever a session is constructed without remoteCustomSettings. But Http2Settings::init (called from fn settings on every JS session.settings({...})) reads — and never resets — buffer[Count + 1]. So this sequence leaks across sessions:

1. Session A constructed (any remoteCustomSettings, even none).
2. JS calls sessionA.settings({ customSettings: { 1244: 456 } }). updateSettingsBuffer writes count=1, id=1244, value=456 into the shared buffer. Rust submits the SETTINGS frame. Buffer count remains 1.
3. Session B is constructed without remoteCustomSettings. JS skips remoteCustomSettingsToBuffer. new InternalHttp2Session(type) calls into Rust → fetch_allowed_remote_custom_settings reads count=1 → registers 1244 as a remote custom setting B should track. Then resets count to 0.
4. If the peer ever sends a SETTINGS entry with id 1244, it will silently appear on sessionB.remoteSettings.customSettings[1244] even though the user didn't ask for it.

The test enables both remoteCustomSettings on construction so it doesn't hit this, but anyone using customSettings send + a separate session without remoteCustomSettings will. Cleanest fix is to zero buffer[Count + 1] in JS at the start of setupHandle / before new InternalHttp2Session, or pass the registered IDs through a dedicated op argument instead of the shared buffer.

(Same comment also applies to the IDs slots at offsets Count+2 + 2*i: Http2Settings::init doesn't clear them either, so the IDs from a prior session.settings call sit there until overwritten.)

Fixed in cc9ec5a. Changed setupHandle in ext/node/polyfills/http2.ts to always call remoteCustomSettingsToBuffer(options.remoteCustomSettings || []), which writes count = 0 into the shared buffer when the user didn't pass remoteCustomSettings. So a session B constructed after session A's session.settings({ customSettings }) now sees count=0 in fetch_allowed_remote_custom_settings and doesn't register the leftover IDs.

The comment is wrong about Node's behavior — Node doesn't capture-at-first-send, it captures per-stream at stream construction by calling nghttp2_session_get_local_settings(session, NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE), and that nghttp2 value does update after a post-init session.settings() ACK round-trip. See src/node_http2.cc#L2247:

// Limit the number of header octets
max_header_length_ =
    std::min(
      nghttp2_session_get_local_settings(
        session->session(),
        NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE),
    MAX_MAX_HEADER_LIST_SIZE);

So Node's actual semantics are: streams created before a post-init session.settings({ maxHeaderListSize: N }) keep the old limit; streams created after the ACK use the new one.

This PR's behavior — frozen at first Http2Settings::send for the whole session, applied per-header on every stream — is more restrictive than Node in both directions:

• For old streams: Node's old code (which read nghttp2_session_get_local_settings on every add_header) was already "live" within a stream; the PR makes those streams use the original session-init value forever, even if the user advertised a larger limit later (e.g. raising the cap from the default to allow big-header tools).
• For new streams: same, but more visibly — the user explicitly tightened the limit, but new streams won't see it.

The test (client.settings({ maxHeaderListSize: 1 })) only checks that the callback fires, not that the new limit is enforced, so this passes — but the semantic is wrong. Easiest fix that matches Node is to drop local_max_header_list_size / initial_settings_applied entirely and keep reading nghttp2_session_get_local_settings(...) in add_header (the original code), but cache it once-per-stream-construction if you want to avoid the FFI call per header.

You're right, thanks for the citation to node_http2.cc#L2247. Fixed in cc9ec5a: dropped local_max_header_list_size / initial_settings_applied from Session, added max_header_length: u64 to Http2Stream, and snapshot it once in Http2Stream::new via nghttp2_session_get_local_settings(session, NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE). add_header reads self.max_header_length, so streams constructed after a post-init session.settings({ maxHeaderListSize: N }) ACK use the new N, while streams from before keep the old value — matching Node's per-stream-at-construction semantics.