# Design ## Context Текущий `ControlApi` — ASGI entrypoint без собственного HTTP server. Он обрабатывает lifespan и вручную сопоставляет четыре встроенных пути в `_dispatch`; прикладных обработчиков в общем API нет. Встроенные endpoints возвращают JSON через `ASGIHttpTransport`. ADR-0001 задаёт целевые внутренние пути `/api/v{version}/...` и внешние пути `/{service-name}/api/v{version}/...`, где Caddy выбирает upstream и удаляет service-префикс. ADR имеет статус `Proposed`; это изменение следует выбранному пользователем целевому направлению, не меняя статус ADR. Изменения конфигурации Caddy находятся вне этого репозитория и scope change. ## Goals / Non-Goals **Goals:** - Сохранить один ASGI entrypoint и listener приложения для встроенных и прикладных endpoints. - Маршрутизировать встроенные endpoints версии `v1` и регистрируемые приложением endpoints через одну таблицу маршрутов. - Передавать прикладным обработчикам полный ASGI request и ответ под контролем приложения. - Сохранить текущие контракты health и lifecycle, изменив только пути встроенных endpoints. **Non-Goals:** - Настройка или деплой Caddy и изменение ingress-конфигурации. - Запуск PLBA собственного HTTP server или открытие отдельного listener. - Совместимость со старыми путями через aliases. - Введение HTTP-фреймворка, схем сериализации, OpenAPI, авторизации или общей обработки тел запросов. - Регистрация и удаление маршрутов после запуска host. ## Decisions 1. **Общий router остаётся внутри `ControlApi`.** `ControlApi` продолжает быть корневым ASGI callable, обрабатывает lifespan и направляет HTTP-запросы во внутренний router. Встроенные endpoints регистрируются в этой же таблице, что и endpoints приложения. Это сохраняет существующий способ подключения PLBA к host и исключает параллельный server. Требование: `API.HTTP.CA-01`. 2. **Приложение передаёт маршруты при сборке зависимостей.** Публичный typed descriptor `HttpRoute` содержит HTTP-метод, path template и ASGI handler. `ControlApi` принимает последовательность таких descriptors при создании; после создания registry неизменяем. Такой constructor injection делает состав API явным в composition root и не допускает гонок с изменением таблицы во время обработки запросов. Это решение покрывает `API.HTTP.CA-06.FR-01`. 3. **Шаблоны путей версионируются и поддерживают именованные сегменты.** Встроенные пути фиксируются на `/api/v1/...`. Каждый прикладной template обязан иметь вид `/api/v<положительное целое число>/<путь>` с хотя бы одним сегментом после версии; параметры записываются отдельным сегментом `{parameter_name}`. Валидатор отклоняет некорректный template, некорректный HTTP-метод, повторяющийся маршрут для одного метода и совпадающие неоднозначные templates равной специфичности. Маршрут с большим числом точных сегментов имеет приоритет; параметры передаются в копии ASGI scope как `path_params`. Требование: `API.HTTP.CA-06.FR-01` и `API.HTTP.CA-06.FR-02`. 4. **Маршрутизация не переписывает запрос приложения.** При совпадении router вызывает handler с ASGI `scope`, `receive` и `send`; handler формирует собственный статус, headers и body. PLBA создаёт только ответы ошибок маршрутизации: 404 для неизвестного пути и 405 для известного пути с неподдерживаемым методом. Ошибки внутри прикладного handler остаются ответственностью приложения и HTTP host. 5. **Старые control paths не сохраняются как aliases.** Все клиенты, health checks и прямые вызовы должны перейти на новые внутренние `/api/v1/...` paths. Во внешнем запросе service slug остаётся префиксом ingress, а Caddy передаёт сервису путь без этого префикса. Это соответствует выбранному варианту ADR-0001; в этом change меняется контракт PLBA, но не конфигурация Caddy. 6. **API-изменение требует обновления версии пакета.** Так как публичные пути меняются с несовместимостью и добавляется возможность регистрации endpoints, версия пакета обновляется согласно проектной политике в последней задаче implementation change. ## Risks / Trade-offs - **Существующие вызовы по `/health` и `/runtime/...` перестанут работать** → обновить клиентов, health checks и интеграционные примеры на `/api/v1/...` в рамках релиза; старые aliases не вводить. - **ASGI handler требует от приложения самостоятельно формировать response** → экспортировать descriptor и документировать минимальный пример регистрации и ответа. - **Пересечение templates может дать неожиданный выбор маршрута** → маршрут с большим числом точных сегментов получает приоритет, а неоднозначные шаблоны равной специфичности отклоняются при сборке registry. - **Публичный URL зависит от настройки Caddy для service slug** → описать внешний и внутренний пути в документации PLBA; конфигурация ingress выполняется отдельно. ## Migration Plan 1. Реализовать общий router и регистрацию `HttpRoute`, сохранив текущие health/lifecycle handlers. 2. Перенести встроенные endpoints на `/api/v1/...` и обновить документацию и проверки PLBA. 3. Обновить потребителей API и конфигурации health checks так, чтобы они использовали versioned paths; для платформенного доступа настроить Caddy на внешний `/{service-name}/api/v{version}/...` и передачу внутреннего `/api/v{version}/...`. 4. Выпустить новую версию пакета после обновления интеграций. Откат к предыдущей версии вернёт старые пути; интеграции на новые пути при таком откате потребуется вернуть к прежним путям одновременно с пакетом.