Add support for HA Proxy Protocol TLV's

damianorenfer · damianorenfer · commit 87477f44d9ee · 2026-02-13T16:58:46.000+01:00
TLV's are supported in netty, but currently not accessible to vert.x
users.
Here the TLV's are exposed in `NetSocket#tlvs`
diff --git a/vertx-core/src/main/java/io/vertx/core/http/HttpConnection.java b/vertx-core/src/main/java/io/vertx/core/http/HttpConnection.java
@@ -16,6 +16,7 @@
 import io.vertx.core.Handler;
 import io.vertx.core.buffer.Buffer;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 
 import javax.net.ssl.SSLPeerUnverifiedException;
 import javax.net.ssl.SSLSession;
@@ -298,4 +299,10 @@ default List<Certificate> peerCertificates() throws SSLPeerUnverifiedException {
    */
   String indicatedServerName();
 
+  /**
+   * @return the type-length-values present in the TCP header, mainly used for HA Proxy Protocol v2
+   */
+  @GenIgnore()
+  List<TLV> tlvs();
+
 }
diff --git a/vertx-core/src/main/java/io/vertx/core/http/impl/HttpNetSocket.java b/vertx-core/src/main/java/io/vertx/core/http/impl/HttpNetSocket.java
@@ -21,11 +21,13 @@
 import io.vertx.core.net.NetSocket;
 import io.vertx.core.net.SSLOptions;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 import io.vertx.core.streams.ReadStream;
 import io.vertx.core.streams.WriteStream;
 
 import javax.net.ssl.SSLSession;
 import java.time.Duration;
+import java.util.List;
 
 /**
  * @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
@@ -229,6 +231,11 @@ public SocketAddress localAddress(boolean real) {
     return stream.connection().localAddress(real);
   }
 
+  @Override
+  public List<TLV> tlvs() {
+    return stream.connection().tlvs();
+  }
+
   @Override
   public Future<Void> close() {
     return end();
diff --git a/vertx-core/src/main/java/io/vertx/core/http/impl/UnpooledHttpClientConnection.java b/vertx-core/src/main/java/io/vertx/core/http/impl/UnpooledHttpClientConnection.java
@@ -21,12 +21,13 @@
 import io.vertx.core.internal.ContextInternal;
 import io.vertx.core.internal.PromiseInternal;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 
 import javax.net.ssl.SSLSession;
 import java.time.Duration;
 import java.util.ArrayDeque;
 import java.util.Deque;
-import java.util.concurrent.TimeUnit;
+import java.util.List;
 
 /**
  * An un-pooled HTTP client connection that maintains a queue for pending requests that cannot be served
@@ -207,6 +208,11 @@ public String indicatedServerName() {
     return actual.indicatedServerName();
   }
 
+  @Override
+  public List<TLV> tlvs() {
+    return actual.tlvs();
+  }
+
   /**
    * Create an HTTP stream.
    *
diff --git a/vertx-core/src/main/java/io/vertx/core/http/impl/http3/Http3Connection.java b/vertx-core/src/main/java/io/vertx/core/http/impl/http3/Http3Connection.java
@@ -26,6 +26,7 @@
 import io.vertx.core.internal.quic.QuicConnectionInternal;
 import io.vertx.core.internal.quic.QuicStreamInternal;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 
 import javax.net.ssl.SSLSession;
 import java.time.Duration;
@@ -332,4 +333,9 @@ public HttpConnection pingHandler(@Nullable Handler<Buffer> handler) {
   public HttpConnection exceptionHandler(Handler<Throwable> handler) {
     return this;
   }
+
+  @Override
+  public List<TLV> tlvs() {
+    return connection.tlvs();
+  }
 }
diff --git a/vertx-core/src/main/java/io/vertx/core/http/impl/tcp/Http2UpgradeClientConnection.java b/vertx-core/src/main/java/io/vertx/core/http/impl/tcp/Http2UpgradeClientConnection.java
@@ -33,11 +33,13 @@
 import io.vertx.core.internal.logging.LoggerFactory;
 import io.vertx.core.net.HostAndPort;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 import io.vertx.core.spi.metrics.ClientMetrics;
-import io.vertx.core.spi.metrics.HttpClientMetrics;
+
 
 import javax.net.ssl.SSLSession;
 import java.time.Duration;
+import java.util.List;
 
 /**
  * A connection that attempts to perform a protocol upgrade to H2C. The connection might use HTTP/1 or H2C
@@ -901,6 +903,11 @@ public String indicatedServerName() {
     return current.indicatedServerName();
   }
 
+  @Override
+  public List<TLV> tlvs() {
+    return current.tlvs();
+  }
+
   @Override
   public String toString() {
     return getClass().getSimpleName() + "[current=" + current.getClass().getSimpleName() + "]";
diff --git a/vertx-core/src/main/java/io/vertx/core/net/NetSocket.java b/vertx-core/src/main/java/io/vertx/core/net/NetSocket.java
@@ -316,5 +316,11 @@ default List<Certificate> peerCertificates() throws SSLPeerUnverifiedException {
    */
   String applicationLayerProtocol();
 
