elmprodvpn/docs/phase-f/F3_CORE_MODULE_LIBRARY_PLAN.md

F3 План: библиотека модулей Go-ядра (deferred)

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

1) Цель

• Подготовить ядро к формату внутренней библиотеки модулей, чтобы backend собирался из чётких переиспользуемых пакетов.
• Снизить связность app/* и закрепить стабильные интерфейсы orchestration/PBR/transport/resolver.

2) Принцип scope

• linux-first: библиотека ориентирована на Linux runtime backend.
• netns — отладочный/инфраструктурный модуль для backend/desktop тестового контура.
• mobile (iOS/Android) не является целью для netns-модуля.
• Для mobile не планируется netns слой: только вызовы backend API (control-plane), без platform-specific system hooks.
• GUI/Web/Mobile должны использовать только API control-plane, а не прямые системные модули.

3) Целевые пакеты

• pkg/orchestrator — lifecycle orchestration (prepare/start/stop/restart/rollback) и locking.
• pkg/transport — shared transport-модели/валидация/runtime helpers.
• pkg/pbr — marks/tables/prefs allocator + compiler.
• pkg/resolver — resolver policy/execution primitives.
• pkg/netnsdebug (или pkg/netns) — Linux-only netns setup/cleanup helpers для debug/test-contour.

4) Шаги реализации (будущий этап)

1. Выделить публичные интерфейсы зависимостей (runner, nft/ip adapters, state store, logger).
2. Перенести код в pkg/* без изменения поведения.
3. Оставить app/* как thin-facade + HTTP слой.
4. Добавить compile/runtime guardrails для Linux-only модулей.
5. Обновить runbook миграции и интеграционные чеклисты.

5) Критерии готовности

• Backend-сборка не зависит от монолитных app/* helper-блоков.
• netns модуль чётко помечен как Linux-only и debug/test-oriented.
• Внешние API (/api/v1/*) не меняются.
• go test ./... зелёный после миграции.