HTTP/2: add per-stream idle and lifetime timeouts to core multiplexer #581

arturobernalg · 2025-12-07T15:07:07Z

This change introduces per-stream idle and lifetime timeouts enforced by the HTTP/2 core multiplexer. Streams that exceed the configured limits are reset with H2StreamTimeoutException, while the underlying HTTP/2 connection remains usable for other streams.

Configuration is exposed via H2Config.setStreamIdleTimeout and setStreamLifetimeTimeout and is disabled by default, so existing users see no behaviour change unless they opt in. H2Stream now tracks creation and last-activity timestamps, and AbstractH2StreamMultiplexer inspects those on I/O events to apply the timeouts without background threads.

rschmitt · 2025-12-09T01:25:32Z

What kinds of timeouts are currently supported with HTTP/2?
Is H2Config the correct place to put these options, since they are not conceptually specific to HTTP/2?

arturobernalg · 2025-12-09T08:09:08Z

What kinds of timeouts are currently supported with HTTP/2?

Is H2Config the correct place to put these options, since they are not conceptually specific to HTTP/2?

At the moment we only expose connection-level timeouts (for example via IOReactorConfig socket and session timeouts); there is no existing notion of per-stream timeout in the HTTP/2 code.
These new options are enforced entirely inside the HTTP/2 stream multiplexer, so they are scoped to HTTP/2 stream semantics and therefore live in H2Config.
If we ever want similar per-message timeouts for other protocols, we can add a higher-level abstraction then without changing this API.

rschmitt · 2025-12-09T17:43:59Z

If we ever want similar per-message timeouts for other protocols, we can add a higher-level abstraction then without changing this API.

What about RequestConfig#setResponseTimeout? The Javadoc seems to indicate that that option is supported everywhere but HTTP/2. Should we start by backfilling multiplexer support for this specific setting?

arturobernalg · 2025-12-09T17:52:30Z

If we ever want similar per-message timeouts for other protocols, we can add a higher-level abstraction then without changing this API.

What about RequestConfig#setResponseTimeout? The Javadoc seems to indicate that that option is supported everywhere but HTTP/2. Should we start by backfilling multiplexer support for this specific setting?

RequestConfig#setResponseTimeout IMO lives in the client API, while H2Config is a transport-level setting in Core. I would keep this change scoped to Core and then look at wiring responseTimeout onto an appropriate per-stream timeout in the httpclient5 layer as a follow-up

ok2c · 2025-12-10T10:14:31Z

@arturobernalg @rschmitt This timeout value / these timeout values must be settable / mutable at runtime exactly the same way as Socket read timeout. Just setting an initial value from a config bean is not good enough. At the client level the request execution pipeline could use that API to apply RequestConfig#responseTimeout at the initiation of the message exchange

arturobernalg · 2025-12-10T10:59:36Z

@arturobernalg @rschmitt This timeout value / these timeout values must be settable / mutable at runtime exactly the same way as Socket read timeout. Just setting an initial value from a config bean is not good enough. At the client level the request execution pipeline could use that API to apply RequestConfig#responseTimeout at the initiation of the message exchange

@ok2c Makes sense. I can treat the timeouts in H2Config as defaults and keep the actual per-stream timeout state on H2Stream.
I will expose a small control API on H2StreamChannel so the client execution pipeline can set / mutate idle / lifetime timeouts at the start of an exchange and map RequestConfig#responseTimeout to the stream lifetime there.

ok2c · 2025-12-10T11:48:40Z

I can treat the timeouts in H2Config as defaults

@arturobernalg I agree with @rschmitt that is the wrong place for timeout settings. Those are meant to be H2 protocol related configs. Please use connection socket timeout as an initial / default value.

arturobernalg · 2025-12-10T19:15:01Z

I can treat the timeouts in H2Config as defaults

@arturobernalg I agree with @rschmitt that is the wrong place for timeout settings. Those are meant to be H2 protocol related configs. Please use connection socket timeout as an initial / default value.

@rschmitt @ok2c please another pass

rschmitt · 2025-12-10T19:28:07Z

I'd like to see HTTP/2 test coverage added to httpclient5-testing/src/test/java/org/apache/hc/client5/testing/async/TestAsyncSocketTimeout.java in the client integration tests. This would provide at least some assurance that we are implementing a consistent contract across the various transports and protocols.

ok2c · 2025-12-10T20:10:42Z

I'd like to see HTTP/2 test coverage added to httpclient5-testing/src/test/java/org/apache/hc/client5/testing/async/TestAsyncSocketTimeout.java in the client integration tests. This would provide at least some assurance that we are implementing a consistent contract across the various transports and protocols.

@rschmitt That is fair, but the feature would need to have been made available in an alpha release of core or the timeout tests would need to be ported to core.

arturobernalg · 2025-12-11T11:56:09Z

