elmprodvpn/docs/phase-e/E1_MULTI_CLIENT_PBR_DESIGN.md

E1 Дизайн multi-client маршрутизации (PBR)

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

1) Цель

• Спроектировать расширение текущего ядра так, чтобы несколько transport-клиентов (sing-box, dnstt-client, phoenix->slipstream) работали под единым control-plane API.
• Сохранить один источник истины для маршрутизации: только Go-ядро управляет PBR/nft/ip rule, UI только вызывает API.
• Обеспечить безопасную многоклиентную схему без конфликтов: один трафик/сайт не должен одновременно идти через два интерфейса.

2) Текущий baseline (по коду)

• Сейчас модель маршрутизации бинарная: vpn|direct + глобальные MARK/MARK_APP/MARK_DIRECT/MARK_INGRESS.
• Runtime app routing хранится в traffic-appmarks.json, persistent launcher-профили в traffic-app-profiles.json.
• Центр оркестрации: traffic_mode.go, traffic_appmarks.go, routes_update.go.
• Ограничение: нет сущности "клиент-транспорт" как объекта с собственным iface/table/mark.

3) Архитектурный инвариант

• PBR Engine в Go-ядре остается единственным writer для:
  • ip rule,
  • ip route table,
  • nft chains/sets/rules,
  • conntrack mark policy.
• Transport backends (sing-box/dnstt/phoenix) подключаются через backend-адаптеры и не пишут маршруты напрямую.
• UI (desktop/web/iOS/android) оперирует одинаковым API-контрактом, не знает о внутреннем устройстве backend-клиентов.

4) Целевая модель данных

4.1 TransportClient

• id: стабильный ключ (sb-main, dnstt-home, phoenix-eu).
• kind: singbox | dnstt | phoenix.
• enabled: bool.
• status: starting | up | degraded | down.
• iface: фактический интерфейс/туннель.
• routing_table: имя таблицы (agvpn_<id>).
• mark_hex: выделенная fwmark клиента.
• priority_base: базовый диапазон ip rule pref для клиента.
• capabilities: tcp, udp, dns_tunnel, ssh_tunnel.
• health: last_check, latency, last_error.

4.2 RouteIntent

• Нормализованная запись назначения трафика к клиенту:
  • selector_type: domain | cidr | app_key | cgroup | uid.
  • selector_value: значение селектора.
  • client_id: целевой клиент.
  • priority: порядок применения.
  • mode: strict | fallback.

4.3 ConflictRecord

• Запись о конфликте маршрутизации:
  • key: нормализованный ключ пересечения.
  • owners: список client_id.
  • severity: warn | block.
  • reason: человеко-читаемая причина.
  • suggested_resolution: автоматическая подсказка.

5) Схема марков и таблиц (без конфликтов)

5.1 Mark allocator

• Ввести менеджер выделения марков из пула, например:
  • 0x100-0x1FF для client-specific route marks,
  • 0x66/0x67/0x68/0x69 оставить для legacy/системных сценариев.
• Для каждого client_id выделяется:
  • client_mark,
  • client_reply_mark (если нужен отдельный ingress stickiness).

5.2 Table allocator

• Для каждого клиента заводится отдельная routing table:
  • agvpn_sb_main, agvpn_dnstt_home, agvpn_phoenix_eu.
• В таблице только default route через iface клиента + локальные bypass-правила.

5.3 Rule priority allocator

• Для каждого клиента выделяется непересекаемый диапазон pref:
  • пример: 13000-13049 клиент A, 13050-13099 клиент B.
• Это исключает перетирание правил между клиентами при apply/reconcile.

6) Защита от "мешанины" трафика

6.1 Destination ownership lock

• Один домен/cidr/app_key в активной конфигурации может иметь только одного владельца (client_id).
• При пересечении:
  • по умолчанию block (HTTP 409 на apply),
  • опционально force_override с явным подтверждением пользователя.

6.2 Flow stickiness (conntrack)

• Для первого пакета потока проставляется ct mark = client_mark.
• Для последующих пакетов mark восстанавливается из ct mark, чтобы один и тот же flow не перескакивал между интерфейсами.
• Правило действует в output и prerouting, аналогично текущему ingress-reply подходу.

