A1 Аудит API и HTTP-маршрутов

Дата: 2026-02-27 Статус: draft Владелец: Engineering

1) Цель

Подтвердить, что все пользовательские сценарии (статусы, смена режимов, управление маршрутами, DNS, VPN, SmartDNS, trace) реализованы в Go-ядре и доступны через единую REST-SSE оболочку.
Зафиксировать текущую структуру /api/v1/*, SSE /api/v1/events/stream и CLI-режимов (routes-update, routes-clear, autoloop) как основу для будущего веб-интерфейса.

1.1) Факт по коду (точный baseline)

Источник: selective-vpn-api/app/server.go.
Зарегистрировано 61 mux.HandleFunc(...).
Из них:
- 60 endpoint под /api/v1/*.
- 1 сервисный endpoint /healthz.
CLI режимы в Run(): routes-update, routes-clear, autoloop.
Изменение от 2026-03-07: в transport добавлены 8 base route (/api/v1/transport/*) и action-subpath GET /api/v1/transport/clients/{id}/metrics.

2) Критерии завершения

Таблица endpoint → handler-файл / CLI mode составлена и вынесена в документ (см. Phase A).
Подтверждено, что GUI не содержит альтернативных реализаций бизнес-логики (всё идет через Go API).
Описаны ответы (CmdResult, dataclasses) и форматы, которые нужно сохранять для веба.

3) Задачи

Выписать все маршруты из selective-vpn-api/app/server.go и сопоставить их с файлами-обработчиками (routes_handlers.go, traffic_mode.go, dns_settings.go, vpn_handlers.go, smartdns_runtime.go, trace_handlers.go, traffic_appmarks.go и др.).
Отметить CLI-флаги и специальные пути (/routes/update, /routes/timer, /routes/rollback, trace, SmartDNS, VPN login) и их привязку к Go-механикам.
Проверить selective-vpn-gui/api_client.py на факт наличия всех URL/методов/форматов и зафиксировать зависимости.
Подготовить краткое описание (для фазы A) о том, какие маршруты уже готовы к прямому вызову чере веб (без правок).

4) Состояние (черновик таблицы)

Endpoint	HTTP	Handler file	Краткая логика	Требования
`/api/v1/status`, `/api/v1/routes/status`	GET	`routes_handlers.go`	Чтение `status.json`, вычисление policy-route через nftables	Файл `status.json`, доступ к nftables
`/api/v1/routes/service[*]`	POST	`routes_handlers.go`	`systemctl start	stop
`/api/v1/routes/update`	POST	`routes_handlers.go` → `routes_update.go`	Сообщает о ручном апдейте через Go-реализацию вместо bash → обновляет set и policy	NFT/state dirs, `stateDir`, `preferredIface`
`/api/v1/routes/timer`, `/routes/timer/toggle`	GET/POST	`routes_handlers.go`	Чтение/запись enable flag для таймера, использует `runRoutesTimerSet`	Файл таймера, systemd
`/api/v1/traffic/mode`, `/traffic/mode/test`	GET/POST	`traffic_mode.go`	Переключает режимы Selective/Full/Direct, включает auto bypass, проверка `TrafficModeState`	Состояние в `stateDir`, доступ к nftables/systemd
`/api/v1/dns-upstreams`, `/api/v1/dns/mode`, `/api/v1/dns/benchmark`	GET/POST	`dns_settings.go`	Управление DNS upstreams, режимом и benchmark (проверка резольвера)	`resolv.conf`, `dnsmaestro`, `SmartDNS`
`/api/v1/vpn/status`, `/api/v1/vpn/autoloop*`	GET/POST	`vpn_handlers.go`	Статусы VPN, управление autoloop/autoconnect (через AdGuard VPN API)	Доступ к AdGuard VPN API, PTY
`/api/v1/events/stream`	GET SSE	`events_handlers.go` / `events_bus.go`	SSE-поток статусов и логов для GUI	Доступ к event bus, `ctx`
`/api/v1/trace`, `/api/v1/trace-json`, `/api/v1/trace/append`	GET/POST	`trace_handlers.go`	tail/JSON/append лог-файла `trace.log`	Доступ к `trace.log`, root
`/api/v1/traffic/advanced/reset`	POST	`traffic_mode.go`	Сброс расширенных bypass-опций (auto-local, ingress)	Доступ к traffic state
`/api/v1/traffic/interfaces`	GET	`traffic_mode.go`	Список интерфейсов и предпочитаемый iface	Просмотр `iproute2` interfaces
`/api/v1/traffic/candidates`	GET	`traffic_candidates.go`	Выборка потенциальных подсетей для bypass	`nft`/routing discovery
`/api/v1/traffic/appmarks`	POST	`traffic_appmarks.go`	Управление cgroup mark (vpn/direct)	`cgroup v2`, systemd scopes
`/api/v1/traffic/appmarks/items`	GET	`traffic_appmarks.go`	Список runtime marks для UI	`cgroup v2` info
`/api/v1/traffic/app-profiles`	GET/POST/DELETE	`traffic_app_profiles.go`	CRUD профилей запуска приложений	Хранение в `stateDir`
`/api/v1/traffic/audit`	GET	`traffic_audit.go`	Проверки консистентности nft/route	Доступ к nft\logs
`/api/v1/vpn/autoloop-status`	GET	`vpn_handlers.go`	Статус autoloop watcher	AdGuard VPN API
`/api/v1/vpn/status`	GET	`vpn_handlers.go`	Общий статус VPN/traffic	AdGuard VPN API
`/api/v1/vpn/autoconnect`	POST	`vpn_handlers.go`	Переключение autoconnect	AdGuard VPN API
`/api/v1/vpn/locations`	GET	`vpn_handlers.go`	Список стран/регионов	AdGuard VPN API (locations)
`/api/v1/vpn/location`	POST	`vpn_handlers.go`	Установка нового location	AdGuard VPN API
`/api/v1/vpn/login/session/*`	POST/GET	`vpn_login_session.go`	Установка интерактивной PTY сессии, проверки, действия	PTY, systemd user session
`/api/v1/vpn/logout`	POST	`vpn_handlers.go`	Выход VPN	AdGuard VPN API
`/api/v1/dns/upstream-pool`	GET/POST	`dns_settings.go`	pool upstreams (итоги)	`dns_upstreams` state
`/api/v1/dns/status`	GET	`dns_settings.go`	Текущий upstreams и режим	`resolver` состояние
`/api/v1/dns/smartdns-service`	POST	`dns_settings.go`	Старт/стоп SmartDNS сервис	`smartdns` бинарь, systemd unit
`/api/v1/smartdns/service`	POST	`smartdns_runtime.go`	Управление SmartDNS runtime	systemd + config
`/api/v1/smartdns/runtime`	GET	`smartdns_runtime.go`	Получение runtime stats	СмартДНС статус
`/api/v1/smartdns/prewarm`	POST	`smartdns_runtime.go`	Прогрев wildcard-базы	smartdns runtime
`/api/v1/domains/table`	GET/POST	`domains_handlers.go`	Загрузка/сохранение таблицы доменов	Файл доменов
`/api/v1/domains/file`	GET	`domains_handlers.go`	Скачать raw файл доменов	Доступ к `domains.json`
`/api/v1/smartdns/wildcards`	GET/POST	`smartdns_wildcards_store.go`	CRUD wildcard-списка	`wildcards.json`

Это рабочая матрица для ключевых сценариев. Полный реестр endpoint’ов из server.go приведён ниже.

5) GUI → API

selective-vpn-gui/api_client.py инкапсулирует все URL/методы/JSON-форматы (например, TrafficModeStatus, TrafficAppMarkItem, CmdResult), поэтому при замене фронта достаточно реализовать аналогичные dataclasses в новой веб-части.
dashboard_controller.py использует эти модели, подписывается на SSE и отображает текущий статус/trace. Нужно подтвердить, что в GUI нет logic-branch (например, расчёт маршрутов), которая должна перейти в веб отдельно.
Задача анализа: пробежать по api_client.py и dashboard_controller.py и отметить все вызовы; в Phase D перенести их в колонку “UI usage” для проверки совместимости.

6) CLI-режимы и API parity

routes-update / selective-vpn-api routes-update — запускает ту же логику, что и POST /api/v1/routes/update, но без HTTP-запросов; используется для cron/автообновления.
routes-clear / /api/v1/routes/rollback — очищает nftables/statestatus; веб должен предоставить rollback-кнопку, чтобы совпадал функционал CLI.
autoloop — опрашивает AdGuard VPN API и пишет autoloop.log; веб потребляет статус через /api/v1/vpn/autoloop-status и SSE события watchers.

7) Полный реестр endpoint (из `server.go`)

/healthz
/api/v1/events/stream
/api/v1/status
/api/v1/routes/status
/api/v1/vpn/login-state
/api/v1/systemd/state
/api/v1/routes/service/start
/api/v1/routes/service/stop
/api/v1/routes/service/restart
/api/v1/routes/service
/api/v1/routes/update
/api/v1/routes/timer
/api/v1/routes/timer/toggle
/api/v1/routes/rollback
/api/v1/routes/clear
/api/v1/routes/cache/restore
/api/v1/routes/precheck/debug
/api/v1/routes/fix-policy-route
/api/v1/routes/fix-policy
/api/v1/traffic/mode
/api/v1/traffic/mode/test
/api/v1/traffic/advanced/reset
/api/v1/traffic/interfaces
/api/v1/traffic/candidates
/api/v1/traffic/appmarks
/api/v1/traffic/appmarks/items
/api/v1/traffic/app-profiles
/api/v1/traffic/audit
/api/v1/trace
/api/v1/trace-json
/api/v1/trace/append
/api/v1/dns-upstreams
/api/v1/dns/upstream-pool
/api/v1/dns/status
/api/v1/dns/mode
/api/v1/dns/benchmark
/api/v1/dns/smartdns-service
/api/v1/smartdns/service
/api/v1/smartdns/runtime
/api/v1/smartdns/prewarm
/api/v1/domains/table
/api/v1/domains/file
/api/v1/smartdns/wildcards
/api/v1/vpn/autoloop-status
/api/v1/vpn/status
/api/v1/vpn/autoconnect
/api/v1/vpn/locations
/api/v1/vpn/location
/api/v1/vpn/login/session/start
/api/v1/vpn/login/session/state
/api/v1/vpn/login/session/action
/api/v1/vpn/login/session/stop
/api/v1/vpn/logout
/api/v1/transport/clients
/api/v1/transport/clients/{id}
/api/v1/transport/clients/{id}/start
/api/v1/transport/clients/{id}/stop
/api/v1/transport/clients/{id}/restart
/api/v1/transport/clients/{id}/health
/api/v1/transport/policies
/api/v1/transport/policies/validate
/api/v1/transport/policies/apply
/api/v1/transport/policies/rollback
/api/v1/transport/conflicts
/api/v1/transport/capabilities

12 KiB Raw Permalink Blame History Unescape Escape

A1 Аудит API и HTTP-маршрутов

1) Цель

1.1) Факт по коду (точный baseline)

2) Критерии завершения

3) Задачи

4) Состояние (черновик таблицы)

5) GUI → API

6) CLI-режимы и API parity

7) Полный реестр endpoint (из server.go)

12 KiB

Raw Permalink Blame History

7) Полный реестр endpoint (из `server.go`)