I'd like to see HTTP/2 test coverage added to httpclient5-testing/src/test/java/org/apache/hc/client5/testing/async/TestAsyncSocketTimeout.java in the client integration tests. This would provide at least some assurance that we are implementing a consistent contract across the various transports and protocols.

@rschmitt I’ve added an async core HTTP/2 socket-timeout test in httpcore5-testing (AsyncH2SocketTimeoutCoreTest) that mirrors the client-side TestAsyncSocketTimeout behaviour. It verifies that a per-request timeout over HTTP/2 results in HttpStreamResetException, so I believe this covers the contract you were asking for – let me know if you had something different in mind.

ok2c · 2025-12-14T09:16:58Z

@arturobernalg Please rebase this change-set off the latest master and I will review it

arturobernalg · 2025-12-14T18:35:43Z

@arturobernalg Please rebase this change-set off the latest master and I will review it

@ok2c please take a look

rschmitt · 2025-12-17T18:37:32Z

@rschmitt I’ve added an async core HTTP/2 socket-timeout test in httpcore5-testing (AsyncH2SocketTimeoutCoreTest) that mirrors the client-side TestAsyncSocketTimeout behaviour. It verifies that a per-request timeout over HTTP/2 results in HttpStreamResetException, so I believe this covers the contract you were asking for – let me know if you had something different in mind.

Ideally I'd like to see contract testing, i.e. the same test cases running for HTTP, HTTPS, h2, and h2c. This ensures that the high-level API behaves consistently across the various implementations; it's also a very effective way of asserting that the various config options are being propagated and applied correctly throughout the client's internals. This is most effectively done through tests in httpclient5 (which has the issue that Oleg pointed out, unless you are backfilling a feature into existing APIs).

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java

ok2c · 2025-12-21T15:22:45Z

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java

                requestExecutionCommand.getExchangeHandler(),
                requestExecutionCommand.getPushHandlerFactory(),
                requestExecutionCommand.getContext()));
+        initializeStreamTimeouts(stream);


@arturobernalg This looks wrong. The idea is to let the callback from RequestExecutionCommand decide what is to be done upon stream initialization. The StreamControl should just provide a setter.

ok2c · 2025-12-21T15:23:38Z

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java

