TCP Q3/Q4: an idle read deadline, and telling the server when a result is abandoned

[alex-clickhouse]

Stacked on #590 (tcp/epic-q1-exceptions). Completes Q3 (read timeouts) and Q4 (cancellation).

ReadTimeout now limits each transport read after the handshake. It defaults to 300 seconds; zero disables it. Each successful read allows the next read a full timeout, and time spent processing a yielded block does not count. Expiry throws ClickHouseTcpConnectionException with an inner TimeoutException and discards the connection. Connection establishment remains governed by DialTimeout.

Incomplete responses trigger a best-effort Cancel packet before the connection closes, including caller cancellation, read timeout, and early disposal of result enumeration. Cancel uses an independent two-second flush timeout. It is suppressed during insert row writes, where a partial Data packet could make the server interpret Cancel as block data.

Timeout exceptions

DialTimeout and ReadTimeout expiry throw ClickHouseTcpConnectionException with an inner TimeoutException. Both are failures between the client and the server, and both discard the connection, so catch (ClickHouseTcpException) covers them. PoolTimeout still throws a plain TimeoutException: no connection failed, and the fix is on the caller's side. So a caller can tell pool saturation from a server that did not answer. A TimeoutException subtype cannot also derive from DbException, so this has to be decided before the API is released.

A dial whose cancellation SslStream reports as an IOException is also reported as a timeout.

The code and comments use "timeout" instead of "deadline": IdleReadDeadline is now IdleReadTimeout.

Timeout completion race

A timer can cancel its token after a transport read succeeds but before the read's continuation disarms the timer. Reusing that cancelled token would make the next read fail immediately.

The transport buffer now obtains a token for each read. CancellationTokenSource.TryReset() disarms and reuses the source only when no timeout callback can remain; otherwise the source is disposed and replaced. Parsing, decompression adapters, and writes receive the caller's token. Normal reads reuse the source without adding per-read allocations.

The new deterministic test holds a successful read's continuation until its timer fires, then verifies the next read succeeds, a later stalled read still times out, and caller cancellation still reaches a replacement source. Restoring the old disarming logic makes the regression test fail on the next read. Existing integration tests exercise cancellation on the server, compression, handshake timeouts, and pooled connection reuse. Comments and XML documentation have also been simplified.

Validation

• After the timeout exception change: the TCP unit tests pass on .NET 9 on this branch (1,916) and on the stack tip (2,192). The integration tests were not run locally (no Docker); CI covers them.

• Full TCP suite on .NET 9 against ClickHouse 26.7.3.19: 3,531 passed.

• Focused protocol and live cancellation tests on .NET 8 and .NET 10: 157 passed on each framework.

• Final deterministic regression cases rerun after test hardening: 2 passed.

• After restacking, 159 selected protocol and live cancellation tests passed on the stack tip. All 95 descendant commits retained identical stable patch IDs and commit messages.

• Coverage: IdleReadDeadline.cs and ReadBuffer.cs 100%; ClickHouseTcpConnection.cs 94.9%. Independent coverage review found no important gaps.

• Independent review, Codex CLI review, and Claude CLI review completed. No correctness findings remain.

[Copilot]

Pull request overview

Adds native TCP idle-read timeouts and best-effort server cancellation when responses are abandoned.

Changes:

• Enforces ReadTimeout per transport read, with zero disabling it.
• Sends Cancel before terminating incomplete queries/inserts.
• Adds timeout, cancellation, pooling, and idle-semantics coverage.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
ClickHouse.Driver.Tcp/Protocol/ReadBuffer.cs	Arms deadlines around transport reads.
ClickHouse.Driver.Tcp/Protocol/IdleReadDeadline.cs	Implements reusable idle deadlines.
ClickHouse.Driver.Tcp/Protocol/ClickHouseTcpConnection.cs	Integrates deadlines and cancellation packets.
ClickHouse.Driver.Tcp/Client/IConnectionFactory.cs	Passes configured read timeout.
ClickHouse.Driver.Tcp/Client/ClickHouseTcpConnectionStringBuilder.cs	Documents zero-timeout behavior.
ClickHouse.Driver.Tcp/Client/ClickHouseTcpClientOptions.cs	Documents and validates timeout semantics.
ClickHouse.Driver.Tcp.Tests/Utilities/ScriptedDuplexStream.cs	Simulates delayed transport reads.
ClickHouse.Driver.Tcp.Tests/Protocol/ClickHouseTcpConnectionQueryTests.cs	Tests query timeout and cancellation behavior.
ClickHouse.Driver.Tcp.Tests/Protocol/ClickHouseTcpConnectionInsertTests.cs	Tests insert cancellation boundaries.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpCancellationIntegrationTests.cs	Verifies server-side cancellation and pooling.
ClickHouse.Driver.Tcp.Tests/Client/ClickHouseTcpClientOptionsTests.cs	Covers updated timeout validation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6f7946d. Configure here.}

[kavirajk]

LGTM