release: 1.3.3 — pagination, host network UI, TUN footgun fix, bulk-action guards

Nodes pagination + filtering (the headline)
- GET /api/nodes/page paginated endpoint with filters
  (subscription_id, local, protocol, enabled, online, group, search)
  and direction (asc/desc, default desc = newest IDs first).
  Returns { items, total, limit, offset } envelope. Legacy
  GET /api/nodes stays for reorder / export / circle-scheduler
  callers that need the unbounded set.
- Frontend Nodes page rewritten: NodeFilterPopup component
  (Source / Protocol / Status / Group axes), Pagination component
  (10/50/100 page sizes persisted to localStorage, sparse page
  strip with ellipsis), sort-direction toggle. Drag-to-reorder
  re-gated: works on visible subset ≤100 regardless of filters
  (was tied to global total, blocked drag on any filtered view).
- Pinned active-node card at top — surfaces "which Node am I
  routing through" when filters/pagination would otherwise hide
  it. Uses dedicated useActiveNode hook so a 1k-row query isn't
  needed just to find one row.
- Confirm-modal guard on Test All / Speed All when nodes > 50
  (mirrors default page size) — prevents accidental hours-long
  sequential sweeps with no abort path.

Host network configuration (UI-driven)
- New GET /api/network/state, /apply, /confirm, /rollback
  endpoints + supporting core/network_config.py +
  core/network_apply.py (manager detection across
  NetworkManager / systemd-networkd / ifupdown / dhcpcd).
- New HostNetworkSection on Settings page lets the operator
  set static IP / gateway / DNS without SSH — addresses the
  "PiTun points at itself as default gateway" footgun.
- install.sh learnt to wire host network config on first deploy.
- New scripts/make-offline-bundle.sh helper for air-gapped installs.

TUN/Both inbound-mode footgun fix (closes backlog item)
- Dashboard Network Mode: TUN and Both buttons rendered as
  disabled with N/A badge + tooltip explaining that vanilla
  XTLS/Xray-core doesn't support `protocol: tun` (sing-box
  feature). Prevents the silent-brick when user picks TUN.
- Backend validation: empty-stderr case now produces a useful
  diagnostic (xray version + inbound_mode + generated inbound
  protocols) instead of the cryptic "(empty stderr)" message.
- PATCH /api/system/settings: inbound_mode changes pre-flighted
  via xray -test on a tmp config. Validation failure rolls back
  the DB row + returns 400 with the detailed diagnostic. The UI
  no longer "lies" about the runtime state.

Stack
- 23 files changed, ~3.8K lines net. 83/83 focused backend
  tests pass (pagination, system, xui_api, uri_formatter).
- Frontend build clean (tsc + Vite). 1.3.2 → 1.3.3 bump.

Author: DaveBugg

backend/app/api/network.py

