Allow connection and stream window target sizes to be configured separately (#543)

Motivation:

At the moment users can only set a target window size which applies to
both the connection and to streams. It should be possible to set these
separately so that one stream can't stall other streams by consuming the
whole flow control window.

Modifications:

- Add target window size to the connection config
- Plumb through the values

Result:

Users can set target flow control window sizes separately
This commit is contained in:
George Barnett authored and GitHub committed 2026-03-18 10:05:08 +00:00
1 parent 9019b76fa8
commit 6d8d596f0a
6 files changed
+209 -29

No files matched your search

@@ -31,7 +31,8 @@ internal struct InlineStreamMultiplexer {
outboundView: NIOHTTP2Handler.OutboundView,
mode: NIOHTTP2Handler.ParserMode,
inboundStreamStateInitializer: MultiplexerAbstractChannel.InboundStreamStateInitializer,
targetWindowSize: Int,
targetConnectionWindowSize: Int,
targetStreamWindowSize: Int,
streamChannelOutboundBytesHighWatermark: Int,
streamChannelOutboundBytesLowWatermark: Int,
streamDelegate: NIOHTTP2StreamDelegate?
@@ -41,7 +42,8 @@ internal struct InlineStreamMultiplexer {
mode: mode,
channel: context.channel,
inboundStreamStateInitializer: inboundStreamStateInitializer,
targetWindowSize: targetWindowSize,
targetConnectionWindowSize: targetConnectionWindowSize,
targetStreamWindowSize: targetStreamWindowSize,
streamChannelOutboundBytesHighWatermark: streamChannelOutboundBytesHighWatermark,
streamChannelOutboundBytesLowWatermark: streamChannelOutboundBytesLowWatermark
)
+67 -18
View File
@@ -132,9 +132,29 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
/// - `NIOHTTP2StreamDelegate`: The delegate to be notified upon stream creation and close.
/// - `InboundStreamMultiplexer`: The component responsible for (de)multiplexing inbound streams.
private enum InboundStreamMultiplexerState {
struct PendingMultiplexerConfig {
var targetConnectionWindowSize: Int
var targetStreamWindowSize: Int
var streamConfiguration: StreamConfiguration
var streamDelegate: NIOHTTP2StreamDelegate?
init(
connectionConfiguration: ConnectionConfiguration,
streamConfiguration: StreamConfiguration,
streamDelegate: NIOHTTP2StreamDelegate?
) {
self.targetConnectionWindowSize =
connectionConfiguration.targetWindowSize.clampedToValidWindowSize
self.targetStreamWindowSize =
streamConfiguration.targetWindowSize.clampedToValidWindowSize
self.streamConfiguration = streamConfiguration
self.streamDelegate = streamDelegate
}
}
case uninitializedLegacy
case uninitializedInline(StreamConfiguration, StreamInitializer, NIOHTTP2StreamDelegate?)
case uninitializedAsync(StreamConfiguration, StreamInitializerWithAnyOutput, NIOHTTP2StreamDelegate?)
case uninitializedInline(PendingMultiplexerConfig, StreamInitializer)
case uninitializedAsync(PendingMultiplexerConfig, StreamInitializerWithAnyOutput)
case initialized(InboundStreamMultiplexer)
case deinitialized
@@ -160,7 +180,7 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
case .uninitializedLegacy:
self = .initialized(.legacy(LegacyInboundStreamMultiplexer(context: context)))
case .uninitializedInline(let streamConfiguration, let inboundStreamInitializer, let streamDelegate):
case .uninitializedInline(let config, let inboundStreamInitializer):
self = .initialized(
.inline(
InlineStreamMultiplexer(
@@ -168,16 +188,18 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
outboundView: .init(http2Handler: http2Handler),
mode: mode,
inboundStreamStateInitializer: .excludesStreamID(inboundStreamInitializer),
targetWindowSize: max(0, min(streamConfiguration.targetWindowSize, Int(Int32.max))),
streamChannelOutboundBytesHighWatermark: streamConfiguration
targetConnectionWindowSize: config.targetConnectionWindowSize,
targetStreamWindowSize: config.targetStreamWindowSize,
streamChannelOutboundBytesHighWatermark: config.streamConfiguration
.outboundBufferSizeHighWatermark,
streamChannelOutboundBytesLowWatermark: streamConfiguration.outboundBufferSizeLowWatermark,
streamDelegate: streamDelegate
streamChannelOutboundBytesLowWatermark: config.streamConfiguration
.outboundBufferSizeLowWatermark,
streamDelegate: config.streamDelegate
)
)
)
case .uninitializedAsync(let streamConfiguration, let inboundStreamInitializer, let streamDelegate):
case .uninitializedAsync(let config, let inboundStreamInitializer):
self = .initialized(
.inline(
InlineStreamMultiplexer(
@@ -185,11 +207,13 @@ public final class NIOHTTP2Handler: ChannelDuplexHandler {
outboundView: .init(http2Handler: http2Handler),
mode: mode,
inboundStreamStateInitializer: .returnsAny(inboundStreamInitializer),
targetWindowSize: max(0, min(streamConfiguration.targetWindowSize, Int(Int32.max))),
streamChannelOutboundBytesHighWatermark: streamConfiguration
targetConnectionWindowSize: config.targetConnectionWindowSize,
targetStreamWindowSize: config.targetStreamWindowSize,
streamChannelOutboundBytesHighWatermark: config.streamConfiguration
.outboundBufferSizeHighWatermark,
streamChannelOutboundBytesLowWatermark: streamConfiguration.outboundBufferSizeLowWatermark,
streamDelegate: streamDelegate
streamChannelOutboundBytesLowWatermark: config.streamConfiguration
.outboundBufferSizeLowWatermark,
streamDelegate: config.streamDelegate
)
)
)
@@ -1431,10 +1455,14 @@ extension NIOHTTP2Handler {
frameDelegate: nil
)
let pendingConfig = InboundStreamMultiplexerState.PendingMultiplexerConfig(
connectionConfiguration: connectionConfiguration,
streamConfiguration: streamConfiguration,
streamDelegate: streamDelegate
)
self.inboundStreamMultiplexerState = .uninitializedInline(
streamConfiguration,
inboundStreamInitializer,
streamDelegate
pendingConfig,
inboundStreamInitializer
)
}
@@ -1465,10 +1493,14 @@ extension NIOHTTP2Handler {
streamErrorCounterWindow: streamConfiguration.streamErrorRateLimit.windowLength,
frameDelegate: frameDelegate
)
let pendingConfig = InboundStreamMultiplexerState.PendingMultiplexerConfig(
connectionConfiguration: connectionConfiguration,
streamConfiguration: streamConfiguration,
streamDelegate: streamDelegate
)
self.inboundStreamMultiplexerState = .uninitializedAsync(
streamConfiguration,
inboundStreamInitializerWithAnyOutput,
streamDelegate
pendingConfig,
inboundStreamInitializerWithAnyOutput
)
}
@@ -1495,6 +1527,16 @@ extension NIOHTTP2Handler {
/// https://github.com/HTTPWorkshop/workshop2024/blob/main/talks/1.%20Security/glitches.pdf
public var maximumConnectionGlitches: Int = GlitchesMonitor.defaultMaximumGlitches
/// The target size of the HTTP/2 connection-level flow control window.
///
/// This is the connection-level inbound flow control window size. It can be set independently
/// of the per-stream window size (``StreamConfiguration/targetWindowSize``) to allow tuning
/// for different workloads (e.g. a large connection window with smaller per-stream windows
/// when many concurrent streams are expected).
///
/// Defaults to 65535 bytes, the HTTP/2 default.
public var targetWindowSize: Int = 65535
public init() {}
}
@@ -1609,3 +1651,10 @@ extension NIOHTTP2Handler {
}
}
}
extension Int {
/// Clamps a target window size to the range `0 ... (1 << 31 - 1)` valid for HTTP/2 flow control.
internal var clampedToValidWindowSize: Int {
Swift.max(0, Swift.min(self, (1 << 31) - 1))
}
}
@@ -32,7 +32,7 @@ internal class HTTP2CommonInboundStreamMultiplexer {
private var connectionFlowControlManager: InboundWindowManager
private let mode: NIOHTTP2Handler.ParserMode
@usableFromInline internal let _targetWindowSize: Int
@usableFromInline internal let _targetStreamWindowSize: Int
@usableFromInline internal let _streamChannelOutboundBytesHighWatermark: Int
@usableFromInline internal let _streamChannelOutboundBytesLowWatermark: Int
@@ -45,14 +45,15 @@ internal class HTTP2CommonInboundStreamMultiplexer {
mode: NIOHTTP2Handler.ParserMode,
channel: Channel,
inboundStreamStateInitializer: MultiplexerAbstractChannel.InboundStreamStateInitializer,
targetWindowSize: Int,
targetConnectionWindowSize: Int,
targetStreamWindowSize: Int,
streamChannelOutboundBytesHighWatermark: Int,
streamChannelOutboundBytesLowWatermark: Int
) {
self._channel = channel
self.inboundStreamStateInitializer = inboundStreamStateInitializer
self._targetWindowSize = targetWindowSize
self.connectionFlowControlManager = InboundWindowManager(targetSize: Int32(targetWindowSize))
self._targetStreamWindowSize = targetStreamWindowSize
self.connectionFlowControlManager = InboundWindowManager(targetSize: Int32(targetConnectionWindowSize))
self._streamChannelOutboundBytesHighWatermark = streamChannelOutboundBytesHighWatermark
self._streamChannelOutboundBytesLowWatermark = streamChannelOutboundBytesLowWatermark
self.mode = mode
@@ -103,7 +104,7 @@ extension HTTP2CommonInboundStreamMultiplexer {
parent: self._channel,
multiplexer: multiplexer,
streamID: streamID,
targetWindowSize: Int32(self._targetWindowSize),
targetWindowSize: Int32(self._targetStreamWindowSize),
outboundBytesHighWatermark: self._streamChannelOutboundBytesHighWatermark,
outboundBytesLowWatermark: self._streamChannelOutboundBytesLowWatermark,
inboundStreamStateInitializer: self.inboundStreamStateInitializer
@@ -340,7 +341,7 @@ extension HTTP2CommonInboundStreamMultiplexer {
parent: self._channel,
multiplexer: multiplexer,
streamID: nil,
targetWindowSize: Int32(self._targetWindowSize),
targetWindowSize: Int32(self._targetStreamWindowSize),
outboundBytesHighWatermark: self._streamChannelOutboundBytesHighWatermark,
outboundBytesLowWatermark: self._streamChannelOutboundBytesLowWatermark,
inboundStreamStateInitializer: .excludesStreamID(nil)
@@ -393,7 +394,7 @@ extension HTTP2CommonInboundStreamMultiplexer {
parent: self._channel,
multiplexer: multiplexer,
streamID: nil,
targetWindowSize: Int32(self._targetWindowSize),
targetWindowSize: Int32(self._targetStreamWindowSize),
outboundBytesHighWatermark: self._streamChannelOutboundBytesHighWatermark,
outboundBytesLowWatermark: self._streamChannelOutboundBytesLowWatermark,
inboundStreamStateInitializer: .excludesStreamID(nil)
@@ -430,7 +431,7 @@ extension HTTP2CommonInboundStreamMultiplexer {
parent: self._channel,
multiplexer: multiplexer,
streamID: streamID,
targetWindowSize: Int32(self._targetWindowSize),
targetWindowSize: Int32(self._targetStreamWindowSize),
outboundBytesHighWatermark: self._streamChannelOutboundBytesHighWatermark,
outboundBytesLowWatermark: self._streamChannelOutboundBytesLowWatermark,
inboundStreamStateInitializer: .includesStreamID(nil)
@@ -254,11 +254,13 @@ public final class HTTP2StreamMultiplexer: ChannelInboundHandler, ChannelOutboun
) {
self.channel = channel
let clampedWindowSize = targetWindowSize.clampedToValidWindowSize
self.commonStreamMultiplexer = HTTP2CommonInboundStreamMultiplexer(
mode: mode,
channel: channel,
inboundStreamStateInitializer: inboundStreamStateInitializer,
targetWindowSize: targetWindowSize,
targetConnectionWindowSize: clampedWindowSize,
targetStreamWindowSize: clampedWindowSize,
streamChannelOutboundBytesHighWatermark: outboundBufferSizeHighWatermark,
streamChannelOutboundBytesLowWatermark: outboundBufferSizeLowWatermark
)
@@ -2473,6 +2473,34 @@ final class HTTP2InlineStreamMultiplexerTests: XCTestCase {
XCTAssertNoThrow(try self.channel.finish())
}
// MARK: - Connection vs Stream Target Window Size Tests
func testConnectionWindowUpdateUsesConnectionTargetWindowSize() throws {
// Use a large connection window and a smaller stream window.
let connectionTargetWindowSize = 1 << 20 // 1 MiB
let streamTargetWindowSize = 1 << 16 // 64 KiB
let multiplexer = HTTP2CommonInboundStreamMultiplexer(
mode: .server,
channel: self.channel,
inboundStreamStateInitializer: .excludesStreamID(nil),
targetConnectionWindowSize: connectionTargetWindowSize,
targetStreamWindowSize: streamTargetWindowSize,
streamChannelOutboundBytesHighWatermark: 8196,
streamChannelOutboundBytesLowWatermark: 4092
)
// The connection window is at connectionTargetWindowSize initially.
// Simulate the window dropping to just above half — no update expected.
let noUpdate = multiplexer.newConnectionWindowSize((connectionTargetWindowSize / 2) + 1)
XCTAssertNil(noUpdate, "No window update expected when window is above half of target")
// Now the window drops to exactly half — should trigger a window update.
let update = multiplexer.newConnectionWindowSize(connectionTargetWindowSize / 2)
XCTAssertNotNil(update, "Window update expected when window reaches half of target")
XCTAssertEqual(update, connectionTargetWindowSize / 2)
}
}
private final class ReadAndFrameConsumer: ChannelInboundHandler, ChannelOutboundHandler {
@@ -723,4 +723,102 @@ class SimpleClientServerInlineStreamMultiplexerTests: XCTestCase {
}
}
}
func testIndependentConnectionAndStreamWindowSizes() throws {
// Configure the server with a large connection window (128 KiB) but the default
// stream window (65535). When the client sends data, the server's inline multiplexer
// should emit WINDOW_UPDATE frames with different increments for connection vs stream
// because the targets differ.
let connectionTargetWindowSize = 1 << 17 // 131072 = 128 KiB
let streamTargetWindowSize = 65535 // default
var serverConnectionConfig = NIOHTTP2Handler.ConnectionConfiguration()
serverConnectionConfig.targetWindowSize = connectionTargetWindowSize
var serverStreamConfig = NIOHTTP2Handler.StreamConfiguration()
serverStreamConfig.targetWindowSize = streamTargetWindowSize
XCTAssertNoThrow(
try self.clientChannel.pipeline.syncOperations.addHandler(
NIOHTTP2Handler(
mode: .client,
eventLoop: self.clientChannel.eventLoop,
inboundStreamInitializer: Self.defaultMultiplexerCallback
)
)
)
XCTAssertNoThrow(
try self.serverChannel.pipeline.syncOperations.addHandler(
NIOHTTP2Handler(
mode: .server,
eventLoop: self.serverChannel.eventLoop,
connectionConfiguration: serverConnectionConfig,
streamConfiguration: serverStreamConfig,
inboundStreamInitializer: { channel in
channel.eventLoop.makeSucceededVoidFuture()
}
)
)
)
try self.assertDoHandshake(client: self.clientChannel, server: self.serverChannel)
// Open a stream and send 64 KiB of data (64 * 1024 = 65536 bytes).
let headers: HPACKHeaders = [
":path": "/", ":method": "POST", ":scheme": "https", ":authority": "localhost",
]
let requestBody = ByteBuffer(repeating: 0x04, count: 1024)
let multiplexer = try self.clientChannel.pipeline.handler(type: NIOHTTP2Handler.self).flatMap {
$0.multiplexer
}.wait()
let childHandler = InboundFramePayloadRecorder()
multiplexer.createStreamChannel(promise: nil) { channel in
let reqFramePayload = HTTP2Frame.FramePayload.headers(.init(headers: headers))
channel.write(reqFramePayload, promise: nil)
var bodyPayload = HTTP2Frame.FramePayload.data(.init(data: .byteBuffer(requestBody)))
for _ in 0..<63 {
channel.write(bodyPayload, promise: nil)
}
bodyPayload = .data(.init(data: .byteBuffer(requestBody), endStream: true))
channel.writeAndFlush(bodyPayload, promise: nil)
return channel.pipeline.addHandler(childHandler)
}
self.clientChannel.embeddedEventLoop.run()
// Let the data flow between client and server.
self.interactInMemory(self.clientChannel, self.serverChannel)
// Collect connection-level (stream 0) WINDOW_UPDATE frames received by the client.
var connectionWindowIncrements: [Int] = []
var streamWindowIncrements: [Int] = []
while let frame = try self.clientChannel.readInbound(as: HTTP2Frame.self) {
if case .windowUpdate(let increment) = frame.payload {
if frame.streamID == .rootStream {
connectionWindowIncrements.append(increment)
}
}
}
// Stream-level window updates are delivered to the child channel.
for framePayload in childHandler.receivedFrames {
if case .windowUpdate(let increment) = framePayload {
streamWindowIncrements.append(increment)
}
}
// The initial HTTP/2 connection window is 65535, the target is 131072. The
// InboundWindowManager fires a WINDOW_UPDATE as soon as the first data is
// consumed so the increment = 131072 - (65535 - 1024) = 66561.
XCTAssertEqual(connectionWindowIncrements, [66561])
// The stream target is 65535 so the stream WINDOW_UPDATE fires at the half-point:
// increment = 65535 - 32767 = 32768.
XCTAssertEqual(streamWindowIncrements, [32768])
XCTAssertNoThrow(try self.clientChannel.finish())
XCTAssertNoThrow(try self.serverChannel.finish())
}
}