6.3 DNS/IP coherence

• Для domain-based маршрутизации вводится owner-cache:
  • domain -> client_id -> ip set с TTL.
• Один и тот же домен в активной политике не может одновременно резолвиться в разные клиентские set-цепочки.

6.4 Audit/guardrail

• Расширить traffic_audit на multi-client проверки:
  • duplicate destination ownership,
  • overlap CIDR между клиентами,
  • app_key на двух клиентах одновременно,
  • nft/rule drift по client chains.

7) UX дизайн (удобное добавление/переключение)

7.1 Экран "Клиенты"

• Список клиентов: имя, тип, статус, интерфейс, health.
• Действия: Добавить, Включить/Выключить, Перезапустить, Удалить.
• Мастер добавления:
  • Шаг 1: тип клиента (sing-box, dnstt, phoenix),
  • Шаг 2: параметры подключения,
  • Шаг 3: health-check,
  • Шаг 4: назначение default policy.
• Подпункты UX для engine:
  • единый селектор Active engine с вариантами singbox|dnstt|phoenix;
  • быстрые действия Connect, Disconnect, Switch to ...;
  • явное отображение desired_engine vs active_engine;
  • при деградации показывать last_error и action Rollback to previous engine.

7.2 Экран "Маршрутизация"

• Матрица Селектор -> Клиент.
• Массовое назначение списков IP/CIDR/доменов.
• Быстрый переключатель "перенести селектор на другой клиент" с dry-run проверкой конфликтов.

7.3 UX предупреждения

• Перед apply показывать diff:
  • какие селекторы сменят владельца,
  • какие потоки могут быть прерваны,
  • какие конфликты заблокируют применение.
• При force_override обязательное подтверждение пользователя с явным риском:
  • "Один и тот же сайт может потерять стабильность при частой смене интерфейса".
• При switch/connect engine:
  • показывать предупреждение о кратковременном разрыве активных сессий;
  • запрещать параллельные mutating-операции до завершения текущего switch;
  • при failed switch предлагать rollback на предыдущий engine.

8) API-контракт (новые ручки, проект)

• GET /api/v1/transport/clients
• POST /api/v1/transport/clients
• POST /api/v1/transport/clients/{id}/start
• POST /api/v1/transport/clients/{id}/stop
• GET /api/v1/transport/clients/{id}/health
• GET /api/v1/transport/policies
• POST /api/v1/transport/policies/validate
• POST /api/v1/transport/policies/apply
• GET /api/v1/transport/conflicts
• GET /api/v1/transport/capabilities

Принцип:

• Все операции изменения policy идут через validate -> apply.
• apply атомарный: либо вся новая политика применена, либо rollback на предыдущую snapshot-конфигурацию.

9) Реализация по шагам

E1.1 Контракты и состояние

• Ввести state-файлы:
  • transport-clients.json,
  • transport-policies.json,
  • transport-conflicts.json.
• Добавить DTO и минимальные read endpoints.

E1.2 PBR compiler v2

• Реализовать компиляцию RouteIntent в:
  • nft sets/chains per client,
  • ip rule pref ranges per client,
  • table route entries per client.

E1.3 Guardrails

• Валидация ownership/overlap до apply.
• Conntrack stickiness rules для стабильности flow.

E1.4 UX-ready слой

• API предупреждений + dry-run diff.
• SSE события:
  • transport_client_state_changed,
  • transport_policy_applied,
  • transport_conflict_detected.

10) Критерии готовности дизайна

• Можно добавить 2+ клиентов и поднять 2+ интерфейса без перезаписи чужих rule/table.
• Нельзя назначить один и тот же selector двум клиентам без explicit override.
• traffic_audit показывает целостную картину конфликтов и drift.
• UI получает понятные предупреждения до применения рискованной конфигурации.

11) Обратная совместимость

• Текущие /api/v1/traffic/* продолжают работать в legacy-режиме.
• При отсутствии multi-client политики ядро использует текущий single-client pipeline.
• Миграция: legacy vpn|direct может быть автоматически представлена как:
  • client_id=legacy-vpn,
  • client_id=legacy-direct.