.NET 11 HTTP/2: Cap Streams Before Server SETTINGS

A fresh .NET 11 HTTP/2 connection has a short but important uncertainty window: the client can start streams before it receives the server’s SETTINGS_MAX_CONCURRENT_STREAMS value. Until .NET 11 RC2, SocketsHttpHandler assumed 100 concurrent streams during that window. If your upstream allows far fewer, the startup burst can exceed its contract before the client has learned the real limit.

.NET 11 RC2 adds SocketsHttpHandler.InitialHttp2MaxConcurrentStreams so you can cap that pre-SETTINGS burst. This guide shows when the new setting is justified, how to configure it without confusing transport streams with application concurrency, and how a frame-level loopback test verified that a cap of two released exactly two requests before server SETTINGS and the remaining three afterward.

Understand the .NET 11 HTTP/2 startup race

HTTP/2 peers advertise connection settings after the connection is established. One of those settings, SETTINGS_MAX_CONCURRENT_STREAMS, tells the client how many streams the server is willing to process concurrently on that connection. Once SocketsHttpHandler receives the value, it honors the server’s advertised limit.

The awkward part is the time before that frame arrives. The client still needs an initial limit so it can decide how many requests to start. The .NET default is 100. That is sensible for general-purpose use, but it can be too high when a known upstream contract is lower—for example, a gateway, proxy, or gRPC service configured for only 20 concurrent streams.

The .NET runtime proposal describes the material failure mode: excess early requests can fail, not every operation is necessarily safe to retry, and a burst can trigger server-side denial-of-service mitigations. The new property does not change what the server ultimately advertises. It controls only the client’s assumption before the first server SETTINGS frame is processed.

Connection phase	Effective stream limit	Who controls it?
Before server SETTINGS	`InitialHttp2MaxConcurrentStreams`	Your client configuration; default 100
After server SETTINGS	Server-advertised value, subject to runtime behavior	The HTTP/2 peer
Across multiple connections	Per-connection stream limits plus connection policy	`EnableMultipleHttp2Connections` and the upstream
Application work	Requests admitted to your endpoint or worker	Your rate limiter, queue, semaphore, or concurrency middleware

That last row prevents a common configuration mistake. The new property is a transport startup guard, not an application-wide bulkhead. If your concern is limiting concurrent work inside ASP.NET Core, use application concurrency controls instead. The ASP.NET Core 11 concurrency-limits workflow covers that separate layer.

Decide whether to change the default

Do not lower the setting just because the API exists. Set it only when you know the upstream’s initial safe limit is below 100 and the consequence of exceeding it matters. The value should come from an owned server configuration, a provider contract, or an observation you can reproduce—not from guesswork.

Situation	Decision	Why
Server limit is unknown	Keep the default 100	A speculative low cap can add queueing without proving a risk reduction
Server contract is 20 streams	Set the initial cap to 20	The startup assumption now matches the known upstream ceiling
Server advertises 100 or more	Keep the default unless testing proves another constraint	The new knob does not create extra capacity
You need a process-wide request limit	Use an application bulkhead or rate limiter	This property is per HTTP/2 connection and only governs streams
You allow multiple HTTP/2 connections	Test the combined burst explicitly	A safe per-connection cap is not automatically a safe total

The minimum allowed value is one. Setting zero throws ArgumentOutOfRangeException; the local proof includes that boundary assertion. A lower value is not inherently safer: if it is below the server’s real capacity, requests wait behind an artificial client-side gate until SETTINGS arrives.

Configure SocketsHttpHandler safely

With IHttpClientFactory, return a new handler from the primary-handler factory. This keeps ownership and handler lifetime aligned with the factory instead of sharing a disposable handler instance yourself.

builder.Services
    .AddHttpClient("low-stream-upstream", client =>
    {
        client.BaseAddress = new Uri("https://api.example.com");
        client.DefaultRequestVersion = HttpVersion.Version20;
        client.DefaultVersionPolicy = HttpVersionPolicy.RequestVersionOrHigher;
    })
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        // Match the known upstream contract before SETTINGS arrives.
        InitialHttp2MaxConcurrentStreams = 20,

        // Keep this explicit when one connection is part of the contract.
        EnableMultipleHttp2Connections = false,

        // Recycle connections deliberately; do not create a reconnect storm.
        PooledConnectionLifetime = TimeSpan.FromMinutes(10)
    });

Configure the property before the handler sends its first request. Like other connection behavior, it belongs in startup configuration. Avoid mutating a live handler in response to a transient error; build a measured policy and deploy it as a versioned application change.

If you construct HttpClient directly, keep both objects long-lived so connection pooling remains effective:

var handler = new SocketsHttpHandler
{
    InitialHttp2MaxConcurrentStreams = 20,
    EnableMultipleHttp2Connections = false
};

var client = new HttpClient(handler)
{
    BaseAddress = new Uri("https://api.example.com"),
    DefaultRequestVersion = HttpVersion.Version20,
    DefaultVersionPolicy = HttpVersionPolicy.RequestVersionExact
};

