fix(client-v2): address review feedback on TLS cipher-suite selection

- Append SSL_CIPHER_SUITES at the end of ClientConfigProperties instead of
  inserting it after SSL_MODE, so the ordinal and values() ordering of every
  existing constant is preserved (docs/changes_checklist.md: "New constant is
  appended, not inserted in the middle").
- Correct the "JVM defaults" wording in the Javadoc, docs/features.md, the
  examples and the changelog: when cipher suites are unset the effective suites
  are the transport defaults, i.e. Apache HttpClient enables the JVM's default
  suites minus the ones it considers weak (TlsCiphers.excludeWeak). When suites
  are set they are enabled verbatim, so that wording is unchanged.

Addresses the cursor review on #2919.

Implements: #2882

Author: polyglotAI-bot

CHANGELOG.md

@@ -6,7 +6,7 @@
 
 - **[client-v2, jdbc-v2]** Added TLS cipher suite selection. `Client.Builder.setSSLCipherSuites(String...)` (client-v2)
   and the comma-separated `ssl_cipher_suites` connection property (client-v2 and jdbc-v2) restrict the cipher suites
-  enabled on secure connections; when unset, the JVM defaults are used. Cipher-suite selection is independent of the
+  enabled on secure connections; when unset, the transport defaults are used. Cipher-suite selection is independent of the
   trust configuration and `ssl_mode`. (https://github.com/ClickHouse/clickhouse-java/issues/2882)
 
 ### Bug Fixes 

client-v2/src/main/java/com/clickhouse/client/api/Client.java

@@ -789,7 +789,8 @@ public Builder setSSLMode(SSLMode sslMode) {
         /**
          * Restricts the TLS cipher suites the client may negotiate on secure connections. When set, only
          * the listed cipher suites are enabled on the SSL socket (subject to what the JVM and the server
-         * support); when not set, the JVM defaults are used. Suite names use the standard JSSE names, for
+         * support); when not set, the transport defaults are used (Apache HttpClient enables the JVM's
+         * default suites minus those it considers weak). Suite names use the standard JSSE names, for
          * example {@code TLS_AES_256_GCM_SHA384}.
          *
          * @param cipherSuites cipher suite names to enable

client-v2/src/main/java/com/clickhouse/client/api/ClientConfigProperties.java

@@ -118,13 +118,6 @@ public enum ClientConfigProperties {
 
     SSL_MODE("ssl_mode", SSLMode.class, SSLMode.STRICT.name()),
 
-    /**
-     * Comma-separated list of TLS cipher suites the client is allowed to negotiate on secure connections.
-     * When set, only these cipher suites are enabled on the SSL socket (subject to what the JVM and server
-     * support); when unset, the JVM defaults are used.
-     */
-    SSL_CIPHER_SUITES("ssl_cipher_suites", List.class),
-
     RETRY_ON_FAILURE("retry", Integer.class, "3"),
 
     INPUT_OUTPUT_FORMAT("format", ClickHouseFormat.class),
@@ -211,6 +204,17 @@ public Object parseValue(String value) {
      *  See <a href="https://clickhouse.com/docs/operations/settings/query-level#custom_settings">ClickHouse Docs</a>
      */
     CUSTOM_SETTINGS_PREFIX("custom_settings_prefix", String.class, "custom_"),
+
+    /**
+     * Comma-separated list of TLS cipher suites the client is allowed to negotiate on secure connections.
+     * When set, only these cipher suites are enabled on the SSL socket (subject to what the JVM and server
+     * support); when unset, the transport defaults are used (Apache HttpClient enables the JVM's default
+     * suites minus those it considers weak).
+     * <p>
+     * Appended at the end of the enum on purpose: adding a constant in the middle would shift the ordinal
+     * of every following constant (see {@code docs/changes_checklist.md}).
+     */
+    SSL_CIPHER_SUITES("ssl_cipher_suites", List.class),
     ;
 
     private static final Logger LOG = LoggerFactory.getLogger(ClientConfigProperties.class);

client-v2/src/main/java/com/clickhouse/client/api/internal/HttpAPIClientHelper.java

@@ -1087,14 +1087,14 @@ public static class CustomSSLConnectionFactory extends SSLConnectionSocketFactor
 
         private final SNIHostName defaultSNI;
 
-        // Retained for backward compatibility; delegates with no cipher-suite restriction (JVM defaults).
+        // Retained for backward compatibility; delegates with no cipher-suite restriction (transport defaults).
         public CustomSSLConnectionFactory(String defaultSNI, SSLContext sslContext, HostnameVerifier hostnameVerifier) {
             this(defaultSNI, sslContext, hostnameVerifier, null);
         }
 
         public CustomSSLConnectionFactory(String defaultSNI, SSLContext sslContext, HostnameVerifier hostnameVerifier,
                                           String[] supportedCipherSuites) {
-            // supportedProtocols is left as null (JDK defaults are used); supportedCipherSuites, when
+            // supportedProtocols is left as null (transport defaults apply); supportedCipherSuites, when
             // provided, restricts the cipher suites the base factory enables on each socket. A null
             // hostnameVerifier makes the base factory fall back to its default verifier.
             super(sslContext, null, supportedCipherSuites, hostnameVerifier);

client-v2/src/test/java/com/clickhouse/client/api/internal/HttpAPIClientHelperTest.java

@@ -50,7 +50,7 @@ public void testCipherSuiteConstructorForwardsSuitesToBaseFactory() throws Excep
 
     /**
      * The three-argument constructor is retained for backward compatibility and must delegate with no cipher
-     * restriction, so callers that do not configure cipher suites keep the JVM defaults.
+     * restriction, so callers that do not configure cipher suites keep the transport defaults.
      */
     @Test
     public void testLegacyConstructorAppliesNoCipherRestriction() throws Exception {
@@ -120,7 +120,7 @@ public void testCreateHttpClientStrictWithCipherSuitesForwardsSuitesAndKeepsHost
 
     /**
      * TRUST mode opts out of hostname verification, so the factory must receive a permissive (non-null)
-     * verifier; with no cipher suites configured the factory must keep the JVM defaults (no restriction).
+     * verifier; with no cipher suites configured the factory must keep the transport defaults (no restriction).
      */
     @Test
     public void testCreateHttpClientTrustModeInstallsPermissiveVerifierWithoutCipherRestriction() {
@@ -206,7 +206,7 @@ public void testCreateHttpClientSniAndCipherSuitesCombine() {
     }
 
     /**
-     * Boundary case: an empty cipher-suite list must be treated as "no restriction" (JVM defaults), exactly
+     * Boundary case: an empty cipher-suite list must be treated as "no restriction" (transport defaults), exactly
      * like an unset value - it must NOT be turned into an empty cipher array, which would enable zero suites
      * and make every handshake fail. STRICT with no SNI therefore keeps using the plain factory.
      */
@@ -217,8 +217,8 @@ public void testCreateHttpClientEmptyCipherSuitesTreatedAsNoRestriction() {
 
         List<List<?>> calls = captureCustomFactoryConstruction(config);
 
-        assertEquals(calls.size(), 0, "an empty cipher-suite list must be treated as no restriction (JVM "
-                + "defaults), so the plain SSLConnectionSocketFactory is used");
+        assertEquals(calls.size(), 0, "an empty cipher-suite list must be treated as no restriction "
+                + "(transport defaults), so the plain SSLConnectionSocketFactory is used");
     }
 
     /**
@@ -247,7 +247,7 @@ public void testCreateHttpClientDropsBlankAndWhitespaceCipherTokens() {
     /**
      * Boundary case: a cipher-suite list that contains only blank tokens (e.g. from a property that is just
      * commas/whitespace) has no usable suite, so - like an empty or unset list - it must be treated as "no
-     * restriction" (JVM defaults) rather than forwarding an all-blank array that would fail every handshake.
+     * restriction" (transport defaults) rather than forwarding an all-blank array that would fail every handshake.
      */
     @Test
     public void testCreateHttpClientBlankOnlyCipherSuitesTreatedAsNoRestriction() {
@@ -257,7 +257,7 @@ public void testCreateHttpClientBlankOnlyCipherSuitesTreatedAsNoRestriction() {
         List<List<?>> calls = captureCustomFactoryConstruction(config);
 
         assertEquals(calls.size(), 0, "a cipher-suite list of only blank tokens must be treated as no "
-                + "restriction (JVM defaults), so the plain SSLConnectionSocketFactory is used");
+                + "restriction (transport defaults), so the plain SSLConnectionSocketFactory is used");
     }
 
     /**

docs/features.md

@@ -7,7 +7,7 @@ This document lists stable, user-visible behavior in `client-v2` and `jdbc-v2` t
 - HTTP and HTTPS connectivity: Connects to ClickHouse over HTTP(S), supports endpoint paths, and exposes a basic `ping` health check.
 - TLS configuration: Supports trust stores, client certificates/keys, SSL certificate authentication, and SNI for HTTPS connections. Trust material (root CA and client certificate/key) can be supplied either as a file path or directly as PEM content.
 - SSL verification modes: `Client.Builder.setSSLMode(SSLMode)` (or the `ssl_mode` property) controls how strictly the server identity is verified on secure connections: `DISABLED` (SSL not used; plain protocols only), `TRUST` (accept any server certificate and skip hostname verification; a configured trust store or CA certificate is ignored with a warning, while a client certificate/key is still applied for mTLS if configured), `VERIFY_CA` (validate the certificate chain but skip hostname verification), and `STRICT` (full chain and hostname verification, default).
-- TLS cipher suite selection: `Client.Builder.setSSLCipherSuites(String...)` (or the comma-separated `ssl_cipher_suites` property) restricts the cipher suites enabled on secure connections. When set, only the listed suites are enabled on the SSL socket (subject to JVM and server support); when unset, the JVM defaults apply. Cipher-suite selection is independent of the trust configuration and `ssl_mode`.
+- TLS cipher suite selection: `Client.Builder.setSSLCipherSuites(String...)` (or the comma-separated `ssl_cipher_suites` property) restricts the cipher suites enabled on secure connections. When set, only the listed suites are enabled on the SSL socket (subject to JVM and server support); when unset, the transport defaults apply (Apache HttpClient enables the JVM's default suites minus those it considers weak). Cipher-suite selection is independent of the trust configuration and `ssl_mode`.
 - Authentication modes: Supports username/password credentials, ClickHouse auth headers, bearer tokens, and optional HTTP Basic authentication.
 - Runtime credential updates: Existing `Client` instances can update username/password or bearer-token credentials for subsequent requests without rebuilding the client.
 - Proxy support: Can send requests through configured HTTP proxies, including proxy credentials.

examples/client-v2/src/main/java/com/clickhouse/examples/client_v2/SSLExamples.java

@@ -28,7 +28,7 @@
  *     Use it only for testing or in fully trusted environments.</li>
  *     <li>Restricting the negotiated TLS cipher suites with
  *     {@link Client.Builder#setSSLCipherSuites(String...)} - useful to enforce a stronger or
- *     compliance-mandated set of cipher suites instead of the JVM defaults.</li>
+ *     compliance-mandated set of cipher suites instead of the transport defaults.</li>
  * </ul>
  *
  * <p>More SSL examples (mTLS, trust stores, SNI) will be added to this class later.</p>
@@ -202,7 +202,7 @@ static void connectWithRootCertificateAsString(String endpoint, String database,
      * Connects while restricting the TLS cipher suites the client is allowed to negotiate, using
      * {@link Client.Builder#setSSLCipherSuites(String...)}. Only the listed suites are enabled on the
      * socket (subject to what the JVM and the server support); this is useful to enforce a stronger or
-     * compliance-mandated set of cipher suites rather than relying on the JVM defaults.
+     * compliance-mandated set of cipher suites rather than relying on the transport defaults.
      *
      * <p>The CA certificate is still used to verify the server, and hostname verification stays enabled -
      * cipher-suite selection is independent of the trust configuration and the SSL mode. The suites below

examples/jdbc/src/main/java/com/clickhouse/examples/jdbc/SSLExamples.java

@@ -33,7 +33,7 @@
  *     testing or in fully trusted environments.</li>
  *     <li>Restricting the negotiated TLS cipher suites with the {@code ssl_cipher_suites} connection
  *     property (a comma-separated list) - useful to enforce a stronger or compliance-mandated set of
- *     cipher suites instead of the JVM defaults.</li>
+ *     cipher suites instead of the transport defaults.</li>
  * </ul>
  *
  * <p>More SSL examples (mTLS, trust stores, SNI) will be added to this class later.</p>
@@ -206,7 +206,7 @@ static void connectWithRootCertificateAsString(String url, String user, String p
      * Connects while restricting the TLS cipher suites the driver is allowed to negotiate, using the
      * {@code ssl_cipher_suites} connection property (a comma-separated list). Only the listed suites are
      * enabled on the socket (subject to what the JVM and the server support); this is useful to enforce a
-     * stronger or compliance-mandated set of cipher suites rather than relying on the JVM defaults.
+     * stronger or compliance-mandated set of cipher suites rather than relying on the transport defaults.
      *
      * <p>The CA certificate is still used to verify the server and hostname verification stays enabled -
      * cipher-suite selection is independent of the trust configuration and {@code ssl_mode}. Keep at least