8.4 KiB
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
-
Общий router остаётся внутри
ControlApi.ControlApiпродолжает быть корневым ASGI callable, обрабатывает lifespan и направляет HTTP-запросы во внутренний router. Встроенные endpoints регистрируются в этой же таблице, что и endpoints приложения. Это сохраняет существующий способ подключения PLBA к host и исключает параллельный server. Требование:API.HTTP.CA-01. -
Приложение передаёт маршруты при сборке зависимостей. Публичный typed descriptor
HttpRouteсодержит HTTP-метод, path template и ASGI handler.ControlApiпринимает последовательность таких descriptors при создании; после создания registry неизменяем. Такой constructor injection делает состав API явным в composition root и не допускает гонок с изменением таблицы во время обработки запросов. Это решение покрываетAPI.HTTP.CA-06.FR-01. -
Шаблоны путей версионируются и поддерживают именованные сегменты. Встроенные пути фиксируются на
/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. -
Маршрутизация не переписывает запрос приложения. При совпадении router вызывает handler с ASGI
scope,receiveиsend; handler формирует собственный статус, headers и body. PLBA создаёт только ответы ошибок маршрутизации: 404 для неизвестного пути и 405 для известного пути с неподдерживаемым методом. Ошибки внутри прикладного handler остаются ответственностью приложения и HTTP host. -
Старые control paths не сохраняются как aliases. Все клиенты, health checks и прямые вызовы должны перейти на новые внутренние
/api/v1/...paths. Во внешнем запросе service slug остаётся префиксом ingress, а Caddy передаёт сервису путь без этого префикса. Это соответствует выбранному варианту ADR-0001; в этом change меняется контракт PLBA, но не конфигурация Caddy. -
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
- Реализовать общий router и регистрацию
HttpRoute, сохранив текущие health/lifecycle handlers. - Перенести встроенные endpoints на
/api/v1/...и обновить документацию и проверки PLBA. - Обновить потребителей API и конфигурации health checks так, чтобы они использовали versioned paths; для платформенного доступа настроить Caddy на внешний
/{service-name}/api/v{version}/...и передачу внутреннего/api/v{version}/.... - Выпустить новую версию пакета после обновления интеграций. Откат к предыдущей версии вернёт старые пути; интеграции на новые пути при таком откате потребуется вернуть к прежним путям одновременно с пакетом.