PLBA2-4. Архивация спеки
This commit is contained in:
@@ -0,0 +1,52 @@
|
||||
# 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. Выпустить новую версию пакета после обновления интеграций. Откат к предыдущей версии вернёт старые пути; интеграции на новые пути при таком откате потребуется вернуть к прежним путям одновременно с пакетом.
|
||||
Reference in New Issue
Block a user