Offload request body stream reads

[pavel-ptashyts]

Summary

• offload blocking InputStream request body reads from Netty event-loop threads for HTTP/1.1 and HTTP/2 uploads when enabled
• add client configuration to enable or disable the offload worker pool and tune its thread count and queue size
• preserve the original HTTP/1.1 and HTTP/2 stream writers when offload is disabled
• skip queued reads whose request was cancelled before worker execution
• fail suspended uploads on unchecked stream read errors and retain the original HTTP/2 failure cause
• prevent synchronous writability callbacks from re-entering the HTTP/2 body pump or writing duplicate terminal frames
• document that public executor-aware constructors exist only for cross-package client wiring

Configuration

• requestBodyStreamReadOffloadEnabled defaults to false and must be enabled explicitly
• requestBodyStreamReadThreadsCount defaults to -1, which uses the configured I/O thread count
• requestBodyStreamReadQueueSize defaults to 0, which selects an automatic bounded capacity

Motivation

Blocking InputStream.read(...) calls can stall Netty event-loop threads while streaming request bodies. Under HTTP/2, one blocked upload can also delay sibling streams on the same connection. The feature is opt-in so existing clients retain inline stream reads. When enabled, it keeps stream reads away from the event loop and exposes controls for tuning the worker pool.

The hardened implementation avoids an extra event-loop scheduling hop, makes worker-thread close visibility explicit, and ensures runtime stream failures and cancellation cannot leave an upload suspended indefinitely. A queued task checks cancellation before invoking InputStream.read, preventing a read-after-close race.

A matrix run exposed a flow-control race: flush() can synchronously fire channelWritabilityChanged, re-entering the pump, and another callback can arrive while the terminal write is pending. Explicit pump and terminal-write states prevent duplicate endStream frames.

The executor-aware support constructors are public only because client wiring crosses package boundaries. Applications should enable and tune the feature through AsyncHttpClientConfig.

Validation

• ./mvnw -pl client -am -Dtest='BasicHttpTest#cancelledQueuedInputStreamIsNotReadOverHttp1,Http2StreamingBodyFlowControlTest#blockedInputStreamDoesNotStallSiblingStreamOverHttp2+cancelledQueuedInputStreamIsNotReadOverHttp2' -Dsurefire.failIfNoSpecifiedTests=false test
• ./mvnw -pl client -Dtest=org.asynchttpclient.BasicHttpTest#postInputStreamRuntimeFailureFailsRequest,org.asynchttpclient.Http2StreamingBodyFlowControlTest#inputStreamRuntimeFailureFailsRequestOverHttp2,org.asynchttpclient.request.body.InputStreamTest#testInvalidInputStream test
• ./mvnw -pl client -Dtest='AsyncHttpClientDefaultsTest#testDefaultRequestBodyStreamReadOffloadEnabled,BasicHttpTest#postInputStreamBodyGeneratorReadsOffEventLoop+postInputStreamBodyGeneratorReadsOnEventLoopByDefault+postInputStreamRuntimeFailureFailsRequest,Http2StreamingBodyFlowControlTest#inputStreamBodyReadsOffEventLoopOverHttp2+inputStreamRuntimeFailureFailsRequestOverHttp2+largeUploadCompletesUnderConstrainedFlowControlWindow' test
• ./mvnw -pl client -Dtest='org.asynchttpclient.Http2StreamingBodyFlowControlTest#largeUploadCompletesUnderConstrainedFlowControlWindow' test (3 consecutive passes)
• ./mvnw -pl client -Dtest='InputStreamTest,AsyncHttpClientDefaultsTest#testDefaultRequestBodyStreamReadOffloadEnabled' test
• ./mvnw -pl client -DskipTests -Dgpg.skip=true verify

Attribution

Codex on behalf of Pavel Ptashyts

[pavel-ptashyts]

Closing by decision; performance-plan item 1.2 will be marked skipped.