Add support for direct SSL negotiation (PostgreSQL 17+) (#1659)

* Add support for direct SSL negotiation (PostgreSQL 17+)

Closes #1536

- Added SslNegotiation enum with POSTGRES (default) and DIRECT modes
- Extended PgConnectOptions with sslNegotiation field, supporting configuration via API, connection URI, and environment variable
- Refactored PgConnectionFactory to handle direct SSL with ALPN protocol negotiation
- Added tests with PostgreSQL 17+ version checks
- Updated documentation

The implementation maintains full backward compatibility by defaulting to traditional negotiation (POSTGRES mode).

Some portions of this content were created with the assistance of Claude Code.

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Safely copy ClientSSLOptions

In case it's null, create a new instance

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

---------

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

Author: tsegismont

vertx-pg-client/src/main/asciidoc/index.adoc

@@ -194,6 +194,7 @@ Currently, the client supports the following parameter keys:
 * `password`
 * `dbname`
 * `sslmode`
+* `sslnegotiation`
 
 Additional parameters will be added to the {@link io.vertx.sqlclient.SqlConnectOptions#getProperties properties}.
 
@@ -212,6 +213,7 @@ for more details. The following parameters are supported:
 * `PGUSER`
 * `PGPASSWORD`
 * `PGSSLMODE`
+* `PGSSLNEGOTIATION`
 
 If you don't specify a data object or a connection URI string to connect, environment variables will take precedence over them.
 
@@ -731,6 +733,38 @@ All https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION[
 {@link examples.PgClientExamples#ex10}
 ----
 
+=== SSL Negotiation (PostgreSQL 17+)
+
+PostgreSQL 17 introduced direct SSL negotiation, which allows the client to establish TLS immediately without the traditional protocol handshake.
+This reduces connection latency by one round-trip and enables standard SSL proxies (nginx, haproxy) to terminate TLS for PostgreSQL connections.
+
+The client supports two SSL negotiation modes via {@link io.vertx.pgclient.SslNegotiation}:
+
+- `POSTGRES` (default): Traditional negotiation where the client sends an SSL request and waits for the server's response before establishing TLS
+- `DIRECT`: Direct negotiation where TLS is established immediately (requires PostgreSQL 17+)
+
+[source,$lang]
+----
+{@link examples.PgClientExamples#sslNegotiationDirect}
+----
+
+You can also configure SSL negotiation via connection URI:
+
+[source,$lang]
+----
+{@link examples.PgClientExamples#sslNegotiationUri}
+----
+
+Or using the environment variable:
+
+[source,bash]
+----
+export PGSSLNEGOTIATION=direct
+----
+
+NOTE: Direct SSL negotiation requires PostgreSQL 17 or later.
+Attempting to use `DIRECT` mode with older PostgreSQL versions will result in an SSL handshake failure.
+
 More information can be found in the http://vertx.io/docs/vertx-core/java/#ssl[Vert.x documentation].
 
 == Using a level 4 proxy

vertx-pg-client/src/main/java/examples/PgClientExamples.java

@@ -17,10 +17,7 @@
 import io.vertx.core.net.ClientSSLOptions;
 import io.vertx.core.net.PemTrustOptions;
 import io.vertx.docgen.Source;
-import io.vertx.pgclient.PgBuilder;
-import io.vertx.pgclient.PgConnectOptions;
-import io.vertx.pgclient.PgConnection;
-import io.vertx.pgclient.SslMode;
+import io.vertx.pgclient.*;
 import io.vertx.pgclient.pubsub.PgSubscriber;
 import io.vertx.sqlclient.*;
 import io.vertx.sqlclient.data.Numeric;
@@ -515,6 +512,33 @@ public void ex10(Vertx vertx) {
     });
   }
 
+  public void sslNegotiationDirect(Vertx vertx) {
+    PgConnectOptions options = new PgConnectOptions()
+      .setPort(5432)
+      .setHost("the-host")
+      .setDatabase("the-db")
+      .setUser("user")
+      .setPassword("secret")
+      .setSslMode(SslMode.REQUIRE)
+      .setSslNegotiation(SslNegotiation.DIRECT)
+      .setSslOptions(new ClientSSLOptions()
+        .setTrustOptions(new PemTrustOptions().addCertPath("/path/to/server.crt")));
+
+    PgConnection.connect(vertx, options)
+      .onComplete(res -> {
+        if (res.succeeded()) {
+          System.out.println("Connected with direct SSL negotiation");
+        } else {
+          System.out.println("Could not connect: " + res.cause().getMessage());
+        }
+      });
+  }
+
+  public void sslNegotiationUri() {
+    String connectionUri = "postgresql://localhost/mydb?sslmode=require&sslnegotiation=direct";
+    PgConnectOptions options = PgConnectOptions.fromUri(connectionUri);
+  }
+
   public void jsonExample() {
 
     // Create a tuple

vertx-pg-client/src/main/java/io/vertx/pgclient/PgConnectOptions.java

@@ -1,18 +1,12 @@
 /*
- * Copyright (C) 2017 Julien Viet
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
  *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
  */
 
 package io.vertx.pgclient;
@@ -102,6 +96,9 @@ public static PgConnectOptions fromEnv() {
     if (getenv("PGSSLMODE") != null) {
       pgConnectOptions.setSslMode(SslMode.of(getenv("PGSSLMODE")));
     }
+    if (getenv("PGSSLNEGOTIATION") != null) {
+      pgConnectOptions.setSslNegotiation(SslNegotiation.of(getenv("PGSSLNEGOTIATION")));
+    }
     return pgConnectOptions;
   }
 
@@ -112,6 +109,7 @@ public static PgConnectOptions fromEnv() {
   public static final String DEFAULT_PASSWORD = "pass";
   public static final int DEFAULT_PIPELINING_LIMIT = 256;
   public static final SslMode DEFAULT_SSLMODE = SslMode.DISABLE;
+  public static final SslNegotiation DEFAULT_SSL_NEGOTIATION = SslNegotiation.POSTGRES;
   public static final boolean DEFAULT_USE_LAYER_7_PROXY = false;
   public static final Map<String, String> DEFAULT_PROPERTIES;
 
@@ -126,6 +124,7 @@ public static PgConnectOptions fromEnv() {
 
   private int pipeliningLimit = DEFAULT_PIPELINING_LIMIT;
   private SslMode sslMode = DEFAULT_SSLMODE;
+  private SslNegotiation sslNegotiation = DEFAULT_SSL_NEGOTIATION;
   private boolean useLayer7Proxy = DEFAULT_USE_LAYER_7_PROXY;
 
   public PgConnectOptions() {
@@ -143,13 +142,15 @@ public PgConnectOptions(SqlConnectOptions other) {
       PgConnectOptions opts = (PgConnectOptions) other;
       pipeliningLimit = opts.pipeliningLimit;
       sslMode = opts.sslMode;
+      sslNegotiation = opts.sslNegotiation;
     }
   }
 
   public PgConnectOptions(PgConnectOptions other) {
     super(other);
     pipeliningLimit = other.pipeliningLimit;
     sslMode = other.sslMode;
+    sslNegotiation = other.sslNegotiation;
   }
 
   @Override
@@ -239,6 +240,24 @@ public PgConnectOptions setSslMode(SslMode sslmode) {
     return this;
   }
 
+  /**
+   * @return the value of current SSL negotiation mode
+   */
+  public SslNegotiation getSslNegotiation() {
+    return sslNegotiation;
+  }
+
+  /**
+   * Set {@link SslNegotiation} for the client, this option controls how SSL/TLS is negotiated with the server.
+   *
+   * @param sslNegotiation the SSL negotiation mode
+   * @return a reference to this, so the API can be used fluently
+   */
+  public PgConnectOptions setSslNegotiation(SslNegotiation sslNegotiation) {
+    this.sslNegotiation = sslNegotiation;
+    return this;
+  }
+
   /**
    * @return whether the client interacts with a layer 7 proxy instead of a server
    */
@@ -322,6 +341,7 @@ public boolean equals(Object o) {
 
     if (pipeliningLimit != that.pipeliningLimit) return false;
     if (sslMode != that.sslMode) return false;
+    if (sslNegotiation != that.sslNegotiation) return false;
 
     return true;
   }
@@ -331,6 +351,7 @@ public int hashCode() {
     int result = super.hashCode();
     result = 31 * result + pipeliningLimit;
     result = 31 * result + sslMode.hashCode();
+    result = 31 * result + sslNegotiation.hashCode();
     return result;
   }
 

vertx-pg-client/src/main/java/io/vertx/pgclient/SslNegotiation.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+
+package io.vertx.pgclient;
+
+import io.vertx.codegen.annotations.VertxGen;
+
+/**
+ * SSL negotiation mode for PostgreSQL connections.
+ * <p>
+ * Determines how SSL/TLS is negotiated with the PostgreSQL server.
+ * This setting controls the negotiation protocol, while {@link SslMode}
+ * controls whether encryption is required.
+ *
+ * @see <a href="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLNEGOTIATION">PostgreSQL SSL Negotiation</a>
+ */
+@VertxGen
+public enum SslNegotiation {
+
+  /**
+   * Traditional PostgreSQL SSL negotiation (default).
+   * <p>
+   * The client sends an SSL request message and waits for the server's
+   * response before establishing the SSL connection. This mode works with
+   * all PostgreSQL versions.
+   */
+  POSTGRES("postgres"),
+
+  /**
+   * Direct SSL negotiation (PostgreSQL 17+).
+   * <p>
+   * The client establishes an SSL connection immediately without sending
+   * an SSL request message. This mode:
+   * <ul>
+   * <li>Reduces connection latency by one round-trip</li>
+   * <li>Enables standard SSL proxies (nginx, haproxy) to terminate TLS</li>
+   * <li>Supports SNI/ALPN protocol negotiation</li>
+   * </ul>
+   * <p>
+   * <b>Note:</b> Requires PostgreSQL 17 or later. Attempting to use this mode
+   * with earlier PostgreSQL versions will result in an SSL handshake failure.
+   */
+  DIRECT("direct");
+
+  public static final SslNegotiation[] VALUES = SslNegotiation.values();
+
+  public final String value;
+
+  SslNegotiation(String value) {
+    this.value = value;
+  }
+
+  /**
+   * Parse the SSL negotiation mode from a string value.
+   *
+   * @param value the string value (case-insensitive)
+   * @return the corresponding SSL negotiation mode
+   * @throws IllegalArgumentException if the value is not recognized
+   */
+  public static SslNegotiation of(String value) {
+    for (SslNegotiation sslNegotiation : VALUES) {
+      if (sslNegotiation.value.equalsIgnoreCase(value)) {
+        return sslNegotiation;
+      }
+    }
+
+    throw new IllegalArgumentException("Could not find an appropriate SSL negotiation mode for the value [" + value + "].");
+  }
+}