feat: restrict ICE port ranges and control candidate gathering behavior (#202)

* feat: implement PortAllocatorConfig for ICE candidate management

* test: add integration test for PortAllocatorConfig to verify ICE candidate behavior

* docs: add PortAllocatorConfig guide

Author: devopvoid

docs/_sidebar.md

@@ -21,6 +21,8 @@
         - [Custom Video Source](guide/custom_video_source.md)
     - Data
         - [Data Channels](guide/data_channels.md)
+    - Networking and ICE
+        - [Port Allocator Config](guide/port_allocator_config.md)
     - Monitoring and Debugging
         - [RTC Stats](guide/rtc_stats.md)
         - [Logging](guide/logging.md)

docs/guide/overview.md

@@ -31,6 +31,10 @@ This section provides detailed guides for various features of the webrtc-java li
 - [RTC Stats](guide/rtc_stats.md) - Monitoring connection quality and performance
 - [Logging](guide/logging.md) - Configuring and using the logging system
 
+## Networking and ICE
+
+- [Port Allocator Config](guide/port_allocator_config.md) - Restrict ICE port ranges and control candidate gathering behavior
+
 ## Additional Resources
 
 For a complete API reference, check the [JavaDoc](https://javadoc.io/doc/dev.onvoid.webrtc/webrtc-java/latest/index.html).

docs/guide/port_allocator_config.md

@@ -0,0 +1,105 @@
+# Port Allocator Configuration (ICE) <!-- {docsify-ignore-all} -->
+
+This guide explains how to configure the ICE port allocator using `dev.onvoid.webrtc.PortAllocatorConfig` and how to use it with `RTCConfiguration` when creating a peer connection.
+
+The Port Allocator controls:
+- The local ephemeral port range used for gathering ICE candidates (HOST, SRFLX, RELAY).
+- Transport behavior via bit flags that mirror native WebRTC PortAllocator flags (e.g., disable TCP candidates, enable IPv6, etc.).
+
+When you need to restrict the ports your application binds to (e.g., to satisfy firewall rules) or tweak which transport types are gathered, use `PortAllocatorConfig`.
+
+## API Overview
+
+`PortAllocatorConfig` exposes three fields:
+- `minPort` (int): Minimum UDP/TCP port to use for candidate gathering (inclusive). Set to 0 to leave unspecified.
+- `maxPort` (int): Maximum UDP/TCP port to use for candidate gathering (inclusive). Set to 0 to leave unspecified.
+- `flags` (int): Bitwise OR of allocator flags (default 0).
+
+Notes:
+- If both `minPort` and `maxPort` are set to non‑zero values, `minPort` must be less than or equal to `maxPort`.
+- A value of 0 for either `minPort` or `maxPort` means "not specified" and the native defaults are used.
+
+Convenience methods are provided to toggle specific behaviors and to combine flags:
+- `setFlag(int flag)`, `clearFlag(int flag)`, `isFlagEnabled(int flag)`
+- Boolean helpers like `setDisableTcp(boolean)`, `isTcpDisabled()`, etc.
+
+## Supported Flags
+
+The following flags mirror WebRTC's native PortAllocator flags. You can use them directly via `setFlag/clearFlag` or through the boolean helpers.
+
+- `PORTALLOCATOR_DISABLE_UDP` — Disable local UDP socket allocation for host candidates.
+- `PORTALLOCATOR_DISABLE_STUN` — Disable STUN candidate gathering (server reflexive).
+- `PORTALLOCATOR_DISABLE_RELAY` — Disable TURN relay candidate gathering.
+- `PORTALLOCATOR_DISABLE_TCP` — Disable local TCP candidate gathering.
+- `PORTALLOCATOR_ENABLE_IPV6` — Enable IPv6 support.
+- `PORTALLOCATOR_ENABLE_SHARED_SOCKET` — Enable shared UDP socket mode (platform/stack‑dependent behavior).
+- `PORTALLOCATOR_ENABLE_STUN_RETRANSMIT_ATTRIBUTE` — Include STUN retransmit attribute on requests.
+- `PORTALLOCATOR_DISABLE_ADAPTER_ENUMERATION` — Do not enumerate network adapters.
+- `PORTALLOCATOR_DISABLE_DEFAULT_LOCAL_CANDIDATE` — Do not generate a default local candidate.
+- `PORTALLOCATOR_DISABLE_UDP_RELAY` — Disable UDP TURN relay.
+- `PORTALLOCATOR_DISABLE_COSTLY_NETWORKS` — Avoid cellular/expensive networks for candidate gathering.
+- `PORTALLOCATOR_ENABLE_IPV6_ON_WIFI` — Allow IPv6 over Wi‑Fi.
+- `PORTALLOCATOR_ENABLE_ANY_ADDRESS_PORTS` — Allow binding to any‑address (0.0.0.0/::) ports.
+- `PORTALLOCATOR_DISABLE_LINK_LOCAL_NETWORKS` — Avoid link‑local network interfaces.
+
+## Basic Usage
+
+You configure the port allocator on the `RTCConfiguration` before creating the `RTCPeerConnection`.
+
+```java
+RTCConfiguration cfg = new RTCConfiguration();
+
+// Constrain ephemeral port range for HOST candidates
+cfg.portAllocatorConfig.minPort = 48000;
+cfg.portAllocatorConfig.maxPort = 48100;
+
+// Example: Disable TCP candidates, keep UDP enabled (default)
+cfg.portAllocatorConfig.setDisableTcp(true);
+
+// Optional: Enable IPv6 support
+// cfg.portAllocatorConfig.setEnableIpv6(true);
+
+RTCPeerConnection pc = factory.createPeerConnection(cfg, observer);
+```
+
+## Using Flags Directly
+
+You can combine flags using bitwise OR and set them at once:
+
+```java
+int flags = PortAllocatorConfig.PORTALLOCATOR_DISABLE_TCP
+        | PortAllocatorConfig.PORTALLOCATOR_DISABLE_RELAY
+        | PortAllocatorConfig.PORTALLOCATOR_ENABLE_IPV6;
+
+RTCConfiguration cfg = new RTCConfiguration();
+cfg.portAllocatorConfig.minPort = 50000;
+cfg.portAllocatorConfig.maxPort = 50100;
+cfg.portAllocatorConfig.flags = flags;
+
+RTCPeerConnection pc = factory.createPeerConnection(cfg, observer);
+```
+
+Or use the fluent helpers:
+
+```java
+cfg.portAllocatorConfig
+   .setDisableStun(true)
+   .setDisableRelay(true)
+   .setEnableSharedSocket(true);
+```
+
+## Tips and Troubleshooting
+
+- Port Range Validity: Ensure `minPort <= maxPort` when both are set. If either is 0, the native default behavior applies.
+- Firewalls/NATs: When running behind strict firewalls, restrict the host candidate port range to an allowed window and ensure your firewall allows outbound UDP for STUN/TURN as needed.
+- Disabling Candidates: Disabling STUN and RELAY will limit you to host candidates, which may prevent connectivity across NATs. Use with care.
+- TCP Candidates: Disabling TCP can speed up gathering and reduce unwanted candidates, but may reduce connectivity options in restrictive environments.
+- IPv6: Enabling IPv6 may improve connectivity on IPv6‑capable networks; consider also `setEnableIpv6OnWifi(true)` when applicable.
+
+## Related API
+
+- `RTCConfiguration` — holds `portAllocatorConfig` used by `PeerConnectionFactory#createPeerConnection`.
+- `RTCPeerConnection` — creating a peer connection triggers ICE gathering.
+- `RTCIceServer` — define STUN/TURN servers for non‑host candidates.
+
+For the full API, see the JavaDoc for `PortAllocatorConfig` and `RTCConfiguration`.

webrtc-jni/src/main/cpp/include/api/PortAllocatorConfig.h

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025 Alex Andres
+ *
+ * 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.
+ */
+
+#ifndef JNI_WEBRTC_API_PORT_ALLOCATOR_CONFIG_H_
+#define JNI_WEBRTC_API_PORT_ALLOCATOR_CONFIG_H_
+
+#include "JavaClass.h"
+#include "JavaRef.h"
+
+#include "api/peer_connection_interface.h"
+
+#include <jni.h>
+
+namespace jni
+{
+	namespace PortAllocatorConfig
+	{
+		class JavaPortAllocatorConfigClass : public JavaClass
+		{
+			public:
+				explicit JavaPortAllocatorConfigClass(JNIEnv * env);
+
+				jclass cls;
+				jmethodID ctor;
+				jfieldID minPort;
+				jfieldID maxPort;
+				jfieldID flags;
+		};
+
+		JavaLocalRef<jobject> toJava(JNIEnv * env, const webrtc::PeerConnectionInterface::PortAllocatorConfig & cfg);
+	}
+}
+
+#endif

webrtc-jni/src/main/cpp/include/api/RTCConfiguration.h

@@ -40,6 +40,7 @@ namespace jni
 				jfieldID bundlePolicy;
 				jfieldID rtcpMuxPolicy;
 				jfieldID certificates;
+				jfieldID portAllocatorConfig;
 		};
 
 		JavaLocalRef<jobject> toJava(JNIEnv * env, const webrtc::PeerConnectionInterface::RTCConfiguration & config);

webrtc-jni/src/main/cpp/src/api/PortAllocatorConfig.cpp

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2025 Alex Andres
+ *
+ * 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.
+ */
+
+#include "api/PortAllocatorConfig.h"
+#include "JavaClasses.h"
+#include "JavaObject.h"
+#include "JavaUtils.h"
+#include "JNI_WebRTC.h"
+
+namespace jni
+{
+	namespace PortAllocatorConfig
+	{
+		JavaLocalRef<jobject> toJava(JNIEnv * env, const webrtc::PeerConnectionInterface::PortAllocatorConfig & cfg)
+		{
+			const auto javaClass = JavaClasses::get<JavaPortAllocatorConfigClass>(env);
+
+			jobject jpac = env->NewObject(javaClass->cls, javaClass->ctor);
+
+			JavaObject obj(env, JavaLocalRef<jobject>(env, jpac));
+			obj.setInt(javaClass->minPort, cfg.min_port);
+			obj.setInt(javaClass->maxPort, cfg.max_port);
+			obj.setInt(javaClass->flags, cfg.flags);
+
+			return JavaLocalRef<jobject>(env, jpac);
+		}
+
+		JavaPortAllocatorConfigClass::JavaPortAllocatorConfigClass(JNIEnv * env)
+		{
+			cls = FindClass(env, PKG"PortAllocatorConfig");
+			ctor = GetMethod(env, cls, "<init>", "()V");
+			minPort = GetFieldID(env, cls, "minPort", "I");
+			maxPort = GetFieldID(env, cls, "maxPort", "I");
+			flags = GetFieldID(env, cls, "flags", "I");
+		}
+	}
+}

webrtc-jni/src/main/cpp/src/api/RTCConfiguration.cpp

@@ -16,6 +16,7 @@
 
 #include "api/RTCConfiguration.h"
 #include "api/RTCIceServer.h"
+#include "api/PortAllocatorConfig.h"
 #include "rtc/RTCCertificatePEM.h"
 #include "JavaArrayList.h"
 #include "JavaClasses.h"
@@ -56,6 +57,9 @@ namespace jni
 			env->SetObjectField(config, javaClass->rtcpMuxPolicy, rtcpMuxPolicy.get());
 			env->SetObjectField(config, javaClass->certificates, certificateList.listObject());
 
+			auto pac = jni::PortAllocatorConfig::toJava(env, nativeType.port_allocator_config);
+			env->SetObjectField(config, javaClass->portAllocatorConfig, pac.get());
+
 			return JavaLocalRef<jobject>(env, config);
 		}
 
