release: v1.4.5

Fixed: switching the active node now actually applies. POST /api/system/active-node
only wrote the active_node_id DB row — it never regenerated the xray config or
reloaded xray, so activating a node (a WireGuard chain especially) left traffic
exiting the PREVIOUS node while the UI showed the new one. It now regenerates,
re-applies nftables, and hot-reloads. Also fixed the runtime balancer override:
xray api bo passed the balancer tag positionally instead of via -b <tag>, so
every override was a silent no-op.

Added: seamless NodeCircle rotation. An enabled circle routes proxy traffic at a
per-circle xray balancer over all preloaded members; rotation hot-swaps the
selected node via the gRPC balancerOverride API — no xray restart, so live
connections finish on their current node and only new ones move. Manual
active-node switches into a circle pin the balancer the same way.

Added: node import UX — drag & drop into the upload box, WireGuard .conf (and
.ini) in the file picker, and a name-from-filename toggle for single-config
imports.

Notes: WireGuard remains exit-only in a chain — it can't carry transit as a relay
(re-verified live: a mid-chain WG forwards 0 bytes). No schema migration; Alembic
head unchanged. Backend suite 766 passing.

Author: DaveBugg

CHANGELOG.md

@@ -4,6 +4,39 @@ All notable user-facing changes to PiTun. Full per-release detail lives in the
 [GitHub Releases](https://github.com/DaveBugg/PiTun/releases); this file is the
 committed summary.
 
+## v1.4.5 — 2026-06-18
+
+Node-circle rotation that no longer drops connections, a fix so switching the
+active node (WireGuard chains especially) actually takes effect, and node-import
+quality-of-life (drag & drop, `.conf` files, name-from-filename).
+
+### Fixed
+
+- **Switching the active node now applies immediately.** `POST /api/system/active-node`
+  only wrote the DB row — it never regenerated the xray config or reloaded xray,
+  so activating a node (a WireGuard chain especially) left traffic exiting the
+  *previous* node while the UI showed the new one. It now regenerates + hot-reloads.
+- **Balancer override silently failed.** `xray api bo` was called with the balancer
+  tag positionally instead of via `-b <tag>` ("balancer tag not specified"), so
+  every runtime balancer override was a no-op.
+
+### Added
+
+- **Seamless NodeCircle rotation.** An enabled circle now routes proxy traffic at a
+  per-circle xray balancer over all preloaded members; rotation hot-swaps the
+  selected node via the gRPC `balancerOverride` API — no xray restart, so live
+  connections finish on their current node and only new ones move. Manual
+  active-node switches into a circle pin the balancer the same way.
+- **Node import UX.** The upload box now accepts **drag & drop**, the file picker
+  allows WireGuard `.conf` (and `.ini`), and a **"name from filename"** toggle names
+  a single-config import after the dropped file.
+
+### Notes
+
+- WireGuard can still only be a chain's **exit** hop — it can't carry transit as a
+  relay (verified again live: a mid-chain WG forwards 0 bytes). The circle balancer
+  preloads each member together with its stream relay, so WG-circle rotation works.
+
 ## v1.4.4 — 2026-06-16
 
 Multi-hop node chaining that actually wires every hop, a Route Explainer that

backend/app/api/nodes.py

@@ -419,6 +419,11 @@ async def import_nodes(
     from app.core.uri_parser import parse_uri_list
 
     parsed = parse_uri_list(body.uris)
+    # "Name from filename" (single-config file upload): override the parsed
+    # node's name only when exactly one node came through, so a multi-URI
+    # paste/subscription file never collapses every node to the same name.
+    if body.name_override and len(parsed) == 1:
+        parsed[0]["name"] = body.name_override
     imported = 0
     skipped = 0
     errors: List[str] = []

backend/app/api/system.py

@@ -538,14 +538,46 @@ async def set_mode(body: ModeUpdate, session: AsyncSession = Depends(get_session
     await session.commit()
 
 
+async def _pin_circle_balancer(session: AsyncSession, node_id: int) -> None:
+    """If `node_id` belongs to a running NodeCircle, pin that circle's xray
+    balancer to it via gRPC balancerOverride. The config routes circle proxy
+    traffic at a balancer over all members (cold-start strategy = random), so
+    after a (re)load we must override to the actually-selected node.
+    Best-effort — silently skipped if the API isn't up."""
+    try:
+        from app.core import xray_api
+        from app.core.config_gen import resolve_active_circle
+        from app.models import NodeCircle
+        circles = list((await session.exec(select(NodeCircle))).all())
+        cid, member_ids = resolve_active_circle(circles, node_id)
+        if cid and node_id in (member_ids or []) and await xray_api.is_api_available():
+            await xray_api.override_balancer(f"circle-{cid}", [f"node-{node_id}"])
+    except Exception as exc:
+        logging.getLogger(__name__).debug("pin circle balancer skipped: %s", exc)
+
+
 @router.post("/active-node", status_code=204)
 async def set_active_node(body: ActiveNodeUpdate, session: AsyncSession = Depends(get_session)):
+    from app.core.xray import xray_manager
+
     node = await session.get(Node, body.node_id)
     if not node:
         raise HTTPException(404, "Node not found")
     await _set_setting(session, "active_node_id", str(body.node_id))
     await session.commit()
 
+    # Switching the active node must actually APPLY it: regenerate the xray
+    # config (picks the new active outbound + wires its chain) and hot-reload.
+    # Without this the DB flips but xray keeps serving the PREVIOUS node — so
+    # activating a WireGuard chain left traffic exiting the old node and the
+    # real exit IP never changed, even though the UI showed the new node.
+    await _regenerate_and_write(session)
+    settings_map = await _load_settings_map(session)
+    await _apply_nftables(session, settings_map)
+    if xray_manager.is_running:
+        await xray_manager.reload()
+    await _pin_circle_balancer(session, body.node_id)
+
 
 # ── Settings ──────────────────────────────────────────────────────────────────
 
@@ -983,9 +1015,16 @@ async def _regenerate_and_write(session: AsyncSession, *, _self_heal_attempts: i
     dns_rules = list((await session.exec(select(DNSRule).where(DNSRule.enabled == True))).all())
     balancer_groups = list((await session.exec(select(BalancerGroup))).all())
     routing_sets, device_set_macs = await collect_routing_set_context(session)
+    from app.models import NodeCircle
+    from app.core.config_gen import resolve_active_circle
+    circles = list((await session.exec(select(NodeCircle))).all())
+    active_circle_id, active_circle_node_ids = resolve_active_circle(
+        circles, active_node.id if active_node else None
+    )
     config = generate_config(
         active_node, all_nodes, rules, mode, settings_map, dns_rules, balancer_groups,
         routing_sets=routing_sets, device_set_macs=device_set_macs,
+        active_circle_id=active_circle_id, active_circle_node_ids=active_circle_node_ids,
     )
 
     # On retry passes we skip pre-flight to avoid recursive cost — the

backend/app/config.py

@@ -5,7 +5,7 @@
 # OpenAPI metadata, `/health` response, and `/system/status` so the
 # frontend can display it next to the xray version. Bump this on each
 # release — frontend keeps its own version in `frontend/package.json`.
-APP_VERSION = "1.4.4"
+APP_VERSION = "1.4.5"
 
 
 class Settings(BaseSettings):

backend/app/core/circle_scheduler.py

@@ -399,57 +399,62 @@ async def _safe_event(**kwargs):
     async def _seamless_rotate(
         self, prev_node_id: int, next_node_id: int
     ) -> None:
+        new_tag = f"node-{next_node_id}"
         try:
             from app.core.xray import xray_manager
             if not xray_manager.is_running:
                 return
-
             from app.core import xray_api
-            from app.core.config_gen import _build_outbound, _stream_settings
-
-            if not await xray_api.is_api_available():
-                logger.warning("xray API not available, falling back to full restart")
-                await self._full_reload()
-                return
-
+            from app.core.config_gen import resolve_active_circle
+
+            # Resolve the circle the rotated node belongs to. When the live
+            # config routes that circle's proxy traffic at a balancer over all
+            # preloaded members, we can hot-swap the selected member with a
+            # single gRPC balancerOverride — xray picks the outbound per NEW
+            # connection, so existing connections keep their current member and
+            # finish naturally. Zero restart, zero outbound churn.
             async with AsyncSession(get_async_engine()) as session:
-                next_node = await session.get(Node, next_node_id)
-                if not next_node:
-                    logger.error("Node %d not found for seamless rotation", next_node_id)
-                    await self._full_reload()
-                    return
-                try:
-                    new_outbound = _build_outbound(next_node)
-                except Exception as exc:
-                    logger.error("Failed to build outbound for node %d: %s", next_node_id, exc)
-                    return
+                from app.models import NodeCircle
+                circles = list((await session.exec(select(NodeCircle))).all())
+                cid, member_ids = resolve_active_circle(circles, next_node_id)
 
-            new_tag = f"node-{next_node_id}"
-            old_tag = f"node-{prev_node_id}"
-
-            added = await xray_api.add_outbound(new_outbound)
-            if not added:
-                # `add_outbound` already retries on "existing tag found" via
-                # its idempotency path. Any other failure means the live xray
-                # doesn't know about the new outbound — writing config file
-                # alone would leave live state desynced. Fall back to a full
-                # reload so live xray and config file agree.
-                logger.warning(
-                    "Seamless rotation: add_outbound(%s) failed — falling back to full reload",
-                    new_tag,
+            in_balancer = bool(
+                cid and member_ids and next_node_id in member_ids
+            )
+            if in_balancer and await xray_api.is_api_available():
+                bal_tag = f"circle-{cid}"
+                if await xray_api.override_balancer(bal_tag, [new_tag]):
+                    await self._update_config_file()  # keep file's selector/active in sync
+                    logger.info(
+                        "Seamless rotation: balancerOverride %s → %s "
+                        "(live connections finish on their current node)",
+                        bal_tag, new_tag,
+                    )
+                    return
+                # Override missed — the balancer/members aren't loaded in the
+                # live xray yet (config predates this circle being active).
+                # Reload to materialize them, then pin the rotated node.
+                logger.info(
+                    "balancerOverride(%s) miss — reloading to materialize circle balancer",
+                    bal_tag,
                 )
                 await self._full_reload()
+                try:
+                    await xray_api.override_balancer(bal_tag, [new_tag])
+                except Exception:
+                    pass
                 return
 
-            await self._update_config_file()
-
-            logger.info(
-                "Seamless rotation: %s → %s (old connections finish naturally)",
-                old_tag, new_tag,
+            # No circle balancer (single-node active) or API down → the only
+            # way to apply is a full reload (restart, drops live connections).
+            logger.warning(
+                "Rotation to %s: no circle balancer / xray API unavailable — full reload",
+                new_tag,
             )
+            await self._full_reload()
 
         except Exception as exc:
-            logger.error("Seamless rotation failed, falling back to full restart: %s", exc)
+            logger.error("Seamless rotation failed, falling back to full reload: %s", exc)
             await self._full_reload()
 
     async def _update_config_file(self) -> None:
@@ -471,12 +476,16 @@ async def _update_config_file(self) -> None:
                 dns_rules = list((await session.exec(select(DNSRule).where(DNSRule.enabled == True))).all())
                 balancer_groups = list((await session.exec(select(BalancerGroup))).all())
                 mode = settings_map.get("mode", "rules")
-                from app.core.config_gen import collect_routing_set_context
+                from app.core.config_gen import collect_routing_set_context, resolve_active_circle
+                from app.models import NodeCircle
                 routing_sets, device_set_macs = await collect_routing_set_context(session)
+                circles = list((await session.exec(select(NodeCircle))).all())
+                acid, acids = resolve_active_circle(circles, active_node.id if active_node else None)
                 config = generate_config(
                     active_node, all_nodes, rules, mode, settings_map,
                     dns_rules, balancer_groups,
                     routing_sets=routing_sets, device_set_macs=device_set_macs,
+                    active_circle_id=acid, active_circle_node_ids=acids,
                 )
                 await write_config(config)
         except Exception as exc:

backend/app/core/config_gen.py

@@ -475,14 +475,27 @@ def _build_outbound(node: Node) -> Dict[str, Any]:
 ]
 
 
-def _routing_rule_to_xray(rule: RoutingRule, active_node_id: Optional[int]) -> Optional[Dict[str, Any]]:
-    """Convert a RoutingRule DB row to an xray routing rule dict."""
+def _routing_rule_to_xray(
+    rule: RoutingRule,
+    active_node_id: Optional[int],
+    active_balancer_tag: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Convert a RoutingRule DB row to an xray routing rule dict.
+
+    When `active_balancer_tag` is set (the active node belongs to a running
+    NodeCircle), `action == "proxy"` targets that balancer instead of a
+    single `node-<id>` outbound — so circle rotation can hot-swap the
+    selected node via the gRPC balancerOverride API without a restart.
+    """
     values = [v.strip() for v in rule.match_value.split(",") if v.strip()]
 
     xray_rule: Dict[str, Any] = {"type": "field"}
 
     if rule.action == "proxy":
-        xray_rule["outboundTag"] = f"node-{active_node_id}" if active_node_id else "direct"
+        if active_balancer_tag:
+            xray_rule["balancerTag"] = active_balancer_tag
+        else:
+            xray_rule["outboundTag"] = f"node-{active_node_id}" if active_node_id else "direct"
     elif rule.action == "direct":
         xray_rule["outboundTag"] = "direct"
     elif rule.action == "block":
@@ -760,6 +773,29 @@ def _build_tun_inbound(settings_map: Dict[str, str]) -> Dict[str, Any]:
     return inbound
 
 
+def resolve_active_circle(circles, active_node_id):
+    """Return (circle_id, member_node_ids) of the enabled NodeCircle that
+    contains `active_node_id`, else (None, None).
+
+    Callers pass the active circle into `generate_config` so the proxy
+    traffic routes via a per-circle balancer over all members — that's what
+    lets rotation hot-swap the selected node through the gRPC balancerOverride
+    API without restarting xray (live connections survive).
+    """
+    if not active_node_id:
+        return None, None
+    for c in circles or []:
+        if not getattr(c, "enabled", False):
+            continue
+        try:
+            ids = json.loads(c.node_ids) if isinstance(c.node_ids, str) else (c.node_ids or [])
+        except Exception:
+            ids = []
+        if active_node_id in ids:
+            return c.id, list(ids)
+    return None, None
+
+
 def generate_config(
     active_node: Optional[Node],
     all_nodes: List[Node],
@@ -770,6 +806,8 @@ def generate_config(
     balancer_groups: Optional[List[BalancerGroup]] = None,
     routing_sets: Optional[List[RoutingSet]] = None,
     device_set_macs: Optional[Dict[int, List[str]]] = None,
+    active_circle_id: Optional[int] = None,
+    active_circle_node_ids: Optional[List[int]] = None,
 ) -> Dict[str, Any]:
     """Build full xray JSON configuration.
 
@@ -984,6 +1022,32 @@ def generate_config(
         except Exception as exc:
             logger.error("Failed to build outbound for node %d: %s", active_node.id, exc)
 
+    # NodeCircle members: when the active node belongs to a running circle,
+    # preload EVERY member's outbound (+ its chain) and route proxy traffic at
+    # a balancer over them (built below). Rotation then hot-swaps the selected
+    # member via the gRPC balancerOverride API — no xray restart, so live
+    # connections survive (xray picks the outbound per-connection at dispatch).
+    circle_member_tags: List[str] = []
+    circle_active = bool(active_circle_id and active_circle_node_ids and active_node)
+    if circle_active:
+        for nid in active_circle_node_ids:
+            tag = f"node-{nid}"
+            if not any(o.get("tag") == tag for o in outbounds):
+                node = next((n for n in all_nodes if n.id == nid), None)
+                if node and node.enabled:
+                    try:
+                        ob = _build_outbound(node)
+                        _apply_chain(node, ob, outbounds, used_ids, all_nodes)
+                        outbounds.append(ob)
+                        used_ids.add(nid)
+                    except Exception as exc:
+                        logger.warning("Circle member node %d skip: %s", nid, exc)
+            if any(o.get("tag") == tag for o in outbounds):
+                circle_member_tags.append(tag)
+    active_balancer_tag = (
+        f"circle-{active_circle_id}" if (circle_active and circle_member_tags) else None
+    )
+
     # Additional nodes for "node:<id>" routing rules
     for node in all_nodes:
         if node.id not in used_ids and node.enabled:
@@ -1056,6 +1120,18 @@ def generate_config(
                     "strategy": {"type": bg.strategy},
                 })
 
+    # Active-NodeCircle balancer. Selector lists every preloaded member; the
+    # actually-selected member is pinned at runtime via balancerOverride (the
+    # apply path overrides to active_node on (re)load, the scheduler overrides
+    # to the next member on rotation). `random` is just a valid cold-start
+    # default before the first override lands.
+    if active_balancer_tag and circle_member_tags:
+        xray_balancers.append({
+            "tag": active_balancer_tag,
+            "selector": circle_member_tags,
+            "strategy": {"type": "random"},
+        })
+
     # Routing
     routing_rules: List[Dict[str, Any]] = [
         # Stats API: route api inbound to api outbound (internal)
@@ -1099,10 +1175,14 @@ def generate_config(
     elif mode == "global":
         if bypass_private:
             routing_rules.append({"type": "field", "ip": _PRIVATE_CIDRS, "outboundTag": "direct"})
+        _global_target = (
+            {"balancerTag": active_balancer_tag} if active_balancer_tag
+            else {"outboundTag": f"node-{active_node.id}" if active_node else "direct"}
+        )
         routing_rules.append({
             "type": "field",
             "ip": ["0.0.0.0/0", "::/0"],
-            "outboundTag": f"node-{active_node.id}" if active_node else "direct",
+            **_global_target,
         })
     else:
         # rules mode
@@ -1137,7 +1217,7 @@ def generate_config(
             for rule in sorted_rules:
                 if rule.routing_set_id != sid:
                     continue
-                xray_rule = _routing_rule_to_xray(rule, active_node_id)
+                xray_rule = _routing_rule_to_xray(rule, active_node_id, active_balancer_tag)
                 if xray_rule:
                     xray_rule["inboundTag"] = [tag]
                     routing_rules.append(xray_rule)
@@ -1148,7 +1228,7 @@ def generate_config(
         # (matched by inboundTag), then falls through to globals.
         for rule in sorted_rules:
             if rule.routing_set_id is None:
-                xray_rule = _routing_rule_to_xray(rule, active_node_id)
+                xray_rule = _routing_rule_to_xray(rule, active_node_id, active_balancer_tag)
                 if xray_rule:
                     routing_rules.append(xray_rule)