chore: trim code comments and drop operator identifiers

Comments: cut the long "why it is this way" blocks down to one or two
lines each, mostly in the User-Agent template code added for 1.4.7 but
also in the older modules touched below. Rationale that belongs in a
design doc no longer sits in the source, and references to what the code
used to look like are gone — git already has that. Net -245 lines, no
behaviour change.

OPSEC: removed the maintainer's own LAN addresses from source comments
and docstrings. They had accumulated in burn-in war stories
("observed on <ip> during <version>") across the xray lock timeout, the
DNS-pin rationale in config_gen, the resolv.conf clobber note in
network_apply, the naive sidecar memory limit, and the ifupdown detection
docstring. Each keeps the technical reason, minus the address. The
private-range examples in the knowledge base, UI placeholders and the
config defaults are product content and stay.

Backend 867 passing, frontend 49, tsc and vite build clean.

Author: DaveBugg

backend/alembic/versions/018_add_useragent_templates.py

@@ -1,31 +1,13 @@
-"""Add UserAgentTemplate table and seed it with the former hardcoded presets.
+"""Add UserAgentTemplate table, seeded with the built-in UA presets.
 
-Until v1.4.6 the subscription UA catalogue was two module-level dicts in
-`app/api/subscriptions.py` — `_UA_MAP` (9 UA strings) and `_HAPP_PROFILES`
-(the per-OS Happ device tuples). Adding a preset for a new panel, or
-attaching an extra header the panel gates on, meant a code change and a
-redeploy.
+The presets are keyed by the same slugs already stored in
+`subscription.ua` and carry the same User-Agent strings, so every
+existing subscription resolves to an identical request after the
+upgrade — the rows are simply editable now.
 
-This migration moves the catalogue into `useragenttemplate` and seeds it
-with **exactly** those nine presets, keyed by the same slugs already
-stored in `subscription.ua`. So nothing changes behaviourally on upgrade:
-every existing subscription resolves to the identical User-Agent it used
-yesterday. The difference is that the rows are now editable — the whole
-point of the change is that `happ`'s app version, or `chrome`'s Chrome
-build number, can be bumped from the UI when a panel starts rejecting a
-stale fingerprint.
-
-`builtin=1` on the seeded rows is informational only (it drives a badge
-in the UI and a louder delete confirmation). Built-ins are fully
-editable AND deletable; nothing re-seeds them, because resurrecting a
-row the operator deliberately deleted would be worse than an empty
-dropdown. The runtime keeps a hardcoded fallback map for exactly that
-case (`core/ua_templates.BUILTIN_UA_MAP`), so a deleted or renamed
-template degrades to the old UA instead of breaking a refresh.
-
-Not a foreign key: `subscription.ua` stays a plain string. A dangling
-key has a well-defined fallback, whereas an FK would either block the
-delete or cascade into wiping subscriptions.
+`subscription.ua` stays a plain string rather than a foreign key: a
+dangling key falls back to `core/ua_templates.BUILTIN_UA_MAP`, whereas an
+FK would either block the delete or cascade into wiping subscriptions.
 
 Revision ID: 018
 Revises: 017
@@ -43,24 +25,11 @@
 depends_on: Union[str, Sequence[str], None] = None
 
 
-# The seed rows are INLINED here rather than imported from
-# `app.core.ua_templates`, for two reasons:
-#
-# 1. **A migration is a historical snapshot.** If someone later adds a
-#    tenth preset to `DEFAULT_UA_TEMPLATES`, an import would make this
-#    migration retroactively seed different data than it did for every
-#    install that already ran it. Migrations must not move.
-#
-# 2. **Deploy safety.** `docker-compose.yml` bind-mounts `./backend/app`
-#    and `./backend/alembic` as two separate volumes, and `entrypoint.sh`
-#    runs `alembic upgrade head` with `MIGRATION_STRICT=1` before the app
-#    starts. A hot-deploy that copies the new `alembic/` but not the new
-#    `app/` would hit an ImportError here and put the container in a
-#    crash loop. With no app import there is nothing to get out of sync.
-#
-# `tests/test_ua_templates.py::TestMigrationSeedData` asserts these stay
-# byte-identical to `DEFAULT_UA_TEMPLATES`, so drift is a failing test
-# rather than a silent difference between fresh and upgraded installs.
+# Inlined rather than imported from `app.core.ua_templates`: a migration
+# is a historical snapshot, and `app/` and `alembic/` are separate bind
+# mounts, so an import would crash-loop the container on a deploy that
+# updated one before the other. `TestMigrationSeedData` pins these against
+# the runtime copy so the two cannot drift.
 _HAPP_NOTE = (
     "X-Device-* / X-Hwid headers are added automatically to match this profile."
 )
