# 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).