RAV-2958 - Initial Proxy Protocol processing

.github/workflows/pull_requests.yml

@@ -0,0 +1,43 @@
+name: Pull Request
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and Test (Java ${{ matrix.java }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        java: [ '17', '21' ]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: maven
+
+      - name: Build and test
+        run: |
+          mvn -B -e --fail-at-end clean verify
+
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-reports-java-${{ matrix.java }}
+          path: |
+            ./**/target/surefire-reports/**
+            ./**/target/failsafe-reports/**

LICENSE.BSD-3-Clause

@@ -0,0 +1,27 @@
+Copyright (c) 2025, Semtech Corporation. 
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+* Neither the name of the Eclipse Foundation, Inc. nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,2 +1,62 @@
-# proxy-socket-java
-Java Library to handle ProxyProtocol v2 on standard java sockets
+# Proxy Socket Java (UDP + TCP, Java 17)
+
+## Overview
+
+Library providing HAProxy Proxy Protocol v2 support for UDP and TCP. Multi-module layout:
+
+- proxy-socket-core: zero dependencies, parser, models, interfaces
+- proxy-socket-udp: DatagramSocket wrapper
+- proxy-socket-tcp: ServerSocket/Socket wrappers
+- proxy-socket-guava: optional Guava-based cache
+- proxy-socket-examples: runnable samples
+
+Reference: [HAProxy Proxy Protocol Specifications](https://www.haproxy.org/download/3.3/doc/proxy-protocol.txt)
+
+## Quick start (UDP)
+
+```java
+var socket = new net.airvantage.proxysocket.udp.ProxyDatagramSocket.Builder()
+    .maxEntries(10_000)
+    .ttl(java.time.Duration.ofMinutes(5))
+    .metrics(new MyMetrics())
+    .build();
+socket.bind(new java.net.InetSocketAddress(9999));
+var buf = new byte[2048];
+var packet = new java.net.DatagramPacket(buf, buf.length);
+socket.receive(packet); // header stripped, source set to real client
+socket.send(packet);    // destination rewritten to LB if cached
+```
+
+## Quick start (TCP)
+
+```java
+try (var server = new net.airvantage.proxysocket.tcp.ProxyServerSocket(9998)) {
+  for (;;) {
+    var s = (net.airvantage.proxysocket.tcp.ProxySocket) server.accept();
+    var header = s.getHeader();
+    // header.getSourceAddress() is the real client address
+  }
+}
+```
+
+## License
+
+MIT License © 2025 Semtech. See `LICENSE`.
+
+## Metrics hook
+
+Implement `net.airvantage.proxysocket.core.ProxySocketMetricsListener` and pass it via UDP builder or TCP server ctor.
+
+## Thread safety
+
+- UDP/TCP wrappers follow JDK `DatagramSocket`/`ServerSocket`/`Socket` thread-safety; caches and listeners must be thread-safe.
+- Core parser is stateless and thread-safe.
+
+## Configuration
+
+- UDP cache defaults: 10k entries, 5 min TTL if Guava present; otherwise concurrent map (no TTL).
+- TCP: blocking header read on accept with configurable timeout.
+
+## Examples
+
+See `proxy-socket-examples` module: `UdpEchoWithProxyProtocol`, `TcpEchoWithProxyProtocol`.

pom.xml

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>net.airvantage</groupId>
+    <artifactId>proxysocket-java</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+
+    <description>ProxyProtocol Java implementation.</description>
+
+    <properties>
+
+        <!-- Dependency versions -->
+        <junit.version>5.10.3</junit.version>
+
+    </properties>
+
+    <modules>
+        <module>proxy-socket-core</module>
+    </modules>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.11.0</version>
+                <configuration>
+                    <encoding>UTF-8</encoding>
+                    <release>17</release>
+                </configuration>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.2.5</version>
+                <configuration>
+                    <useModulePath>false</useModulePath>
+                </configuration>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <version>3.3.1</version>
+                <configuration>
+                    <encoding>UTF-8</encoding>
+                </configuration>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-eclipse-plugin</artifactId>
+                <version>2.10</version>
+                <configuration>
+                    <downloadSources>true</downloadSources>
+                    <downloadJavadocs>true</downloadJavadocs>
+                </configuration>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>3.3.0</version>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
+        </plugins>
+    </build>
+</project>

proxy-socket-core/pom.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>net.airvantage</groupId>
+        <artifactId>proxysocket-java</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>proxy-socket-core</artifactId>
+    <name>Proxy Protocol - Core</name>
+    <packaging>jar</packaging>
+
+    <properties>
+        <maven.compiler.release>17</maven.compiler.release>
+    </properties>
+
+    <dependencies>
+        <!-- Core must have zero required dependencies -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${junit.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <!-- AWS ProProt library for test validation against known encoder -->
+        <dependency>
+            <groupId>com.amazonaws.proprot</groupId>
+            <artifactId>proprot</artifactId>
+            <version>1.0</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+</project>
+
+

proxy-socket-core/src/main/java/net/airvantage/proxysocket/core/ProxyAddressCache.java

@@ -0,0 +1,17 @@
+/**
+ * BSD-3-Clause License.
+ * Copyright (c) 2025 Semtech
+ */
+package net.airvantage.proxysocket.core;
+
+import java.net.InetSocketAddress;
+
+/**
+ * Thread-safe cache abstraction mapping real client addresses to proxy/load-balancer addresses.
+ */
+public interface ProxyAddressCache {
+    void put(InetSocketAddress clientAddr, InetSocketAddress proxyAddr);
+    InetSocketAddress get(InetSocketAddress clientAddr);
+    void invalidate(InetSocketAddress clientAddr);
+    void clear();
+}

proxy-socket-core/src/main/java/net/airvantage/proxysocket/core/ProxyProtocolException.java

@@ -0,0 +1,16 @@
+/**
+ * BSD-3-Clause License.
+ * Copyright (c) 2025 Semtech
+ */
+package net.airvantage.proxysocket.core;
+
+public class ProxyProtocolException extends Exception {
+    private static final long serialVersionUID = 1L;
+
+    public ProxyProtocolException(String message) {
+        super(message);
+    }
+    public ProxyProtocolException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

proxy-socket-core/src/main/java/net/airvantage/proxysocket/core/ProxyProtocolMetricsListener.java

@@ -0,0 +1,19 @@
+/**
+ * BSD-3-Clause License.
+ * Copyright (c) 2025 Semtech
+ */
+package net.airvantage.proxysocket.core;
+
+import net.airvantage.proxysocket.core.v2.ProxyHeader;
+import java.net.InetSocketAddress;
+
+/**
+ * Metrics/observability callbacks for Proxy Protocol processing.
+ * Implementations must be thread-safe.
+ */
+public interface ProxyProtocolMetricsListener {
+    default void onHeaderParsed(ProxyHeader header) {}
+    default void onParseError(Exception e) {}
+    default void onCacheHit(InetSocketAddress client) {}
+    default void onCacheMiss(InetSocketAddress client) {}
+}

proxy-socket-core/src/main/java/net/airvantage/proxysocket/core/ProxyProtocolParseException.java

@@ -0,0 +1,16 @@
+/**
+ * BSD-3-Clause License.
+ * Copyright (c) 2025 Semtech
+ */
+package net.airvantage.proxysocket.core;
+
+public final class ProxyProtocolParseException extends ProxyProtocolException {
+    private static final long serialVersionUID = 1L;
+
+    public ProxyProtocolParseException(String message) {
+        super(message);
+    }
+    public ProxyProtocolParseException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

proxy-socket-core/src/main/java/net/airvantage/proxysocket/core/cache/ConcurrentMapProxyAddressCache.java

@@ -0,0 +1,37 @@
+/**
+ * BSD-3-Clause License.
+ * Copyright (c) 2025 Semtech
+ */
+package net.airvantage.proxysocket.core.cache;
+
+import net.airvantage.proxysocket.core.ProxyAddressCache;
+import java.net.InetSocketAddress;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+
+/**
+ * Simple thread-safe cache backed by {@link ConcurrentHashMap}.
+ */
+public final class ConcurrentMapProxyAddressCache implements ProxyAddressCache {
+    private final ConcurrentMap<InetSocketAddress, InetSocketAddress> map = new ConcurrentHashMap<>();
+
+    @Override
+    public void put(InetSocketAddress clientAddr, InetSocketAddress proxyAddr) {
+        map.put(clientAddr, proxyAddr);
+    }
+
+    @Override
+    public InetSocketAddress get(InetSocketAddress clientAddr) {
+        return map.get(clientAddr);
+    }
+
+    @Override
+    public void invalidate(InetSocketAddress clientAddr) {
+        map.remove(clientAddr);
+    }
+
+    @Override
+    public void clear() {
+        map.clear();
+    }
+}