PLBA2-2. Архивация спек
This commit is contained in:
@@ -0,0 +1,284 @@
|
||||
# Capability: HTTP API управления приложением
|
||||
|
||||
## Purpose
|
||||
|
||||
Объединить health и управление lifecycle приложения в одном HTTP API, подключаемом к host приложения.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят маршруты /health, /runtime/start, /runtime/stop и /runtime/status, подключаемые к HTTP host приложения.
|
||||
|
||||
## 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](#apihttpca-01fr-01-подключение-к-host-приложения).
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### 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](../../../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`; путь: `/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<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](../../../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`; путь: `/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](../../../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`; путь: `/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](#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`; путь: `/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-ожидание-и-статус-остановки) |
|
||||
Reference in New Issue
Block a user