26 KiB
Capability: HTTP API управления приложением
Purpose
Объединить health, управление lifecycle приложения и endpoints приложения в одном HTTP API, подключаемом к host приложения.
Границы
- В capability входят встроенные маршруты
/api/v1/health,/api/v1/runtime/start,/api/v1/runtime/stopи/api/v1/runtime/status, а также регистрация прикладных endpoints в том же HTTP host и listener. - Приложение владеет HTTP host, listener и логикой собственных endpoints; Caddy отвечает за внешний service-prefix и маршрутизацию к сервису.
Requirements
Requirement: Единый HTTP adapter
ID: API.HTTP.CA-01
PLBA2 SHALL предоставлять единую точку маршрутизации для встроенных HTTP endpoints PLBA и endpoints, зарегистрированных приложением; adapter подключается к host приложения и использует его единственный listener.
Scenario: Сокращенный use case: подключение control API
Основной поток
- Приложение подключает route adapter к своему host по API.HTTP.CA-01.FR-01.
Функциональные требования
API.HTTP.CA-01.FR-01: Подключение к host приложения
Приложение подключает один ASGI adapter к собственному HTTP host. Adapter маршрутизирует встроенные endpoints PLBA и endpoints приложения через общий route registry и тот же listener. PLBA2 не запускает HTTP server и не открывает отдельный порт.
Requirement: Health через GET /api/v1/health
ID: API.HTTP.CA-02
PLBA2 SHALL возвращать агрегированный health report приложения через GET /api/v1/health.
Scenario: Получение health-отчёта через GET /health
Участники
- HTTP-клиент, route adapter PLBA2 и health aggregator.
Предусловия
- Control API подключён к host приложения.
- Health aggregator получает состояния зарегистрированных workers и contributors.
Основной поток
- Клиент вызывает GET /api/v1/health; adapter получает запрос.
- Adapter запрашивает агрегированный health report по HL.AG-01.FR-01.
- Adapter сериализует report по API.HTTP.CA-02.FR-01 и завершает с HEALTH_RESPONSE_RETURNED.
Альтернативы и ошибки
- Aggregator отклоняет некорректное состояние компонента — adapter передаёт ошибку с кодом HEALTH_INPUT_INVALID по API.HTTP.CA-02.FR-02.
Результат
Клиент получает текущий агрегированный health status, lifecycle и состояния компонентов приложения.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
HEALTH_RESPONSE_RETURNED |
Агрегированный health report сериализован и возвращён клиенту | API.HTTP.CA-02.FR-01 |
HEALTH_INPUT_INVALID |
Aggregator отклонил некорректное состояние компонента | API.HTTP.CA-02.FR-02 |
Функциональные требования
API.HTTP.CA-02.FR-01: Сериализация health-отчёта
Adapter возвращает без пересчёта агрегированный health report, включая application_id, lifecycle, итоговый status и состояния компонентов; при успешной сериализации завершает с HEALTH_RESPONSE_RETURNED. Правила агрегирования и состав report задаёт HL.AG-01.
API.HTTP.CA-02.FR-02: Ошибка источника health
Если health aggregator отклоняет входное состояние, adapter передаёт ошибку HEALTH_INPUT_INVALID и не подменяет причину или повторно не рассчитывает статусы.
CONTRACT
Request
Метод: GET; путь: /api/v1/health. Тело запроса и query-параметры отсутствуют.
Response
HTTP status: 200 при успешной сериализации health report.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
|---|---|---|---|---|---|
application_id |
string |
Обязательное | null запрещён | Идентификатор приложения | Берётся из runtime context по RT.AI-01.FR-01 |
lifecycle |
string |
Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Lifecycle приложения | Копируется из runtime state по RT.AL-01.FR-01 и RT.AL-02.FR-02 |
status |
string |
Обязательное | ok, degraded, unhealthy или stopped; null запрещён | Итоговый health status приложения | Рассчитывается aggregator согласно HL.AG-01.FR-01 и HL.AG-01.FR-02 |
components |
array<object> |
Обязательное | null запрещён; пустой массив допустим | Health-состояния workers и contributors | Содержит состояния, переданные aggregator; workers с disabled: true исключены |
components[].name |
string |
Обязательное | null запрещён | Имя worker или health contributor | Копируется из имени, с которым компонент зарегистрирован в приложении |
components[].status |
string |
Обязательное | ok, degraded или unhealthy; null запрещён | Health status компонента | Копируется из переданного компонентом health-состояния |
components[].critical |
boolean |
Обязательное | null запрещён | Влияние компонента на общий health | Копируется из признака critical, переданного при регистрации или health-отчёте |
components[].detail |
string or null |
Обязательное | null допустим | Краткое пояснение состояния | Копируется из detail health-состояния; при отсутствии передаётся null |
components[].meta |
object |
Обязательное | null запрещён | Дополнительные структурированные данные | Копируется из meta health-состояния; при отсутствии передаётся пустой объект |
Requirement: Запуск приложения через POST /api/v1/runtime/start
ID: API.HTTP.CA-03
PLBA2 SHALL запускать приложение по запросу POST /api/v1/runtime/start и возвращать итоговый lifecycle status.
Scenario: Запуск приложения через POST /runtime/start
Участники
- HTTP-клиент, route adapter PLBA2, runtime и workers приложения.
Предусловия
- Control API подключён, workers зарегистрированы, конфигурация приложения загружена.
Основной поток
- Клиент вызывает POST /api/v1/runtime/start без тела запроса.
- Adapter запускает приложение по RT.AL-01.FR-01.
- Adapter возвращает итоговый lifecycle status по API.HTTP.CA-03.FR-01 и завершает с APPLICATION_STARTED.
Альтернативы и ошибки
- Не удалось запустить один или несколько workers — runtime получает status failed, adapter возвращает его с кодом APPLICATION_START_FAILED по API.HTTP.CA-03.FR-02.
Результат
Клиент получает lifecycle status после попытки запуска приложения.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
APPLICATION_STARTED |
Приложение перешло в lifecycle status running | API.HTTP.CA-03.FR-01 |
APPLICATION_START_FAILED |
Запуск приложения завершился ошибкой; lifecycle status равен failed | API.HTTP.CA-03.FR-02 |
Функциональные требования
API.HTTP.CA-03.FR-01: Результат запуска
Adapter делегирует запуск runtime по RT.AL-01, возвращает APPLICATION_STARTED после успешного запуска и lifecycle status running.
API.HTTP.CA-03.FR-02: Ошибка запуска
Если запуск одного или нескольких workers завершается ошибкой, runtime устанавливает status failed; adapter возвращает APPLICATION_START_FAILED и status failed.
CONTRACT
Request
Метод: POST; путь: /api/v1/runtime/start. Тело запроса отсутствует.
Response
HTTP status: 200 после обработки запроса запуска; результат запуска передаётся в поле status.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
|---|---|---|---|---|---|
status |
string |
Обязательное | running или failed; null запрещён | Итоговый lifecycle status после запуска | running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED |
Requirement: Остановка приложения через POST /api/v1/runtime/stop
ID: API.HTTP.CA-04
PLBA2 SHALL останавливать приложение через POST /api/v1/runtime/stop и возвращать его актуальный lifecycle status.
Scenario: Остановка приложения через POST /runtime/stop
Участники
- HTTP-клиент, route adapter PLBA2, runtime, supervisor и workers приложения.
Предусловия
- Control API подключён, приложение запущено, workers зарегистрированы.
Основной поток
- Клиент передаёт параметры остановки в теле POST /api/v1/runtime/stop.
- Adapter валидирует запрос и делегирует остановку по RT.AL-02.FR-01 и RT.AL-02.FR-02.
- Adapter возвращает stopped или stopping по API.HTTP.CA-04.FR-02 с кодом APPLICATION_STOPPED или APPLICATION_STOPPING.
Альтернативы и ошибки
- Таймаут ожидания истёк — остановка продолжается, adapter возвращает HTTP 202 и APPLICATION_STOPPING.
- Тело или значение timeout невалидно — adapter возвращает HTTP 400 с кодом HTTP_CONTROL_REJECTED по API.HTTP.CA-04.FR-01.
Результат
Клиент получает status stopped после завершения workers либо stopping, пока приложение завершает их работу.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
APPLICATION_STOPPED |
Все workers остановлены; ответ содержит stopped | API.HTTP.CA-04.FR-02 |
APPLICATION_STOPPING |
Остановка продолжается после истечения времени ожидания API | API.HTTP.CA-04.FR-02 |
HTTP_CONTROL_REJECTED |
Параметры stop-запроса отклонены | API.HTTP.CA-04.FR-01 |
Функциональные требования
API.HTTP.CA-04.FR-01: Валидация запроса остановки
Adapter принимает объект запроса по контракту ниже; невалидное тело или значение timeout_seconds отклоняется с HTTP 400 и кодом HTTP_CONTROL_REJECTED. Правила остановки определяет RT.AL-02.
API.HTTP.CA-04.FR-02: Результат остановки
Без timeout_seconds adapter ожидает завершения всех workers без ограничения времени. force=true прерывает активную обработку; timeout ограничивает ожидание ответа и не включает force. Если workers завершились, adapter возвращает HTTP 200, status stopped и APPLICATION_STOPPED. При истечении timeout он возвращает HTTP 202, status stopping и APPLICATION_STOPPING; остановка продолжается.
CONTRACT
Request
Метод: POST; путь: /api/v1/runtime/stop. Тело запроса — JSON object.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
|---|---|---|---|---|
force |
boolean |
Опциональное | null запрещён; по умолчанию false | Принудительно прервать активную обработку workers |
timeout_seconds |
number |
Опциональное | Положительное число секунд; null запрещён; отсутствие означает неограниченное ожидание | Ограничить время ожидания завершения workers |
Response
HTTP status: 200, если остановка завершена; 202, если она продолжается после истечения timeout; 400 для отклонённого запроса.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
|---|---|---|---|---|---|
status |
string |
Обязательное | Для HTTP 200 — stopped; для HTTP 202 — stopping; null запрещён | Текущий lifecycle status приложения | Берётся из runtime: stopped после остановки всех workers; stopping, пока их остановка продолжается |
Requirement: Lifecycle status через GET /api/v1/runtime/status
ID: API.HTTP.CA-05
PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /api/v1/runtime/status.
Scenario: Чтение lifecycle status через GET /runtime/status
Участники
- HTTP-клиент, route adapter PLBA2 и runtime приложения.
Предусловия
- Control API подключён к host приложения.
Основной поток
- Клиент вызывает GET /api/v1/runtime/status.
- Adapter читает lifecycle status без запуска или остановки компонентов по API.HTTP.CA-05.FR-01.
- Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED.
Альтернативы и ошибки
- Приложение ещё не запускалось или уже остановлено — endpoint возвращает соответственно new или stopped.
Результат
Клиент получает текущее lifecycle status приложения без изменения его состояния.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
APPLICATION_STATUS_RETURNED |
Текущее lifecycle status сериализовано и возвращено клиенту | API.HTTP.CA-05.FR-01 |
Функциональные требования
API.HTTP.CA-05.FR-01: Чтение lifecycle status
Adapter читает status без побочных действий и завершает с APPLICATION_STATUS_RETURNED по RT.AL-01 и RT.AL-02.
CONTRACT
Request
Метод: GET; путь: /api/v1/runtime/status. Тело запроса и query-параметры отсутствуют.
Response
HTTP status: 200 при успешном чтении lifecycle status.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
|---|---|---|---|---|---|
status |
string |
Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Текущее lifecycle status приложения | Копируется без пересчёта из runtime state по RT.AL-01.FR-01 и RT.AL-02.FR-02 |
Requirement: Регистрация прикладных HTTP endpoints
ID: API.HTTP.CA-06
PLBA2 SHALL позволять приложению регистрировать собственные HTTP endpoints в общей маршрутизации и передавать им запросы через listener приложения.
Scenario: Регистрация и вызов прикладного HTTP endpoint
Участники
- Composition root приложения, общий HTTP adapter PLBA2, обработчик приложения и HTTP-клиент.
Предусловия
- Приложение создало HTTP adapter PLBA2.
- Обработчик приложения реализует ASGI callable для требуемых HTTP-запросов.
Основной поток
- Приложение регистрирует endpoint по API.HTTP.CA-06.FR-01.
- Клиент вызывает зарегистрированный путь, а adapter выбирает обработчик по методу и пути по API.HTTP.CA-06.FR-02.
- Adapter передаёт запрос обработчику и возвращает созданный им HTTP-ответ.
- Завершаем с
APPLICATION_ENDPOINT_DISPATCHED— обработчик получил запрос по API.HTTP.CA-06.FR-02.
Альтернативы и ошибки
- Регистрация содержит невалидный или конфликтующий метод и путь — приложение получает
APPLICATION_ENDPOINT_REGISTRATION_REJECTEDпо API.HTTP.CA-06.FR-01. - Путь не зарегистрирован — adapter возвращает HTTP 404 и
HTTP_ROUTE_NOT_FOUNDпо API.HTTP.CA-06.FR-02. - Путь зарегистрирован, но для метода нет обработчика — adapter возвращает HTTP 405 и
HTTP_METHOD_NOT_ALLOWEDпо API.HTTP.CA-06.FR-02.
Результат
Запросы к endpoint приложения обслуживаются через общий API и listener сервиса.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
APPLICATION_ENDPOINT_DISPATCHED |
Запрос передан зарегистрированному обработчику приложения | API.HTTP.CA-06.FR-02 |
APPLICATION_ENDPOINT_REGISTRATION_REJECTED |
Регистрация endpoint отклонена из-за невалидного или повторяющегося маршрута | API.HTTP.CA-06.FR-01 |
HTTP_ROUTE_NOT_FOUND |
Для пути нет зарегистрированного endpoint | API.HTTP.CA-06.FR-02 |
HTTP_METHOD_NOT_ALLOWED |
Для пути нет обработчика указанного HTTP-метода | API.HTTP.CA-06.FR-02 |
Функциональные требования
API.HTTP.CA-06.FR-01: Регистрация endpoint приложения
Приложение передаёт adapter-у типизированное описание endpoint, содержащее HTTP-метод, шаблон пути и ASGI callable обработчика. Регистрация выполняется до запуска HTTP host. Шаблон должен начинаться с /api/v{version}/..., где {version} — положительное целое число, и содержать хотя бы один сегмент после версии; параметры пути задаются отдельным именованным сегментом {parameter_name}. Невалидный HTTP-метод, шаблон без версии, повторяющаяся пара метода и шаблона или два маршрута одного метода с одинаковой специфичностью, способные совпасть с одним путём, отклоняются с APPLICATION_ENDPOINT_REGISTRATION_REJECTED; регистрация не создаёт HTTP response.
API.HTTP.CA-06.FR-02: Сопоставление маршрута и вызов обработчика
Adapter сопоставляет запросы по HTTP-методу и пути в общей таблице встроенных и прикладных endpoints. Маршрут с большим числом точных сегментов имеет приоритет над маршрутом с параметрами; неоднозначные шаблоны равной специфичности отклоняются при регистрации. Значения именованных сегментов передаются обработчику в scope["path_params"] как строки. Adapter передаёт обработчику ASGI scope, receive и send, добавляя path_params в копию scope; обработчик формирует HTTP status, headers и body ответа, а adapter завершает с APPLICATION_ENDPOINT_DISPATCHED. При отсутствии совпадающего пути adapter возвращает HTTP 404 с HTTP_ROUTE_NOT_FOUND; если путь совпадает, но метод не разрешён, возвращает HTTP 405 с HTTP_METHOD_NOT_ALLOWED.