RequestVersionExact is useful in a verification harness because it makes an HTTP/1.1 fallback fail visibly. In production, choose RequestVersionOrHigher or RequestVersionExact according to the upstream contract; do not copy the test policy without deciding what fallback behavior your application needs.

Verify the cap before server SETTINGS

A normal test server sends SETTINGS too quickly to make the boundary obvious. The proof for this article used a small TLS loopback server with ALPN set to h2. It accepted the HTTP/2 client preface, withheld its SETTINGS frame, counted incoming HEADERS frames, and failed immediately if more than two request streams appeared during the quiet window.

const int configuredInitialLimit = 2;
const int requestCount = 5;

using var handler = new SocketsHttpHandler
{
    InitialHttp2MaxConcurrentStreams = configuredInitialLimit,
    EnableMultipleHttp2Connections = false,
    SslOptions = testTlsOptions
};

using var client = new HttpClient(handler);

var requests = Enumerable.Range(0, requestCount)
    .Select(_ => new HttpRequestMessage(HttpMethod.Get, proofUri)
    {
        Version = HttpVersion.Version20,
        VersionPolicy = HttpVersionPolicy.RequestVersionExact
    })
    .Select(message => client.SendAsync(message))
    .ToArray();

The server side deliberately reads two HEADERS frames and then waits 300 milliseconds. Observing a third HEADERS frame in that period is a failing assertion. Only after the quiet window does the server send SETTINGS_MAX_CONCURRENT_STREAMS = 5.

while (streamsBeforeSettings.Count < configuredInitialLimit)
{
    var frame = await ReadFrameAsync(ssl, token);
    if (frame.Type == 1) // HEADERS
        streamsBeforeSettings.Add(frame.StreamId);
}

await AssertNoMoreHeadersForAsync(
    ssl,
    TimeSpan.FromMilliseconds(300),
    token);

await SendSettingsAsync(
    ssl,
    maxConcurrentStreams: requestCount,
    token);

while (allStreams.Count < requestCount)
{
    var frame = await ReadFrameAsync(ssl, token);
    if (frame.Type == 1)
        allStreams.Add(frame.StreamId);
}

This is stronger than asserting that five requests eventually succeed. It observes the decision at the protocol boundary: two streams before SETTINGS, then three more after the server raises the available concurrency. The harness also returns HTTP/2 200 OK responses so the client tasks complete and their negotiated protocol version can be checked.

Read the verified result

The proof ran with the official .NET SDK 11.0.100-rc.2.26504.105 on Linux x64. The SDK archive was checked against Microsoft’s published SHA-512 before extraction. The test exited successfully with this output:

sdk=11.0.0
configured_initial_limit=2
headers_before_server_settings=2
headers_after_server_settings=3
responses_http2_ok=True
zero_rejected=True

Assertion	Expected	Observed
HEADERS before server SETTINGS	2	2
Additional HEADERS after server advertises 5	3	3
All responses use HTTP/2 and succeed	True	True
Value zero is rejected	True	True

The result verifies the narrow claim that matters to the adoption decision: the configured value gates streams before server SETTINGS, and a later, higher server value releases queued requests. It is not a throughput benchmark and it does not prove how your proxy, service mesh, or cloud gateway behaves.

Roll out without moving the bottleneck

Confirm the upstream contract. Record where the lower-than-100 limit comes from and whether it is per connection, per client, or global.

Test a fresh connection. Warm pools hide the startup window. Include DNS, TLS, ALPN, proxy, and gateway layers that exist in production.
Keep multiple connections explicit. If EnableMultipleHttp2Connections is true, measure the aggregate request burst and connection count.
Separate waiting from failure. A lower initial cap may reduce rejected streams while increasing request queue time. Track both latency and errors.

Classify retries. Retry only operations that are safe under your idempotency rules. The transport setting reduces a known cause; it does not make every failed request replayable.
Roll out gradually. Compare connection creation, HTTP/2 stream errors, upstream rejection signals, request latency, and pool churn before expanding.

Connection lifetime deserves special attention. Aggressively recycling pooled connections repeatedly recreates the exact pre-SETTINGS window the property guards. A safe cap can prevent an oversized burst, but excessive reconnects can still produce extra handshakes, queueing, and upstream load.

Also test the server moving in both directions. The runtime implementation remembers a lower server limit for later connections to the same endpoint. A higher advertised value does not mean you should raise your configured initial assumption without revisiting the upstream contract. Preserve the distinction between what you know before SETTINGS and what the current connection learns afterward.

Know what this setting does not solve

It does not raise the server’s maximum concurrent streams.
It does not limit total application concurrency across hosts or connections.
It does not guarantee that failed requests are safe to retry.

It does not replace a queue, rate limiter, circuit breaker, or backpressure policy.
It does not prove production throughput from a loopback result.
It applies to a .NET 11 release candidate; confirm the final API and rerun the proof when you move to a newer build.

The practical rule for .NET 11 HTTP/2 clients is deliberately narrow: leave the default alone unless you have a known lower upstream limit. When you do, set the initial cap to that contract, keep connection policy explicit, and verify the pre- and post-SETTINGS phases separately. That turns a new runtime knob into an auditable transport decision rather than a speculative tuning change.