elmprodvpn/docs/phase-a/A1_API_AUDIT.md

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