+                }
+            }
+
+            if (lifetimeTimeout != null && lifetimeTimeout.isEnabled()) {


@arturobernalg What lifetimeTimeout could be good for? Why do we need it?

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2StreamTimeoutException.java

ok2c · 2025-12-21T15:27:50Z

@arturobernalg Please try to minimize changes to H2 protocol code. More functionality can be added incrementally at a later point. Try to keep it small and lean.

arturobernalg · 2025-12-22T08:18:22Z

@arturobernalg Please try to minimize changes to H2 protocol code. More functionality can be added incrementally at a later point. Try to keep it small and lean.

@ok2c please another pass

ok2c · 2025-12-22T17:40:14Z

@arturobernalg Better, but please look at all my comments

arturobernalg · 2025-12-22T19:11:25Z

@o

@arturobernalg Better, but please look at all my comments

@ok2c I’ve updated the patch to reflect your feedback. please let me know if I missed anything.

ok2c · 2025-12-25T14:24:24Z

@o

@arturobernalg Better, but please look at all my comments

@ok2c I’ve updated the patch to reflect your feedback. please let me know if I missed anything.

@arturobernalg I seem unable to get the message across or articulate it correctly. The patch still does too much and in the wrong places. I am not in favor of applying the changes in their present state. I suggest we drop this pull request and revisit the issue at a later point.

ok2c · 2025-12-26T14:15:36Z

@arturobernalg Please see 64b89f2

arturobernalg · 2025-12-26T15:00:02Z

@arturobernalg Please see 64b89f2

oh. much simple and clean.

ok2c · 2025-12-26T17:12:34Z

@arturobernalg Feel free to re-open this pull request and re-base your changes off the latest master.

ok2c · 2026-01-19T10:50:40Z

@arturobernalg Please re-open and rebase this change-set off the latest master. This is presently more important than other open pull requests in core

arturobernalg · 2026-01-19T14:32:17Z

@arturobernalg Please re-open and rebase this change-set off the latest master. This is presently more important than other open pull requests in core

@ok2c done

...ore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/bootstrap/CancellableExecution.java

Expose configuration via H2Config, throw H2StreamTimeoutException on expiry and keep the connection alive Extend test coverage and add an example client demonstrating timed-out and successful streams

; Handle cancelled SelectionKey in interestOps access

ok2c · 2026-01-20T18:44:27Z

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/H2Stream.java

+        return idleTimeout;
+    }
+
+    void setIdleTimeout(final Timeout idleTimeout) {


@arturobernalg Why are you still doing this? Please implement this method instead

@Override public void setTimeout(final Timeout timeout) { // not supported }

This is how the timeout should get initialized. Please remove all your timeout initialization code. It is not needed.

ok2c · 2026-01-20T18:46:44Z

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/H2Stream.java

+    }
+
+    Timeout getLifetimeTimeout() {
+        return lifetimeTimeout;


@arturobernalg Why do we need it? What purpose does it serve?

Please remove it. Please focus on the most fundamental and useful scenario for now.

Agreed. Let's solve one problem at a time

ok2c · 2026-01-20T18:47:43Z

httpcore5/src/main/java/org/apache/hc/core5/reactor/IOSessionImpl.java

    @Override
    public int getEventMask() {
-        return this.key.interestOps();
+        try {


@arturobernalg Christ on cross. Why do you still have this?

arturobernalg requested a review from ok2c December 7, 2025 15:07

arturobernalg force-pushed the h2Stream branch 2 times, most recently from 2f5d095 to 31bbf5b Compare December 10, 2025 18:56

arturobernalg force-pushed the h2Stream branch 2 times, most recently from c6364c8 to d7b8e8b Compare December 14, 2025 18:34

arturobernalg force-pushed the h2Stream branch 3 times, most recently from b60f8b0 to ccf73f8 Compare December 15, 2025 12:31

ok2c requested changes Dec 21, 2025

View reviewed changes

arturobernalg force-pushed the h2Stream branch from 084cab8 to 5cd4675 Compare December 22, 2025 08:16

arturobernalg requested a review from ok2c December 22, 2025 08:18

arturobernalg force-pushed the h2Stream branch from ee03f78 to e627911 Compare December 22, 2025 08:49

arturobernalg force-pushed the h2Stream branch from 8534aa0 to 8cf5233 Compare December 22, 2025 19:10

arturobernalg closed this Dec 26, 2025

arturobernalg reopened this Jan 19, 2026

arturobernalg force-pushed the h2Stream branch from 8cf5233 to 127a32f Compare January 19, 2026 10:55

ok2c reviewed Jan 19, 2026

View reviewed changes

...ore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/bootstrap/CancellableExecution.java Outdated Show resolved Hide resolved

arturobernalg force-pushed the h2Stream branch from 978dfae to ce72c8c Compare January 19, 2026 19:04

arturobernalg requested a review from ok2c January 19, 2026 19:05

arturobernalg added 2 commits January 20, 2026 19:02

HTTP/2: add per-stream idle and lifetime timeouts to core multiplexer

26993ee

Expose configuration via H2Config, throw H2StreamTimeoutException on expiry and keep the connection alive Extend test coverage and add an example client demonstrating timed-out and successful streams

add per-stream idle timeout and suppress CancelledKeyException on cancel

a500259

; Handle cancelled SelectionKey in interestOps access

arturobernalg force-pushed the h2Stream branch from ce72c8c to a500259 Compare January 20, 2026 18:02

ok2c requested changes Jan 20, 2026

View reviewed changes

HTTP/2: add per-stream idle and lifetime timeouts to core multiplexer #581

Are you sure you want to change the base?

HTTP/2: add per-stream idle and lifetime timeouts to core multiplexer #581

Conversation

arturobernalg commented Dec 7, 2025

Uh oh!

rschmitt commented Dec 9, 2025

Uh oh!

arturobernalg commented Dec 9, 2025

Uh oh!

rschmitt commented Dec 9, 2025

Uh oh!

arturobernalg commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ok2c commented Dec 10, 2025

Uh oh!

arturobernalg commented Dec 10, 2025

Uh oh!

ok2c commented Dec 10, 2025

Uh oh!

arturobernalg commented Dec 10, 2025

Uh oh!

rschmitt commented Dec 10, 2025

Uh oh!

ok2c commented Dec 10, 2025

Uh oh!

arturobernalg commented Dec 11, 2025

Uh oh!

ok2c commented Dec 14, 2025

Uh oh!

arturobernalg commented Dec 14, 2025

Uh oh!

rschmitt commented Dec 17, 2025

Uh oh!

Uh oh!

Uh oh!

ok2c Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

ok2c Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ok2c commented Dec 21, 2025

Uh oh!

arturobernalg commented Dec 22, 2025

Uh oh!

ok2c commented Dec 22, 2025

Uh oh!

arturobernalg commented Dec 22, 2025

Uh oh!

ok2c commented Dec 25, 2025

Uh oh!

ok2c commented Dec 26, 2025

Uh oh!

arturobernalg commented Dec 26, 2025

Uh oh!

ok2c commented Dec 26, 2025

Uh oh!

ok2c commented Jan 19, 2026

Uh oh!

arturobernalg commented Jan 19, 2026

Uh oh!

Uh oh!

ok2c Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

ok2c Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

rschmitt Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

ok2c Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

arturobernalg commented Dec 9, 2025 •

edited

Loading