@@ -104,11 +73,9 @@ def upgrade() -> None:
     templates = op.create_table(
         "useragenttemplate",
         sa.Column("id", sa.Integer(), primary_key=True),
-        # Stable slug referenced by `subscription.ua`.
         sa.Column("key", sa.String(), nullable=False),
         sa.Column("name", sa.String(), nullable=False),
         sa.Column("user_agent", sa.String(), nullable=False, server_default=""),
-        # JSON object of extra request headers merged over the base set.
         sa.Column("headers", sa.String(), nullable=False, server_default="{}"),
         sa.Column("description", sa.String(), nullable=True),
         sa.Column(

backend/app/api/subscriptions.py

@@ -18,14 +18,6 @@
 
 router = APIRouter(prefix="/subscriptions", tags=["subscriptions"])
 
-# The UA catalogue lived in this module until v1.4.7 as two hardcoded
-# dicts (`_UA_MAP` + `_HAPP_PROFILES`). It now lives in the
-# `useragenttemplate` table — CRUD in `api/user_agents.py`, resolution
-# and the remaining code-side pieces (the built-in fallback map, and
-# Happ's X-* bundle whose `X-Hwid` must be derived per request) in
-# `core/ua_templates.py`.
-
-
 # ── CRUD ──────────────────────────────────────────────────────────────────────
 
 @router.get("", response_model=List[SubscriptionRead])
@@ -96,18 +88,10 @@ async def refresh_subscription(
     sub = await session.get(Subscription, sub_id)
     if not sub:
         raise HTTPException(404, "Subscription not found")
-    # Per-subscription mutex — concurrent calls return 409 instead of
-    # spawning duplicate fetch tasks. Without this, two clicks within
-    # a few hundred ms (UI double-click, scheduler tick overlapping a
-    # manual refresh, two browser tabs etc.) used to fire two
-    # background `_fetch_subscription` runs against the same row.
-    # Each one would `delete all old nodes → insert new`, so the
-    # second one racing the first could observe a half-deleted state
-    # and import a partial node set, or both could land near-
-    # simultaneously and corrupt `active_node_id` via duplicate
-    # delete-then-create. Observed in the wild on 192.168.1.4 —
-    # logs show 4 refreshes within 60s with one returning 57 nodes
-    # instead of the canonical 1256.
+    # Per-subscription mutex. Two refreshes racing (double-click,
+    # scheduler tick overlapping a manual refresh, two tabs) could each
+    # observe a half-deleted node set and import a partial one, or
+    # corrupt `active_node_id`.
     if _is_refresh_active(sub_id):
         raise HTTPException(
             status_code=409,
@@ -211,11 +195,6 @@ async def _fetch_subscription_unlocked(sub_id: int) -> None:
         if not sub:
             return
 
-        # Resolve the full request fingerprint from the UA template the
-        # subscription points at: User-Agent, the base Accept-* set, the
-        # dynamic Happ X-* bundle where applicable, and any extra headers
-        # the template declares. Precedence and merge order are
-        # documented on `build_subscription_headers`.
         headers = await build_subscription_headers(session, sub)
 
         content: str = ""

backend/app/api/system.py

@@ -1193,13 +1193,10 @@ async def _collect_naive_bypass_dsts(session: AsyncSession) -> List[str]:
     Domain names are resolved via ``socket.getaddrinfo`` (A records only).
 
     Resolution runs OFF the event loop thread (``asyncio.to_thread``)
-    and with a 2-second per-host budget. The earlier sync version
-    blocked the entire FastAPI event loop when /etc/resolv.conf was
-    misconfigured — observed in the wild on 192.168.1.4 during 1.3.3
-    burn-in: every API endpoint that touched ``_auto_reload_xray``
-    (routing-rule CRUD, ``/system/restart``) stalled forever because
-    the underlying ``getaddrinfo`` call wedged the loop while glibc
-    retried against zero nameservers.
+    and with a 2-second per-host budget. Resolving inline wedges the
+    whole event loop when /etc/resolv.conf is misconfigured: glibc
+    retries against zero nameservers and every endpoint touching
+    ``_auto_reload_xray`` stalls with it.
 
     DNS-broken or host-unreachable cases are absorbed silently
     (worst case: loop prevention doesn't apply until the host

backend/app/api/user_agents.py

@@ -1,24 +1,8 @@
 """User-Agent template CRUD + JSON export/import.
 
-A `UserAgentTemplate` is the client fingerprint a subscription fetch
-presents: the `User-Agent` string plus any extra request headers the
-panel gates on. The catalogue used to be two hardcoded dicts in
-`api/subscriptions.py`; Alembic 018 seeds the table with exactly those
-presets, and everything here exists so the operator can edit, extend and
-move them between installs without a redeploy.
-
-Header-merge order, the reason Happ's X-* bundle is still generated in
-code, and the validation ruleset all live in `app/core/ua_templates.py`.
-
-Endpoint summary
-----------------
-* `GET    /api/user-agents`                    — list, dropdown order, with usage counts
-* `POST   /api/user-agents`                    — create
-* `GET    /api/user-agents/export-json`        — downloadable bundle
-* `POST   /api/user-agents/import-json`        — restore a bundle (`?replace=`, `?overwrite=`)
-* `GET    /api/user-agents/{id}`               — read one
-* `PATCH  /api/user-agents/{id}`               — edit; a key rename re-points its subscriptions
-* `DELETE /api/user-agents/{id}`               — delete; 409 while subscriptions use it unless `?force=true`
+A template is the fingerprint a subscription fetch presents: the
+`User-Agent` string plus any extra headers the panel gates on. Header
+assembly and the validation ruleset live in `app/core/ua_templates.py`.
 """
 import logging
 from datetime import datetime, timezone
@@ -47,8 +31,7 @@
 EXPORT_KIND = "pitun-ua-templates-export"
 EXPORT_VERSION = 1
 
-# Sanity ceiling on the table. The dropdown becomes unusable long before
-# this, and it bounds an import bundle's blast radius.
+# Bounds the dropdown and an import bundle's blast radius.
 MAX_TEMPLATES = 200
 
 
@@ -57,9 +40,8 @@
 async def _usage_counts(session: AsyncSession) -> Dict[str, int]:
     """How many subscriptions reference each template key.
 
-    One query for the whole table, counted in Python — the subscription
-    count is in the tens at most, and this avoids a GROUP BY that would
-    need a raw-SQL escape hatch under SQLModel's async session.
+    Counted in Python: subscriptions number in the tens, and a GROUP BY
+    would need a raw-SQL escape hatch under SQLModel's async session.
     """
     keys = (await session.exec(select(Subscription.ua))).all()
     counts: Dict[str, int] = {}
@@ -91,14 +73,12 @@ async def _get_or_404(session: AsyncSession, tpl_id: int) -> UserAgentTemplate:
 
 
 def _row_label(entry: Any) -> str:
-    """Safe identifier for an import row, for use in logs and error text.
-
-    Taken from the row's raw `key` because that is the only field present
-    on a row that failed validation. Sanitised before it goes anywhere:
-    control characters are stripped (CWE-117 log injection) and the value
-    is truncated, since a bundle is untrusted input. Only the key is ever
-    surfaced — never `user_agent` or `headers`, which can carry the
-    operator's panel credentials.
+    """Safe identifier for an import row, for logs and error text.
+
+    The raw `key` is the only field present on a row that failed
+    validation. Stripped of control characters (CWE-117) and truncated,
+    since a bundle is untrusted. Never surfaces `user_agent` or
+    `headers` — those can carry panel credentials.
     """
     if not isinstance(entry, dict):
         return "?"
@@ -162,9 +142,7 @@ async def create_ua_template(
     return _to_read(row, 0)
 
 
-# Declared BEFORE `/{tpl_id}` so FastAPI matches the literal path instead
-# of reading "export-json" as an int path param (same trick as
-# routing_sets' /capacity).
+# Must precede `/{tpl_id}` or FastAPI reads "export-json" as an int param.
 @router.get("/export-json")
 async def export_ua_templates(session: AsyncSession = Depends(get_session)):
     """Return every template as a downloadable JSON bundle."""
@@ -182,8 +160,7 @@ async def export_ua_templates(session: AsyncSession = Depends(get_session)):
                 "key": r.key,
                 "name": r.name,
                 "user_agent": r.user_agent,
-                # Sanitised, not raw: an exported bundle must be
-                # re-importable, and import re-validates every header.
+                # Sanitised so the bundle survives import re-validation.
                 "headers": sanitize_headers(r.headers),
                 "description": r.description,
                 "order": r.order,
@@ -222,18 +199,12 @@ async def import_ua_templates(
     ),
     session: AsyncSession = Depends(get_session),
 ):
-    """Restore templates from a previously-exported bundle.
-
-    Three behaviours, in increasing destructiveness:
-
-    * default — additive; a key that already exists is **skipped**.
-    * `overwrite=true` — additive, but a matching key is **updated** in
-      place. Keeps its id, so subscriptions pointing at it are unaffected.
-    * `replace=true` — wipe the table first, then insert. The only way to
-      drop templates that aren't in the bundle.
+    """Restore templates from an exported bundle.
 
-    Rows are validated individually: one bad entry lands in `errors` and
-    the rest still import.
+    Additive by default (existing key skipped); `overwrite` updates a
+    match in place, keeping its id so subscriptions stay attached;
+    `replace` wipes first. Rows validate individually — one bad entry
+    lands in `errors` and the rest still import.
     """
     if not isinstance(payload, dict):
         raise HTTPException(400, "Invalid bundle: expected a JSON object at the top level")
@@ -261,21 +232,18 @@ async def import_ua_templates(
             await session.delete(row)
         await session.flush()
 
-    # Track keys seen in this bundle so a bundle containing the same key
-    # twice reports a clean per-row error instead of tripping the UNIQUE
-    # constraint and rolling back the whole request.
+    # A key twice in one bundle should be a per-row error, not a UNIQUE
+    # violation that rolls back the whole request.
     seen_keys: set[str] = set()
 
     for entry in entries:
-        # Label the row from its RAW key before validating, so a row that
-        # fails validation is still identifiable in `errors` — deriving it
-        # from the validated object would leave every rejected row as "?".
+        # Label from the RAW key: deriving it from the validated object
+        # would leave every rejected row as "?".
         row_label = _row_label(entry)
         try:
             if not isinstance(entry, dict):
                 raise ValueError("entry is not an object")
-            # Drop unknown fields (forward-compat: a newer export with
-            # extra columns still imports into an older PiTun).
+            # Forward-compat: a newer export with extra columns still imports.
             allowed = set(UserAgentTemplateCreate.model_fields.keys())
             clean = {k: v for k, v in entry.items() if k in allowed}
             validated = UserAgentTemplateCreate(**clean)
@@ -319,12 +287,9 @@ async def import_ua_templates(
             await session.flush()
             imported += 1
         except Exception as exc:  # noqa: BLE001 — surface per-row errors
-            # Log the exception *type* only, never the value: a bundle row
-            # can carry operator secrets (panel API keys live in the
-            # headers object) and a pydantic ValidationError message
-            # echoes the offending input verbatim. Same envelope as nodes'
-            # import-json (CWE-209/532/117). `row_label` is already
-            # sanitised by `_row_label`.
+            # Type only, never the value: a ValidationError echoes its
+            # input and a row's headers can hold a panel API key
+            # (CWE-209/532/117).
             logger.warning(
                 "UA template import row failed: key=%r err_type=%s",
                 row_label, type(exc).__name__,
@@ -354,12 +319,12 @@ async def update_ua_template(
     body: UserAgentTemplateUpdate,
     session: AsyncSession = Depends(get_session),
 ):
-    """Edit a template, including the built-in ones.
+    """Edit a template, built-ins included.
 
-    Renaming the `key` would orphan every subscription pointing at the
-    old value — those would silently fall back to the built-in UA map and
-    start presenting a different fingerprint. So we re-point them in the
-    same transaction instead.
+    Renaming the `key` would orphan every subscription pointing at the old
+    value — they would fall back to the built-in map and start presenting
+    a different fingerprint — so they are re-pointed in the same
+    transaction.
     """
     row = await _get_or_404(session, tpl_id)
     patch = body.model_dump(exclude_unset=True)

backend/app/core/config_gen.py

@@ -695,10 +695,9 @@ def _format_rule_addr(host: str, rtype: str) -> str:
     # captures the DNS resolver's own connection to 8.8.8.8:53,
     # tunnelling it through the active node. If the node is flaky or
     # under handshake-failure, the whole DNS layer dies — and with
-    # broken DNS, nothing else resolves either. Observed in the wild on
-    # the 1256-node burn-in (192.168.1.4): user added "Port Range
-    # 0-65535 → proxy", node had a transient handshake failure, the
-    # whole API and proxy locked up.
+    # broken DNS, nothing else resolves either. A catch-all proxy rule
+    # plus one transient handshake failure is enough to lock up both
+    # the API and the proxy.
     #
     # The `outboundTag` field on a DNS server config is exactly the
     # escape hatch — xray short-circuits routing for THAT server's
@@ -1091,9 +1090,7 @@ def generate_config(
         # `port: 0-65535 → proxy`, `geoip:!ru → proxy`) intercepts
         # the DNS dial too and tunnels it through the active VPN
         # node — if that node has any handshake issue, DNS dies and
-        # nothing else can resolve. Observed in the wild on
-        # 192.168.1.4 during 1.3.4 burn-in (1256-node subscription
-        # + Port Range 0-65535 → proxy rule). Pair with the
+        # nothing else can resolve. Pair with the
         # `outboundTag: direct` per-DNS-server pin in `_build_dns_section`
         # — that one wins for any internal xray query that goes
         # through the routing engine BEFORE hitting the outbound.
@@ -1155,8 +1152,8 @@ def generate_config(
     # so a user `port: 0-65535 → proxy` (or `geoip:!ru → proxy`) rule
     # would otherwise capture the DNS dial and tunnel it through the
     # active VPN node, breaking the resolver when that node has any
-    # handshake issue. Burn-in on 192.168.1.4 nailed the exact case:
-    # add the catch-all rule → kill DNS → kill everything.
+    # handshake issue: add the catch-all rule → kill DNS → kill
+    # everything.
     #
     # Why we don't pin via dns-out's `proxySettings.tag`: that field
     # chains outbounds (dns-out's resolved data flows through direct)

backend/app/core/naive_manager.py

@@ -228,13 +228,12 @@ def _run_container_sync(self, node: Node) -> None:
                     type=docker.types.LogConfig.types.JSON,
                     config={"max-size": "10m", "max-file": "3"},
                 ),
-                # 96 MB (was 64 MB through v1.2.5). Observed `exit=137`
-                # SIGKILL on cold start at 192.168.1.3 — Caddy's TLS
-                # session-ticket cache + naive's QUIC connection pool
-                # spike RSS briefly above 64 MB on a freshly provisioned
-                # container. 96 MB gives headroom without significant
-                # memory pressure on a Pi 4 (typical sidecar steady-state
-                # is ~30-40 MB). Combined with the supervisor's
+                # 96 MB. At 64 MB a cold start could `exit=137` (OOM
+                # SIGKILL): Caddy's TLS session-ticket cache plus naive's
+                # QUIC connection pool spike RSS briefly on a freshly
+                # provisioned container. 96 MB gives headroom without
+                # significant memory pressure on a Pi 4 (typical sidecar
+                # steady-state is ~30-40 MB). Combined with the supervisor's
                 # exponential backoff (v1.2.6), tight OOM-restart loops
                 # should no longer be reachable.
                 mem_limit="96m",