Files
alex 2f47fc74cf
PLBA package CI / Python tests (push) Successful in 8s
PLBA package CI / Package version increment (push) Skipped
PLBA2-4. Архивация спеки
2026-10-11 11:01:02 +03:00

8.4 KiB
Raw Permalink Blame History

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. Выпустить новую версию пакета после обновления интеграций. Откат к предыдущей версии вернёт старые пути; интеграции на новые пути при таком откате потребуется вернуть к прежним путям одновременно с пакетом.