Files
plba_v2/openspec/changes/plba2-runtime-and-adapters/specs/api/http/control-api/spec.md
T

19 KiB
Raw Blame History

Spec Delta

Purpose

Объединить health и управление lifecycle приложения в одном HTTP API, подключаемом к host приложения.

ADDED Requirements

Requirement: Единый HTTP adapter

ID: API.HTTP.CA-01

PLBA2 SHALL предоставлять один route adapter для всех HTTP endpoints управления приложением; adapter подключается к host приложения и использует его единственный listener.

Scenario: Сокращенный use case: подключение control API

Основной поток
  1. Приложение подключает route adapter к своему host по API.HTTP.CA-01.FR-01.

Функциональные требования

API.HTTP.CA-01.FR-01: Подключение к host приложения

Приложение подключает route adapter к собственному HTTP host. Все endpoints control API используют его listener и порт. PLBA2 не запускает HTTP server и не открывает отдельный порт; adapter делегирует обработку соответствующим capabilities.

Requirement: Health через GET /health

ID: API.HTTP.CA-02

PLBA2 SHALL возвращать агрегированный health report приложения через GET /health.

Scenario: Получение health-отчёта через GET /health

Участники
  • HTTP-клиент, route adapter PLBA2 и health aggregator.
Предусловия
  • Control API подключён к host приложения.
  • Health aggregator получает состояния зарегистрированных workers и contributors.
Основной поток
  1. Клиент вызывает GET /health; adapter получает запрос.
  2. Adapter запрашивает агрегированный health report по HL.AG-01.FR-01.
  3. 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; путь: /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 /runtime/start

ID: API.HTTP.CA-03

PLBA2 SHALL запускать приложение по запросу POST /runtime/start и возвращать итоговый lifecycle status.

Scenario: Запуск приложения через POST /runtime/start

Участники
  • HTTP-клиент, route adapter PLBA2, runtime и workers приложения.
Предусловия
  • Control API подключён, workers зарегистрированы, конфигурация приложения загружена.
Основной поток
  1. Клиент вызывает POST /runtime/start без тела запроса.
  2. Adapter запускает приложение по RT.AL-01.FR-01.
  3. 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; путь: /runtime/start. Тело запроса отсутствует.

Response

HTTP status: 200 после обработки запроса запуска; результат запуска передаётся в поле status.

Поле Тип Обязательность Ограничения и значение по умолчанию Назначение Формирование значения
status string Обязательное running или failed; null запрещён Итоговый lifecycle status после запуска running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED

Requirement: Остановка приложения через POST /runtime/stop

ID: API.HTTP.CA-04

PLBA2 SHALL останавливать приложение через POST /runtime/stop и возвращать его актуальный lifecycle status.

Scenario: Остановка приложения через POST /runtime/stop

Участники
  • HTTP-клиент, route adapter PLBA2, runtime, supervisor и workers приложения.
Предусловия
  • Control API подключён, приложение запущено, workers зарегистрированы.
Основной поток
  1. Клиент передаёт параметры остановки в теле POST /runtime/stop.
  2. Adapter валидирует запрос и делегирует остановку по RT.AL-02.FR-01 и RT.AL-02.FR-02.
  3. 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; путь: /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 /runtime/status

ID: API.HTTP.CA-05

PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /runtime/status.

Scenario: Чтение lifecycle status через GET /runtime/status

Участники
  • HTTP-клиент, route adapter PLBA2 и runtime приложения.
Предусловия
  • Control API подключён к host приложения.
Основной поток
  1. Клиент вызывает GET /runtime/status.
  2. Adapter читает lifecycle status без запуска или остановки компонентов по API.HTTP.CA-05.FR-01.
  3. 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; путь: /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