[client-v2] Reading Array(IPv6) / Array(Nullable(IPv6)) fails when an element is an IPv4-mapped address (::ffff:a.b.c.d)

Start with BinaryStreamReader.java, especially readArrayItem and resolveArrayItemClass, which the issue identifies as the two paths that choose IPv6 array component types. Reproduce with the mixed IPv6 and IPv4-mapped IPv6 queries in the issue, then run the relevant client-v2 reader and jdbc-v2 tests. Done when nullable and non-nullable arrays read mixed addresses without losing rows, while Array(IPv4) remains Inet4Address[].

Description

The binary reader cannot read an Array(IPv6) or Array(Nullable(IPv6)) value that contains an IPv4-mapped address (::ffff:a.b.c.d), unless every element of the array is IPv4-mapped. The read throws IllegalArgumentException: array element type mismatch. The failure is at record level, so the complete row is lost: in jdbc-v2, ResultSet.next() throws.

Affected shapes (verified on a live server, RowBinaryWithNamesAndTypes and Native):

The same failures occur through Client.newBinaryFormatReader(...), Client.queryAll(...) and jdbc-v2 Statement.executeQuery(...).

Steps to reproduce

1. Run SELECT [toNullable(toIPv6('::ffff:10.0.0.1'))] AS a or SELECT [toIPv6('2001:db8::1'), toIPv6('::ffff:10.0.0.1')] AS a with client-v2 or jdbc-v2.
2. Read the row.
3. The read throws the exception below.

The server returns these values without problems:

$ curl ... --data-binary "SELECT [toNullable(toIPv6('::ffff:10.0.0.1'))] AS a, toTypeName(a)"
['::ffff:10.0.0.1']	Array(Nullable(IPv6))
$ curl ... --data-binary "SELECT [toIPv6('2001:db8::1'), toIPv6('::ffff:10.0.0.1')] AS a, toTypeName(a)"
['2001:db8::1','::ffff:10.0.0.1']	Array(IPv6)

Error Log or Exception StackTrace

com.clickhouse.client.api.ClientException: Failed to read value for column a
Caused by: java.lang.IllegalArgumentException: Failed to set value at index: 0 value /10.0.0.1 of class java.net.Inet4Address when array type is class [Ljava.net.Inet6Address;
Caused by: java.lang.IllegalArgumentException: array element type mismatch

Reverse order ([toIPv6('::ffff:10.0.0.1'), toIPv6('2001:db8::1')]):

java.lang.IllegalArgumentException: Failed to set value at index: 1 value /2001:db8:0:0:0:0:0:1 of class java.net.Inet6Address when array type is class [Ljava.net.Inet4Address;

jdbc-v2: the same chain, wrapped in java.sql.SQLException: Failed to read value for column a, thrown from ResultSet.next().

Expected Behaviour

The read succeeds and the array holds one InetAddress for each element, as the server returns. A scalar IPv6 value that is IPv4-mapped already reads correctly as Inet4Address (see #2140). An array of the same values must also read correctly.

Root cause

• BinaryStreamReader.java:254 reads IPv6 with Inet6Address.getByAddress(readNBytes(input, 16)). This is the static InetAddress.getByAddress(byte[]). For an IPv4-mapped address it returns an Inet4Address, otherwise an Inet6Address.
• Nullable element: readArrayItem (lines 803-808) creates the backing array with resolveArrayItemClass(...). For IPv6 this falls to the default branch (line 877), dataType.getObjectClass(), which is Inet6Address.class (ClickHouseDataType.java:101). Array.set(...) of an Inet4Address element into an Inet6Address[] throws.
• Non-nullable element: readArrayItem (lines 817-818) uses the class of the first element as the component type. When a later element has the other InetAddress subclass, Array.set(...) throws. Thus an array works only if all its elements are mapped, or none are.

Suggested fix

Use InetAddress.class as the array component type for IPv6 elements, in both branches:

• resolveArrayItemClass: return InetAddress.class for IPv6 (nullable branch; the non-nullable branch too, so that empty arrays get the same type).
• readArrayItem, non-nullable branch: use InetAddress.class for IPv6 instead of firstValue.getClass().

I tested this change locally: all failing shapes in the table above then read correctly, through the client-v2 reader, queryAll, and jdbc-v2, in RowBinaryWithNamesAndTypes and Native.

Contrast cases:

• Array(IPv4) must stay Inet4Address[]. IPv4 always decodes to Inet4Address.
• The fix changes the runtime component type for IPv6 arrays to InetAddress[]. Today the type already depends on the data (Inet4Address[] for an all-mapped array, Inet6Address[] otherwise). The change agrees with the jdbc-v2 type mapping in #3191, which reports java.net.InetAddress for IPv6.

Code Example

Client client = new Client.Builder()
        .addEndpoint("http://localhost:8123")
        .setUsername("default").setPassword("")
        .build();

// Array(Nullable(IPv6)) with an IPv4-mapped element: throws
client.queryAll("SELECT [toNullable(toIPv6('::ffff:10.0.0.1'))] AS a");

// Array(IPv6) with a plain and an IPv4-mapped element (either order): throws
client.queryAll("SELECT [toIPv6('2001:db8::1'), toIPv6('::ffff:10.0.0.1')] AS a");

// jdbc-v2
try (Connection conn = DriverManager.getConnection("jdbc:clickhouse://localhost:8123/default", "default", "");
     Statement st = conn.createStatement();
     ResultSet rs = st.executeQuery("SELECT [toNullable(toIPv6('::ffff:10.0.0.1'))] AS a")) {
    rs.next(); // throws SQLException: Failed to read value for column a
}

Configuration

Client Configuration

// defaults; only endpoint and credentials set

Environment

• Cloud
• Client version: main @ 67a6b9e (0.12.0-rc1-SNAPSHOT)
• Language version: OpenJDK 17.0.20
• OS: Linux (Docker)

ClickHouse Server

• ClickHouse Server version: 26.9.1.1629
• ClickHouse Server non-default settings, if any: none
• CREATE TABLE statements for tables involved:

  CREATE TABLE ipv6_arr (id Int32, a Array(Nullable(IPv6)), f Float64) ENGINE = MergeTree ORDER BY id;
  INSERT INTO ipv6_arr VALUES (1, ['2001:db8::1', NULL, '::ffff:10.0.0.1'], 1.5);
  SELECT a FROM ipv6_arr ORDER BY id; -- fails
  

• Sample data for all these tables: above

Found by automated analysis of the client (Polyglot AI) while working on #3189. Verified against a live ClickHouse server with a reproduction program, not only by code inspection.