TCP H2: Add FixedString(N) support

[alex-clickhouse]

What it does

FixedString(N) is the last Epic H type: N contiguous bytes per row, no length prefix, so a column body is exactly num_rows * N bytes.

• FixedStringColumn surfaces each row as a byte[]. It mirrors StringColumn's design (pooled blob, zero-copy GetBytes(row), GetString(row, encoding), lazy materialized view) but uses a fixed stride instead of an offsets array. byte[] is the honest default for a byte-oriented type, so embedded NULs and non-UTF-8 bytes round-trip intact. Out-of-range access is bounded against RowCount (not the rented blob) so it fails fast rather than returning stale pooled data.
• FixedStringColumnCodec parses N (rejecting missing/non-integer/non-positive/multi-arg), bulk-reads the body, and on write emits each value verbatim. Nullable(FixedString(N)) composes through the existing reference-nullable shape, substituting an N-zero-byte placeholder so a null never reaches this codec.

Write semantics: exactly N bytes, no padding

A value must be exactly N bytes. Over-length is rejected (matching the server, which errors rather than truncating) and so is under-length — the write path does not zero-pad.

Two reasons:

1. Padding silently rewrites the caller's data, so a wrong-width value reaches the server looking correct instead of surfacing the bug that produced it.
2. The HTTP path already rejects it. ClickHouse.Driver/Types/FixedStringType.cs requires a byte[] to be exactly N bytes (as do its ReadOnlyMemory<byte> and Stream overloads) and pads only for string. Padding here would mean the same package accepts over TCP what it refuses over HTTP.

That also draws the line for the deferred string-write overload: padding is a string affordance, not a byte[] one, and belongs there when it lands — mirroring FixedStringType.WriteString.

Both rejection messages carry the offending position — its row in a column, its index within the row's array under Array(FixedString(N)) — since rejecting is now the caller's only signal.

Dense write is one blit

