Skip to content

Evict dead connections after deadlines and read-idle timeouts - #6

Merged
gartnera merged 7 commits into
mainfrom
claude/vibrant-lamport-9dam4d
Nov 10, 2026
Merged

gartnera merged 7 commits into
mainfrom
claude/vibrant-lamport-9dam4d

Conversation

@gartnera

@gartnera gartnera commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Over HTTP/2, neither URLSession nor Cronet notices a dead connection, because neither exposes HTTP/2 pings. New calls keep going to the dead connection, and each one waits until it times out. This PR adds three opt-in client options. With them, once a call on a connection runs out of time while the connection has gone quiet, new calls move off it.

NativeHttpConfig(
  readIdleTimeout: const Duration(seconds: 30), // fail calls that receive nothing for this long
  deadlineStep: const Duration(seconds: 1),     // send the server a deadline this much shorter
  evictOnDeadline: true,                        // a deadline that fires on the client evicts a quiet connection
);

All three are off by default. With none of them set, the client behaves as before.

deadlineStep and evictOnDeadline

  • deadlineStep: connect-dart sends a call's deadline to the server in connect-timeout-ms. With this option the client sends that much less, or half the deadline when that is less, so the server never gets zero. A reachable server then answers deadline_exceeded before the client's own deadline fires. Servers that call further services should take their own step off the deadline they pass on.
  • evictOnDeadline: a call that hits its deadline on the client is canceled, and its connection is evicted if it has gone quiet.
  • Use them together. Without a step, the server enforces the same deadline as the client but its clock starts later. On a healthy connection the client's deadline usually fires first, so the connection would be evicted for nothing.

readIdleTimeout

Every call on the client fails as unavailable once it has received nothing for this long. The timer runs from the call's start, so it also bounds the wait for response headers. Streams that go quiet for long need a client without it.

  • iOS: URLRequest.timeoutInterval, which fails with NSURLErrorTimedOut (-1001). URLSession treats a request's 60 s as "not set" (Apple DTS), so a 60 s timeout is sent as 60.001 s.
  • Android: a timer on the bridge's thread, reset by headers, body reads and trailers. A timeout fails the call with net::ERR_TIMED_OUT (-7).

Evicting a dead connection

  • When: a call runs out of time by its read-idle timeout, or by its deadline with evictOnDeadline, and nothing has arrived from its origin (host and port), on any call, since the call last received anything. If something has arrived, the connection is alive and only that call was slow, so nothing changes.
  • How: neither stack can close a single connection.
    • iOS: new calls go to a fresh URLSession, and the old one gets finishTasksAndInvalidate().
    • Android: the engine's CronetEngine is retired. New calls go to a fresh one, and the old one shuts down after its last call ends.
  • What stays: calls already on the old connection are not canceled. Several calls running out of time on the same connection evict it once.

Test server

  • TCP freeze: POST /freeze?for=…&path=tcp black-holes the TCP (HTTP/2) connections that are open at that moment, then closes them. Connections accepted later work. path defaults to udp, the existing behavior. The admin endpoint now also runs with -no-h3.
  • Client address: responses carry X-Remote-Addr, so a test can tell whether two calls shared a connection.

Integration tests (HTTP/2, both platforms)

On iOS each case first freezes the server's UDP, so URLSession falls back to TCP as it would where UDP is blocked. Every case checks X-Proto: HTTP/2.0.

  1. With a 1 s read-idle timeout, a quiet stream fails within the bound, with the platform's code.
  2. A stream that receives a message every 0.6 s outlives its 1 s timeout.
  3. On a frozen connection, nothing arrives for 3 s, and a new call waits on it until its 2 s deadline. With evictOnDeadline, the next call is on a new connection: its X-Remote-Addr differs.
  4. With a 2 s read-idle timeout, the stream on a frozen connection fails, and the next call is on a new connection.
  5. With deadlineStep, the server answers a 3 s deadline with deadline_exceeded in under 2.8 s, and the next call stays on the same connection.

The native suites cover:

  • a read-idle timeout on a quiet call, then a working next call;
  • an evicting cancel, then a working next call;
  • on Android, received data resetting the timer;
  • malformed-argument checks for both new bridge arguments.

Verified

  • Locally:
    • Dart format, analyze (package and example) and flutter test (52 tests) pass.
    • go vet and go test pass for the test server.
    • CronetBridge.kt and CronetBridgeTest.kt compile against the real cronet-api 143.7445.0 jar, with Android stubs.
  • CI on 25afc05: all jobs passed, with the same native code and integration cases always enabled rather than opt-in. The iOS simulator and Android emulator logs show all five HTTP/2 cases and the new native tests passing.
  • This head: it only makes the step and eviction opt-in, and the integration cases that need them now set them. CI runs it now.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i

