TCP Q1/Q2: public exception hierarchy and named server error codes

[alex-clickhouse]

Stacked on #589 (tcp/epic-p-observability). Review only the last commit.

Closes Q1 (exception type hierarchy) and Q2 (server error to typed .NET mapping).

The problem

Neither of the two types that carry the driver's semantics could be caught by name — both were internal sealed. Everything else escaping a public method was an undifferentiated BCL type with no common base, so the only way to distinguish a server rejection from a broken socket was GetType().Name.

The shape

An abstract ClickHouseTcpException : DbException with private protected constructors, so the hierarchy is closed at three leaves:

Type	Means
ClickHouseTcpServerException	the server reported an error
ClickHouseTcpProtocolException	the bytes did not match the protocol
ClickHouseTcpTransportException	the connection failed

Argument validation, disposal and cancellation keep their framework types — those are the caller's mistakes, not the database's.

DbException was chosen over plain Exception for ErrorCode, which retry frameworks probe for, and because the shipped HTTP ClickHouseServerException already derives from it.

Q2: codes, not subclasses

A 26.7 server names about 660 error codes, so subclassing is not on. ClickHouseErrorCode names the 54 worth branching on; anything else reads as Unknown with RawCode intact. Every value was read off a live 26.7.1 server rather than transcribed.

catch (ClickHouseTcpServerException e) when (e.Code == ClickHouseErrorCode.UnknownTable)

The client does not tell the caller which errors are worth retrying. That judgement is debatable for several codes, and code written against one client's opinion of it cannot be corrected later. The caller branches on Code, or on the inner exception a transport failure keeps.

Wrapping, and what is not wrapped

The transport exceptions are never constructed by this code — there is no throw new IOException anywhere in the project — so all 338 throw sites were never the work. They enter through four calls into the socket: the two reads in ReadBuffer, the write in ClickHouseBinaryWriter, and connect plus the TLS handshake.

ObjectDisposedException is not wrapped. A socket or stream only raises it because this process disposed it — the pool aborting a connection, a session disposing under a live read, the caller disposing the client. Wrapping it as a transport failure would have masked TlsParameters' refusal to fall back from pinned roots to the machine trust store.

For the same reason TlsParameters now builds its handshake options separately from handshaking, and the connect runs that first. A ConfigureTls hook that fails loading a client certificate off disk throws IOException, and run inside the connect that read as a network error.

InvalidDataException is folded into the protocol exception, including the frames raised by the shared CompressionFrame, which cannot name a TCP type and so is translated at the frame reader.

Tests

3692 pass, 5 skipped, against a real server.

New integration coverage asserts four real server errors map to their named code (60/62/46/81, each verified against the server before being written down), a max_execution_time breach reaching TimeoutExceeded, a wrong password reaching AuthenticationFailed, and connect-refused producing a transport exception that names the endpoint and keeps the SocketException. Unit tests cover only what a live server cannot produce on demand: an unnamed code, and the two disposal paths.

Two things caught during the change, both worth noting because they were caught by existing machinery rather than by reading:

• TcpActivity.cs built the OTel db.response.status_code tag from .Code, which silently became the enum — the tag would have started emitting AuthenticationFailed instead of 516. An existing test failed on it.
• Nine assertions compared .Code against an int. NUnit2021/NUnit2041 failed the build rather than letting them mis-compare at runtime.

Not in scope

No PublicAPI.Tcp.txt and no XML doc generation — the project has neither today, and both belong with R1/R4, which own the surface. The <exception> tags added here are therefore source-only for now.

No changelog fragment, consistent with the rest of this stack.

[Copilot]

Pull request overview

Adds a public TCP exception hierarchy, named server error codes, transport wrapping, and protocol-failure classification.

Changes:

• Introduces typed server, protocol, and transport exceptions.
• Maps selected ClickHouse error codes and transient status.
• Updates diagnostics and test coverage for the new behavior.

Reviewed changes

