elmprodvpn/PLAN_DHSQ_GLOBAL.md

Global Plan: DHSQ (Domain Health Scoring + Quarantine)

Execution checklist (live)

• 1. Implement attempt budget + early stop semantics.
• 2. Implement domain/resolver scoring and quarantine states.
• 3. Add stale-keep policy.
• 4. Wire 24h precheck cycle (soft pruning only).
• 5. Expose metrics/log clarity in API + GUI (API/trace done; DNS benchmark load-profile UI done; route badges done).
• 6. Tune thresholds with production data (pass-1 done: timeout-only stays suspect; pass-2 done: NX hard-quarantine disabled by default).

1) Goal

• Stabilize resolver behavior under high domain volume.
• Reduce timeout storms and DNS provider rate-limit effects.
• Keep routing safety (avoid missing required IPs for selective VPN).
• Preserve wildcard flow via SmartDNS without forcing subs brute-force.

2) Current pain points

• Too many DNS attempts per domain in wave mode.
• Upstream DNS throttling leads to large timeout counts.
• Mixed signal: hard to separate dead domains vs temporary resolver failure.
• Risk of dropping useful domains when pruning is too aggressive.

3) Target model (approved)

• Use DHSQ as soft-pruning model, not hard deny.
• Run precheck cycle every 24h (not weekly).
• Maintain separate health for:
  • domain_score (domain reliability),
  • resolver_score (upstream DNS reliability).
• Wildcard remains SmartDNS-driven.
• Subs fan-out is optional/aggressive mode only.

4) Attempt budget policy

• Per-domain cap:
  • direct domains: 2 attempts (max 3),
  • wildcard path: 1 attempt (max 2 with controlled fallback).
• Time budget per domain: ~1200 ms.
• Retry policy:
  • confirmed NXDOMAIN -> early stop,
  • timeout/temporary -> one fallback attempt.

5) Domain scoring policy (initial values)

• A/AAAA OK: +8
• runtime observed: +12
• NXDOMAIN confirmed by 2 resolvers: -15
• NXDOMAIN from 1 resolver: -7
• timeout: -3
• temporary/servfail: -2

State thresholds:

• >= +20: Active
• +5..+19: Stable
• -10..+4: Suspect (short retest, e.g. 6h)
• < -10: Quarantine (24h)
• < -30: Hard quarantine (7d, but 1 probe/day)

Exit rules:

• Any successful resolve or runtime observation removes quarantine.

6) Quarantine + stale protection

• Quarantine is soft suppression for noisy/unreliable domains.
• Never treat timeout as long-term dead by default.
• Keep stale known-good IPs for 48-72h on temporary failures.
• If runtime observes a quarantined host, promote it immediately.

7) Resolver pool policy

• Active resolver set: 4-6 best DNS at runtime.
• Benchmark can test larger list; resolver uses selected active subset.
• Use resolver cooldown after repeated failures.
• Optional hedged query: second DNS after 100-150 ms delay.

8) SmartDNS integration direction

• Keep SmartDNS as managed child process (not embedded library).
• API controls status/start/stop/reload and generated config.
• Wildcard source remains:
  • resolver + smartdns runtime (with clear visibility in trace/logs).

9) Observability and metrics

• Add/track:
  • attempts_total,
  • attempts_avg_per_domain,
  • budget_exhausted_domains,
  • early_stop_nxdomain,
  • cache_neg_hits,
  • timeouts_by_upstream,
  • resolver_score/domain_score summaries.

10) Rollout order

1. Implement attempt budget + early stop semantics.
2. Implement domain/resolver scoring and quarantine states.
3. Add stale-keep policy.
4. Wire 24h precheck cycle (soft pruning only).
5. Expose metrics/log clarity in API + GUI.
6. Tune thresholds with production data.

11) Non-goals (for now)

• No full architecture switch to FakeDNS/TProxy pipeline.
• No hard dependency on sing-box routing core.
• No removal of existing SmartDNS wildcard path.

12) Sing-box integration extension (client side)

