elmprodvpn/docs/phase-b/B2_RESOLVER_DIFF_AND_IMPROVEMENT_PLAN.md

B2 Resolver: разница ролей и план улучшения

Дата: 2026-03-07
Статус: planned
Владелец: Engineering

1) Цель

• Зафиксировать, чем отличается текущий системный resolver selective-vpn от DNS-модуля sing-box.
• Зафиксировать roadmap доработки нашего resolver, чтобы он оставался основой для selective-маршрутизации.

2) Роли компонентов

• System resolver (Go + SmartDNS + nftset):
  • источник истины для PBR (routes/update, nft sets, wildcard/static fallback),
  • системный контроль резолва для selective-режима.
• SingBox DNS:
  • DNS-часть transport-профиля sing-box,
  • управляет резолвом внутри конкретного engine/profile.

Правило слоя:

• В текущей архитектуре authoritative для маршрутизации остаётся системный resolver.
• SingBox DNS используется как transport-level capability и не заменяет системный PBR resolver.

3) Матрица различий

Область	System resolver (текущий)	SingBox DNS
Основная роль	Системная selective-маршрутизация	DNS внутри transport engine
Связь с nft/PBR	Прямая (agvpn4/agvpn_dyn4, routes/update)	Непрямая, через поведение engine
Wildcard runtime	Да (SmartDNS nftset + merge в routes/update)	Нет прямого контроля системных nft sets
Static fallback	Да (static-ips.txt, policy merge)	Через raw/typed config профиля
Единая картина для всех клиентов	Да, через Go state/API	Нет, scoped к конкретному профилю
Риск рассинхрона	Низкий при single source of truth	Высокий, если использовать как отдельный source of truth

4) Основные gap-ы текущего resolver

• Недостаточная наблюдаемость по качеству резолва (latency/error-rate/NX/servfail per upstream).
• Нет отдельного endpoint'а с полным health snapshot resolver pipeline.
• Нужна более строгая TTL/refresh-стратегия для mixed источников (cache + wildcard runtime + static).
• Нужен формализованный negative caching и rate-limit на проблемные домены при деградации upstream.
• Нужна формализация owner-map для доменов в multi-client сценариях (без дублей и гонок).

5) План улучшения resolver (приоритеты)

R1 Надёжность и консистентность

• Ввести unified resolver state snapshot (updated_at, stale, refresh_in_progress, last_error, next_retry_at, counters).
• Усилить single-flight на expensive refresh-path и добавить доменный backoff.
• Нормализовать merge-порядок источников: static fallback -> wildcard runtime -> resolver cache.

R2 Качество резолва

• Добавить adaptive upstream scoring (latency/success/NX/timeout/servfail).
• Добавить sticky-preferred upstream с безопасным failover.
• Ввести отдельную политику negative cache TTL для NXDOMAIN/SERVFAIL.

R3 Наблюдаемость и API

• Добавить API snapshot для resolver health:
  • GET /api/v1/resolver/status (target),
  • POST /api/v1/resolver/refresh (target trigger),
  • GET /api/v1/resolver/upstreams (target metrics).
• Добавить SSE-события:
  • resolver_status_changed,
  • resolver_upstream_degraded,
  • resolver_refresh_completed.

R4 Multi-client безопасность

• Ввести domain_owner_map и conflict-detection до применения policy.
• Гарантировать, что один domain-selector не получает двух владельцев без explicit override.
• Синхронизировать resolver ownership с transport policy revision.

6) Критерии готовности B2

• Есть документированная и реализуемая разница ролей system resolver vs sing-box DNS.
• Resolver имеет прозрачный health/status API и наблюдаемость по upstream.
• При деградации upstream UI получает stale-safe состояние, а не "пустой провал".
• В multi-client режиме домены не уходят в двойное владение без подтверждённого override.

7) Ограничения этапа

• В этом этапе не переводим управление маршрутизацией на SingBox DNS.
• DNSTT/Phoenix DNS-аспекты не расширяются в UI до завершения SingBox API/GUI трека.