feat(wireguard): add shared IP allocator for bulk user creation

- Add `build_wireguard_peer_ip_allocator()` to create a stateful allocator pre-loaded with used networks
- Add `prepare_wireguard_proxy_settings_with_allocator()` to allocate IPs against a shared allocator
- Add `is_reserved()`, `conflicts()`, and `reserve()` methods to WireGuardPeerIPAllocator for IP validation and blocking
- Add `get_wireguard_tags_from_groups()` import to detect WireGuard groups
- Update bulk user creation to use shared allocator when WireGuard is enabled, preventing duplicate IP allocation race conditions
- Import `wireguard_settings` and new utility functions in user operation module
- Validates user-supplied peer IPs and raises descriptive errors for reserved or conflicting addresses

Author: x0sina

app/operation/user.py

@@ -94,11 +94,14 @@
 from app.utils.jwt import create_subscription_token
 from app.utils.logger import get_logger
 from app.utils.wireguard import (
+    build_wireguard_peer_ip_allocator,
     bulk_reallocate_wireguard_peer_ips as run_bulk_reallocate_wireguard_peer_ips,
+    get_wireguard_tags_from_groups,
     prepare_wireguard_keys_only,
     prepare_wireguard_proxy_settings,
+    prepare_wireguard_proxy_settings_with_allocator,
 )
-from config import subscription_env_settings
+from config import subscription_env_settings, wireguard_settings
 
 logger = get_logger("user-operation")
 
@@ -237,12 +240,26 @@ async def _persist_bulk_users(
         if not users_to_create:
             return []
 
-        for user_to_create in users_to_create:
-            user_to_create.proxy_settings = await self._prepare_user_proxy_settings(
-                db,
-                groups,
-                user_to_create.proxy_settings,
-            )
+        wireguard_tags = await get_wireguard_tags_from_groups(groups)
+        use_shared_allocator = bool(wireguard_tags) and wireguard_settings.enabled
+
+        if use_shared_allocator:
+            allocator = await build_wireguard_peer_ip_allocator(db)
+            for user_to_create in users_to_create:
+                try:
+                    user_to_create.proxy_settings = prepare_wireguard_proxy_settings_with_allocator(
+                        user_to_create.proxy_settings,
+                        allocator,
+                    )
+                except ValueError as exc:
+                    await self.raise_error(message=str(exc), code=400, db=db)
+        else:
+            for user_to_create in users_to_create:
+                user_to_create.proxy_settings = await self._prepare_user_proxy_settings(
+                    db,
+                    groups,
+                    user_to_create.proxy_settings,
+                )
 
         db_users = await create_users_bulk(db, users_to_create, groups, db_admin)
 

app/utils/ip_pool.py

@@ -210,6 +210,39 @@ def allocate(self) -> str | None:
             return f"{ip_address(raw_candidate)}/32"
         return None
 
+    def is_reserved(self, peer_ip: str) -> bool:
+        """Whether the given IP/network falls inside the WireGuard reserved ranges."""
+        try:
+            candidate = ip_network(peer_ip, strict=False)
+        except ValueError:
+            return False
+        candidate_ip = ip_address(candidate.network_address)
+        return any(candidate_ip in net for net in WIREGUARD_RESERVED)
+
+    def conflicts(self, peer_ip: str) -> bool:
+        """Whether the given IP/network overlaps already-blocked addresses (used or reserved)."""
+        try:
+            candidate = ip_network(peer_ip, strict=False)
+        except ValueError:
+            return False
+        if candidate.version != 4:
+            return False
+        for addr in candidate:
+            if int(addr) in self._blocked:
+                return True
+        return False
+
+    def reserve(self, peer_ip: str) -> None:
+        """Mark every address in the given IPv4 network as blocked so future allocations skip it."""
+        try:
+            candidate = ip_network(peer_ip, strict=False)
+        except ValueError:
+            return
+        if candidate.version != 4:
+            return
+        for addr in candidate:
+            self._blocked.add(int(addr))
+
 
 async def allocate_from_global_pool(
     db: AsyncSession,

app/utils/wireguard.py

@@ -17,7 +17,9 @@
     WireGuardPeerIPAllocator,
     allocate_and_validate_peer_ips,
     collect_used_peer_networks_from_proxy_settings_rows,
+    get_global_used_networks,
     peer_ips_outside_global_pool,
+    validate_peer_ips_within_global_pool,
 )
 from config import wireguard_settings
 
@@ -141,6 +143,57 @@ async def prepare_wireguard_proxy_settings(
     return proxy_settings
 
 
+async def build_wireguard_peer_ip_allocator(
+    db: AsyncSession,
+    *,
+    exclude_user_id: int | None = None,
+) -> "WireGuardPeerIPAllocator":
+    """Build a stateful peer-IP allocator pre-loaded with all currently used peer networks.
+
+    Used by bulk-creation flows where many users need IPs allocated within a single
+    transaction; reusing one allocator avoids the duplicate-allocation bug that occurs
+    when each user independently re-reads the database before any of the new users have
+    been committed.
+    """
+    used_networks = await get_global_used_networks(db, exclude_user_id=exclude_user_id)
+    return WireGuardPeerIPAllocator(used_networks)
+
+
+def prepare_wireguard_proxy_settings_with_allocator(
+    proxy_settings: ProxyTable,
+    allocator: "WireGuardPeerIPAllocator",
+) -> ProxyTable:
+    """Prepare WireGuard settings for a single user against a shared allocator.
+
+    Caller is responsible for confirming the user belongs to a WireGuard group and that
+    `wireguard_settings.enabled` is true. Validates any user-supplied peer_ips against
+    the allocator's current blocked set, then either reserves them or allocates a fresh
+    IP. The allocator is mutated to reflect the new reservation.
+    """
+    prepare_wireguard_keys_for_member(proxy_settings)
+
+    peer_ips = list(proxy_settings.wireguard.peer_ips or [])
+
+    if peer_ips:
+        validate_peer_ips_within_global_pool(peer_ips)
+        for peer_ip in peer_ips:
+            if allocator.is_reserved(peer_ip):
+                raise ValueError(f"peer IP '{peer_ip}' is reserved")
+            if allocator.conflicts(peer_ip):
+                raise ValueError(
+                    f"peer IP/network '{peer_ip}' is already in use by an existing user's peer network"
+                )
+            allocator.reserve(peer_ip)
+        proxy_settings.wireguard.peer_ips = peer_ips
+        return proxy_settings
+
+    candidate = allocator.allocate()
+    if candidate is None:
+        raise ValueError("unable to allocate wireguard peer IP")
+    proxy_settings.wireguard.peer_ips = [candidate]
+    return proxy_settings
+
+
 async def prepare_wireguard_keys_only(
     db: AsyncSession,
     proxy_settings: ProxyTable,