• Integrate sing-box as optional sidecar engine (managed child process), not as hard replacement of resolver.
• Use sing-box to expand client protocols and node compatibility:
  • vless, vmess, trojan, shadowsocks, hysteria2, wireguard (actual enabled set configurable).
• Keep current backend as policy/controller layer:
  • profile storage,
  • launch/stop/restart,
  • health checks,
  • status and failover logic.
• Keep DHSQ resolver path independent; sing-box is additive for transport/client capability.

13) UI redesign scope for protocol profiles

• Add dedicated UI area for transport/client management (separate from DNS tab):
  • Profiles (name, protocol, server, creds, tls/reality params),
  • Nodes (region/endpoint list, priority),
  • Health (latency, last check, fail state),
  • Binding (which traffic/app/profile uses which transport profile).
• Add per-profile validation before apply (schema + connection smoke test).
• Keep "basic mode" with defaults and hide advanced fields unless requested.

14) Multi-interface model (important)

• Multiple VPN interfaces can run simultaneously on Linux (allowed), e.g. tun0, wg0, sbx0.
• Not forbidden, but requires strict policy routing ownership:
  • unique route table per interface/profile,
  • unique fwmark ranges per engine,
  • deterministic rule priority order,
  • conflict guard with existing agvpn nft rules.
• Default route should be controlled by selected traffic mode only; other interfaces stay available for policy-based routing.

15) Sing-box rollout order (after DHSQ stabilization)

1. Add backend profile schema + secure storage + validation API.
2. Add sing-box process manager (start/stop/reload/status/log tail).
3. Add one protocol first (minimal path), verify policy routing isolation.
4. Add multi-interface binding and per-profile routing table allocation.
5. Extend GUI with protocol profile editor and health dashboard.
6. Add controlled failover and rollback to previous working profile.

---

Глобальный план: DHSQ (Domain Health Scoring + Quarantine)

1) Цель

• Стабилизировать работу резолвера при большом объеме доменов.
• Снизить шторма таймаутов и эффекты rate-limit со стороны DNS-провайдеров.
• Сохранить безопасность маршрутизации (не терять нужные IP для selective VPN).
• Сохранить wildcard-поток через SmartDNS без brute-force по subs.

2) Текущие проблемы

• Слишком много DNS-попыток на один домен в wave-режиме.
• Троттлинг апстримов приводит к большому числу таймаутов.
• Смешение сигналов: сложно отделить мертвый домен от временного сбоя резолвера.
• Риск потерять полезные домены при слишком агрессивной фильтрации.

3) Целевая модель (подтверждено)

• Использовать DHSQ как мягкую фильтрацию, а не жесткий deny.
• Запускать precheck каждые 24 часа (не раз в неделю).
• Вести отдельное здоровье для:
  • domain_score (надежность домена),
  • resolver_score (надежность DNS-апстрима).
• Wildcard остается на SmartDNS.
• Расширение по subs остается опциональным (aggressive mode).

4) Политика attempt budget

• Лимит попыток на домен:
  • direct-домены: 2 попытки (максимум 3),
  • wildcard-путь: 1 попытка (максимум 2 с контролируемым fallback).
• Бюджет времени на домен: ~1200 мс.
• Политика повторов:
  • подтвержденный NXDOMAIN -> ранняя остановка,
  • timeout/temporary -> одна fallback-попытка.

5) Политика scoring доменов (начальные значения)

• A/AAAA OK: +8
• runtime observed: +12
• NXDOMAIN, подтвержденный 2 резолверами: -15
• NXDOMAIN от 1 резолвера: -7
• timeout: -3
• temporary/servfail: -2

Пороги состояний:

• >= +20: Active
• +5..+19: Stable
• -10..+4: Suspect (короткий ретест, например 6ч)
• < -10: Quarantine (24ч)
• < -30: Hard quarantine (7д, но 1 проба/сутки)

Правила выхода:

• Любой успешный резолв или runtime-наблюдение снимает quarantine.

6) Quarantine + stale-защита