A dense FixedStringColumn already holds its rows at the wire stride, so rows [start, start + length) are a single contiguous slice of the blob and go out in one WriteBytes — the hot path when re-inserting a value read straight back, and the same shape FixedWidthColumnCodec uses via ISpanColumn<T>. Every other write source is jagged byte[][] (a caller's ArrayColumn<byte[]>, a Nullable substitute, a Tuple field, an Array element run), so those keep the per-row path.

The blit is guarded on the column's width matching the codec's. That guard fixes a latent bug, not just the fast path: the previous dense branch had no width check at all, and CanWrite only tests the CLR element type (column is IColumn<byte[]>), so inserting a FixedString(2) read-back into a FixedString(4) target silently zero-padded every row to 4 bytes. A mismatched column now falls through to the per-row path and is rejected on width.

Testing

• FixedStringColumnCodecTests — parse errors, exact-width write, wrong-width rejection (parametrized: empty / short / long), null-row rejection, embedded-NUL and non-UTF-8 round-trip, zero rows, out-of-range before and after cache materialization, CanWrite, plus four shapes no server round-trip can reach: the sub-range blit, the mismatched-width dense fallback, GetBytes(start, length) bounds past RowCount, and the placeholder's content.
• InsertRoundTripCase — live-server round-trips for FixedString(4), FixedString(200) (a stride wider than one row, so a slipped blit is visible), Nullable(FixedString(4)) (interleaved + all-null, per the "always test inside Nullable" rule), Array(FixedString(4)), and Tuple(FixedString(4), String) — the one entrance that reaches the strict per-value branch through a field projection rather than a dense blob.
• Full TCP suite green (865 tests, incl. containerized round-trips). Both new files fully covered except the defensive read-failure leak-guard catch, matching sibling codecs.

Notes

• No size cap on N: the checked multiply already prevents overflow-to-negative; a policy cap on blob size is deferred by design decision Q5, so none is introduced here.
• NullPlaceholder is N zero bytes, built lazily — a codec is resolved per column per block, so allocating it eagerly would charge every read of a wide FixedString for a buffer only the Nullable write path touches.
• Write accepts byte[] only (not string) for now, keeping Nullable composition single-write-type; string-write ergonomics can be a follow-up.

🤖 Generated with Claude Code

[github-actions]

Triage

Category: feature • Risk: high

Summary
Adds FixedString(N) support to the TCP driver (ClickHouse.Driver.Tcp). The PR introduces FixedStringColumn (a fixed-stride pooled-blob column surfacing byte[] per row) and FixedStringColumnCodec (parses the N argument, bulk-reads rowCount × N bytes on read, and emits verbatim bytes with zero-right-padding on write). The codec is registered in ColumnCodecRegistry via a new factory entry. This is the last "Epic H" type for the TCP driver. Tests cover parse-error paths, padding, over-length/null rejection, embedded-NUL/non-UTF-8 round-trips, zero-row and out-of-range bounds, Nullable(FixedString(N)), and Array(FixedString(N)) live server round-trips.

What this impacts

• ClickHouse.Driver.Tcp/Types/ — two new files: FixedStringColumn.cs and Codecs/FixedStringColumnCodec.cs
• ClickHouse.Driver.Tcp/Types/ColumnCodecRegistry.cs — new AddFactory("FixedString", …) entry wires in type-argument parsing
• Binary read/write path: fixed-stride bulk read (ReadBytesAsync) and zero-padded write loop with stackalloc zero buffer
• InsertRoundTripCase extended for bare, padding, Nullable, and Array variants

Concerns

• High rule: binary protocol + type system — new binary read/write serialization path fires both the "Binary protocol / serialization layout" and "Type system / binary read/write paths" rules regardless of the additive-only nature of the change.
• Thread-safety assumption in FixedStringColumn.Values — the lazy cache initialization at line ~82 of FixedStringColumn.cs has no synchronization guard. The comment says "Single-consumer per connection, so the lazy fill needs no synchronization." If the assumption is ever violated (e.g., two threads calling Values on the same column object), the cache could be double-allocated or partially visible. Reviewer should verify this assumption is enforced at the call site, not just documented.
• No size cap on N — acknowledged in the PR body as a deferred policy decision (Q5). The checked multiply prevents integer overflow, but a caller can request a single-row read of 2 GB; reviewer should confirm this is acceptable for now.
• PR is in DRAFT state — may still be in flux.

Required reviewer action

• PR body already includes an architectural description. Human reviewer should verify binary encoding correctness (exact N-byte stride, null-placeholder → N zeros, padding contract) against ClickHouse protocol docs, and confirm the single-consumer thread-safety assumption for Values.

[Copilot]

Pull request overview

This PR adds full TCP (native) client support for ClickHouse FixedString(N) by introducing a fixed-width binary column representation and codec, registering it in the TCP codec registry, and extending the TCP test suite with unit + live round-trip coverage.

Changes:

• Added FixedStringColumn to expose FixedString(N) rows as fixed-stride slices over a pooled blob (with lazy per-row byte[] materialization).
• Added FixedStringColumnCodec to parse N, bulk-read/write rowCount * N bytes, right-pad short values to N, and reject over-length/null rows (nulls only via Nullable + placeholder).
• Extended TCP tests with FixedString unit tests and integration round-trip cases (including Nullable(...) and Array(...) compositions).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
ClickHouse.Driver.Tcp/Types/FixedStringColumn.cs	New fixed-stride pooled-blob column implementation with zero-copy GetBytes and cached byte[] view.
ClickHouse.Driver.Tcp/Types/ColumnCodecRegistry.cs	Registers FixedString as a parameterized codec factory.
ClickHouse.Driver.Tcp/Types/Codecs/FixedStringColumnCodec.cs	New codec handling parsing, bulk read, fixed-width write with padding, and null placeholder semantics.
ClickHouse.Driver.Tcp.Tests/Utilities/InsertRoundTripCase.cs	Adds live-server insert/read-back cases for FixedString, Nullable(FixedString), and Array(FixedString).
ClickHouse.Driver.Tcp.Tests/Types/FixedStringColumnCodecTests.cs	New unit tests covering parse errors, padding, multi-chunk padding, null/over-length rejection, stride correctness, and bounds checks.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!