@@ -0,0 +1,164 @@
+"""Network configuration API (v1.3.3).
+
+Endpoints for the Settings → Network page.
+
+Read paths:
+    GET  /api/network/state           — current snapshot
+    GET  /api/network/backups         — list of saved rollback points
+    GET  /api/network/probe?ip=...    — pre-apply reachability check
+
+Mutation paths (gateway / DNS only — see core/network_apply for the
+scope rationale):
+    POST /api/network/apply           — backup + apply gateway/DNS
+    POST /api/network/rollback        — restore a backup (default: most recent)
+
+Auth: every endpoint inherits the global auth dependency wired in
+main.py via ``app.include_router(network.router, dependencies=_auth)``.
+"""
+from __future__ import annotations
+
+import logging
+from typing import List, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, Field
+
+from app.core import network_config
+from app.core import network_apply
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/network", tags=["network"])
+
+
+# ── Schemas ────────────────────────────────────────────────────────────────
+
+class ApplyBody(BaseModel):
+    # Both optional — empty body is rejected in core.apply (no-op
+    # surfaces as a 400 with a useful message). Mixing the two is
+    # the common case: "set gateway to X, leave DNS alone".
+    gateway: Optional[str] = Field(default=None, description="New default-route gateway IPv4")
+    dns: Optional[List[str]] = Field(default=None, description="New DNS server list (replaces existing)")
+
+
+class RollbackBody(BaseModel):
+    # Empty = roll back the most recent backup.
+    backup_id: Optional[str] = Field(default=None, description="Specific backup id; defaults to newest")
+
+
+# ── Endpoints ──────────────────────────────────────────────────────────────
+
+@router.get("/state")
+def get_network_state() -> dict:
+    """Current host network configuration snapshot.
+
+    Pure read, ~50ms. Safe to poll from the UI.
+    """
+    state = network_config.read_state()
+    logger.debug(
+        "network state: iface=%r manager=%r mode=%r gw=%r warnings=%d",
+        state.interface, state.manager, state.mode, state.gateway,
+        len(state.warnings),
+    )
+    return state.to_dict()
+
+
+@router.get("/backups")
+def get_backups() -> dict:
+    """List saved rollback points, newest first."""
+    items = network_apply.list_backups()
+    return {"items": items, "count": len(items)}
+
+
+@router.delete("/backups/{backup_id}")
+def delete_backup(backup_id: str) -> dict:
+    """Delete one backup. Idempotent — gone-already is treated as ok."""
+    try:
+        network_apply.delete_backup(backup_id)
+    except network_apply.NetworkApplyError as e:
+        raise HTTPException(400, detail=str(e))
+    return {"ok": True, "id": backup_id}
+
+
+@router.delete("/backups")
+def clear_backups() -> dict:
+    """Wipe every backup. UI confirms first."""
+    try:
+        removed = network_apply.delete_all_backups()
+    except network_apply.NetworkApplyError as e:
+        raise HTTPException(400, detail=str(e))
+    return {"ok": True, "removed": removed}
+
+
+@router.get("/probe")
+def probe(ip: str = Query(..., description="Candidate gateway IPv4 address")) -> dict:
+    """Quick reachability check on a candidate gateway.
+
+    Frontend uses this BEFORE submitting an apply — refusing to even
+    attempt the change if the new gateway can't be pinged saves the
+    operator from a bad reapply that leaves them without internet.
+    """
+    try:
+        return network_apply.probe_gateway(ip)
+    except network_apply.NetworkApplyError as e:
+        raise HTTPException(400, detail=str(e))
+
+
+@router.post("/apply")
+def apply_changes(body: ApplyBody) -> dict:
+    """Apply gateway and/or DNS changes.
+
+    Captures a backup of the current config FIRST so /rollback can
+    return to this state at any time. Apply itself uses ``ip route
+    replace`` + /etc/resolv.conf rewrite for immediate effect, plus
+    edits the persistent manager config (interfaces / nmconnection)
+    so the change survives reboot.
+    """
+    try:
+        backup = network_apply.apply(
+            network_apply.ApplyRequest(gateway=body.gateway, dns=body.dns),
+        )
+    except network_apply.NetworkApplyError as e:
+        raise HTTPException(400, detail=str(e))
+    except Exception as e:  # noqa: BLE001
+        logger.exception("network apply failed unexpectedly")
+        raise HTTPException(500, detail=f"Internal error during apply: {e}")
+
+    new_state = network_config.read_state()
+    return {
+        "ok": True,
+        "backup": {
+            "id": backup.id,
+            "created_at": backup.created_at,
+            "manager": backup.manager,
+            "live_state": backup.live_state,
+        },
+        "new_state": new_state.to_dict(),
+    }
+
+
+@router.post("/rollback")
+def rollback(body: RollbackBody) -> dict:
+    """Restore a backup.
+
+    Default (no body or empty backup_id) → newest backup. Explicit
+    id rolls back to that specific snapshot — useful for going
+    further back than the immediately preceding state.
+    """
+    try:
+        backup = network_apply.rollback(body.backup_id)
+    except network_apply.NetworkApplyError as e:
+        raise HTTPException(400, detail=str(e))
+    except Exception as e:  # noqa: BLE001
+        logger.exception("network rollback failed unexpectedly")
+        raise HTTPException(500, detail=f"Internal error during rollback: {e}")
+
+    new_state = network_config.read_state()
+    return {
+        "ok": True,
+        "restored_from": {
+            "id": backup.id,
+            "created_at": backup.created_at,
+            "live_state": backup.live_state,
+        },
+        "new_state": new_state.to_dict(),
+    }

backend/app/api/nodes.py

@@ -4,6 +4,7 @@
 from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func
 from sqlmodel import select
 from sqlmodel.ext.asyncio.session import AsyncSession
 
@@ -18,6 +19,7 @@
     NodeCreate,
     NodeImportRequest,
     NodeImportResponse,
+    NodePage,
     NodeRead,
     NodeUpdate,
     SpeedTestResult,