@@ -70,6 +74,7 @@ namespace jni
 			JavaLocalRef<jobject> bp = obj.getObject(javaClass->bundlePolicy);
 			JavaLocalRef<jobject> mp = obj.getObject(javaClass->rtcpMuxPolicy);
 			JavaLocalRef<jobject> cr = obj.getObject(javaClass->certificates);
+			JavaLocalRef<jobject> pac = obj.getObject(javaClass->portAllocatorConfig);
 
 			webrtc::PeerConnectionInterface::RTCConfiguration configuration;
 
@@ -89,6 +94,15 @@ namespace jni
 				}
 			}
 
+			if (pac.get() != nullptr) {
+				const auto pacJavaClass = JavaClasses::get<PortAllocatorConfig::JavaPortAllocatorConfigClass>(env);
+				JavaObject pacObj(env, pac);
+
+				configuration.port_allocator_config.min_port = pacObj.getInt(pacJavaClass->minPort);
+				configuration.port_allocator_config.max_port = pacObj.getInt(pacJavaClass->maxPort);
+				configuration.port_allocator_config.flags = pacObj.getInt(pacJavaClass->flags);
+			}
+
 			return configuration;
 		}
 
@@ -103,6 +117,7 @@ namespace jni
 			bundlePolicy = GetFieldID(env, cls, "bundlePolicy", "L" PKG "RTCBundlePolicy;");
 			rtcpMuxPolicy = GetFieldID(env, cls, "rtcpMuxPolicy", "L" PKG "RTCRtcpMuxPolicy;");
 			certificates = GetFieldID(env, cls, "certificates", LIST_SIG);
+			portAllocatorConfig = GetFieldID(env, cls, "portAllocatorConfig", "L" PKG "PortAllocatorConfig;");
 		}
 	}
 }