feat(http2): configurable receive windows and frame size

[banglcb]

Fixes #1997.

A connection on package:http2 moved at most 64 KiB per round trip: the
connection receive window is fixed at the protocol's 65535 bytes, so
streamWindowSize alone cannot raise throughput. With a 4 MiB body from a
Go net/http server and 100 ms of added round-trip time, dart:io's
HTTP/1.1 client took ~350 ms and this package's client 7.1 s.

The new settings live on Settings, so they apply to clients and servers
alike:

• Settings.connectionWindowSize (65535..2147483647) grants a larger
  connection window with a WINDOW_UPDATE on stream 0 after the initial
  SETTINGS.
• Settings.maxFrameSize is sent as SETTINGS_MAX_FRAME_SIZE.
• A larger initial streamWindowSize, and maxFrameSize, apply to this
  end's receive side from the moment they are sent: a peer that has not read
  them yet stays within the defaults, which they still allow. Waiting for the
  ACK capped every early response's first round trip at 64 KiB. A smaller
  streamWindowSize still applies on ACK, since a client may send before it
  has read the server's SETTINGS (RFC 9113 section 3.4).
• From twice the default window, received data is acknowledged once per half
  window rather than once per DATA frame (the TODO in
  IncomingWindowHandler.dataProcessed); smaller windows are acknowledged
  at once, as before.
• The new settings are validated up front in _validateSettings.

Fixed on the way (from review): the peer's SETTINGS_MAX_FRAME_SIZE is
honored when sending and refused outside 16384..16777215; the ACK of this
end's own SETTINGS_INITIAL_WINDOW_SIZE no longer resizes send windows; a
WINDOW_UPDATE of 0 is never sent.

Defaults are unchanged; whether a client should default to larger values
can be taken up separately once this has landed. With streamWindowSize
6 MiB, connectionWindowSize 16 MiB and maxFrameSize 1 MiB the transfer
above takes ~340 ms (~140 ms without added delay, against ~155 ms for
HTTP/1.1).

Tests: test/flow_control_test.dart drives a raw peer and checks each
behaviour on the wire, using a PING round trip (not a sleep) wherever it
asserts that a frame was not sent; settings_handler_test.dart and
window_handler_test.dart cover the review fixes. Each test fails with its
part of the change removed. dart analyze --fatal-infos, dart format and
the full dart test pass (254 tests).

• I've reviewed the contributor guide and applied the relevant portions to this PR.

🤖 Generated with Claude Code

[mosuem]

Note

This review was generated by an AI coding agent (Jetski) on behalf of @mosuem.

[mosuem]

Note

This review was generated by an AI coding agent (Jetski) on behalf of @mosuem.

Thanks for the quick turnaround on the last round. I re-checked all four fixes in 53e7ee3 against the source (the peerSettings guard, SETTINGS_MAX_FRAME_SIZE on both the read and the write side, the connectionWindowSize range, the zero-byte guard) and they look right; dart analyze --fatal-infos, dart format and the full dart test run are clean for me locally too.

One remaining issue on the server side (inline on connection.dart), plus a few non-blocking nits. Two points that don't belong to a line:

• The title and description say "client", but connectionWindowSize / maxFrameSize live on Settings, so they apply to ServerSettings as well, and the pre-application in _setupConnection runs for servers too. Worth reflecting in the title/CHANGELOG.
• On whether the tuned values should become defaults: I'd keep the defaults unchanged in this PR and take that up separately once this has landed.

[banglcb]

Thanks for the second round. Both general points are addressed: the title, description and CHANGELOG no longer say "client", as the settings live on Settings and apply to servers too, and the defaults stay unchanged here; making larger values a client default can be a separate discussion once this lands. The inline points are fixed in d94afb5.

[mosuem]

Note

This review was generated by an AI coding agent (Jetski) on behalf of @mosuem.

Thanks — d94afb5 checks out. Verified locally: dart format, dart analyze --fatal-infos and the full suite (254 tests) are clean; the new server test fails without the >= guard exactly as it should (Connection is being forcefully terminated. (errorCode: 3)), incoming-window-handler-batches-from-twice-the-default fails without the threshold change, and flow_control_test.dart with the PING barriers is green on 10 consecutive runs. Title, description and CHANGELOG read well now.

One correction on the test-coverage claim, not blocking:

• the ACK of our SETTINGS never grows what we SEND on an open stream no longer exercises the if (peerSettings) guard in _modifySettings. With tuned (6 MiB) the pre-application already sets _acknowledgedSettings.initialWindowSize to 6 MiB at construction, so by the time the ACK arrives difference is 0 and the guard is moot. I removed the if (peerSettings) locally and the test passed 5/5. The guard still matters for a window below 65535, which is not pre-applied: without it the ACK would shrink the send window of an open stream by 64535. A variant that catches that — fails with the guard removed (Expected: <131070> Actual: <66535>), passes as is:

  variant

  test('the ACK of our SETTINGS never changes what we SEND, also for a '
      'window below 65535 (which is not pre-applied)', () async {
    await connect(const ClientSettings(streamWindowSize: 1000));
    peer
      ..sendSettings()
      ..send(_windowUpdate, 0, 0, [0x00, 0x10, 0x00, 0x00]);
    final stream = client.makeRequest([
      Header.ascii(':method', 'POST'),
      Header.ascii(':path', '/upload'),
      Header.ascii(':scheme', 'http'),
      Header.ascii(':authority', 'peer'),
    ]);
    stream.sendData(Uint8List(200000), endStream: true);
    int sent() => peer.frames
        .where((f) => f.type == _data && f.stream == 1)
        .fold<int>(0, (n, f) => n + f.payload.length);
    await peer.until(() => sent() >= 65535);
    peer.ackSettings();
    await peer.barrier();
    await peer.barrier();
    expect(sent(), 65535);
  
    // The peer grants the stream another default window: all of it must be
    // usable, i.e. the ACK of our own smaller window must not have shrunk
    // the send window.
    peer.send(_windowUpdate, 0, 1, [0x00, 0x00, 0xff, 0xff]);
    await peer.until(() => sent() > 65535);
    await peer.barrier();
    await peer.barrier();
    expect(sent(), 2 * 65535);
  });

  Either replacing the existing test with it or adding it alongside would make "each test fails with its part removed" hold for this one too.

• Nit: the doc on Settings.streamWindowSize says "Above 2 * 65535 bytes", while the code (and the CHANGELOG / dataProcessed comment) batch from 2 × 65535 inclusive.

Otherwise this looks good to me.

[banglcb]

Thanks, both right. You're correct about the coverage claim: my earlier check removed the guard together with the pre-application, so it never isolated the guard. Fixed in aa701ae: the existing test is replaced by your variant (a window below 65535, then a further stream WINDOW_UPDATE that must be fully usable after the ACK). It fails 5/5 with if (peerSettings) removed (Expected: <131070> Actual: <66535>) and passes 5/5 as is; full suite 254 green. The pre-application of a larger window stays covered by before the SETTINGS are acknowledged, a stream takes one DATA frame larger than both 16 KiB and 65535 bytes. The doc on Settings.streamWindowSize now says "From 2 * 65535 bytes on".