# 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 ##### Основной поток 1. Приложение подключает route adapter к своему host по [API.HTTP.CA-01.FR-01](#apihttpca-01fr-01-подключение-к-host-приложения). #### Функциональные требования ##### 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. ##### Основной поток 1. Клиент вызывает GET /api/v1/health; adapter получает запрос. 2. Adapter запрашивает агрегированный health report по [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов). 3. Adapter сериализует report по [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) и завершает с HEALTH_RESPONSE_RETURNED. ##### Альтернативы и ошибки - Aggregator отклоняет некорректное состояние компонента — adapter передаёт ошибку с кодом HEALTH_INPUT_INVALID по [API.HTTP.CA-02.FR-02](#apihttpca-02fr-02-ошибка-источника-health). ##### Результат Клиент получает текущий агрегированный health status, lifecycle и состояния компонентов приложения. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `HEALTH_RESPONSE_RETURNED` | Агрегированный health report сериализован и возвращён клиенту | [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) | | `HEALTH_INPUT_INVALID` | Aggregator отклонил некорректное состояние компонента | [API.HTTP.CA-02.FR-02](#apihttpca-02fr-02-ошибка-источника-health) | #### Функциональные требования ##### API.HTTP.CA-02.FR-01: Сериализация health-отчёта Adapter возвращает без пересчёта агрегированный health report, включая application_id, lifecycle, итоговый status и состояния компонентов; при успешной сериализации завершает с HEALTH_RESPONSE_RETURNED. Правила агрегирования и состав report задаёт [HL.AG-01](../../../health/aggregation/spec.md). ##### 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](../../../runtime/application-identity/spec.md#rtai-01fr-01-разрешение-идентификатора) | | `lifecycle` | `string` | Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Lifecycle приложения | Копируется из runtime state по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки) | | `status` | `string` | Обязательное | ok, degraded, unhealthy или stopped; null запрещён | Итоговый health status приложения | Рассчитывается aggregator согласно [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов) и [HL.AG-01.FR-02](../../../health/aggregation/spec.md#hlag-01fr-02-результат-агрегации) | | `components` | `array` | Обязательное | 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 зарегистрированы, конфигурация приложения загружена. ##### Основной поток 1. Клиент вызывает POST /api/v1/runtime/start без тела запроса. 2. Adapter запускает приложение по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения). 3. Adapter возвращает итоговый lifecycle status по [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) и завершает с APPLICATION_STARTED. ##### Альтернативы и ошибки - Не удалось запустить один или несколько workers — runtime получает status failed, adapter возвращает его с кодом APPLICATION_START_FAILED по [API.HTTP.CA-03.FR-02](#apihttpca-03fr-02-ошибка-запуска). ##### Результат Клиент получает lifecycle status после попытки запуска приложения. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `APPLICATION_STARTED` | Приложение перешло в lifecycle status running | [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) | | `APPLICATION_START_FAILED` | Запуск приложения завершился ошибкой; lifecycle status равен failed | [API.HTTP.CA-03.FR-02](#apihttpca-03fr-02-ошибка-запуска) | #### Функциональные требования ##### API.HTTP.CA-03.FR-01: Результат запуска Adapter делегирует запуск runtime по [RT.AL-01](../../../runtime/application-lifecycle/spec.md), возвращает 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 зарегистрированы. ##### Основной поток 1. Клиент передаёт параметры остановки в теле POST /api/v1/runtime/stop. 2. Adapter валидирует запрос и делегирует остановку по [RT.AL-02.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-02fr-01-режимы-остановки-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки). 3. Adapter возвращает stopped или stopping по [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) с кодом APPLICATION_STOPPED или APPLICATION_STOPPING. ##### Альтернативы и ошибки - Таймаут ожидания истёк — остановка продолжается, adapter возвращает HTTP 202 и APPLICATION_STOPPING. - Тело или значение timeout невалидно — adapter возвращает HTTP 400 с кодом HTTP_CONTROL_REJECTED по [API.HTTP.CA-04.FR-01](#apihttpca-04fr-01-валидация-запроса-остановки). ##### Результат Клиент получает status stopped после завершения workers либо stopping, пока приложение завершает их работу. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `APPLICATION_STOPPED` | Все workers остановлены; ответ содержит stopped | [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) | | `APPLICATION_STOPPING` | Остановка продолжается после истечения времени ожидания API | [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) | | `HTTP_CONTROL_REJECTED` | Параметры stop-запроса отклонены | [API.HTTP.CA-04.FR-01](#apihttpca-04fr-01-валидация-запроса-остановки) | #### Функциональные требования ##### API.HTTP.CA-04.FR-01: Валидация запроса остановки Adapter принимает объект запроса по контракту ниже; невалидное тело или значение timeout_seconds отклоняется с HTTP 400 и кодом HTTP_CONTROL_REJECTED. Правила остановки определяет [RT.AL-02](../../../runtime/application-lifecycle/spec.md). ##### 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 приложения. ##### Основной поток 1. Клиент вызывает GET /api/v1/runtime/status. 2. Adapter читает lifecycle status без запуска или остановки компонентов по [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status). 3. Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED. ##### Альтернативы и ошибки - Приложение ещё не запускалось или уже остановлено — endpoint возвращает соответственно new или stopped. ##### Результат Клиент получает текущее lifecycle status приложения без изменения его состояния. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `APPLICATION_STATUS_RETURNED` | Текущее lifecycle status сериализовано и возвращено клиенту | [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status) | #### Функциональные требования ##### API.HTTP.CA-05.FR-01: Чтение lifecycle status Adapter читает status без побочных действий и завершает с APPLICATION_STATUS_RETURNED по [RT.AL-01](../../../runtime/application-lifecycle/spec.md) и [RT.AL-02](../../../runtime/application-lifecycle/spec.md). #### 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](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-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-запросов. ##### Основной поток 1. Приложение регистрирует endpoint по [API.HTTP.CA-06.FR-01](#apihttpca-06fr-01-регистрация-endpoint-приложения). 2. Клиент вызывает зарегистрированный путь, а adapter выбирает обработчик по методу и пути по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика). 3. Adapter передаёт запрос обработчику и возвращает созданный им HTTP-ответ. 4. Завершаем с `APPLICATION_ENDPOINT_DISPATCHED` — обработчик получил запрос по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика). ##### Альтернативы и ошибки - Регистрация содержит невалидный или конфликтующий метод и путь — приложение получает `APPLICATION_ENDPOINT_REGISTRATION_REJECTED` по [API.HTTP.CA-06.FR-01](#apihttpca-06fr-01-регистрация-endpoint-приложения). - Путь не зарегистрирован — adapter возвращает HTTP 404 и `HTTP_ROUTE_NOT_FOUND` по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика). - Путь зарегистрирован, но для метода нет обработчика — adapter возвращает HTTP 405 и `HTTP_METHOD_NOT_ALLOWED` по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика). ##### Результат Запросы к endpoint приложения обслуживаются через общий API и listener сервиса. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `APPLICATION_ENDPOINT_DISPATCHED` | Запрос передан зарегистрированному обработчику приложения | [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика) | | `APPLICATION_ENDPOINT_REGISTRATION_REJECTED` | Регистрация endpoint отклонена из-за невалидного или повторяющегося маршрута | [API.HTTP.CA-06.FR-01](#apihttpca-06fr-01-регистрация-endpoint-приложения) | | `HTTP_ROUTE_NOT_FOUND` | Для пути нет зарегистрированного endpoint | [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика) | | `HTTP_METHOD_NOT_ALLOWED` | Для пути нет обработчика указанного HTTP-метода | [API.HTTP.CA-06.FR-02](#apihttpca-06fr-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`.