elmprodvpn/docs/phase-e/E5_SINGBOX_PROTOCOLS_REQUIREMENTS.md

E5 Требования: SingBox Protocols (UI tab + Go API)

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

1) Цель

• Зафиксировать требования для реализации протоколов во вкладке SingBox без архитектурной "мешанины".
• Зафиксировать целевой Go API для singbox с поддержкой "всех фишек" через typed-профили и raw-режим.

2) Архитектурные границы (чтобы не смешивать слои)

• Слой Transport Engine:
  • lifecycle (provision/start/stop/restart), health/metrics, runtime_mode/packaging.
  • уже реализован в /api/v1/transport/clients/*.
• Слой Routing Policy:
  • validate -> confirm -> apply -> rollback.
  • уже реализован в /api/v1/transport/policies/*.
• Слой Protocol Profile (новый E5):
  • описание конфигов sing-box (outbounds/rules/dns/tun и т.д.).
  • не дублирует lifecycle и не дублирует policy.

Правило:

• Protocol Profile готовит/валидирует/рендерит sing-box config.
• Transport Engine запускает этот config.
• Routing Policy решает, какой engine владеет трафиком.

3) Требования к вкладке SingBox (GUI)

3.1 Блоки UI (обязательные)

• Profiles list:
  • список профилей, тип протокола, версия, последний apply, статус валидации.
• Editor:
  • режим Typed (форма) и режим Raw JSON (полный контроль).
• Validation:
  • синтаксис, обязательные поля, совместимость с бинарём/features.
• Apply:
  • Validate -> Preview -> Apply.
  • при рисках/конфликтах — confirm flow.
• Diagnostics:
  • last_error, warning, render-diff, health summary.
• Rollback:
  • откат к предыдущей рабочей версии профиля.

3.2 Поведение

• Нельзя применять профиль без успешной валидации.
• Apply профиля не должен неявно менять transport-policy ownership.
• Секреты в UI маскируются, редактируются только write-only полями.
• Все mutating-операции идемпотентны и привязаны к ревизии.

3.3 Desktop layout freeze

• Вкладка SingBox на desktop фиксируется в 3 секции:
  • Connection card (runtime),
  • Profile settings (per profile),
  • Global defaults.
• Для profile-параметров используется правило Use global/Override.
• Детальная спецификация: docs/phase-e/E5_2_SINGBOX_DESKTOP_DASHBOARD_SPEC.md.

4) Требования к модели профилей (Go)

4.1 Поддерживаемые режимы профиля

• typed:
  • структурированная схема под основные протоколы.
• raw:
  • полный sing-box JSON для "всех фишек", не покрытых формой.

4.2 Минимальный набор протоколов для typed-режима

• vless (в т.ч. reality/tls варианты),
• trojan,
• shadowsocks,
• wireguard,
• hysteria2,
• tuic.

Примечание:

• Для нестандартных/редких фич используется raw без потери совместимости.

4.3 Версионирование

• schema_version для профиля.
• profile_revision (optimistic lock).
• render_revision (версия сгенерированного итогового конфига).

4.4 DNS (встроенный resolver sing-box)

• Профиль singbox должен включать секцию DNS как часть единого конфига (dns.servers, dns.rules, strategy, final и связанные поля).
• В typed-режиме нужен базовый DNS-набор:
  • выбор DNS-провайдеров/серверов,
  • rule-based DNS routing (по доменам/гео/режимам),
  • переключение стратегий резолва (например, prefer IPv4/IPv6 по профилю).
• Для расширенных сценариев (fakeip, cache tuning, нетиповые rules/actions) используется raw режим без ограничений формы.
• Ограничение границ:
  • DNS sing-box отвечает за резолв внутри transport-профиля,
  • системный selective routing policy (/transport/policies/*) остаётся отдельным слоем и не дублируется в profile editor.

5) Требования к Go API singbox

5.1 Новые endpoint-группы (target)

• GET/POST /api/v1/transport/singbox/profiles
• GET/PATCH/DELETE /api/v1/transport/singbox/profiles/{id}
• POST /api/v1/transport/singbox/profiles/{id}/validate
• POST /api/v1/transport/singbox/profiles/{id}/render
• POST /api/v1/transport/singbox/profiles/{id}/apply
• POST /api/v1/transport/singbox/profiles/{id}/rollback
• GET /api/v1/transport/singbox/profiles/{id}/history
• GET /api/v1/transport/singbox/features

5.2 Контракт операций

• validate:
  • возвращает ошибки схемы, ошибок протокола, неподдерживаемых фич по текущему binary.
• render:
  • детерминированно строит финальный sing-box config + diff к текущему active.
• apply:
  • атомарно: запись конфига -> backend provision -> optional restart/start -> health check.
  • при fail: автоматический rollback.
• rollback:
  • откат к последнему успешному render/apply snapshot.

5.3 Совместимость и безопасность

• Не ломать текущий /api/v1/transport/* контракт.
• Для mutating запросов:
  • Idempotency-Key,
  • base_revision.
• Секреты:
  • отдельное хранение, выдача в API только masked.
  • запрет на логирование plain-secret в trace/events.

6) "Все фишки" sing-box: как закрываем требование

• Typed-форма покрывает частые production-сценарии.
• Raw-режим гарантирует доступ к полному синтаксису sing-box.
• GET /transport/singbox/features отражает реальные возможности текущего binary:
  • поддерживаемые протоколы,
  • transport/tls/reality/quic опции,
  • ограничения версии.

7) Хранение и артефакты

• Профили: /var/lib/selective-vpn/transport/singbox-profiles.json
• История/snapshots: /var/lib/selective-vpn/transport/singbox-history/*.json
• Rendered configs: /var/lib/selective-vpn/transport/singbox-rendered/{profile_id}.json
• Secrets store: /var/lib/selective-vpn/transport/secrets/singbox/{profile_id}.json (0600)

8) SSE-события (обязательные)

• singbox_profile_saved
• singbox_profile_validated
• singbox_profile_rendered
• singbox_profile_applied
• singbox_profile_rollback
• singbox_profile_failed

9) Поэтапная реализация (рекомендуемый порядок)

1. E5.1 Requirements freeze (этот документ).
2. E5.2 Go: state/model + CRUD + versioning + secrets storage.
3. E5.3 Go: validate/render/apply/rollback + SSE events.
4. E5.4 GUI: SingBox profiles tab (list/editor/validate/preview/apply/rollback).
5. E5.5 Совместимость web/mobile: reuse того же API-контракта.

10) Критерии готовности E5

• Можно создать/редактировать профиль singbox без ручного правки файлов на хосте.
• Apply проходит через validate и имеет rollback safety.
• Raw-режим позволяет применить фичи, которых нет в typed-форме.
• Наблюдаемость достаточна для диагностики (events + health + last_error + history).