+  /**
+   * @return the type-length-values present in the TCP header, mainly used for HA Proxy Protocol v2
+   */
+  @GenIgnore()
+  List<TLV> tlvs();
+
 }
 
diff --git a/vertx-core/src/main/java/io/vertx/core/net/QuicConnection.java b/vertx-core/src/main/java/io/vertx/core/net/QuicConnection.java
@@ -18,6 +18,7 @@
 
 import javax.net.ssl.SSLSession;
 import java.time.Duration;
+import java.util.List;
 
 /**
  * <p>A Quic connection between a client and a server, providing support for handling or creating Quic {@link QuicStream streams}</p>
@@ -176,4 +177,10 @@ default Future<Void> shutdown(Duration timeout) {
    */
   SocketAddress localAddress();
 
+  /**
+   * @return the type-length-values present in the TCP header, mainly used for HA Proxy Protocol v2
+   */
+  @GenIgnore()
+  List<TLV> tlvs();
+
 }
diff --git a/vertx-core/src/main/java/io/vertx/core/net/TLV.java b/vertx-core/src/main/java/io/vertx/core/net/TLV.java
@@ -0,0 +1,19 @@
+/*
+ * 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.core.net;
+
+import io.vertx.core.buffer.Buffer;
+
+public interface TLV {
+  Buffer type();
+
+  Buffer value();
+}
diff --git a/vertx-core/src/main/java/io/vertx/core/net/impl/ConnectionBase.java b/vertx-core/src/main/java/io/vertx/core/net/impl/ConnectionBase.java
@@ -27,11 +27,13 @@
 import io.vertx.core.internal.net.NetSocketInternal;
 import io.vertx.core.internal.net.SslHandshakeCompletionHandler;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 import io.vertx.core.spi.metrics.NetworkMetrics;
 import io.vertx.core.spi.metrics.TransportMetrics;
 
 import javax.net.ssl.SSLSession;
 import java.net.InetSocketAddress;
+import java.util.List;
 
 /**
  * Abstract base class for connections managed by a vertx instance. This base implementation does not handle
@@ -53,6 +55,7 @@ public abstract class ConnectionBase {
   public static final VertxException CLOSED_EXCEPTION = NetSocketInternal.CLOSED_EXCEPTION;
   public static final AttributeKey<SocketAddress> REMOTE_ADDRESS_OVERRIDE = AttributeKey.valueOf("RemoteAddressOverride");
   public static final AttributeKey<SocketAddress> LOCAL_ADDRESS_OVERRIDE = AttributeKey.valueOf("LocalAddressOverride");
+  public static final AttributeKey<List<TLV>> TLVS = AttributeKey.valueOf("TLVS");
   private static final Logger log = LoggerFactory.getLogger(ConnectionBase.class);
 
   protected final VertxInternal vertx;
@@ -426,4 +429,8 @@ public SocketAddress localAddress(boolean real) {
     }
   }
 
+  public List<TLV> tlvs() {
+    return channel.hasAttr(TLVS) ? channel.attr(TLVS).getAndSet(null) : null;
+  }
+
 }
diff --git a/vertx-core/src/main/java/io/vertx/core/net/impl/HAProxyMessageCompletionHandler.java b/vertx-core/src/main/java/io/vertx/core/net/impl/HAProxyMessageCompletionHandler.java
@@ -11,9 +11,12 @@
 import io.vertx.core.internal.logging.Logger;
 import io.vertx.core.internal.logging.LoggerFactory;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 
 import java.io.IOException;
 import java.util.List;
+import java.util.Objects;
+import java.util.stream.Collectors;
 
 public class HAProxyMessageCompletionHandler extends MessageToMessageDecoder<HAProxyMessage> {
   //Public because its used in tests
@@ -71,6 +74,11 @@ protected void decode(ChannelHandlerContext ctx, HAProxyMessage msg, List<Object
           ctx.channel().attr(ConnectionBase.LOCAL_ADDRESS_OVERRIDE)
             .set(createAddress(protocol, msg.destinationAddress(), msg.destinationPort()));
         }
+
+        if (msg.tlvs() != null) {
+          ctx.channel().attr(ConnectionBase.TLVS)
+            .set(createTLVs(msg.tlvs()));
+        }
       }
       ctx.pipeline().remove(this);
       promise.setSuccess(ctx.channel());
@@ -103,4 +111,11 @@ private SocketAddress createAddress(HAProxyProxiedProtocol protocol, String sour
         throw new IllegalStateException("Should never happen");
     }
   }
+
+  private List<TLV> createTLVs(List<io.netty.handler.codec.haproxy.HAProxyTLV> haProxyTLVs) {
+    return haProxyTLVs.stream()
+      .filter(Objects::nonNull)
+      .map(HAProxyTLV::from)
+      .collect(Collectors.toList());
+  }
 }
diff --git a/vertx-core/src/main/java/io/vertx/core/net/impl/HAProxyTLV.java b/vertx-core/src/main/java/io/vertx/core/net/impl/HAProxyTLV.java
@@ -0,0 +1,42 @@
+/*
+ * 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.core.net.impl;
+
+import io.netty.buffer.ByteBufUtil;
+import io.vertx.core.buffer.Buffer;
+import io.vertx.core.net.TLV;
+
+public class HAProxyTLV implements TLV {
+
+  private final Buffer type;
+  private final Buffer value;
+
+  public HAProxyTLV(Buffer type, Buffer value) {
+    this.type = type;
+    this.value = value;
+  }
+
+  public static TLV from(io.netty.handler.codec.haproxy.HAProxyTLV haProxyTLV) {
+    Buffer type = Buffer.buffer().appendByte(haProxyTLV.typeByteValue());
+    Buffer value = Buffer.buffer(ByteBufUtil.getBytes(haProxyTLV.content()));
+    return new HAProxyTLV(type, value);
+  }
+
+  @Override
+  public Buffer type() {
+    return type;
+  }
+
+  @Override
+  public Buffer value() {
+    return value;
+  }
+}
diff --git a/vertx-core/src/test/java/io/vertx/test/proxy/HAProxy.java b/vertx-core/src/test/java/io/vertx/test/proxy/HAProxy.java
@@ -8,6 +8,7 @@
 
 import java.net.InetAddress;
 import java.nio.charset.StandardCharsets;
+import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
 import java.util.stream.Stream;
@@ -172,7 +173,7 @@ private static Buffer createIPv4IPv6ProtocolHeader(byte protocolByte, SocketAddr
 
 
   private static Buffer createVersion2ProtocolHeader(byte protocolByte, Buffer address) {
-    byte[] header = new byte[15];
+    byte[] header = new byte[14];
     header[0] = 0x0D;        // Binary Prefix
     header[1] = 0x0A;        // -----
     header[2] = 0x0D;        // -----
@@ -189,10 +190,16 @@ private static Buffer createVersion2ProtocolHeader(byte protocolByte, Buffer add
     header[12] = 0x21;        // v2, cmd=PROXY
     header[13] = protocolByte;
 
-    header[14] = 0x00;        // Remaining Bytes
+
+    UUID uuid = UUID.fromString("1f29a3b5-7cc4-4592-a8f1-879ff1f47124");
+    Buffer uniqueIdTLVBuffer = Buffer.buffer().appendByte((byte) 0x05); // PP2_TYPE_UNIQUE_ID
+    uniqueIdTLVBuffer.appendUnsignedShort(Long.BYTES*2);              // UUID length
+    uniqueIdTLVBuffer.appendLong(uuid.getMostSignificantBits());        // UUID value
+    uniqueIdTLVBuffer.appendLong(uuid.getLeastSignificantBits());
 
     return Buffer.buffer(header)
-      .appendByte((byte) address.length())
-      .appendBuffer(address);
+      .appendUnsignedShort(address.length() + uniqueIdTLVBuffer.length())
+      .appendBuffer(address)
+      .appendBuffer(uniqueIdTLVBuffer);
   }
 }
diff --git a/vertx-core/src/test/java/io/vertx/tests/http/HAProxyTest.java b/vertx-core/src/test/java/io/vertx/tests/http/HAProxyTest.java
@@ -15,13 +15,18 @@
 import io.vertx.core.http.HttpMethod;
 import io.vertx.core.http.RequestOptions;
 import io.vertx.core.net.SocketAddress;
+import io.vertx.core.net.TLV;
 import io.vertx.core.net.impl.HAProxyMessageCompletionHandler;
 import io.vertx.test.http.HttpTestBase;
 import io.vertx.test.proxy.HAProxy;
 import org.junit.Test;
 
+import java.util.List;
+import java.util.UUID;
 import java.util.concurrent.TimeUnit;
 
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.Matchers.hasSize;
 import static org.junit.Assume.assumeTrue;
 
 public abstract class HAProxyTest extends HttpTestBase {
@@ -158,6 +163,7 @@ private void testHAProxyProtocolAccepted(Buffer header, SocketAddress remote, So
             proxy.getConnectionRemoteAddress() :
             local,
           req.localAddress());
+        assertUniqueIdTLV(header, req.connection().tlvs());
         req.response().end();
         complete();
       });
@@ -277,4 +283,19 @@ private void assertAddresses(SocketAddress address1, SocketAddress address2) {
       assertEquals(address1.port(), address2.port());
     }
   }
+
+  private void assertUniqueIdTLV(Buffer header, List<TLV> tlvs) {
+    // only supported for v2 header and protocol family != unknown
+    if (header.length() < 12 || header.getByte(12) != 0x21 || header.getByte(13) == 0x00) {
+      return;
+    }
+
+    assertThat(tlvs, hasSize(1));
+
+    TLV uniqueIdTLV = tlvs.get(0);
+    assertThat(uniqueIdTLV.type().getByte(0), equalTo((byte)0x05));
+
+    UUID uuid = new UUID(uniqueIdTLV.value().getLong(0), uniqueIdTLV.value().getLong(Long.BYTES));
+    assertThat(uuid, equalTo(UUID.fromString("1f29a3b5-7cc4-4592-a8f1-879ff1f47124")));
+  }
 }