A call fails as unavailable once it has received nothing from the server
for its read-idle timeout. Set it per call with
Headers.setReadIdleTimeout (carried in a header the client strips), or
as a client default with NativeHttpConfig.readIdleTimeout.

- iOS: URLRequest.timeoutInterval; NSURLErrorTimedOut (-1001). A 60 s
  value is sent as 60.001 s, since URLSession ignores a request's 60 s.
- Android: a timer on the bridge's thread, reset by headers, data and
  trailers; net::ERR_TIMED_OUT (-7).
- On a timeout the engine moves new calls to a fresh URLSession or
  CronetEngine, so they dial a new connection. The old one finishes its
  calls and is then released.

The test server's /freeze?path=tcp black-holes the HTTP/2 connections
open at the time. New integration cases use it to check, over HTTP/2 on
both platforms, that a quiet stream fails at its timeout, a busy one
doesn't, a dead connection goes unnoticed without a timeout, and with
one the next call gets through on a new connection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i
On the Android emulator, the first call on a fresh Cronet engine spent
longer than its 500 ms read-idle timeout in the TLS handshake, so the
timer ended it before the greeting arrived. The timeout covers
connection setup by design. The timed calls now reuse a connection an
earlier call left behind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i
A call that hits its deadline may be stuck on a dead connection, and
without eviction the next call would go to the same one. But the server
enforces the same deadline (connect-dart sends connect-timeout-ms) and
answers deadline_exceeded about a round trip after the client's own
deadline, so the client firing first says nothing about the connection.

- The call still fails at its deadline: Dart fails it immediately and
  tells the bridge to cancel it after a 1 s grace period.
- During the grace period the stream stays open. If anything arrives
  from the call's origin, the server's answer included, the connection
  is alive. If not, new calls move to a fresh URLSession or
  CronetEngine, as after a read-idle timeout.
- A read-idle timeout now only evicts under the same guard: nothing has
  arrived from the origin, on any call, since the call last received
  anything.

The test server now reports each client's address in X-Remote-Addr, so
the integration tests can check whether a call reused a connection.
They check that a deadline on a frozen HTTP/2 connection moves the next
call to a new one, that a read-idle timeout does too, and that a
deadline the server answers keeps the connection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i
@gartnera gartnera changed the title Add a per-call read-idle timeout that evicts the dead connection Read-idle timeouts, and evict dead connections after timeouts and deadlines Nov 10, 2026
The read-idle timeout is now only NativeHttpConfig.readIdleTimeout,
applied to every call on the client. Per-call bounds come from a call's
deadline, which already moves the client off a dead connection after
its grace period. setReadIdleTimeout and readIdleTimeoutHeader are
gone, along with the header the client stripped before sending.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i
@gartnera gartnera changed the title Read-idle timeouts, and evict dead connections after timeouts and deadlines Evict dead connections after deadlines and read-idle timeouts Nov 10, 2026
The client now sends the server a connect-timeout-ms 1 s shorter than
the call's own deadline (or half of it, under 2 s), so a reachable
server answers deadline_exceeded before the client's deadline fires.
When the client's deadline does fire, the server's answer never came:
the bridge cancels the call at once and evicts its connection, under
the same "nothing else arrived from the origin" check as a read-idle
timeout. The separate 1 s timer after the deadline is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i
Both are now NativeHttpConfig options, off by default:

- deadlineStep: how much shorter a deadline the server gets in
  connect-timeout-ms than the call's own (half the deadline when that is
  less). Unset, the deadline is sent unchanged.
- evictOnDeadline: whether a call that hits its deadline on the client
  moves new calls off its connection, under the usual guard. Unset, a
  deadline just cancels the call.

The docs recommend using them together: without a step, the client's
deadline usually beats the server's deadline_exceeded on a healthy
connection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i
- With evictOnDeadline, a call that received anything since the
  server's deadline (the head start deadlineStep gave the server) no
  longer evicts its connection: the server was still answering,
  whatever it made of the deadline.
- Android: a URL java.net.URI rejects no longer fails the call; it just
  stands for its own origin in the eviction guard.
- iOS builds the origin string once; stale comments that tied engine
  retirement to read-idle timeouts only, or mentioned a per-request
  read-idle timeout, are updated.
- New tests: the head-start window (Dart unit), and a read-idle timeout
  on one stream that leaves the connection to a stream still receiving
  (integration, HTTP/2, checked by X-Remote-Addr).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXX1R55toGUCQrbJY4i
@gartnera
gartnera enabled auto-merge (squash) November 10, 2026 01:46
@gartnera
gartnera merged commit e7e58eb into main Nov 10, 2026
6 checks passed
@gartnera
gartnera deleted the claude/vibrant-lamport-9dam4d branch November 10, 2026 01:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants