PLBA2-4. Архивация спеки
This commit is contained in:
@@ -2,11 +2,12 @@
|
|||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
Объединить health и управление lifecycle приложения в одном HTTP API, подключаемом к host приложения.
|
Объединить health, управление lifecycle приложения и endpoints приложения в одном HTTP API, подключаемом к host приложения.
|
||||||
|
|
||||||
## Границы
|
## Границы
|
||||||
|
|
||||||
- В capability входят маршруты /health, /runtime/start, /runtime/stop и /runtime/status, подключаемые к HTTP 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
|
## Requirements
|
||||||
|
|
||||||
@@ -14,7 +15,7 @@
|
|||||||
|
|
||||||
**ID:** `API.HTTP.CA-01`
|
**ID:** `API.HTTP.CA-01`
|
||||||
|
|
||||||
PLBA2 SHALL предоставлять один route adapter для всех HTTP endpoints управления приложением; adapter подключается к host приложения и использует его единственный listener.
|
PLBA2 SHALL предоставлять единую точку маршрутизации для встроенных HTTP endpoints PLBA и endpoints, зарегистрированных приложением; adapter подключается к host приложения и использует его единственный listener.
|
||||||
|
|
||||||
#### Scenario: Сокращенный use case: подключение control API
|
#### Scenario: Сокращенный use case: подключение control API
|
||||||
|
|
||||||
@@ -26,13 +27,13 @@ PLBA2 SHALL предоставлять один route adapter для всех HT
|
|||||||
|
|
||||||
##### API.HTTP.CA-01.FR-01: Подключение к host приложения
|
##### API.HTTP.CA-01.FR-01: Подключение к host приложения
|
||||||
|
|
||||||
Приложение подключает route adapter к собственному HTTP host. Все endpoints control API используют его listener и порт. PLBA2 не запускает HTTP server и не открывает отдельный порт; adapter делегирует обработку соответствующим capabilities.
|
Приложение подключает один ASGI adapter к собственному HTTP host. Adapter маршрутизирует встроенные endpoints PLBA и endpoints приложения через общий route registry и тот же listener. PLBA2 не запускает HTTP server и не открывает отдельный порт.
|
||||||
|
|
||||||
### Requirement: Health через GET /health
|
### Requirement: Health через GET /api/v1/health
|
||||||
|
|
||||||
**ID:** `API.HTTP.CA-02`
|
**ID:** `API.HTTP.CA-02`
|
||||||
|
|
||||||
PLBA2 SHALL возвращать агрегированный health report приложения через GET /health.
|
PLBA2 SHALL возвращать агрегированный health report приложения через GET /api/v1/health.
|
||||||
|
|
||||||
#### Scenario: Получение health-отчёта через GET /health
|
#### Scenario: Получение health-отчёта через GET /health
|
||||||
|
|
||||||
@@ -47,7 +48,7 @@ PLBA2 SHALL возвращать агрегированный health report пр
|
|||||||
|
|
||||||
##### Основной поток
|
##### Основной поток
|
||||||
|
|
||||||
1. Клиент вызывает GET /health; adapter получает запрос.
|
1. Клиент вызывает GET /api/v1/health; adapter получает запрос.
|
||||||
2. Adapter запрашивает агрегированный health report по [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов).
|
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.
|
3. Adapter сериализует report по [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) и завершает с HEALTH_RESPONSE_RETURNED.
|
||||||
|
|
||||||
@@ -80,7 +81,7 @@ Adapter возвращает без пересчёта агрегированн
|
|||||||
|
|
||||||
##### Request
|
##### Request
|
||||||
|
|
||||||
Метод: `GET`; путь: `/health`. Тело запроса и query-параметры отсутствуют.
|
Метод: `GET`; путь: `/api/v1/health`. Тело запроса и query-параметры отсутствуют.
|
||||||
|
|
||||||
##### Response
|
##### Response
|
||||||
|
|
||||||
@@ -98,11 +99,11 @@ HTTP status: 200 при успешной сериализации health report.
|
|||||||
| `components[].detail` | `string or null` | Обязательное | null допустим | Краткое пояснение состояния | Копируется из detail health-состояния; при отсутствии передаётся null |
|
| `components[].detail` | `string or null` | Обязательное | null допустим | Краткое пояснение состояния | Копируется из detail health-состояния; при отсутствии передаётся null |
|
||||||
| `components[].meta` | `object` | Обязательное | null запрещён | Дополнительные структурированные данные | Копируется из meta health-состояния; при отсутствии передаётся пустой объект |
|
| `components[].meta` | `object` | Обязательное | null запрещён | Дополнительные структурированные данные | Копируется из meta health-состояния; при отсутствии передаётся пустой объект |
|
||||||
|
|
||||||
### Requirement: Запуск приложения через POST /runtime/start
|
### Requirement: Запуск приложения через POST /api/v1/runtime/start
|
||||||
|
|
||||||
**ID:** `API.HTTP.CA-03`
|
**ID:** `API.HTTP.CA-03`
|
||||||
|
|
||||||
PLBA2 SHALL запускать приложение по запросу POST /runtime/start и возвращать итоговый lifecycle status.
|
PLBA2 SHALL запускать приложение по запросу POST /api/v1/runtime/start и возвращать итоговый lifecycle status.
|
||||||
|
|
||||||
#### Scenario: Запуск приложения через POST /runtime/start
|
#### Scenario: Запуск приложения через POST /runtime/start
|
||||||
|
|
||||||
@@ -116,7 +117,7 @@ PLBA2 SHALL запускать приложение по запросу POST /ru
|
|||||||
|
|
||||||
##### Основной поток
|
##### Основной поток
|
||||||
|
|
||||||
1. Клиент вызывает POST /runtime/start без тела запроса.
|
1. Клиент вызывает POST /api/v1/runtime/start без тела запроса.
|
||||||
2. Adapter запускает приложение по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения).
|
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.
|
3. Adapter возвращает итоговый lifecycle status по [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) и завершает с APPLICATION_STARTED.
|
||||||
|
|
||||||
@@ -149,7 +150,7 @@ Adapter делегирует запуск runtime по [RT.AL-01](../../../runti
|
|||||||
|
|
||||||
##### Request
|
##### Request
|
||||||
|
|
||||||
Метод: `POST`; путь: `/runtime/start`. Тело запроса отсутствует.
|
Метод: `POST`; путь: `/api/v1/runtime/start`. Тело запроса отсутствует.
|
||||||
|
|
||||||
##### Response
|
##### Response
|
||||||
|
|
||||||
@@ -159,11 +160,11 @@ HTTP status: 200 после обработки запроса запуска; р
|
|||||||
| --- | --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- | --- |
|
||||||
| `status` | `string` | Обязательное | running или failed; null запрещён | Итоговый lifecycle status после запуска | running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED |
|
| `status` | `string` | Обязательное | running или failed; null запрещён | Итоговый lifecycle status после запуска | running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED |
|
||||||
|
|
||||||
### Requirement: Остановка приложения через POST /runtime/stop
|
### Requirement: Остановка приложения через POST /api/v1/runtime/stop
|
||||||
|
|
||||||
**ID:** `API.HTTP.CA-04`
|
**ID:** `API.HTTP.CA-04`
|
||||||
|
|
||||||
PLBA2 SHALL останавливать приложение через POST /runtime/stop и возвращать его актуальный lifecycle status.
|
PLBA2 SHALL останавливать приложение через POST /api/v1/runtime/stop и возвращать его актуальный lifecycle status.
|
||||||
|
|
||||||
#### Scenario: Остановка приложения через POST /runtime/stop
|
#### Scenario: Остановка приложения через POST /runtime/stop
|
||||||
|
|
||||||
@@ -177,7 +178,7 @@ PLBA2 SHALL останавливать приложение через POST /run
|
|||||||
|
|
||||||
##### Основной поток
|
##### Основной поток
|
||||||
|
|
||||||
1. Клиент передаёт параметры остановки в теле POST /runtime/stop.
|
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-ожидание-и-статус-остановки).
|
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.
|
3. Adapter возвращает stopped или stopping по [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) с кодом APPLICATION_STOPPED или APPLICATION_STOPPING.
|
||||||
|
|
||||||
@@ -212,7 +213,7 @@ Adapter принимает объект запроса по контракту
|
|||||||
|
|
||||||
##### Request
|
##### Request
|
||||||
|
|
||||||
Метод: `POST`; путь: `/runtime/stop`. Тело запроса — JSON object.
|
Метод: `POST`; путь: `/api/v1/runtime/stop`. Тело запроса — JSON object.
|
||||||
|
|
||||||
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
|
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
|
||||||
| --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- |
|
||||||
@@ -227,11 +228,11 @@ HTTP status: 200, если остановка завершена; 202, если
|
|||||||
| --- | --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- | --- |
|
||||||
| `status` | `string` | Обязательное | Для HTTP 200 — stopped; для HTTP 202 — stopping; null запрещён | Текущий lifecycle status приложения | Берётся из runtime: stopped после остановки всех workers; stopping, пока их остановка продолжается |
|
| `status` | `string` | Обязательное | Для HTTP 200 — stopped; для HTTP 202 — stopping; null запрещён | Текущий lifecycle status приложения | Берётся из runtime: stopped после остановки всех workers; stopping, пока их остановка продолжается |
|
||||||
|
|
||||||
### Requirement: Lifecycle status через GET /runtime/status
|
### Requirement: Lifecycle status через GET /api/v1/runtime/status
|
||||||
|
|
||||||
**ID:** `API.HTTP.CA-05`
|
**ID:** `API.HTTP.CA-05`
|
||||||
|
|
||||||
PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /runtime/status.
|
PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /api/v1/runtime/status.
|
||||||
|
|
||||||
#### Scenario: Чтение lifecycle status через GET /runtime/status
|
#### Scenario: Чтение lifecycle status через GET /runtime/status
|
||||||
|
|
||||||
@@ -245,7 +246,7 @@ PLBA2 SHALL возвращать текущее lifecycle status приложе
|
|||||||
|
|
||||||
##### Основной поток
|
##### Основной поток
|
||||||
|
|
||||||
1. Клиент вызывает GET /runtime/status.
|
1. Клиент вызывает GET /api/v1/runtime/status.
|
||||||
2. Adapter читает lifecycle status без запуска или остановки компонентов по [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status).
|
2. Adapter читает lifecycle status без запуска или остановки компонентов по [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status).
|
||||||
3. Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED.
|
3. Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED.
|
||||||
|
|
||||||
@@ -273,7 +274,7 @@ Adapter читает status без побочных действий и заве
|
|||||||
|
|
||||||
##### Request
|
##### Request
|
||||||
|
|
||||||
Метод: `GET`; путь: `/runtime/status`. Тело запроса и query-параметры отсутствуют.
|
Метод: `GET`; путь: `/api/v1/runtime/status`. Тело запроса и query-параметры отсутствуют.
|
||||||
|
|
||||||
##### Response
|
##### Response
|
||||||
|
|
||||||
@@ -282,3 +283,56 @@ 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-ожидание-и-статус-остановки) |
|
| `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`.
|
||||||
|
|||||||
Reference in New Issue
Block a user