@@ -105,6 +107,111 @@ async def list_nodes(
     return list((await session.exec(stmt)).all())
 
 
+@router.get("/page", response_model=NodePage)
+async def list_nodes_paginated(
+    # Pagination. `limit=0` is a deliberate escape hatch for "give me
+    # the whole filtered set" — used by bulk-export and tests. The UI
+    # always sends a positive limit.
+    limit: int = Query(50, ge=0, le=500),
+    offset: int = Query(0, ge=0),
+    # Filters
+    subscription_id: Optional[int] = Query(
+        None, description="Match nodes belonging to this subscription"
+    ),
+    local: Optional[bool] = Query(
+        None,
+        description=(
+            "When True, match only nodes WITHOUT a subscription "
+            "(`subscription_id IS NULL`). Mutually exclusive with "
+            "`subscription_id` — if both are provided, `subscription_id` "
+            "wins (more specific). Used by the UI to show 'local nodes "
+            "only' separately from any registered subscription."
+        ),
+    ),
+    protocol: Optional[str] = Query(
+        None, description="Filter by protocol (vless/vmess/trojan/ss/wg/...)"
+    ),
+    enabled: Optional[bool] = Query(None),
+    online: Optional[bool] = Query(
+        None, description="Match `is_online` flag from last healthcheck"
+    ),
+    group: Optional[str] = Query(None),
+    search: Optional[str] = Query(
+        None, description="Substring match on node.name (case-insensitive)"
+    ),
+    direction: str = Query(
+        "desc",
+        pattern="^(asc|desc)$",
+        description=(
+            "Sort direction for the `id` tiebreaker. `desc` (default) "
+            "shows newest-added nodes first — natural for subscription "
+            "imports where the operator wants to see what just landed. "
+            "`asc` reverses to oldest-first. `Node.order` stays the "
+            "primary sort key either way so drag-to-reorder still wins."
+        ),
+    ),
+    session: AsyncSession = Depends(get_session),
+) -> NodePage:
+    """Paginated + filtered Node listing (since v1.3.3).
+
+    Needed because a single subscription can pull 1000+ nodes — the
+    legacy unbounded endpoint left the UI rendering 1000 cards in one
+    pass, which was unusable on a Raspberry Pi-served UI.
+
+    Filters compose via AND. `total` is the count BEFORE pagination so
+    the UI can render "Showing 51–100 of 1256". The stable sort order
+    (`Node.order` then `Node.id`) is preserved so paging through a
+    reorderable list works without jumping.
+    """
+    base_filters = []
+    if subscription_id is not None:
+        base_filters.append(Node.subscription_id == subscription_id)
+    elif local is True:
+        # Only applied when `subscription_id` wasn't passed — they
+        # describe overlapping axes and the explicit subscription id
+        # always wins.
+        base_filters.append(Node.subscription_id.is_(None))  # type: ignore[union-attr]
+    if protocol is not None:
+        base_filters.append(Node.protocol == protocol)
+    if enabled is not None:
+        base_filters.append(Node.enabled == enabled)
+    if online is not None:
+        base_filters.append(Node.is_online == online)
+    if group is not None:
+        base_filters.append(Node.group == group)
+    if search:
+        # Case-insensitive substring match on `name`. SQLite's LIKE is
+        # case-insensitive by default for ASCII; for the small chance
+        # the operator named a node in Cyrillic we explicitly LOWER both
+        # sides so the filter still matches in practice.
+        pattern = f"%{search.lower()}%"
+        base_filters.append(func.lower(Node.name).like(pattern))
+
+    # Total count (unpaginated). Using a count(*) keyed on id avoids
+    # pulling every Node row into memory just to size the result.
+    count_stmt = select(func.count(Node.id))
+    for f in base_filters:
+        count_stmt = count_stmt.where(f)
+    total = (await session.exec(count_stmt)).one() or 0
+
+    # Paged result. Limit=0 = no LIMIT clause (escape hatch — see
+    # docstring); otherwise the normal limit/offset combo. The `order`
+    # column is always the primary sort axis so manual drag-to-reorder
+    # placement wins; `id` is just the tiebreaker for rows with equal
+    # `order` values (subscription imports leave that field at 0).
+    id_axis = Node.id.desc() if direction == "desc" else Node.id.asc()  # type: ignore[union-attr]
+    stmt = select(Node).order_by(Node.order, id_axis)
+    for f in base_filters:
+        stmt = stmt.where(f)
+    if limit > 0:
+        stmt = stmt.limit(limit).offset(offset)
+    elif offset > 0:
+        stmt = stmt.offset(offset)
+    items = list((await session.exec(stmt)).all())
+
+    return NodePage(items=items, total=int(total), limit=limit, offset=offset)
+
+
 @router.post("", response_model=NodeRead, status_code=201)
 async def create_node(data: NodeCreate, session: AsyncSession = Depends(get_session)):
     node = Node(**data.model_dump())