[fredjoonpark]

What's Changed

Adds an optional hostnameOverride connection property to the Flight SQL JDBC driver. When TLS is enabled, the driver verifies the server certificate against this hostname and sends it for SNI and as the gRPC :authority, instead of using the host in the JDBC URL. This lets the driver connect with full certificate verification through SSH tunnels, port-forwarding, private endpoints, or IP addresses that don't match the server certificate. Today the only option in those cases is disableCertificateVerification=true.

• New property hostnameOverride (string, default unset) in ArrowFlightConnectionProperty, passed from ArrowFlightConnection to ArrowFlightSqlClientHandler.Builder.
• Builder.build() calls NettyClientBuilder.overrideHostname(...) when encryption is on. The property is ignored when useEncryption=false, and a blank value is treated as unset.
• Extra endpoint locations in getStreams(): the override is applied only when the endpoint host and port match the original connection (host compared case-insensitively, IPv6 brackets ignored). Endpoints at any other location, or any endpoint when the original connection isn't encrypted, are verified against their own hostname, as they are today. This logic is in Builder.getHostnameOverrideForEndpoint(URI) so it can be unit-tested.
• Documented in docs/source/flight_sql_jdbc_driver.rst next to tlsRootCerts.

Example:

jdbc:arrow-flight-sql://192.0.2.10:443?useEncryption=true&tlsRootCerts=/path/ca.pem&hostnameOverride=flight.example.com

Tests

• New ConnectionTlsHostnameOverrideTest. It uses the existing test certificate, which is issued for localhost and has no IP SAN. Its servers bind to 127.0.0.1 and the tests connect there, so they don't depend on how localhost resolves. Failure cases assert that the cause is a CertificateException, not just any SQLException:
  • without the property, the connection fails (No subject alternative names present);
  • with hostnameOverride=localhost, set in the URL or in Properties, it succeeds with full verification;
  • a non-matching override fails, which shows verification uses the override;
  • a blank hostnameOverride= behaves as unset;
  • the property is ignored for unencrypted connections;
  • a partitioned query whose endpoint is at the connection's host and port succeeds, which shows the override reaches endpoint clients;
  • a partitioned query whose endpoint is on the connection's IP but a different port fails, which shows the override is not applied there.
• ArrowFlightSqlClientHandlerBuilderTest: the default is unset and the builder copy keeps the value. The endpoint rule is covered for same host and port, different port, no port, different case, IPv6 with and without brackets, different host, unencrypted connection, blank value, and no override set.
• ArrowFlightConnectionConfigImplTest: the property is parsed.

This change is additive and has no breaking changes.

Closes #1319.

[fredjoonpark]

@lidavidm @laurentgo @wgtmac @jbonofre any chance we can get this reviewed?

[jbonofre]

@fredjoonpark I'm resuming the review on this one.

[jbonofre]

I will rebase, as the CI has been fixed on main.