• Quarantine — это мягкое подавление шумных/ненадежных доменов.
• Таймауты по умолчанию не считаем долгосрочной смертью домена.
• При временных сбоях держим stale known-good IP 48-72ч.
• Если runtime видит quarantined-хост, сразу повышаем его приоритет.

7) Политика пула резолверов

• Активный пул в рантайме: 4-6 лучших DNS.
• Benchmark может проверять больший список; резолвер использует выбранный активный поднабор.
• Добавить cooldown для резолвера после повторяющихся ошибок.
• Опционально hedged query: второй DNS через 100-150 мс.

8) Направление интеграции SmartDNS

• Оставить SmartDNS как управляемый child-процесс (не embedded library).
• API управляет status/start/stop/reload и генерацией конфига.
• Источник wildcard остается:
  • resolver + smartdns runtime (с прозрачностью в trace/logs).

9) Наблюдаемость и метрики

• Добавить/отслеживать:
  • attempts_total,
  • attempts_avg_per_domain,
  • budget_exhausted_domains,
  • early_stop_nxdomain,
  • cache_neg_hits,
  • timeouts_by_upstream,
  • сводки resolver_score/domain_score.

10) Порядок внедрения

1. Реализовать attempt budget + правила ранней остановки.
2. Реализовать scoring доменов/резолверов и состояния quarantine.
3. Добавить stale-keep policy.
4. Подключить 24ч precheck-cycle (только мягкая фильтрация).
5. Вывести метрики и прозрачные логи в API + GUI.
6. Подстроить пороги по данным продакшена.

11) Что не делаем сейчас

• Не делаем полный переход архитектуры на FakeDNS/TProxy pipeline.
• Не делаем жесткую зависимость от routing core sing-box.
• Не убираем текущий SmartDNS wildcard path.

12) Расширение интеграции sing-box (клиентская часть)

• Интегрировать sing-box как опциональный sidecar engine (управляемый child-процесс), а не как жесткую замену резолвера.
• Использовать sing-box для расширения клиентских протоколов и совместимости с нодами:
  • vless, vmess, trojan, shadowsocks, hysteria2, wireguard (набор включается конфигом).
• Оставить текущий backend как слой политики/контроля:
  • хранение профилей,
  • launch/stop/restart,
  • health checks,
  • status и failover-логика.
• Путь резолва DHSQ оставить независимым; sing-box использовать как дополнение к transport/client части.

13) Область редизайна UI под протокольные профили

• Добавить отдельную зону UI для transport/client управления (отдельно от DNS-вкладки):
  • Profiles (имя, протокол, сервер, креды, tls/reality параметры),
  • Nodes (список регионов/endpoint, приоритет),
  • Health (задержка, последняя проверка, fail-state),
  • Binding (какой трафик/app/profile использует какой transport-profile).
• Добавить валидацию профиля перед применением (schema + connection smoke test).
• Сохранить "basic mode" с дефолтами и скрыть advanced-поля до явного запроса.

14) Модель multi-interface (важно)

• Несколько VPN-интерфейсов могут работать одновременно на Linux (разрешено), например tun0, wg0, sbx0.
• Это не запрещено, но требует строгого разделения policy routing:
  • отдельная route table на интерфейс/профиль,
  • отдельные диапазоны fwmark на engine,
  • детерминированный порядок приоритетов rule,
  • защита от конфликтов с текущими agvpn nft-правилами.
• Default route должен управляться только выбранным traffic mode; остальные интерфейсы доступны для policy-based routing.

15) Порядок внедрения sing-box (после стабилизации DHSQ)

1. Добавить schema профилей в backend + безопасное хранение + validation API.
2. Добавить process manager для sing-box (start/stop/reload/status/log tail).
3. Сначала включить один протокол (минимальный путь) и проверить изоляцию policy routing.
4. Добавить multi-interface binding и выделение route table на профиль.
5. Расширить GUI редактором протокольных профилей и health-dashboard.
6. Добавить контролируемый failover и rollback на предыдущий рабочий профиль.