feat(error): add typed Error::ServerError { code, name, message } variant

[gregvirgin-ls]

Summary

Adds a typed Error::ServerError { code: u32, name: Option<String>, message: String } variant alongside the existing Error::BadResponse(String). ClickHouse server exceptions arrive in two wire shapes today (streaming body and X-ClickHouse-Exception-Code header fast-fail) and both flatten into BadResponse(String), forcing every downstream that wants code-aware control flow to substring-match the text. This change recognises the canonical shapes and produces the typed variant; anything that doesn't match still falls through to BadResponse, so every existing match arm still compiles.

Behaviour change

Recognisable ClickHouse server exceptions now surface as Error::ServerError { code, name, message } instead of Error::BadResponse(String). Both the streaming wire path (extract_exception_old, extract_exception_new) and the header fast-fail path (collect_bad_response) emit the typed variant when the body parses cleanly. Anything unrecognised — proxy errors, malformed bodies, non-ClickHouse responses, compressed bodies that didn't decompress — continues to surface as Error::BadResponse(String).

Error is #[non_exhaustive], so the new variant is additive: existing match arms with a _ => fallback (or that already matched on BadResponse) keep compiling. The new variant gives consumers an option to do better, not a required migration.

Migration example

Code that today substring-matches the body text:

match err {
    clickhouse::error::Error::BadResponse(s) if s.contains("(TOO_MANY_PARTS)") => {
        alert_on_too_many_parts();
    }
    other => return Err(other),
}

Becomes a clean code-based dispatch:

match err {
    clickhouse::error::Error::ServerError { code: 252, .. } => alert_on_too_many_parts(),
    other => return Err(other),
}

Or, for an exception class that matters by name rather than code:

match err {
    clickhouse::error::Error::ServerError { name: Some(n), .. } if n == "TIMEOUT_EXCEEDED" => {
        retry_with_longer_timeout();
    }
    other => return Err(other),
}

Existing Error::BadResponse(...) match arms continue to fire on responses that do not parse as a recognised CH exception (proxy errors, malformed bodies, compressed payloads). Consumers who only have a BadResponse arm today will silently miss the typed variant on canonical responses; adding a ServerError { .. } arm above it is the upgrade path.

Tests

Ten unit tests in src/response.rs::tests cover:

• Streaming body with (NAME) tag and (version ...) trailer.
• Header-only Code: NNN fast-fail.
• (TOO_MANY_PARTS) (the motivating ClickFlow case).
• Bodies that should fall back to BadResponse: non-ClickHouse responses, malformed code, missing-Code: strings.
• No-name-tag form (some CH versions / proxies trim the tag).
• Compressed (zstd / lz4) error bodies — fall through to BadResponse.
• Code: N. DB::Exception:<no-space>message — parser intentionally tolerates the missing space; code, name, and the full message are all extracted (the variant captures the same fields it would with the space present).
• User-data parens in the message (must NOT be misread as the (NAME) tag).
• Header code with non-ClickHouse proxy body (must fall back to BadResponse).

Existing integration test in tests/it/fetch_bytes.rs updated to match.

Clippy / test matrix

Before pushing:

cargo fmt -- --check
cargo clippy --all-targets --no-default-features
cargo clippy --all-targets --all-features
cargo clippy --features native-tls
cargo clippy --features rustls-tls
cargo clippy --features rustls-tls-ring,rustls-tls-webpki-roots
cargo clippy --features rustls-tls-ring,rustls-tls-native-roots
cargo clippy --features rustls-tls-aws-lc,rustls-tls-webpki-roots
cargo clippy --features rustls-tls-aws-lc,rustls-tls-native-roots
cargo test --workspace
cargo test --workspace --no-default-features
cargo test --workspace --all-features
cargo rustdoc -p clickhouse --all-features -- -D warnings --cfg docsrs

What this does NOT do

• Does not introduce a hardcoded code → name lookup table. When CH includes the (NAME) tag we capture it; when the response is bare Code: NNN we leave name as None.
• Does not change BadResponse's representation or remove it. It remains the fallback for anything the parser doesn't recognise.
• Does not make ServerError exhaustive. The struct fields can grow under #[non_exhaustive].

Downstream motivation

ClickFlow (a Rust SDK on top of clickhouse-rs) carries two substring-matching helpers that this change retires:

• is_too_many_parts in crates/clickflow/src/batch.rs.
• is_caller_caused_ch_error in crates/clickflow-mcp/src/error.rs (matches CH codes 43/47/53/386 to map to JSON-RPC -32602 invalid_params).

Every non-trivial clickhouse-rs consumer ends up with some version of these helpers. The typed variant retires the class.

[abonander]

Even if it's not technically a breaking API change, this is a significant enough behavior change that it may be better to wait for 0.16.0. Error handling is one of those things that you don't want to change out from under people if you can avoid it.

[abonander]

I'm starting to think that structured errors like this should be their own structs. That allows for more flexible handling, as you can write functions which handle that error type specifically.