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

This ignores the port (the builder test asserts it), so the override applies to every TLS endpoint on the connection host. If the server returns an endpoint on another port of that host that serves a different certificate (e.g. grpc+tls://10.0.0.5:9000 with a cert for 10.0.0.5 or its own name). It's now verified against hostnameOverride and fails, and there's no way to opt out.

Could we match on host and port, so the override only applies to the location it was configured for?

Suggested change

	|| !endpointHost.equalsIgnoreCase(host)) {
	|| endpointUri.getPort() != port
	|| !endpointHost.equalsIgnoreCase(host)) {

If covering every port on the host is need, I'm fine keeping it, but I would love to document it.

[fredjoonpark]

OK we can go with your suggestion. I'd originally left the port out for servers that hand out endpoints on other ports of the same host, but we can add this as an opt-in flag later if anyone asks for it.

The builder test now expects no override on a different port, and the endpoint integration test is split- an endpoint at the connection's host and port uses the override, and one on a different port fails verification.

[jbonofre]

URI#getHost keeps the brackets on IPv6 literals, but host doesn't always have them. JDBC URLs are fine (also parsed with URI#getHost), but when the host comes from Properties or the DataSource as ::1, the root connection works (Location.forGrpcTls adds the brackets) while "[::1]".equalsIgnoreCase("::1") is false.
Endpoints on the same host then silently skip the override and fail verification.

Could we strip the brackets on both sides before comparing (and add a test with withHost("::1")? Something like:

private static String stripBrackets(final String host) {
  return host != null && host.startsWith("[") && host.endsWith("]")
      ? host.substring(1, host.length() - 1)
      : host;
}

[fredjoonpark]

Yes good catch. Both sides now go through stripBrackets before the comparison, and I added a test for it.

[jbonofre]

Whichever way the port question goes (see my comment on getHostnameOverrideForEndpoint), could we make this explicit? Either "on the same host and port as the connection" or "on the same host as the connection, on any port".

[jbonofre]

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