Copilot reviewed 53 out of 53 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
ClickHouse.Driver.Tcp/Types/Codecs/StringColumnCodec.cs	Uses the public protocol exception.
ClickHouse.Driver.Tcp/Types/Codecs/NestedColumnCodec.cs	Updates offset-validation exceptions.
ClickHouse.Driver.Tcp/Types/Codecs/MapColumnCodec.cs	Updates map protocol exceptions.
ClickHouse.Driver.Tcp/Types/Codecs/LowCardinalityColumnCodec.cs	Updates wire-validation exceptions.
ClickHouse.Driver.Tcp/Types/Codecs/JsonStringColumnCodec.cs	Updates serialization-version failure.
ClickHouse.Driver.Tcp/Types/Codecs/DynamicColumnCodec.cs	Updates Dynamic protocol failures.
ClickHouse.Driver.Tcp/Types/Codecs/ArrayColumnCodec.cs	Updates array offset failures.
ClickHouse.Driver.Tcp/Protocol/TransportFailure.cs	Centralizes transport classification and wrapping.
ClickHouse.Driver.Tcp/Protocol/TlsParameters.cs	Separates TLS option construction from negotiation.
ClickHouse.Driver.Tcp/Protocol/ReadBuffer.cs	Wraps read and EOF failures.
ClickHouse.Driver.Tcp/Protocol/Handshake.cs	Uses typed handshake exceptions.
ClickHouse.Driver.Tcp/Protocol/ClickHouseTcpConnection.cs	Propagates the new hierarchy through operations.
ClickHouse.Driver.Tcp/Protocol/ClickHouseProtocolException.cs	Removes the old internal exception.
ClickHouse.Driver.Tcp/Protocol/ClickHouseBinaryWriter.cs	Wraps write failures.
ClickHouse.Driver.Tcp/Protocol/ClickHouseBinaryReader.cs	Classifies malformed wire values.
ClickHouse.Driver.Tcp/Format/BlockReader.cs	Updates block protocol failures.
ClickHouse.Driver.Tcp/Exceptions/ClickHouseTcpTransportException.cs	Adds the transport exception leaf.
ClickHouse.Driver.Tcp/Exceptions/ClickHouseTcpServerException.cs	Publishes server errors and code mapping.
ClickHouse.Driver.Tcp/Exceptions/ClickHouseTcpProtocolException.cs	Adds the protocol exception leaf.
ClickHouse.Driver.Tcp/Exceptions/ClickHouseTcpException.cs	Adds the shared DbException base.
ClickHouse.Driver.Tcp/Exceptions/ClickHouseErrorCode.cs	Defines named server error codes.
ClickHouse.Driver.Tcp/Diagnostic/TcpActivity.cs	Preserves raw error codes in telemetry.
ClickHouse.Driver.Tcp/Compression/CompressedFrameReader.cs	Translates malformed compression frames.
ClickHouse.Driver.Tcp/Client/MetadataCallbackBridge.cs	Updates metadata protocol failures.
ClickHouse.Driver.Tcp.Tests/Types/QBitColumnCodecTests.cs	Updates truncated-read expectations.
ClickHouse.Driver.Tcp.Tests/Types/NestedColumnCodecTests.cs	Updates protocol assertions.
ClickHouse.Driver.Tcp.Tests/Types/MapColumnCodecTests.cs	Updates protocol assertions.
ClickHouse.Driver.Tcp.Tests/Types/LowCardinalityColumnCodecTests.cs	Updates protocol assertions.
ClickHouse.Driver.Tcp.Tests/Types/JsonStringColumnCodecTests.cs	Updates protocol assertions.
ClickHouse.Driver.Tcp.Tests/Types/DynamicColumnCodecTests.cs	Updates version-failure assertion.
ClickHouse.Driver.Tcp.Tests/Types/ArrayColumnCodecTests.cs	Updates protocol assertions.
ClickHouse.Driver.Tcp.Tests/Protocol/TlsParametersTests.cs	Covers separated TLS configuration.
ClickHouse.Driver.Tcp.Tests/Protocol/ReadBufferTests.cs	Covers wrapping and disposal behavior.
ClickHouse.Driver.Tcp.Tests/Protocol/HandshakeTests.cs	Updates handshake exception assertions.
ClickHouse.Driver.Tcp.Tests/Protocol/CompressedSendFailureTests.cs	Expects transport exceptions on send failure.
ClickHouse.Driver.Tcp.Tests/Protocol/ClickHouseTcpConnectionTests.cs	Updates ping and handshake failures.
ClickHouse.Driver.Tcp.Tests/Protocol/ClickHouseTcpConnectionQueryTests.cs	Updates query failure assertions.
ClickHouse.Driver.Tcp.Tests/Protocol/ClickHouseTcpConnectionInsertTests.cs	Updates insert failure assertions.
ClickHouse.Driver.Tcp.Tests/Protocol/ClickHouseBinaryReaderWriterTests.cs	Tests typed reader failures.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpTracingIntegrationTests.cs	Updates tracing error types.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpSessionIntegrationTests.cs	Updates session error assertions.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpParameterIntegrationTests.cs	Updates parameter error assertions.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpLoggingIntegrationTests.cs	Updates logged exception types.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpExceptionIntegrationTests.cs	Adds end-to-end exception mapping tests.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpConnectionQueryIntegrationTests.cs	Verifies typed query errors.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpConnectionIntegrationTests.cs	Verifies authentication and transport errors.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpConnectionInsertIntegrationTests.cs	Verifies typed insert errors.
ClickHouse.Driver.Tcp.Tests/Integration/ClickHouseTcpClientIntegrationTests.cs	Updates client error assertions.
ClickHouse.Driver.Tcp.Tests/Format/BlockInfoTests.cs	Updates block-info exception assertion.
ClickHouse.Driver.Tcp.Tests/Exceptions/ClickHouseTcpServerExceptionTests.cs	Tests code and transient mapping.
ClickHouse.Driver.Tcp.Tests/Diagnostic/TcpActivityTests.cs	Verifies raw telemetry status codes.
ClickHouse.Driver.Tcp.Tests/Compression/CompressedFrameStreamingTests.cs	Updates compression protocol assertions.
ClickHouse.Driver.Tcp.Tests/Client/MetadataCallbackBridgeTests.cs	Updates metadata exception assertions.

---

💡 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]

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 019c831. Configure here.}