Compare commits
5
Commits
295cc30ead
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2f47fc74cf | ||
|
|
d46993a092 | ||
|
|
a0d2db6bd0 | ||
|
|
d517820088 | ||
|
|
19fa591c31 |
@@ -0,0 +1,72 @@
|
||||
name: PLBA package CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
|
||||
jobs:
|
||||
tests:
|
||||
name: Python tests
|
||||
runs-on: cloud-build
|
||||
steps:
|
||||
- name: Check out repository
|
||||
env:
|
||||
GITEA_SERVER_URL: ${{ gitea.server_url }}
|
||||
GITEA_REPOSITORY: ${{ gitea.repository }}
|
||||
GITEA_REF: ${{ gitea.ref }}
|
||||
run: |
|
||||
set -eu
|
||||
repository_url="${GITEA_SERVER_URL%/}/${GITEA_REPOSITORY}.git"
|
||||
git init .
|
||||
git remote add origin "$repository_url"
|
||||
git fetch --no-tags --depth=1 origin "$GITEA_REF"
|
||||
git checkout --detach FETCH_HEAD
|
||||
|
||||
- name: Check Python version
|
||||
run: |
|
||||
python3 - <<'PY'
|
||||
import sys
|
||||
|
||||
print(f"Using Python {sys.version.split()[0]}")
|
||||
if sys.version_info < (3, 11):
|
||||
raise SystemExit("PLBA v2 CI requires Python 3.11 or newer")
|
||||
PY
|
||||
|
||||
- name: Install package and test dependencies
|
||||
run: |
|
||||
python3 -m venv .venv
|
||||
.venv/bin/python -m pip install -e ".[test]"
|
||||
|
||||
- name: Run tests
|
||||
run: .venv/bin/python -m pytest
|
||||
|
||||
package-version:
|
||||
name: Package version increment
|
||||
if: ${{ gitea.event_name == 'pull_request' }}
|
||||
runs-on: cloud-build
|
||||
steps:
|
||||
- name: Check out repository and target branch history
|
||||
env:
|
||||
GITEA_SERVER_URL: ${{ gitea.server_url }}
|
||||
GITEA_REPOSITORY: ${{ gitea.repository }}
|
||||
GITEA_REF: ${{ gitea.ref }}
|
||||
BASE_REF: ${{ gitea.base_ref }}
|
||||
run: |
|
||||
set -eu
|
||||
test -n "$BASE_REF"
|
||||
repository_url="${GITEA_SERVER_URL%/}/${GITEA_REPOSITORY}.git"
|
||||
git init .
|
||||
git remote add origin "$repository_url"
|
||||
git fetch --no-tags --depth=1 origin "$GITEA_REF"
|
||||
git checkout --detach FETCH_HEAD
|
||||
git fetch --no-tags --depth=1 origin "refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}"
|
||||
|
||||
- name: Check package version increment
|
||||
env:
|
||||
BASE_REF: ${{ gitea.base_ref }}
|
||||
run: |
|
||||
test -n "$BASE_REF"
|
||||
python3 scripts/check_package_version.py --base-ref "origin/${BASE_REF}"
|
||||
@@ -50,7 +50,7 @@ PLBA v2 — независимая от транспорта библиотек
|
||||
- `runtime/worker` регистрирует worker-ы с уникальными именами, применяет флаг `disabled`, выполняет последовательные циклы по расписанию, объединяет прикладное и автоматическое состояние health и поддерживает штатную и принудительную остановку.
|
||||
- `runtime/application-lifecycle` запускает и останавливает все включённые worker-ы и сообщает состояние жизненного цикла приложения.
|
||||
- `health/aggregation` объединяет состояния worker-ов и дополнительных компонентов с учётом критичности, отсутствующих компонентов и состояния приложения.
|
||||
- `api/http/control-api` — подключаемый ASGI-адаптер для `GET /health`, `POST /runtime/start`, `POST /runtime/stop` и `GET /runtime/status`.
|
||||
- `api/http/control-api` — подключаемый ASGI-адаптер для `GET /api/v1/health`, `POST /api/v1/runtime/start`, `POST /api/v1/runtime/stop` и `GET /api/v1/runtime/status`; приложение может передать ему собственные `HttpRoute` для той же маршрутизации.
|
||||
- `configuration/application-config-file` загружает типизированную конфигурацию приложения из корневого `config.yaml` и атомарно применяет корректные обновления без перезапуска.
|
||||
- `configuration/application-settings` предоставляет типизированный `SettingsReader` и PostgreSQL-адаптер для принадлежащей приложению таблицы `settings`.
|
||||
- `workflow/orchestration` выполняет именованные шаги по объявленным переходам и сохраняет снимки запуска и шагов через порт, реализуемый приложением.
|
||||
@@ -79,7 +79,7 @@ supervisor = WorkerSupervisor(workers, config_manager)
|
||||
runtime = ApplicationRuntime(runtime_context, supervisor)
|
||||
```
|
||||
|
||||
Приложение создаёт собственный HTTP host и подключает `ControlApi` к тому же listener. `RuntimeHealthInputProvider` связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с `HealthAggregator`. Приложение само запускает сервер и определяет, когда вызвать `runtime.start()` и `runtime.stop()`.
|
||||
Приложение создаёт собственный HTTP host и подключает `ControlApi` к тому же listener. Встроенные endpoints PLBA и переданные через `application_routes` прикладные `HttpRoute` доступны через общий API; каждый путь начинается с `/api/v{version}/`. `RuntimeHealthInputProvider` связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с `HealthAggregator`. Приложение само запускает сервер и определяет, когда вызвать `runtime.start()` и `runtime.stop()`.
|
||||
|
||||
Чтобы применять изменения конфигурации, запустите `config_manager.watch(...)` как задачу приложения и обработайте ошибки перезагрузки в переданном callback. Уже выданные снимки конфигурации остаются неизменными; при некорректном обновлении активным остаётся последний корректный снимок.
|
||||
|
||||
|
||||
+49
-4
@@ -12,10 +12,55 @@ Register `WorkerDefinition` objects in a `WorkerRegistry`, pass the registry and
|
||||
`ApplicationRuntime`. Register non-worker checks in `HealthContributorRegistry`
|
||||
and connect it to `HealthAggregator` with `RuntimeHealthInputProvider`.
|
||||
|
||||
Mount `ControlApi(runtime, health_aggregator)` in the application's ASGI host.
|
||||
The host owns the socket and listener; the adapter contributes `/health`,
|
||||
`/runtime/start`, `/runtime/stop`, and `/runtime/status` to that same listener.
|
||||
The application chooses when to start and stop the runtime.
|
||||
Register application endpoints as typed `HttpRoute` values when composing the
|
||||
ASGI application. The built-in routes and application handlers share the same
|
||||
`ControlApi` router and listener:
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
from plba.http import ControlApi, HttpRoute
|
||||
|
||||
|
||||
async def get_order(scope, receive, send):
|
||||
body = json.dumps({"order_id": scope["path_params"]["order_id"]}).encode()
|
||||
await send(
|
||||
{
|
||||
"type": "http.response.start",
|
||||
"status": 200,
|
||||
"headers": [(b"content-type", b"application/json")],
|
||||
}
|
||||
)
|
||||
await send({"type": "http.response.body", "body": body})
|
||||
|
||||
|
||||
api = ControlApi(
|
||||
runtime,
|
||||
health_aggregator,
|
||||
application_routes=(
|
||||
HttpRoute("GET", "/api/v1/orders/{order_id}", get_order),
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
The built-in API paths are:
|
||||
|
||||
- `GET /api/v1/health`
|
||||
- `POST /api/v1/runtime/start`
|
||||
- `POST /api/v1/runtime/stop`
|
||||
- `GET /api/v1/runtime/status`
|
||||
|
||||
Application route templates must also start with `/api/v{version}/`, where
|
||||
`{version}` is a positive integer such as `v1`. Named path segments are
|
||||
available in `scope["path_params"]`, and the application handler owns its
|
||||
response.
|
||||
|
||||
For platform access, the public request path is
|
||||
`/{service-name}/api/v{version}/...`. Caddy selects the service upstream and
|
||||
removes `/{service-name}` before proxying, so the application receives the
|
||||
internal `/api/v{version}/...` path. The application host still owns one
|
||||
socket and listener; PLBA does not start a separate HTTP server. The
|
||||
application chooses when to start and stop the runtime.
|
||||
|
||||
## Configuration and settings
|
||||
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
schema: function-driven
|
||||
created: 2026-10-10
|
||||
skip_specs: true
|
||||
@@ -0,0 +1,42 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
Пакету требуется Python 3.11 или новее; он использует setuptools с исходниками в `src/`, объявляет pytest в extra `test` и хранит тесты в `tests/`. Infra v2 поднимает общий Python CI runner на `cloud`; workflow Gitea выбирают его по метке `cloud-build`.
|
||||
|
||||
Существующая проверка версии читает базовую версию командой `git show <ref>:pyproject.toml`, поэтому целевая ветка pull request должна присутствовать в локальной истории Git. Мотивация и общий scope приведены в `proposal.md`.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Запускать тесты пакета для pull request и push в `main` на build runner infra v2.
|
||||
- Требовать один допустимый шаг SemVer для каждого pull request.
|
||||
- Выполнять CI пакета без прав и секретов деплоя приложений.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Автоматически публиковать wheel, container image или релиз приложения.
|
||||
- Деплоить сам PLBA через `infra_v2`.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Использовать единый `.gitea/workflows/ci.yml` для тестов пакета и проверки версии pull request. Проверки остаются отдельными jobs одного workflow.
|
||||
- Запускать тесты для pull request и push в `main`. Проверять версию только для pull request, используя `github.base_ref` как целевую ветку.
|
||||
- Выбирать метку `cloud-build`, соответствующую host runner, зарегистрированному как `cloud-build:host`.
|
||||
- Использовать Python, установленный для runner; завершать job с понятной ошибкой, если версия ниже 3.11. Устанавливать пакет и test-зависимости через `python -m pip install -e ".[test]"`, затем запускать `python -m pytest`.
|
||||
- Загружать полную историю Git для job проверки версии и вызывать существующий checker со ссылкой `origin/${{ github.base_ref }}`. Checker использует только стандартную библиотеку Python.
|
||||
- До `1.0.0` использовать PATCH для исправлений, рефакторинга и документации; MINOR — для новых возможностей и любых изменений публичного контракта, включая несовместимые. Версия `1.0.0` обозначает начало стабильного контракта. Начиная с `1.0.0`, использовать PATCH для совместимых исправлений, MINOR — для совместимых возможностей, MAJOR — для несовместимых изменений публичного контракта.
|
||||
- Проверка принимает только один допустимый шаг SemVer относительно base pull request. Она не определяет, соответствует ли выбранный компонент типу изменения; это проверяют OpenSpec-планирование и code review.
|
||||
- Не настраивать доступ к registry или токен деплоя. PLBA является Python-пакетом; публикацией образа и деплоем занимаются репозитории приложений.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- На build runner может оказаться Python ниже 3.11 → проверять версию интерпретатора до установки и выводить обнаруженную версию при ошибке.
|
||||
- Для установки extra `test` нужен доступ к package index → устанавливать только объявленные зависимости и сохранять ошибки установки в job log.
|
||||
- Контекст pull request в Gitea должен предоставлять `github.base_ref`, а checkout action — получать целевую ветку → загружать полную историю и использовать тот же контекст, что и текущая проверка версии.
|
||||
- Внешние структурные заголовки OpenSpec остаются на английском, чтобы инструменты схемы распознавали артефакты; весь пояснительный текст, включая заголовки групп задач и сценариев, оформляется на русском.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Заменить version-only workflow объединённым CI workflow. Первый pull request запускает тесты и проверяет версию относительно целевой ветки; последующие push в `main` запускают тестовую job. Production-деплой и миграция данных не затрагиваются.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
PLBA v2 нужен единый порядок версионирования пакета и автоматические проверки на Gitea runner для Python-проектов. Кроме того, артефакты OpenSpec change должны создаваться на русском языке, а CI должен запускать тесты при push в `main`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Требовать от каждого реализованного OpenSpec change отдельную финальную задачу на увеличение версии пакета по правилам SemVer для версий до и после `1.0.0`.
|
||||
- Проверять версию pull request относительно целевой ветки и запускать Python-тесты для pull request и push в `main` на общем build runner.
|
||||
- Требовать русский язык для пояснительного текста всех артефактов change: `proposal.md`, `design.md`, `specs/**/*.md` и `tasks.md`.
|
||||
- Ограничить CI проверками Python-пакета: не публиковать container image и не запускать деплой приложения.
|
||||
- Увеличить версию пакета ровно один раз: с `0.1.0` до `0.1.1`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
Нет. Изменение добавляет правила разработки и CI-инструменты репозитория, не меняя runtime-поведение PLBA.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
Нет. В `.openspec.yaml` указано `skip_specs: true`, поскольку продуктовые возможности и контракты не меняются.
|
||||
|
||||
## Impact
|
||||
|
||||
- Обновляет `openspec/config.yaml`, инструкции и шаблоны схемы `function-driven`.
|
||||
- Добавляет `scripts/check_package_version.py` и workflow Gitea Actions.
|
||||
- Использует дополнительную зависимость `test`, уже объявленную в `pyproject.toml`.
|
||||
- Требует Gitea runner `cloud-build` с Python 3.11 или новее; секреты registry и деплоя не нужны.
|
||||
@@ -0,0 +1,18 @@
|
||||
# Tasks
|
||||
|
||||
## 1. Политика версии пакета
|
||||
|
||||
- [x] 1.1 Добавить в `openspec/config.yaml` правила SemVer для версий до и после `1.0.0`; проверить, что правила задач требуют финальную задачу версии для каждого реализуемого изменения.
|
||||
- [x] 1.2 Добавить финальную задачу версии в шаблон `function-driven` и реализовать `scripts/check_package_version.py`; проверить отклонение неизменённой, ошибочной, пропущенной и пониженной версии.
|
||||
|
||||
## 2. CI Python-пакета PLBA
|
||||
|
||||
- [x] 2.1 Добавить `.gitea/workflows/ci.yml` для pull request и push в `main` с runner `cloud-build`; проверить события и метку runner в workflow.
|
||||
- [x] 2.2 Добавить job тестов Python, которая проверяет версию Python 3.11+, устанавливает `.[test]` и запускает `python -m pytest`; сверить команды с `pyproject.toml`.
|
||||
- [x] 2.3 Добавить job проверки версии для pull request, получать целевую ветку и вызывать `scripts/check_package_version.py`; удалить прежний version-only workflow и проверить ref, передаваемый checker.
|
||||
- [x] 2.4 Задать русский язык для пояснительного текста каждого изменения в `openspec/config.yaml` и инструкциях `function-driven`; проверить, что правило охватывает proposal, design, specs и tasks.
|
||||
- [x] 2.5 Перевести пояснительный текст артефактов этого изменения на русский; проверить сохранение обязательных заголовков OpenSpec и технических идентификаторов.
|
||||
|
||||
## 3. Версия этого change
|
||||
|
||||
- [x] 3.1 Последней задачей увеличить версию в `pyproject.toml` с `0.1.0` до `0.1.1` на один PATCH и проверить её скриптом `scripts/check_package_version.py` относительно базового коммита.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: use-case-driven
|
||||
created: 2026-10-11
|
||||
@@ -0,0 +1,52 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
Текущий `ControlApi` — ASGI entrypoint без собственного HTTP server. Он обрабатывает lifespan и вручную сопоставляет четыре встроенных пути в `_dispatch`; прикладных обработчиков в общем API нет. Встроенные endpoints возвращают JSON через `ASGIHttpTransport`.
|
||||
|
||||
ADR-0001 задаёт целевые внутренние пути `/api/v{version}/...` и внешние пути `/{service-name}/api/v{version}/...`, где Caddy выбирает upstream и удаляет service-префикс. ADR имеет статус `Proposed`; это изменение следует выбранному пользователем целевому направлению, не меняя статус ADR. Изменения конфигурации Caddy находятся вне этого репозитория и scope change.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Сохранить один ASGI entrypoint и listener приложения для встроенных и прикладных endpoints.
|
||||
- Маршрутизировать встроенные endpoints версии `v1` и регистрируемые приложением endpoints через одну таблицу маршрутов.
|
||||
- Передавать прикладным обработчикам полный ASGI request и ответ под контролем приложения.
|
||||
- Сохранить текущие контракты health и lifecycle, изменив только пути встроенных endpoints.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Настройка или деплой Caddy и изменение ingress-конфигурации.
|
||||
- Запуск PLBA собственного HTTP server или открытие отдельного listener.
|
||||
- Совместимость со старыми путями через aliases.
|
||||
- Введение HTTP-фреймворка, схем сериализации, OpenAPI, авторизации или общей обработки тел запросов.
|
||||
- Регистрация и удаление маршрутов после запуска host.
|
||||
|
||||
## Decisions
|
||||
|
||||
1. **Общий router остаётся внутри `ControlApi`.** `ControlApi` продолжает быть корневым ASGI callable, обрабатывает lifespan и направляет HTTP-запросы во внутренний router. Встроенные endpoints регистрируются в этой же таблице, что и endpoints приложения. Это сохраняет существующий способ подключения PLBA к host и исключает параллельный server. Требование: `API.HTTP.CA-01`.
|
||||
|
||||
2. **Приложение передаёт маршруты при сборке зависимостей.** Публичный typed descriptor `HttpRoute` содержит HTTP-метод, path template и ASGI handler. `ControlApi` принимает последовательность таких descriptors при создании; после создания registry неизменяем. Такой constructor injection делает состав API явным в composition root и не допускает гонок с изменением таблицы во время обработки запросов. Это решение покрывает `API.HTTP.CA-06.FR-01`.
|
||||
|
||||
3. **Шаблоны путей версионируются и поддерживают именованные сегменты.** Встроенные пути фиксируются на `/api/v1/...`. Каждый прикладной template обязан иметь вид `/api/v<положительное целое число>/<путь>` с хотя бы одним сегментом после версии; параметры записываются отдельным сегментом `{parameter_name}`. Валидатор отклоняет некорректный template, некорректный HTTP-метод, повторяющийся маршрут для одного метода и совпадающие неоднозначные templates равной специфичности. Маршрут с большим числом точных сегментов имеет приоритет; параметры передаются в копии ASGI scope как `path_params`. Требование: `API.HTTP.CA-06.FR-01` и `API.HTTP.CA-06.FR-02`.
|
||||
|
||||
4. **Маршрутизация не переписывает запрос приложения.** При совпадении router вызывает handler с ASGI `scope`, `receive` и `send`; handler формирует собственный статус, headers и body. PLBA создаёт только ответы ошибок маршрутизации: 404 для неизвестного пути и 405 для известного пути с неподдерживаемым методом. Ошибки внутри прикладного handler остаются ответственностью приложения и HTTP host.
|
||||
|
||||
5. **Старые control paths не сохраняются как aliases.** Все клиенты, health checks и прямые вызовы должны перейти на новые внутренние `/api/v1/...` paths. Во внешнем запросе service slug остаётся префиксом ingress, а Caddy передаёт сервису путь без этого префикса. Это соответствует выбранному варианту ADR-0001; в этом change меняется контракт PLBA, но не конфигурация Caddy.
|
||||
|
||||
6. **API-изменение требует обновления версии пакета.** Так как публичные пути меняются с несовместимостью и добавляется возможность регистрации endpoints, версия пакета обновляется согласно проектной политике в последней задаче implementation change.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **Существующие вызовы по `/health` и `/runtime/...` перестанут работать** → обновить клиентов, health checks и интеграционные примеры на `/api/v1/...` в рамках релиза; старые aliases не вводить.
|
||||
- **ASGI handler требует от приложения самостоятельно формировать response** → экспортировать descriptor и документировать минимальный пример регистрации и ответа.
|
||||
- **Пересечение templates может дать неожиданный выбор маршрута** → маршрут с большим числом точных сегментов получает приоритет, а неоднозначные шаблоны равной специфичности отклоняются при сборке registry.
|
||||
- **Публичный URL зависит от настройки Caddy для service slug** → описать внешний и внутренний пути в документации PLBA; конфигурация ingress выполняется отдельно.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Реализовать общий router и регистрацию `HttpRoute`, сохранив текущие health/lifecycle handlers.
|
||||
2. Перенести встроенные endpoints на `/api/v1/...` и обновить документацию и проверки PLBA.
|
||||
3. Обновить потребителей API и конфигурации health checks так, чтобы они использовали versioned paths; для платформенного доступа настроить Caddy на внешний `/{service-name}/api/v{version}/...` и передачу внутреннего `/api/v{version}/...`.
|
||||
4. Выпустить новую версию пакета после обновления интеграций. Откат к предыдущей версии вернёт старые пути; интеграции на новые пути при таком откате потребуется вернуть к прежним путям одновременно с пакетом.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
`ControlApi` сейчас обслуживает только четыре зашитых в код маршрута, поэтому приложение не может добавить собственные endpoints в общую точку маршрутизации PLBA. Кроме того, текущие пути не соответствуют целевому versioned-префиксу ADR-0001, из-за чего сервисы не имеют единого контракта для внутренних и внешних запросов через Caddy.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**: перенести встроенные endpoints на `/api/v1/`: `/health`, `/runtime/start`, `/runtime/stop` и `/runtime/status`.
|
||||
- Добавить расширяемую маршрутизацию, где приложение регистрирует собственные endpoints в том же API и listener, что и endpoints PLBA.
|
||||
- Требовать путь `/api/v{version}/...` для всех регистрируемых endpoints и поддержать маршруты с параметрами пути.
|
||||
- Документировать внешний путь `/{service-name}/api/v{version}/...` и проксирование Caddy с удалением service-префикса.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `api/http/control-api`: изменить пути встроенных endpoints и расширить общую точку маршрутизации для endpoints приложения.
|
||||
|
||||
## Impact
|
||||
|
||||
- HTTP API и публичный интерфейс PLBA в `src/plba/http/`.
|
||||
- Контракт существующих клиентов и проверок health: они должны вызывать новые versioned-пути.
|
||||
- Документация интеграции, unit/contract проверки HTTP API и `pyproject.toml`.
|
||||
- ADR-0001 задаёт целевой нейминг и ingress-маршрутизацию; его статус остаётся `Proposed` до явного принятия владельцем решения.
|
||||
+357
@@ -0,0 +1,357 @@
|
||||
# Spec Delta
|
||||
|
||||
## RENAMED Requirements
|
||||
|
||||
### Requirement: Health через GET /api/v1/health
|
||||
|
||||
FROM: `Health через GET /health`
|
||||
|
||||
TO: `Health через GET /api/v1/health`
|
||||
|
||||
### Requirement: Запуск приложения через POST /api/v1/runtime/start
|
||||
|
||||
FROM: `Запуск приложения через POST /runtime/start`
|
||||
|
||||
TO: `Запуск приложения через POST /api/v1/runtime/start`
|
||||
|
||||
### Requirement: Остановка приложения через POST /api/v1/runtime/stop
|
||||
|
||||
FROM: `Остановка приложения через POST /runtime/stop`
|
||||
|
||||
TO: `Остановка приложения через POST /api/v1/runtime/stop`
|
||||
|
||||
### Requirement: Lifecycle status через GET /api/v1/runtime/status
|
||||
|
||||
FROM: `Lifecycle status через GET /runtime/status`
|
||||
|
||||
TO: `Lifecycle status через GET /api/v1/runtime/status`
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Единый HTTP adapter
|
||||
|
||||
**ID:** `API.HTTP.CA-01`
|
||||
|
||||
PLBA2 SHALL предоставлять единую точку маршрутизации для встроенных HTTP endpoints и endpoints, зарегистрированных приложением; она подключается к host приложения и использует его единственный listener.
|
||||
|
||||
#### Scenario: Сокращенный use case: подключение control API
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Приложение подключает общую точку маршрутизации к своему 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 /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<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 /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 /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 /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-ожидание-и-статус-остановки) |
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### 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`.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Tasks
|
||||
|
||||
## 1. Общая маршрутизация HTTP API
|
||||
|
||||
- [x] 1.1 Добавить в `plba.http` типизированный descriptor `HttpRoute` и route registry: валидировать HTTP-методы и templates `/api/v{version}/...`, параметры пути, дубли и неоднозначные маршруты; покрыть проверки регистрации и сопоставления тестами `tests/test_http_routes.py`.
|
||||
- [x] 1.2 Перевести `ControlApi` на общий router, зарегистрировать встроенные endpoints `/api/v1/health`, `/api/v1/runtime/start`, `/api/v1/runtime/stop`, `/api/v1/runtime/status` и принимать прикладные `HttpRoute` при создании; проверить сохранение health/lifecycle контрактов и передачу ASGI handler-у ответа и `path_params` тестами `tests/test_health_http.py` и `tests/test_http_routes.py` (`API.HTTP.CA-01`, `API.HTTP.CA-02`–`CA-06`).
|
||||
- [x] 1.3 Проверить HTTP ошибки и совместную таблицу маршрутов: неизвестный путь возвращает 404 `HTTP_ROUTE_NOT_FOUND`, известный путь с неподдерживаемым методом возвращает 405 `HTTP_METHOD_NOT_ALLOWED`, конфликт регистрации отклоняется; выполнить `pytest -q tests/test_http_routes.py tests/test_health_http.py` (`API.HTTP.CA-06.FR-01`–`FR-02`).
|
||||
|
||||
## 2. Интеграционная документация и проверка
|
||||
|
||||
- [x] 2.1 Обновить `README.md` и `docs/integration.md`: описать маршруты `/api/v1/...`, пример передачи прикладных `HttpRoute` в `ControlApi`, внутренний путь сервиса и внешний `/{service-name}/api/v{version}/...`, который Caddy проксирует после удаления service-префикса; проверить примеры и ссылки в документации.
|
||||
- [x] 2.2 Выполнить полный набор тестов проекта и OpenSpec-валидацию change; убедиться, что `openspec validate versioned-extensible-http-api` и тесты проходят, а старые unversioned paths больше не документируются как действующий API.
|
||||
|
||||
## 3. Версия пакета
|
||||
|
||||
- [x] 3.1 Последней задачей повысить версию `pyproject.toml` с `0.1.1` до `0.2.0` как MINOR bump для нового API и изменения публичного контракта; проверить версию через `scripts/check_package_version.py --base-ref <target-ref>`.
|
||||
+16
-28
@@ -1,33 +1,21 @@
|
||||
schema: function-driven
|
||||
schema: use-case-driven
|
||||
|
||||
context: |
|
||||
Актуальные спецификации проекта находятся в openspec/specs/.
|
||||
Старые документы spec/specs/ устарели и не подтверждают текущее поведение.
|
||||
Capability имеет отдельную бизнес-функцию или понятный результат и живёт
|
||||
в иерархии доменов, например orders/snapshot-sync.
|
||||
Requirement описывает одну завершённую техническую функцию.
|
||||
Формат требований определяется локальной схемой function-driven.
|
||||
Включай только сведения, влияющие на наблюдаемое поведение, устойчивый
|
||||
контракт или обязательное техническое ограничение; не добавляй повторы и
|
||||
пояснительный текст без такого влияния.
|
||||
Пиши спецификации по-русски; имена API, SQL-полей и кодов сохраняй.
|
||||
ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и
|
||||
реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если
|
||||
запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о
|
||||
конфликте пользователю; не обходи решение молча. Новые ADR оформляй по
|
||||
шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом
|
||||
Proposed; не помечай решение Accepted без явного принятия владельцем решения.
|
||||
|
||||
rules:
|
||||
specs:
|
||||
- Каждый Requirement содержит ровно один Use case. Автор выбирает полный или сокращенный формат независимо от типа FR и предмета описания.
|
||||
- Обычный FR без метки описывает логику, правила или последовательность шагов; специальные типы помечай в заголовке FR как [DB], [API] или [UI].
|
||||
- FR [DB] с таблицей БД оформляй по openspec/schemas/function-driven/patterns/database-table.md.
|
||||
- Каждый HTTP endpoint описывай отдельным Requirement с полным Use case; сложные шаги выноси в FR и связывай со сценарием.
|
||||
- Контракт endpoint помещай после FR в завершающий CONTRACT с подразделами Request и Response; не создавай для request/response отдельные FR.
|
||||
- Таблицы тела запроса и ответа в CONTRACT оформляй по openspec/schemas/function-driven/patterns/message-contract.md; для каждого поля Response указывай источник или правило формирования значения.
|
||||
- Сериализуемые контракты сообщений и технических логов описывай в FR [API] по openspec/schemas/function-driven/patterns/message-contract.md; один FR описывает одно направление.
|
||||
- Детали находятся в локально нумерованных FR за пределами Scenario; шаги ссылаются на FR.
|
||||
- Коды завершения сами передают смысл результата и связаны с FR о текстах и дальнейшем поведении.
|
||||
- Для master spec используй templates/main-spec.md выбранной схемы; для delta используй templates/spec.md.
|
||||
- Проверяй формат командой python3 openspec/schemas/function-driven/validate_format.py <spec-path>.
|
||||
proposal:
|
||||
- Сохраняй полные иерархические пути capabilities.
|
||||
design:
|
||||
- Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований.
|
||||
tasks:
|
||||
- Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты.
|
||||
- >-
|
||||
Завершай каждый реализуемый change отдельной последней задачей на
|
||||
увеличение версии пакета в `pyproject.toml`; один change повышает версию
|
||||
ровно один раз. До 1.0.0 используй PATCH для исправлений, рефакторинга и
|
||||
документации, MINOR для новых возможностей и изменений публичного
|
||||
контракта, в том числе несовместимых; переход на 1.0.0 начинает стабильный
|
||||
публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений,
|
||||
рефакторинга и документации, MINOR для обратно совместимых возможностей,
|
||||
MAJOR для несовместимых изменений публичного контракта.
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
status: Proposed
|
||||
date: 2026-10-11
|
||||
decision-makers:
|
||||
- Владелец проекта
|
||||
supersedes: []
|
||||
superseded-by: null
|
||||
---
|
||||
|
||||
# ADR-0001: Нейминг API-путей и маршрутизация сервисов через Caddy
|
||||
|
||||
## Контекст и проблема
|
||||
|
||||
На платформе PLBA будет работать несколько сервисов с одинаковыми шаблонами API-путей. PLBA предоставляет общие endpoints управления приложением, а сервисы должны иметь возможность добавлять собственные endpoints в тот же HTTP API и listener. Фронтенду также нужно однозначно выбирать сервис при вызове API.
|
||||
|
||||
Существующие endpoints `/health`, `/runtime/start`, `/runtime/stop` и `/runtime/status` не содержат версии API. Внешний ingress платформы построен на Caddy с `caddy-docker-proxy`.
|
||||
|
||||
## Факторы решения
|
||||
|
||||
- Все endpoints конкретного сервиса должны находиться в одном версионируемом пространстве путей.
|
||||
- Правило версионирования применяется к endpoints PLBA и к endpoints, добавленным приложением.
|
||||
- Сервисы должны использовать одинаковые внутренние пути независимо от имени сервиса на платформе.
|
||||
- Внешний запрос должен однозначно маршрутизироваться к нужному сервису через Caddy.
|
||||
- PLBA не запускает отдельный HTTP listener; control- и прикладные endpoints обслуживаются через общий listener сервиса.
|
||||
|
||||
## Рассмотренные варианты
|
||||
|
||||
- **Включать имя сервиса во внутренние пути** — например, `/{service-name}/api/v1/orders`. Маршрут явно различает сервисы, но связывает путь приложения с его именем и конфигурацией размещения.
|
||||
- **Добавлять имя сервиса на ingress** — внешний путь имеет вид `/{service-name}/api/v1/orders`, а Caddy выбирает upstream и удаляет `/{service-name}` перед передачей запроса. Внутренний путь сервиса остаётся `/api/v1/orders`.
|
||||
|
||||
## Решение
|
||||
|
||||
Предлагается принять второй вариант.
|
||||
|
||||
Путь endpoint внутри сервиса начинается с `/api/v{version}/...`, где версия задаётся сегментом пути, например `v1`. Это правило распространяется на все endpoints сервиса, включая endpoints PLBA. В версии `v1` пути PLBA будут такими:
|
||||
|
||||
- `GET /api/v1/health`
|
||||
- `POST /api/v1/runtime/start`
|
||||
- `POST /api/v1/runtime/stop`
|
||||
- `GET /api/v1/runtime/status`
|
||||
|
||||
Внешний путь фронтенда начинается с `/{service-name}/api/v{version}/...`. `service-name` — стабильный slug сервиса, настроенный на ingress. Caddy направляет запрос соответствующему upstream и удаляет service-префикс. Приложение получает запрос уже по внутреннему пути `/api/v{version}/...`.
|
||||
|
||||
PLBA предоставляет общую точку маршрутизации для своих endpoints и endpoints, зарегистрированных приложением. Приложение не создаёт для прикладных endpoints параллельный HTTP listener.
|
||||
|
||||
## Последствия
|
||||
|
||||
- Положительные: сервисы сохраняют единый набор путей; имя размещённого сервиса остаётся настройкой ingress; новые версии API можно публиковать отдельными путями.
|
||||
- Отрицательные или компромиссы: Caddy должен иметь маршрут для каждого публичного service-prefix и корректно удалять его перед проксированием.
|
||||
- Существующие клиенты, прямые вызовы сервисов и health checks нужно перевести на версионированные внутренние пути.
|
||||
- Если приложение формирует абсолютные ссылки на свои endpoints, оно должно учитывать внешний публичный префикс или получать публичный base URL из конфигурации.
|
||||
|
||||
## Связанные решения
|
||||
|
||||
- Нет.
|
||||
@@ -1,19 +0,0 @@
|
||||
# Коды capabilities
|
||||
|
||||
Каждому пути capability соответствует один стабильный короткий префикс. Полные
|
||||
префиксы должны быть уникальны в проекте; при переименовании capability код не
|
||||
переиспользуется для другой capability.
|
||||
|
||||
| Путь capability | Префикс Requirement |
|
||||
| --- | --- |
|
||||
| `configuration/application-settings` | `CFG.AS` |
|
||||
| `configuration/application-config-file` | `CFG.ACF` |
|
||||
| `health/aggregation` | `HL.AG` |
|
||||
| `api/http/control-api` | `API.HTTP.CA` |
|
||||
| `runtime/application-lifecycle` | `RT.AL` |
|
||||
| `runtime/application-identity` | `RT.AI` |
|
||||
| `runtime/worker` | `RT.WK` |
|
||||
| `workflow/orchestration` | `WF.OR` |
|
||||
| `observability/business-tracing` | `OBS.BT` |
|
||||
| `observability/technical-logging` | `OBS.TL` |
|
||||
|
||||
@@ -1,266 +0,0 @@
|
||||
name: function-driven
|
||||
version: 1
|
||||
description: Иерархические capabilities, завершённые технические функции и краткие use cases с локальными FR
|
||||
artifacts:
|
||||
- id: proposal
|
||||
generates: proposal.md
|
||||
description: Initial proposal document outlining the change
|
||||
template: proposal.md
|
||||
instruction: |
|
||||
Create the proposal document that establishes WHY this change is needed.
|
||||
|
||||
Sections:
|
||||
- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
|
||||
- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
|
||||
- **Capabilities**: Identify which specs will be created or modified:
|
||||
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
|
||||
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
|
||||
- **Impact**: Affected code, APIs, dependencies, or systems.
|
||||
|
||||
IMPORTANT: The Capabilities section is critical. It creates the contract between
|
||||
proposal and specs phases. Research existing specs before filling this in:
|
||||
run `openspec list --specs` for the project's capability inventory, then
|
||||
`openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
|
||||
look related - that returns a capability's purpose and requirement texts
|
||||
without pulling whole spec files into context. Append `--store "<id>"` to
|
||||
both commands only for a registered standalone store, and keep `--type
|
||||
spec`: a change and a spec sharing a name is otherwise an ambiguous-item
|
||||
error. `openspec list` without `--specs` lists in-flight changes, not
|
||||
specs - it never shows what the project already covers. Reuse an existing
|
||||
capability's exact path instead of introducing a near-duplicate name.
|
||||
The filtered read is only an overview. Before deciding what is already
|
||||
covered or what should change, read each relevant spec in full, including
|
||||
scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
|
||||
Each capability listed here will need a corresponding spec file.
|
||||
|
||||
Every change must either declare at least one capability (new or
|
||||
modified) or explicitly opt out of specs: `openspec validate` rejects a
|
||||
change with zero deltas unless the change's `.openspec.yaml` sets
|
||||
`skip_specs: true`. Use `skip_specs: true` only when no spec-level
|
||||
behavior changes (pure refactor, tooling, docs) - specs describe
|
||||
behavior, so if behavior does not change, no spec should change either.
|
||||
Do not invent a requirement just to satisfy validation.
|
||||
|
||||
Keep it concise (1-2 pages). Focus on the "why" not the "how" -
|
||||
implementation details belong in design.md.
|
||||
|
||||
This is the foundation - specs, design, and tasks all build on this.
|
||||
requires: []
|
||||
|
||||
- id: specs
|
||||
generates: "specs/**/*.md"
|
||||
description: Detailed specifications for the change
|
||||
template: spec.md
|
||||
instruction: |
|
||||
Создай спецификации наблюдаемого поведения и устойчивых контрактов.
|
||||
Правила ниже применяются к master specs и к полным блокам ADDED/MODIFIED
|
||||
в delta specs. Это пользовательский формат без Gherkin.
|
||||
|
||||
Иерархия и границы:
|
||||
- Capability имеет отдельную бизнес-функцию или понятный результат.
|
||||
- Сохраняй полный иерархический путь, например orders/snapshot-sync.
|
||||
- Один Requirement описывает одну завершённую техническую функцию.
|
||||
- Не дроби один процесс на Requirements для чтения, валидации и записи.
|
||||
- Каждый Requirement имеет стабильный ID вида CFG.AS-01 и ровно один Scenario.
|
||||
- Префикс Requirement уникален для пути capability и регистрируется в
|
||||
capability-codes.md: configuration/application-settings получает CFG.AS.
|
||||
Номер Requirement уникален внутри capability, что делает полный ID
|
||||
уникальным в проекте. Существующие, ещё не рефакторенные Requirements
|
||||
могут сохранять старый ID.
|
||||
- Заголовки OpenSpec: ### Requirement: и #### Scenario:.
|
||||
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
|
||||
- Включай только сведения, меняющие наблюдаемое поведение, устойчивый
|
||||
контракт или обязательное техническое ограничение. Удаляй повторы,
|
||||
пояснения и формулировки, которые не меняют поведение и не снимают
|
||||
неоднозначность контракта.
|
||||
|
||||
Scenario:
|
||||
- Поддерживаются два формата Use case: полный и сокращенный. Автор
|
||||
выбирает формат по ситуации, независимо от типа FR и того, что
|
||||
описывается: runtime-процесс, БД, API, UI или другая часть системы.
|
||||
- Полный Use case содержит разделы Участники, Предусловия,
|
||||
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
|
||||
в таком порядке.
|
||||
- Сокращенный Use case содержит только раздел `##### Основной поток`;
|
||||
каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит
|
||||
участников, предусловий, альтернатив и ошибок, результата или кодов
|
||||
завершения и не задаёт отдельные runtime-развилки.
|
||||
- В обычном сценарии Назначение опционально; добавляй только если оно
|
||||
сообщает сведения, которых нет в заголовке. Контекст отсутствует.
|
||||
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
|
||||
- Шаг runtime-сценария может назвать действие, endpoint или способ записи
|
||||
и сослаться на FR.
|
||||
- Каждый HTTP endpoint описывай в отдельном Requirement с полным Use case.
|
||||
Сложные правила шага выноси в FR и связывай со сценарием ссылками.
|
||||
- Основной поток и альтернативы обычного сценария включают коды
|
||||
завершения, если они определены для этой функции.
|
||||
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
|
||||
сообщений и дальнейшая логика располагаются за пределами Scenario.
|
||||
- Единственная таблица Scenario — Коды завершения с колонками
|
||||
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
|
||||
- Код сам сообщает смысл итога; дополнительный stage или свободный текст
|
||||
не должен требоваться для понимания кода. События промежуточных шагов
|
||||
не являются кодами завершения. Не создавай код для каждой диагностики.
|
||||
- Каждая запись кода ссылается на локальные FR, определяющие дальнейшую
|
||||
логику, текст или применимые правила результата.
|
||||
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
|
||||
содержательного текста без адресов Markdown-ссылок.
|
||||
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
|
||||
|
||||
Функциональные требования:
|
||||
- После Scenario, на уровне ####, идёт раздел Функциональные требования.
|
||||
- Внутри: ##### CFG.AS-01.FR-01: <название>, ##### CFG.AS-01.FR-02 [DB]: <название>, ##### CFG.AS-01.FR-03 [API]: <название> и так далее.
|
||||
- ID FR содержит ID Requirement и локальный номер: <requirement-id>.FR-NN.
|
||||
Номер начинается с FR-01 в каждом Requirement.
|
||||
- FR содержит отдельное понятное правило или связанный контракт; не дроби
|
||||
связную логику на множество атомарных FR.
|
||||
- Обычный FR без метки описывает логику, правила или последовательность
|
||||
шагов. Типизированный FR помечай сразу после ID меткой [DB], [API]
|
||||
или [UI]; метка не входит в ID и не меняет slug ссылки.
|
||||
- [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает
|
||||
контракт сообщения или технического лога. Контракт HTTP endpoint
|
||||
размещается в отдельном разделе CONTRACT. [UI] описывает требования к
|
||||
UI; детальный паттерн будет добавлен отдельно.
|
||||
- Для FR [DB] с таблицей БД следуй паттерну
|
||||
`openspec/schemas/function-driven/patterns/database-table.md`.
|
||||
- Для сериализуемого контракта сообщения в FR [API] следуй паттерну
|
||||
`openspec/schemas/function-driven/patterns/message-contract.md`.
|
||||
- Контракт HTTP endpoint не оформляй отдельными FR. После раздела
|
||||
Функциональные требования добавляй завершающий раздел CONTRACT с
|
||||
подразделами Request и Response в таком порядке. В Request указывай
|
||||
один HTTP-метод и путь; для отсутствующего тела явно отмечай это.
|
||||
Таблицы тела запроса и ответа оформляй по паттерну message-contract.md.
|
||||
- В таблице Response раздела CONTRACT укажи для каждого поля источник
|
||||
значения или правило его формирования в последней колонке.
|
||||
- В таблице response-контракта FR [API] укажи для каждого поля источник
|
||||
значения или правило его формирования в колонке «Формирование значения».
|
||||
- Не добавляй HTML-якоря вида <a id="..."></a>. Markdown генерирует
|
||||
якоря из заголовков Requirement и FR.
|
||||
- Ссылайся на FR по полному ID и slug его заголовка, например
|
||||
[CFG.AS-01.FR-01](#cfgas-01fr-01-правило-обработки). Полный ID
|
||||
используется и для ссылки внутри Requirement, и для ссылки на другой
|
||||
Requirement.
|
||||
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
|
||||
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
|
||||
новые FR добавляй в конец. Порядок первого документа последовательный.
|
||||
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие
|
||||
сообщения/действия, если это часть контракта. Параметры сообщений
|
||||
являются данными, а не скрытым значением кода.
|
||||
- Если смысловой код спецификации отличается от действующего runtime,
|
||||
явно опиши соответствие и статус реализации в FR. Не утверждай,
|
||||
что новый код или текст уже возвращается приложением.
|
||||
|
||||
Работа с OpenSpec:
|
||||
- Создай specs/<capability-path>/spec.md для каждой capability из proposal.
|
||||
- Master spec использует шаблон templates/main-spec.md этой схемы.
|
||||
- Delta spec использует templates/spec.md и разделы ## ADDED Requirements,
|
||||
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
|
||||
- Для новой capability delta начинается с ## Purpose (50+ знаков).
|
||||
Для существующей capability Purpose в delta не добавляй.
|
||||
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR.
|
||||
Его заголовок должен совпадать с заголовком master spec.
|
||||
- REMOVED содержит Reason и Migration; RENAMED использует FROM/TO.
|
||||
Это операции над требованиями, не сценарии технических функций.
|
||||
- При копировании блоков в delta сохраняй ID Requirements, номера и
|
||||
заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в
|
||||
неизменённый Requirement master spec, проверяй delta с --base <master-spec>.
|
||||
- Не создавай delta для чистого форматирования, tooling или рефакторинга.
|
||||
Для change без изменения поведения используй skip_specs: true.
|
||||
- Проверь schema через openspec schema validate function-driven.
|
||||
- Проверь spec через openspec validate и отдельно через
|
||||
python3 openspec/schemas/function-driven/validate_format.py
|
||||
--require-qualified-ids <spec-path>. Для неизменённых legacy specs
|
||||
этот флаг не нужен.
|
||||
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
|
||||
requires:
|
||||
- proposal
|
||||
|
||||
- id: design
|
||||
generates: design.md
|
||||
description: Technical design document with implementation details
|
||||
template: design.md
|
||||
instruction: |
|
||||
Create the design document that explains HOW to implement the change.
|
||||
|
||||
When to include design.md (create only if any apply):
|
||||
- Cross-cutting change (multiple services/modules) or new architectural pattern
|
||||
- New external dependency or significant data model changes
|
||||
- Security, performance, or migration complexity
|
||||
- Ambiguity that benefits from technical decisions before coding
|
||||
|
||||
Sections:
|
||||
- **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
|
||||
- **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
|
||||
- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
|
||||
- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
|
||||
- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
|
||||
- **Open Questions**: Unknowns that can safely be answered later without
|
||||
changing the specs, the approach, or the task breakdown. Omit if none.
|
||||
|
||||
Open questions are for genuinely deferrable unknowns, not decisions you
|
||||
skipped. If a question would change the specs, the chosen approach, or
|
||||
the task breakdown, resolve it now - ask the user instead of guessing.
|
||||
|
||||
Focus on architecture and approach, not line-by-line implementation.
|
||||
The proposal covers why and what; design covers how. Reference the
|
||||
proposal for motivation and, once written, the specs for requirements -
|
||||
if a section would only restate them, point to them instead.
|
||||
|
||||
Good design docs explain the "why" behind technical decisions.
|
||||
requires:
|
||||
- proposal
|
||||
|
||||
- id: tasks
|
||||
generates: tasks.md
|
||||
description: Implementation checklist with trackable tasks
|
||||
template: tasks.md
|
||||
instruction: |
|
||||
Create the task list that breaks down the implementation work.
|
||||
|
||||
Before writing tasks, check design.md for Open Questions. If any of them
|
||||
would change what gets built, resolve them with the user first - do not
|
||||
bake an unstated assumption into the task list.
|
||||
|
||||
**IMPORTANT: Follow the template below exactly.** The apply phase parses
|
||||
checkbox format to track progress. A box holding only `x` counts as done,
|
||||
upper or lower case and with any spacing, so `- [ x]` is done too. Every
|
||||
other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
|
||||
unfinished. A line with no checkbox is not tracked at all.
|
||||
|
||||
Guidelines:
|
||||
- Group related tasks under ## numbered headings
|
||||
- Each task MUST be a checkbox: `- [ ] X.Y Task description`
|
||||
- Tasks should be small enough to complete in one session
|
||||
- Order tasks by dependency (what must be done first?)
|
||||
- Each task MUST state how to verify completion (a test, command,
|
||||
observable behavior, or delivered artifact). Put the verification in
|
||||
that task's checkbox description. Use a separate verification task only
|
||||
when it checks broader integration or system behavior that spans
|
||||
multiple implementation tasks.
|
||||
|
||||
Example:
|
||||
```
|
||||
# Tasks
|
||||
|
||||
## 1. Setup
|
||||
|
||||
- [ ] 1.1 Create new module structure and verify expected files are present
|
||||
- [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
|
||||
|
||||
## 2. Core Implementation
|
||||
|
||||
- [ ] 2.1 Implement data export function and verify the export test passes
|
||||
- [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
|
||||
```
|
||||
|
||||
Reference specs for what needs to be built, design for how to build it.
|
||||
requires:
|
||||
- specs
|
||||
- design
|
||||
|
||||
apply:
|
||||
requires: [ tasks ]
|
||||
tracks: tasks.md
|
||||
instruction: |
|
||||
Read context files, work through pending tasks, mark complete as you go.
|
||||
Pause if you hit blockers or need clarification.
|
||||
@@ -1,21 +0,0 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
<!-- What this design aims to achieve -->
|
||||
|
||||
**Non-Goals:**
|
||||
<!-- What is explicitly out of scope -->
|
||||
|
||||
## Decisions
|
||||
|
||||
<!-- Key design decisions with rationale and alternatives considered -->
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
<!-- Known risks and trade-offs -->
|
||||
@@ -1,106 +0,0 @@
|
||||
# Capability: <название>
|
||||
|
||||
## Purpose
|
||||
|
||||
<Бизнес-функция capability и понятный результат, не менее 50 знаков.>
|
||||
|
||||
<!-- Включай только сведения, меняющие поведение, контракт или обязательное
|
||||
ограничение. Удаляй повторы и пояснения без такого влияния. -->
|
||||
|
||||
## Границы
|
||||
|
||||
- <область ответственности capability>.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: <название завершённой технической функции>
|
||||
|
||||
**ID:** `AREA.CAP-01`
|
||||
|
||||
Система SHALL <наблюдаемый результат завершённой функции>.
|
||||
|
||||
#### Scenario: <название завершённого процесса>
|
||||
|
||||
##### Участники
|
||||
|
||||
- <участники процесса>.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- <условия начала процесса>.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. <Что делаем — как делаем> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-или-устойчивый-контракт).
|
||||
2. Завершаем с `FUNCTION_COMPLETED` — фиксируем результат по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- <условие ошибки> — завершаем с `FUNCTION_FAILED` по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение).
|
||||
|
||||
##### Результат
|
||||
|
||||
<Наблюдаемое состояние после завершения>.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `FUNCTION_COMPLETED` | <самодостаточный смысл успешного завершения> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) |
|
||||
| `FUNCTION_FAILED` | <самодостаточный смысл ошибки> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### AREA.CAP-01.FR-01: Правило обработки
|
||||
|
||||
<Обычный FR описывает логику, правило или последовательность шагов. Для
|
||||
специального формата добавь метку после ID: [DB], [API] или [UI]. Структуру
|
||||
таблицы БД и контракт сообщения оформи по соответствующему паттерну. Контракт
|
||||
HTTP endpoint располагай в завершающем разделе CONTRACT.>
|
||||
|
||||
##### AREA.CAP-01.FR-02: Коды завершения, тексты и дальнейшее поведение
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `FUNCTION_COMPLETED` | <текст или явное отсутствие сообщения> | <следующие действия> |
|
||||
| `FUNCTION_FAILED` | <текст ошибки> | <обработка ошибки, повтор, действие оператора> |
|
||||
|
||||
<При необходимости — параметры сообщений, связанные требования и соответствие
|
||||
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
|
||||
|
||||
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case.
|
||||
Контракт размещай в конце Requirement, не разбивая request/response на FR:
|
||||
|
||||
#### CONTRACT
|
||||
|
||||
##### Request
|
||||
|
||||
Метод: `POST`; путь: `/resource`. <Тело запроса или явное отсутствие тела.>
|
||||
|
||||
##### Response
|
||||
|
||||
HTTP status: <код и условие возврата>.
|
||||
|
||||
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
|
||||
-->
|
||||
|
||||
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от
|
||||
типа FR и предмета описания. Для сокращенного Use case используй только основной
|
||||
поток и ссылки на FR:
|
||||
|
||||
#### Scenario: Сокращенный use case: <предмет описания>
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. <Кратко опиши первый аспект> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
|
||||
2. <Кратко опиши следующий аспект> по [AREA.CAP-01.FR-02](#areacap-01fr-02-правило-или-контракт).
|
||||
-->
|
||||
|
||||
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
|
||||
[API] — контракт сообщения или технического лога; [UI] — требования к UI.
|
||||
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md.
|
||||
Сериализуемый контракт FR [API] оформляй по
|
||||
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице
|
||||
добавь колонку «Формирование значения» для каждого поля. -->
|
||||
@@ -1,31 +0,0 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
|
||||
|
||||
## What Changes
|
||||
|
||||
<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
|
||||
(e.g., user-auth or identity/user-auth) that follow the project's existing
|
||||
spec organization. Each creates specs/<capability-path>/spec.md. -->
|
||||
- `<capability-path>`: <brief description of what this capability covers>
|
||||
|
||||
### Modified Capabilities
|
||||
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
|
||||
Only list here if spec-level behavior changes. Each needs a delta spec file.
|
||||
Use the exact existing path under openspec/specs/. Leave empty if no requirement
|
||||
changes. A change with no capabilities at all (pure refactor, tooling, docs)
|
||||
must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
|
||||
a zero-delta change without that marker. Do not invent a requirement just to
|
||||
satisfy validation. -->
|
||||
- `<existing-capability-path>`: <what requirement is changing>
|
||||
|
||||
## Impact
|
||||
|
||||
<!-- Affected code, APIs, dependencies, systems -->
|
||||
@@ -1,11 +0,0 @@
|
||||
# Tasks
|
||||
|
||||
## 1. <!-- Task Group Name -->
|
||||
|
||||
- [ ] 1.1 <!-- Task description -->
|
||||
- [ ] 1.2 <!-- Task description -->
|
||||
|
||||
## 2. <!-- Task Group Name -->
|
||||
|
||||
- [ ] 2.1 <!-- Task description -->
|
||||
- [ ] 2.2 <!-- Task description -->
|
||||
+67
-24
@@ -1,30 +1,36 @@
|
||||
# Схема function-driven
|
||||
# Схема use-case-driven
|
||||
|
||||
Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на
|
||||
`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`.
|
||||
Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes
|
||||
с явно указанной `schema: spec-driven` продолжают использовать свою схему;
|
||||
их миграция не является частью изменения формата master spec.
|
||||
`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на
|
||||
`spec-driven`. Она задаёт workflow `proposal → specs / design → tasks`;
|
||||
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
|
||||
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
|
||||
|
||||
## Уровни спецификации
|
||||
|
||||
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
|
||||
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
|
||||
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
|
||||
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
|
||||
- FR — подробные правила и контракты сообщений за пределами Scenario;
|
||||
контракт HTTP endpoint размещается в завершающем CONTRACT.
|
||||
|
||||
В спецификацию включаются только сведения, влияющие на наблюдаемое поведение,
|
||||
устойчивый контракт или обязательное техническое ограничение. Повторы и
|
||||
пояснения без такого влияния удаляются.
|
||||
Requirements и FR включают только сведения, влияющие на наблюдаемое поведение,
|
||||
устойчивый контракт или обязательное техническое ограничение. Раздел «Границы»
|
||||
кратко фиксирует ответственность и владение capability, не повторяя Requirements.
|
||||
Повторы и пояснения без такого влияния удаляются.
|
||||
|
||||
Для каждой capability зарегистрируй стабильный уникальный префикс в
|
||||
[`capability-codes.md`](capability-codes.md). Его сегменты отражают путь
|
||||
capability: например, `configuration/application-settings` получает `CFG.AS`.
|
||||
ID Requirement имеет вид `CFG.AS-01`; его номер уникален внутри capability.
|
||||
В сочетании с уникальным префиксом это даёт уникальный ID в проекте.
|
||||
ID FR включает ID Requirement и локальный номер: `CFG.AS-01.FR-01`,
|
||||
`CFG.AS-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement.
|
||||
Составной префикс Requirement строится из сокращений сегментов пути capability:
|
||||
для однословного сегмента используй первые три буквы, для сегмента с дефисами —
|
||||
первые буквы его частей. Приводи сокращения к верхнему регистру. Например,
|
||||
`domain/capability-name` получает `DOM.CN`. Если префикс уже занят, удлиняй
|
||||
сокращения новых сегментов до уникальности; ранее назначенные префиксы не меняй.
|
||||
Сохраняй префикс при переименовании capability. Валидатор проверяет уникальность
|
||||
по ID в master specs и активных changes; отдельный реестр кодов не ведётся.
|
||||
|
||||
ID Requirement имеет вид `AREA.CAP-01`; его номер уникален внутри capability.
|
||||
Полный ID уникален в проекте благодаря уникальному префиксу и номеру.
|
||||
ID FR включает ID Requirement и локальный номер: `AREA.CAP-01.FR-01`,
|
||||
`AREA.CAP-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement.
|
||||
В новых и изменяемых Requirements используй составные ID. Неизменённые legacy
|
||||
specs могут сохранять прежние ID до отдельного рефакторинга.
|
||||
|
||||
@@ -58,7 +64,7 @@ Markdown-рендерер автоматически создаёт якоря
|
||||
В Scenario «Назначение» опционально и добавляется только при наличии сведений,
|
||||
которых нет в заголовке. «Контекст» в Scenario отсутствует. Основной поток —
|
||||
нумерованные короткие шаги «Что делаем — как делаем», например:
|
||||
«Получаем клиентов — вызываем GET /cp/users по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)».
|
||||
«Получаем данные — вызываем GET /api/resources по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)».
|
||||
|
||||
## Форматы Use case
|
||||
|
||||
@@ -124,12 +130,17 @@ FR, описывающий таблицу БД, оформляется по
|
||||
В response-таблице также указывается источник или правило формирования каждого поля.
|
||||
Другие паттерны добавляются отдельными файлами по мере появления потребности.
|
||||
|
||||
## Шаблоны и delta specs
|
||||
## Форматы master и delta specs
|
||||
|
||||
- `templates/main-spec.md` — постоянная спецификация capability.
|
||||
- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`.
|
||||
- `templates/main-spec.md` — краткая схема постоянной master spec: Purpose, Границы и Requirements; это не артефакт change.
|
||||
- `templates/spec.md` — полный шаблон delta для change, предоставляемый `openspec instructions specs`.
|
||||
- `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow.
|
||||
|
||||
В master spec раздел `## Границы` располагается между Purpose и Requirements.
|
||||
Он описывает ответственность capability, её включённую область и явные
|
||||
исключения или передачу ответственности другим capabilities и приложению.
|
||||
В delta spec этот раздел не повторяется: delta меняет отдельные Requirements.
|
||||
|
||||
ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration,
|
||||
RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный
|
||||
Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и
|
||||
@@ -140,12 +151,44 @@ Scenario в таких операциях не создаётся. В delta со
|
||||
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
|
||||
Форматирование спецификации само по себе не реализует этот контракт в приложении.
|
||||
|
||||
## Архитектурные решения (ADR)
|
||||
|
||||
Храни ADR проекта в `openspec/context/adr/` и называй файлы
|
||||
`ADR-<номер>-<краткое-описание>.md`, например
|
||||
`ADR-0001-use-postgresql.md`. Используй четырёхзначную последовательную
|
||||
нумерацию: новый номер на единицу больше максимального номера в каталоге.
|
||||
Номер не переиспользуется, даже если решение отклонено или заменено. Краткое
|
||||
описание в имени файла пиши в `kebab-case`.
|
||||
|
||||
Создавай ADR для долгосрочных архитектурных решений с последствиями для
|
||||
будущих изменений: выбора между значимыми вариантами, общих ограничений,
|
||||
границ компонентов и решений, которые иначе пришлось бы повторно принимать.
|
||||
Не создавай ADR для каждого change, деталей реализации, уже полностью заданных
|
||||
спецификацией, или временных задач.
|
||||
|
||||
В ADR фиксируй контекст и проблему, факторы решения, рассмотренные варианты,
|
||||
выбранное решение и его последствия. Используй статусы `Proposed`, `Accepted`,
|
||||
`Rejected` и `Superseded`. Предложенный ADR становится действующим только после
|
||||
явного принятия владельцем решения. Отклонённые и заменённые ADR сохраняй как
|
||||
историю. Не меняй принятое решение задним числом: при пересмотре создай новый
|
||||
ADR со ссылкой на заменяемый и обнови его статус на `Superseded`. В новом ADR
|
||||
укажи заменяемый ID в `supersedes`, а в прежнем — новый ID в `superseded-by`.
|
||||
|
||||
Перед проектированием и реализацией агент читает применимые принятые ADR.
|
||||
Изменение должно ссылаться на относящиеся к нему ADR в `design.md`. При
|
||||
противоречии между запросом и принятым ADR агент явно сообщает о конфликте и
|
||||
получает решение пользователя, а не обходит ADR молча. Агент может подготовить
|
||||
ADR со статусом `Proposed`, но не принимает его самостоятельно.
|
||||
|
||||
Шаблон нового решения находится в
|
||||
[`templates/adr.md`](templates/adr.md).
|
||||
|
||||
## Проверки
|
||||
|
||||
```sh
|
||||
openspec schema validate function-driven
|
||||
openspec validate orders/snapshot-sync --type spec --strict --no-interactive
|
||||
python3 openspec/schemas/function-driven/validate_format.py --require-qualified-ids openspec/specs/orders/snapshot-sync/spec.md
|
||||
openspec schema validate use-case-driven
|
||||
openspec validate domain/capability-name --type spec --strict --no-interactive
|
||||
python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids openspec/specs/domain/capability-name/spec.md
|
||||
```
|
||||
|
||||
Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`.
|
||||
@@ -158,7 +201,7 @@ python3 openspec/schemas/function-driven/validate_format.py --require-qualified-
|
||||
неизменённые legacy specs. Проверка охватывает один Scenario,
|
||||
обычную структуру use case или формат сокращенного use case, ссылки шагов на FR,
|
||||
форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков
|
||||
в Scenario, ID из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
|
||||
в Scenario, префиксы из ID master specs, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
|
||||
таблицу кодов и её связь с FR.
|
||||
Семантическую завершённость функции и понятность кода оценивает автор/reviewer.
|
||||
Схема требует от автора запускать обе проверки; автоматического hook в CLI нет.
|
||||
+7
-9
@@ -19,19 +19,17 @@
|
||||
## Пример
|
||||
|
||||
```markdown
|
||||
##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings
|
||||
##### AREA.CAP-01.FR-01 [DB]: Таблица хранения записей
|
||||
|
||||
Таблица `settings` создаётся в схеме приложения и содержит:
|
||||
Таблица `example_records` создаётся в схеме приложения и содержит:
|
||||
|
||||
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- |
|
||||
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки |
|
||||
| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения |
|
||||
| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки |
|
||||
| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки |
|
||||
| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей |
|
||||
| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении |
|
||||
| `description` | `TEXT` | NULL | Пояснение к настройке |
|
||||
| `external_id` | `VARCHAR(64)` | NOT NULL | Идентификатор записи во внешней системе |
|
||||
| `status` | `VARCHAR(32)` | NOT NULL | Текущее состояние записи |
|
||||
| `created_at` | `TIMESTAMP` | NOT NULL | Время создания записи |
|
||||
| `updated_at` | `TIMESTAMP` | NULL | Время последнего изменения записи |
|
||||
|
||||
Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается.
|
||||
Индекс поддерживает выборку по `external_id` и `status`. Ограничение уникальности на `external_id` устанавливается, если внешняя система гарантирует его уникальность.
|
||||
```
|
||||
@@ -0,0 +1,351 @@
|
||||
name: use-case-driven
|
||||
version: 1
|
||||
description: >-
|
||||
Иерархические спецификации поведения: один Requirement описывает завершённую
|
||||
функцию через сценарий использования без Gherkin, а связанные FR фиксируют
|
||||
подробные правила, устойчивые контракты и обязательные ограничения системы.
|
||||
artifacts:
|
||||
- id: proposal
|
||||
generates: proposal.md
|
||||
description: Начальный документ предложения, описывающий изменение
|
||||
template: proposal.md
|
||||
instruction: |
|
||||
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки
|
||||
OpenSpec и технические идентификаторы, названия API, файлов,
|
||||
инструментов, команд и коды без перевода.
|
||||
|
||||
Создай документ предложения, объясняющий, ПОЧЕМУ требуется это изменение.
|
||||
|
||||
Разделы:
|
||||
- **Why**: 1–2 предложения о проблеме или возможности. Какую проблему
|
||||
решает изменение? Почему его нужно сделать сейчас?
|
||||
- **What Changes**: Список изменений. Точно опиши новые возможности,
|
||||
изменения и удаления. Помечай несовместимые изменения как **BREAKING**.
|
||||
- **Capabilities**: Укажи, какие спецификации будут созданы или изменены:
|
||||
Capability представляет отдельную бизнес-функцию или понятный результат;
|
||||
сохраняй полный иерархический путь, например `domain/capability-name`.
|
||||
Для новой capability сформируй короткий читаемый префикс Requirement:
|
||||
для однословного сегмента используй первые три буквы, для сегмента с
|
||||
дефисами — первые буквы его частей. Приводи сокращения к верхнему
|
||||
регистру, разделяй сегменты кода точкой и сохраняй их порядок:
|
||||
`domain/capability-name` → `DOM.CN`.
|
||||
Перед назначением проверь уникальность префикса по Requirement ID в
|
||||
основных спецификациях проекта. Если префикс занят, удлиняй сокращения
|
||||
новых сегментов до уникальности; уже используемые префиксы не меняй.
|
||||
Сохраняй префикс при переименовании capability.
|
||||
- **New Capabilities**: Перечисли добавляемые capabilities. Для каждой
|
||||
создай `specs/<capability-path>/spec.md`. Используй `kebab-case` для
|
||||
новых сегментов пути (например, `user-auth` или `identity/user-auth`)
|
||||
и следуй принятой в проекте структуре спецификаций.
|
||||
- **Modified Capabilities**: Перечисли существующие capabilities, чьи
|
||||
REQUIREMENTS меняются. Добавляй сюда capability только при изменении
|
||||
поведения, описанного в спецификации, а не только деталей реализации.
|
||||
Для каждой создай delta spec по точному существующему пути внутри
|
||||
`openspec/specs/`. Оставь список пустым, если требования не меняются.
|
||||
- **Impact**: Затронутые участки кода, API, зависимости и системы.
|
||||
|
||||
ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs.
|
||||
Перед его заполнением изучи существующие спецификации: выполни
|
||||
`openspec list --specs`, чтобы получить список capabilities проекта.
|
||||
Для подходящих вариантов выполни `openspec show "<spec-id>" --type spec --json --no-scenarios`.
|
||||
Команда вернёт назначение capability и тексты требований, не загружая
|
||||
целые файлы спецификаций. Добавляй `--store "<id>"` к обеим командам
|
||||
только для зарегистрированного отдельного хранилища и сохраняй
|
||||
`--type spec`: если артефакт `change` и спецификация имеют одинаковое имя,
|
||||
без этого параметра возникнет неоднозначность при выборе. Команда
|
||||
`openspec list` без `--specs` показывает активные изменения (`changes`),
|
||||
а не спецификации, поэтому не отражает уже описанное в проекте поведение.
|
||||
Используй точный путь
|
||||
существующей capability, не создавай похожее имя.
|
||||
Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже
|
||||
описано и что нужно изменить, прочитай каждую подходящую спецификацию
|
||||
целиком, включая сценарии, командой `openspec show "<spec-id>" --type spec`
|
||||
(с тем же правилом для `--store`). Для каждой перечисленной capability
|
||||
потребуется соответствующий файл спецификации.
|
||||
|
||||
В каждом изменении (`change`) должна быть указана хотя бы одна новая или
|
||||
изменяемая capability либо явный отказ от спецификаций: `openspec validate`
|
||||
отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не
|
||||
задано `skip_specs: true`.
|
||||
Используй `skip_specs: true` только когда поведение, описываемое
|
||||
спецификациями, не меняется (например, при чистом рефакторинге, изменении
|
||||
инструментов или документации). Не добавляй требование только ради
|
||||
прохождения проверки.
|
||||
|
||||
Пиши кратко (1–2 страницы). Сосредоточься на причинах изменения, а не на
|
||||
способе реализации: детали реализации относятся к design.md.
|
||||
|
||||
Этот документ задаёт основу: на нём строятся specs, design и tasks.
|
||||
requires: []
|
||||
|
||||
- id: specs
|
||||
generates: "specs/**/*.md"
|
||||
description: Подробные спецификации изменения
|
||||
template: spec.md
|
||||
instruction: |
|
||||
Пиши пояснительный текст спецификаций по-русски. Сохраняй обязательные
|
||||
заголовки OpenSpec, идентификаторы, названия API и коды без перевода.
|
||||
|
||||
Создай спецификации наблюдаемого поведения и устойчивых контрактов.
|
||||
Правила ниже применяются к основным спецификациям и к полным блокам
|
||||
ADDED/MODIFIED в delta-спецификациях. Это пользовательский формат без Gherkin.
|
||||
|
||||
Иерархия и границы:
|
||||
- Capability описывает отдельную бизнес-функцию или понятный результат.
|
||||
- Сохраняй полный иерархический путь, например domain/capability-name.
|
||||
- Основная спецификация содержит раздел ## Границы между Purpose и
|
||||
Requirements. Кратко укажи, за что отвечает capability, что входит в её
|
||||
область и что находится за её пределами или относится к другой capability
|
||||
либо приложению. Не дублируй Requirements и FR.
|
||||
- Один Requirement описывает одну завершённую техническую функцию.
|
||||
- Не дроби один процесс на Requirements для чтения, валидации и записи.
|
||||
- Каждый Requirement имеет стабильный составной ID вида AREA.CAP-01 и ровно один Scenario.
|
||||
- Префикс Requirement состоит из сокращений сегментов пути capability,
|
||||
разделённых точками; его уникальность проверяется по ID в основных
|
||||
спецификациях. Номер Requirement уникален внутри capability. Существующие
|
||||
унаследованные Requirements могут сохранять прежние ID.
|
||||
- Заголовки OpenSpec: ### Requirement: и #### Scenario:.
|
||||
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
|
||||
- В Requirements и FR включай только сведения, меняющие наблюдаемое
|
||||
поведение, устойчивый контракт или обязательное техническое ограничение.
|
||||
Удаляй повторы, пояснения и формулировки, которые не меняют поведение и
|
||||
не снимают неоднозначность контракта. В ## Границы оставляй краткие
|
||||
сведения об ответственности и владении, необходимые для понимания
|
||||
области capability, даже если они сами по себе не задают поведение.
|
||||
|
||||
Scenario:
|
||||
- Поддерживаются два формата сценария использования: полный и
|
||||
сокращённый. Автор выбирает формат по ситуации, независимо от типа FR
|
||||
и описываемой части системы: процесса выполнения, БД, API, UI и других.
|
||||
- Полный сценарий использования содержит разделы Участники, Предусловия,
|
||||
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
|
||||
в таком порядке.
|
||||
- Сокращённый сценарий использования содержит только раздел `##### Основной поток`;
|
||||
каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит
|
||||
участников, предусловий, альтернатив и ошибок, результата или кодов
|
||||
завершения и не задаёт отдельные ветвления во время выполнения.
|
||||
- В обычном сценарии Назначение опционально; добавляй только если оно
|
||||
сообщает сведения, которых нет в заголовке. Контекст отсутствует.
|
||||
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
|
||||
- Шаг сценария выполнения может назвать действие, конечную точку API или
|
||||
способ записи и сослаться на FR.
|
||||
- Каждую конечную точку HTTP описывай в отдельном Requirement с полным
|
||||
сценарием использования.
|
||||
Сложные правила шага выноси в FR и связывай со сценарием ссылками.
|
||||
- Основной поток и альтернативы обычного сценария включают коды
|
||||
завершения, если они определены для этой функции.
|
||||
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
|
||||
сообщений и дальнейшая логика располагаются за пределами Scenario.
|
||||
- Единственная таблица Scenario — Коды завершения с колонками
|
||||
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
|
||||
- Код сам сообщает смысл итога; дополнительный этап или свободный текст
|
||||
не должен требоваться для понимания кода. События промежуточных шагов
|
||||
не являются кодами завершения. Не создавай код для каждой диагностики.
|
||||
- Каждая запись кода ссылается на локальные FR, определяющие дальнейшую
|
||||
логику, текст или применимые правила результата.
|
||||
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
|
||||
содержательного текста без адресов Markdown-ссылок.
|
||||
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
|
||||
|
||||
Функциональные требования:
|
||||
- После Scenario, на уровне ####, идёт раздел Функциональные требования.
|
||||
- Внутри: ##### AREA.CAP-01.FR-01: <название>, ##### AREA.CAP-01.FR-02 [DB]: <название>, ##### AREA.CAP-01.FR-03 [API]: <название> и так далее.
|
||||
- ID FR содержит ID Requirement и локальный номер: <requirement-id>.FR-NN.
|
||||
Номер начинается с FR-01 в каждом Requirement.
|
||||
- FR содержит отдельное понятное правило или связанный контракт; не дроби
|
||||
связную логику на множество атомарных FR.
|
||||
- Обычный FR без метки описывает логику, правила или последовательность
|
||||
шагов. Типизированный FR помечай сразу после ID меткой [DB], [API]
|
||||
или [UI]; метка не входит в ID и не меняет slug ссылки.
|
||||
- [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает
|
||||
контракт сообщения или технического лога. Контракт конечной точки HTTP
|
||||
размещается в отдельном разделе CONTRACT. [UI] описывает требования к
|
||||
UI; детальный паттерн будет добавлен отдельно.
|
||||
- Для FR [DB] с таблицей БД следуй паттерну
|
||||
`openspec/schemas/use-case-driven/patterns/database-table.md`.
|
||||
- Для сериализуемого контракта сообщения в FR [API] следуй паттерну
|
||||
`openspec/schemas/use-case-driven/patterns/message-contract.md`.
|
||||
- Контракт конечной точки HTTP не оформляй отдельными FR. После раздела
|
||||
Функциональные требования добавляй завершающий раздел CONTRACT с
|
||||
подразделами Request и Response в таком порядке. В Request указывай
|
||||
один HTTP-метод и путь; для отсутствующего тела явно отмечай это.
|
||||
Таблицы тела запроса и ответа оформляй по паттерну message-contract.md.
|
||||
- В таблице Response раздела CONTRACT укажи для каждого поля источник
|
||||
значения или правило его формирования в последней колонке.
|
||||
- В таблице ответа контракта FR [API] укажи для каждого поля источник
|
||||
значения или правило его формирования в колонке «Формирование значения».
|
||||
- Не добавляй HTML-якоря вида <a id="..."></a>. Markdown генерирует
|
||||
якоря из заголовков Requirement и FR.
|
||||
- Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его
|
||||
заголовка, например
|
||||
[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID
|
||||
используется и для ссылки внутри Requirement, и для ссылки на другой
|
||||
Requirement.
|
||||
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
|
||||
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
|
||||
новые FR добавляй в конец. Порядок первого документа последовательный.
|
||||
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие
|
||||
сообщения/действия, если это часть контракта. Параметры сообщений
|
||||
являются данными, а не скрытым значением кода.
|
||||
- Если смысловой код спецификации отличается от текущего поведения системы,
|
||||
явно опиши соответствие и статус реализации в FR. Не утверждай,
|
||||
что новый код или текст уже возвращается приложением.
|
||||
|
||||
Работа с OpenSpec:
|
||||
- Создай specs/<capability-path>/spec.md для каждой capability из proposal.
|
||||
- Основная спецификация следует краткой схеме templates/main-spec.md; это формат-
|
||||
ориентир, а не генерируемый артефакт. Сохраняй в ней Purpose, ## Границы
|
||||
и полный актуальный набор Requirements.
|
||||
- Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements,
|
||||
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
|
||||
- Для новой capability delta-спецификация начинается с ## Purpose
|
||||
(не менее 50 знаков). Для существующей capability Purpose в delta не добавляй.
|
||||
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR.
|
||||
Его заголовок должен совпадать с заголовком соответствующего Requirement
|
||||
в основной спецификации.
|
||||
- В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO.
|
||||
Это операции над требованиями, не сценарии технических функций.
|
||||
- При копировании блоков в delta сохраняй ID Requirements, номера и
|
||||
заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в
|
||||
неизменённый Requirement основной спецификации, проверяй delta с
|
||||
`--base <master-spec>`.
|
||||
- Не создавай delta для чистого форматирования, изменений инструментов
|
||||
или рефакторинга. Для изменения без изменения поведения используй
|
||||
`skip_specs: true`.
|
||||
- Проверь schema через openspec schema validate use-case-driven.
|
||||
- Проверь spec через openspec validate и отдельно через
|
||||
python3 openspec/schemas/use-case-driven/validate_format.py
|
||||
--require-qualified-ids <spec-path>. Для неизменённых спецификаций
|
||||
со старыми ID этот флаг не нужен.
|
||||
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
|
||||
requires:
|
||||
- proposal
|
||||
|
||||
- id: design
|
||||
generates: design.md
|
||||
description: Техническое описание решения и деталей реализации
|
||||
template: design.md
|
||||
instruction: |
|
||||
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки
|
||||
OpenSpec и технические идентификаторы, названия файлов, инструментов
|
||||
и команд без перевода.
|
||||
|
||||
Создай документ design, объясняющий, КАК реализовать изменение.
|
||||
|
||||
Когда добавлять design.md (достаточно любого из условий):
|
||||
- Изменение затрагивает несколько сервисов или модулей либо вводит новый
|
||||
архитектурный подход.
|
||||
- Добавляется внешняя зависимость или существенно меняется модель данных.
|
||||
- Есть сложность, связанная с безопасностью, производительностью или
|
||||
миграцией.
|
||||
- До начала разработки нужно принять технические решения, чтобы устранить
|
||||
неоднозначность.
|
||||
|
||||
Разделы:
|
||||
- **Context**: Только текущее состояние и ограничения, необходимые для
|
||||
объяснения подхода. Причины изменения смотри в proposal, не повторяй их
|
||||
(например: «См. proposal.md — Why»).
|
||||
- **Goals / Non-Goals**: Что это решение обеспечивает и что явно исключает.
|
||||
Не повторяй область работ из proposal; указывай только границы решения.
|
||||
- **Decisions**: Ключевые технические решения и их обоснование: почему
|
||||
выбран один вариант вместо другого. Укажи рассмотренные альтернативы.
|
||||
- **Risks / Trade-offs**: Известные ограничения и возможные проблемы.
|
||||
Формат: [Риск] → [Меры снижения].
|
||||
- **Migration Plan**: Шаги развёртывания и стратегия отката, если применимо.
|
||||
- **Open Questions**: Неизвестные, которые можно безопасно выяснить позже,
|
||||
не меняя спецификации, подход или состав задач. Не добавляй, если таких
|
||||
вопросов нет.
|
||||
|
||||
Открытые вопросы предназначены для действительно отложенных решений, а не
|
||||
для пропущенных решений. Если ответ может изменить спецификации, выбранный
|
||||
подход или состав задач, выясни его сейчас: спроси пользователя, а не
|
||||
делай предположение.
|
||||
|
||||
Сосредоточься на архитектуре и подходе, а не на пошаговом описании кода.
|
||||
В proposal описаны причины и состав изменения, в design — способ
|
||||
реализации. Ссылайся на proposal для обоснования и на specs для требований;
|
||||
если раздел только повторяет их, дай ссылку вместо повтора.
|
||||
|
||||
Ссылайся на Requirement ID и локальные FR; описывай решения реализации
|
||||
без копирования требований.
|
||||
|
||||
Перед проектированием прочитай применимые принятые ADR из
|
||||
`openspec/context/adr/` и укажи их идентификаторы в Decisions. Если
|
||||
изменение принимает долгосрочное архитектурное решение или заменяет
|
||||
принятое решение, запланируй создание нового ADR по шаблону
|
||||
`openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed.
|
||||
Не помечай ADR принятым самостоятельно. Если запрос противоречит
|
||||
действующему ADR, явно опиши конфликт и запроси решение пользователя до
|
||||
выбора расходящегося подхода.
|
||||
|
||||
Хороший design объясняет причины технических решений.
|
||||
requires:
|
||||
- proposal
|
||||
|
||||
- id: tasks
|
||||
generates: tasks.md
|
||||
description: Контрольный список задач с отслеживаемым выполнением
|
||||
template: tasks.md
|
||||
instruction: |
|
||||
Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные
|
||||
идентификаторы, пути файлов, названия API, коды и команды без перевода.
|
||||
|
||||
Создай список задач, разбивающий работу по реализации на части.
|
||||
|
||||
Перед составлением задач проверь Open Questions в design.md. Если ответ на
|
||||
какой-либо вопрос повлияет на результат разработки, сначала обсуди его с
|
||||
пользователем; не закладывай в список задач неоговорённые предположения.
|
||||
|
||||
**ВАЖНО: точно следуй шаблону ниже.** Этап apply отслеживает выполнение по
|
||||
формату чекбоксов. Чекбокс, содержащий только `x`, считается выполненным
|
||||
независимо от регистра и пробелов; например, `- [ x]` тоже означает
|
||||
выполнение. Любая другая отметка, включая `- [~]`, `- [-]` и пустой `- []`,
|
||||
считается незавершённой. Строки без чекбокса вообще не отслеживаются.
|
||||
|
||||
Правила:
|
||||
- Группируй связанные задачи под нумерованными заголовками `##`.
|
||||
- Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`.
|
||||
- Разбивай задачи так, чтобы каждую можно было выполнить за одну сессию.
|
||||
- Располагай задачи в порядке зависимостей: сначала то, что нужно сделать
|
||||
раньше.
|
||||
- Для каждой задачи укажи способ проверки выполнения: тест, команду,
|
||||
наблюдаемое поведение или готовый артефакт. Добавь проверку в описание
|
||||
чекбокса. Выноси проверку в отдельную задачу только для интеграционных
|
||||
или системных сценариев, охватывающих несколько задач реализации.
|
||||
|
||||
Пример:
|
||||
```
|
||||
# Tasks
|
||||
|
||||
## 1. Подготовка
|
||||
|
||||
- [ ] 1.1 Создать структуру модулей и проверить наличие ожидаемых файлов
|
||||
- [ ] 1.2 Добавить необходимые зависимости и проверить успешность установки
|
||||
|
||||
## 2. Основная реализация
|
||||
|
||||
- [ ] 2.1 Реализовать экспорт данных и проверить прохождение теста экспорта
|
||||
- [ ] 2.2 Добавить форматирование CSV и проверить обработку кавычек и разделителей модульными тестами
|
||||
```
|
||||
|
||||
Сверяйся со specs, чтобы определить, что нужно создать, и с design — как это
|
||||
реализовать.
|
||||
|
||||
Связывай задачи с Requirement ID, FR и кодами завершения, если задача
|
||||
затрагивает эти результаты.
|
||||
|
||||
Если в design предусмотрен новый или заменяющий ADR, включи в tasks
|
||||
отдельную задачу на его создание в `openspec/context/adr/` со статусом
|
||||
Proposed. При замене принятого решения свяжи новый и прежний ADR через
|
||||
поля `supersedes` и `superseded-by`.
|
||||
requires:
|
||||
- specs
|
||||
- design
|
||||
|
||||
apply:
|
||||
requires: [ tasks ]
|
||||
tracks: tasks.md
|
||||
instruction: |
|
||||
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
|
||||
выполненными по мере работы. Остановись, если столкнёшься с препятствием или
|
||||
потребуется уточнение.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
status: Proposed
|
||||
date: YYYY-MM-DD
|
||||
decision-makers:
|
||||
- <имя или роль владельца решения>
|
||||
supersedes: []
|
||||
superseded-by:
|
||||
---
|
||||
|
||||
# ADR-<номер>: <Краткое название решения>
|
||||
|
||||
## Контекст и проблема
|
||||
|
||||
Какую проблему нужно решить и какие ограничения важны для выбора?
|
||||
|
||||
## Факторы решения
|
||||
|
||||
- <Требование или ограничение, влияющее на решение>
|
||||
|
||||
## Рассмотренные варианты
|
||||
|
||||
- **<Вариант>** — преимущества и недостатки.
|
||||
|
||||
## Решение
|
||||
|
||||
Какой вариант выбран и почему? Заполняется при принятии ADR; до этого раздел
|
||||
может содержать предлагаемое решение.
|
||||
|
||||
## Последствия
|
||||
|
||||
- Положительные: <результаты и преимущества>.
|
||||
- Отрицательные или компромиссы: <цена решения, ограничения, риски>.
|
||||
|
||||
## Связанные решения
|
||||
|
||||
- <ID и ссылка на связанные ADR, если есть>
|
||||
@@ -0,0 +1,21 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
<!-- Текущее состояние и ограничения. Мотивация описана в proposal.md — не повторяй её. -->
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
<!-- Цели этого design -->
|
||||
|
||||
**Non-Goals:**
|
||||
<!-- Что явно не входит в scope -->
|
||||
|
||||
## Decisions
|
||||
|
||||
<!-- Ключевые технические решения, причины и рассмотренные альтернативы -->
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
<!-- Известные риски и компромиссы -->
|
||||
@@ -0,0 +1,16 @@
|
||||
# Capability: <название>
|
||||
|
||||
## Purpose
|
||||
|
||||
<Бизнес-функция capability и понятный результат, не менее 50 знаков.>
|
||||
|
||||
## Границы
|
||||
|
||||
<!-- Кратко опиши ответственность capability: что входит в её область,
|
||||
что остаётся за её пределами и кому это принадлежит. Не дублируй Requirements. -->
|
||||
|
||||
## Requirements
|
||||
|
||||
<!-- Полный актуальный набор Requirements capability. Оформляй Requirements
|
||||
по правилам schema.yaml. Не используй заголовки операций delta:
|
||||
ADDED, MODIFIED, REMOVED или RENAMED. -->
|
||||
@@ -0,0 +1,29 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
<!-- Объясни мотивацию change: какую проблему он решает и почему нужен сейчас. -->
|
||||
|
||||
## What Changes
|
||||
|
||||
<!-- Опиши изменения: новые возможности, доработки и удаления. -->
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
<!-- Добавляемые capabilities. Новые сегменты пути пиши в kebab-case и
|
||||
согласуй с существующей структурой спецификаций. Для каждой создай
|
||||
specs/<capability-path>/spec.md. -->
|
||||
- `<capability-path>`: <brief description of what this capability covers>
|
||||
|
||||
### Modified Capabilities
|
||||
<!-- Существующие capabilities, требования которых меняются. Указывай их только
|
||||
при изменении поведения на уровне спецификации; для каждой создай delta
|
||||
spec по точному пути openspec/specs/. Если требования не меняются, оставь
|
||||
раздел пустым и установи skip_specs: true в .openspec.yaml. Не создавай
|
||||
требование только ради прохождения проверки. -->
|
||||
- `<existing-capability-path>`: <what requirement is changing>
|
||||
|
||||
## Impact
|
||||
|
||||
<!-- Затронутые код, API, зависимости и системы -->
|
||||
+2
-2
@@ -101,7 +101,7 @@ HTTP status: <код и условие возврата>.
|
||||
|
||||
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
|
||||
[API] — контракт сообщения или технического лога; [UI] — требования к UI.
|
||||
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md.
|
||||
[DB] с таблицей оформляй по openspec/schemas/use-case-driven/patterns/database-table.md.
|
||||
Сериализуемый контракт FR [API] оформляй по
|
||||
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице
|
||||
openspec/schemas/use-case-driven/patterns/message-contract.md. В response-таблице
|
||||
добавь колонку «Формирование значения» для каждого поля. -->
|
||||
@@ -0,0 +1,11 @@
|
||||
# Tasks
|
||||
|
||||
## 1. <!-- Название группы задач -->
|
||||
|
||||
- [ ] 1.1 <!-- Формулировка задачи -->
|
||||
- [ ] 1.2 <!-- Формулировка задачи -->
|
||||
|
||||
## 2. <!-- Название группы задач -->
|
||||
|
||||
- [ ] 2.1 <!-- Формулировка задачи -->
|
||||
- [ ] 2.2 <!-- Формулировка задачи -->
|
||||
+193
-42
@@ -1,4 +1,4 @@
|
||||
"""Read-only checks of function-driven Markdown conventions; no dependencies."""
|
||||
"""Read-only checks of use-case-driven Markdown conventions; no dependencies."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -27,8 +27,6 @@ HTML_ANCHOR = re.compile(r"<a\b[^>]*\bid\s*=", re.IGNORECASE)
|
||||
DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение")
|
||||
CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение")
|
||||
RESPONSE_CONTRACT_COLUMNS = (*CONTRACT_COLUMNS, "Формирование значения")
|
||||
CAPABILITY_CODES_PATH = Path(__file__).with_name("capability-codes.md")
|
||||
CAPABILITY_CODE_ROW = re.compile(r"^\|\s*`([^`]+)`\s*\|\s*`([^`]+)`\s*\|$")
|
||||
|
||||
|
||||
def plain_text(value: str) -> str:
|
||||
@@ -65,27 +63,165 @@ def parse_fr_reference(label: str) -> tuple[str | None, str] | None:
|
||||
return None
|
||||
|
||||
|
||||
def load_capability_codes() -> tuple[dict[str, str], list[str]]:
|
||||
codes: dict[str, str] = {}
|
||||
errors: list[str] = []
|
||||
try:
|
||||
lines = CAPABILITY_CODES_PATH.read_text(encoding="utf-8").splitlines()
|
||||
except OSError as error:
|
||||
return {}, [f"не удалось прочитать реестр capability codes: {error}"]
|
||||
def openspec_root_for(path: Path) -> Path:
|
||||
"""Find the OpenSpec root containing a master or change spec."""
|
||||
resolved = path.resolve()
|
||||
for parent in (resolved, *resolved.parents):
|
||||
if parent.name == "openspec":
|
||||
return parent
|
||||
return (Path.cwd() / "openspec").resolve()
|
||||
|
||||
prefixes: dict[str, str] = {}
|
||||
for line in lines:
|
||||
match = CAPABILITY_CODE_ROW.match(line)
|
||||
if not match:
|
||||
|
||||
def load_capability_prefixes(openspec_root: Path) -> tuple[dict[str, str], list[str]]:
|
||||
"""Read the active path-to-prefix mapping from master specs."""
|
||||
specs_root = openspec_root / "specs"
|
||||
spec_paths = set(specs_root.rglob("spec.md"))
|
||||
prefixes_by_capability: dict[str, set[str]] = {}
|
||||
errors: list[str] = []
|
||||
for spec_path in sorted(spec_paths):
|
||||
capability_path = spec_path.parent.relative_to(specs_root).as_posix()
|
||||
try:
|
||||
ids = REQUIREMENT_ID.findall(spec_path.read_text(encoding="utf-8"))
|
||||
except OSError as error:
|
||||
errors.append(f"не удалось прочитать спецификацию {spec_path}: {error}")
|
||||
continue
|
||||
capability_path, prefix = match.groups()
|
||||
if capability_path in codes:
|
||||
errors.append(f"путь capability повторяется в реестре: {capability_path}")
|
||||
if prefix in prefixes:
|
||||
errors.append(f"префикс {prefix} повторяется для {prefixes[prefix]} и {capability_path}")
|
||||
codes[capability_path] = prefix
|
||||
prefixes[prefix] = capability_path
|
||||
return codes, errors
|
||||
prefixes = {
|
||||
requirement_id.rsplit("-", 1)[0]
|
||||
for requirement_id in ids
|
||||
if "." in requirement_id
|
||||
}
|
||||
if prefixes:
|
||||
prefixes_by_capability.setdefault(capability_path, set()).update(prefixes)
|
||||
|
||||
prefix_owners: dict[str, set[str]] = {}
|
||||
mappings: dict[str, str] = {}
|
||||
for capability_path, prefixes in prefixes_by_capability.items():
|
||||
if len(prefixes) != 1:
|
||||
errors.append(
|
||||
f"capability {capability_path} использует несколько префиксов: "
|
||||
f"{', '.join(sorted(prefixes))}"
|
||||
)
|
||||
continue
|
||||
prefix = next(iter(prefixes))
|
||||
mappings[capability_path] = prefix
|
||||
prefix_owners.setdefault(prefix, set()).add(capability_path)
|
||||
|
||||
for prefix, owners in prefix_owners.items():
|
||||
if len(owners) > 1:
|
||||
errors.append(
|
||||
f"префикс {prefix} используется несколькими capabilities: "
|
||||
f"{', '.join(sorted(owners))}"
|
||||
)
|
||||
return mappings, errors
|
||||
|
||||
|
||||
def load_active_change_prefixes(
|
||||
openspec_root: Path,
|
||||
exclude_path: Path,
|
||||
) -> dict[str, set[str]]:
|
||||
"""Read prefixes declared by other in-flight changes."""
|
||||
changes_root = openspec_root / "changes"
|
||||
excluded = exclude_path.resolve()
|
||||
prefixes_by_capability: dict[str, set[str]] = {}
|
||||
if not changes_root.is_dir():
|
||||
return prefixes_by_capability
|
||||
|
||||
for change_dir in changes_root.iterdir():
|
||||
if not change_dir.is_dir() or change_dir.name == "archive":
|
||||
continue
|
||||
for spec_path in change_dir.rglob("spec.md"):
|
||||
if spec_path.resolve() == excluded:
|
||||
continue
|
||||
capability_path = spec_capability_path(spec_path)
|
||||
if not capability_path:
|
||||
continue
|
||||
try:
|
||||
ids = REQUIREMENT_ID.findall(spec_path.read_text(encoding="utf-8"))
|
||||
except OSError:
|
||||
continue
|
||||
prefixes = {
|
||||
requirement_id.rsplit("-", 1)[0]
|
||||
for requirement_id in ids
|
||||
if "." in requirement_id
|
||||
}
|
||||
if prefixes:
|
||||
prefixes_by_capability.setdefault(capability_path, set()).update(prefixes)
|
||||
return prefixes_by_capability
|
||||
|
||||
|
||||
def check_capability_ids(
|
||||
path: Path,
|
||||
requirement_ids: list[str],
|
||||
known_prefixes: dict[str, str],
|
||||
base: Path | None = None,
|
||||
) -> list[str]:
|
||||
"""Check that a spec uses one stable, project-unique capability prefix."""
|
||||
prefixes = {
|
||||
requirement_id.rsplit("-", 1)[0]
|
||||
for requirement_id in requirement_ids
|
||||
if "." in requirement_id
|
||||
}
|
||||
if not prefixes:
|
||||
return []
|
||||
|
||||
capability_path = spec_capability_path(path)
|
||||
if not capability_path:
|
||||
return ["по пути файла не удалось определить capability для составного Requirement ID"]
|
||||
|
||||
errors: list[str] = []
|
||||
if len(prefixes) > 1:
|
||||
errors.append(
|
||||
f"capability {capability_path} использует несколько префиксов: "
|
||||
f"{', '.join(sorted(prefixes))}"
|
||||
)
|
||||
|
||||
base_capability_path = spec_capability_path(base) if base else None
|
||||
owners_by_prefix: dict[str, set[str]] = {}
|
||||
for known_path, known_prefix in known_prefixes.items():
|
||||
owners_by_prefix.setdefault(known_prefix, set()).add(known_path)
|
||||
|
||||
expected_prefix = known_prefixes.get(capability_path)
|
||||
if expected_prefix is None and base_capability_path:
|
||||
expected_prefix = known_prefixes.get(base_capability_path)
|
||||
active_change_prefixes: dict[str, set[str]] = {}
|
||||
if is_change_spec(path):
|
||||
active_change_prefixes = load_active_change_prefixes(
|
||||
openspec_root_for(path), path
|
||||
)
|
||||
|
||||
for prefix in prefixes:
|
||||
if expected_prefix and prefix != expected_prefix:
|
||||
errors.append(
|
||||
f"ID использует префикс {prefix}, но для capability {capability_path} "
|
||||
f"уже назначен {expected_prefix}"
|
||||
)
|
||||
owners = owners_by_prefix.get(prefix, set())
|
||||
if owners and capability_path not in owners and base_capability_path not in owners:
|
||||
errors.append(
|
||||
f"префикс {prefix} уже используется capability "
|
||||
f"{', '.join(sorted(owners))}"
|
||||
)
|
||||
for active_path, active_prefixes in active_change_prefixes.items():
|
||||
if active_path == capability_path and len(active_prefixes) > 1:
|
||||
errors.append(
|
||||
f"активные changes для capability {capability_path} используют "
|
||||
f"несколько префиксов: {', '.join(sorted(active_prefixes))}"
|
||||
)
|
||||
if active_path == capability_path and prefix not in active_prefixes:
|
||||
errors.append(
|
||||
f"change для capability {capability_path} использует другой префикс: "
|
||||
f"{', '.join(sorted(active_prefixes))}"
|
||||
)
|
||||
elif (
|
||||
prefix in active_prefixes
|
||||
and active_path != capability_path
|
||||
and active_path != base_capability_path
|
||||
):
|
||||
errors.append(
|
||||
f"префикс {prefix} уже используется активным change "
|
||||
f"для capability {active_path}"
|
||||
)
|
||||
return errors
|
||||
|
||||
|
||||
def spec_capability_path(path: Path) -> str | None:
|
||||
@@ -97,6 +233,13 @@ def spec_capability_path(path: Path) -> str | None:
|
||||
return "/".join(capability_parts) if capability_parts else None
|
||||
|
||||
|
||||
def is_change_spec(path: Path) -> bool:
|
||||
parts = path.parts
|
||||
changes_indexes = [index for index, part in enumerate(parts) if part == "changes"]
|
||||
specs_indexes = [index for index, part in enumerate(parts) if part == "specs"]
|
||||
return bool(changes_indexes and specs_indexes and specs_indexes[-1] > changes_indexes[-1])
|
||||
|
||||
|
||||
def heading_targets(text: str) -> tuple[set[str], dict[str, tuple[str, str]]]:
|
||||
"""Return generated heading fragments and fragments that target FR headings."""
|
||||
targets: set[str] = set()
|
||||
@@ -258,7 +401,7 @@ def check_requirement(
|
||||
requirement_id = ids[0]
|
||||
is_qualified = "." in requirement_id
|
||||
if require_qualified_ids and not is_qualified:
|
||||
errors.append("новый или изменённый Requirement должен иметь составной ID capability, например CFG.AS-01")
|
||||
errors.append("новый или изменённый Requirement должен иметь составной ID capability, например AREA.CAP-01")
|
||||
level_four = re.findall(r"^#### (.+)$", block, re.MULTILINE)
|
||||
has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT"
|
||||
expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"]
|
||||
@@ -423,7 +566,8 @@ def validate(
|
||||
path: Path,
|
||||
base: Path | None = None,
|
||||
require_qualified_ids: bool = False,
|
||||
capability_codes: dict[str, str] | None = None,
|
||||
capability_prefixes: dict[str, str] | None = None,
|
||||
capability_inventory_errors: list[str] | None = None,
|
||||
) -> list[str]:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
if HTML_ANCHOR.search(text):
|
||||
@@ -435,23 +579,17 @@ def validate(
|
||||
targets.update(base_targets)
|
||||
fr_targets.update(base_fr_targets)
|
||||
|
||||
errors = []
|
||||
if capability_codes is None:
|
||||
capability_codes, registry_errors = load_capability_codes()
|
||||
errors.extend(registry_errors)
|
||||
errors = list(capability_inventory_errors or [])
|
||||
if capability_prefixes is None:
|
||||
capability_prefixes, inventory_errors = load_capability_prefixes(
|
||||
openspec_root_for(path)
|
||||
)
|
||||
errors.extend(inventory_errors)
|
||||
blocks = list(requirement_blocks(text))
|
||||
ids = REQUIREMENT_ID.findall(text)
|
||||
if len(ids) != len(set(ids)):
|
||||
errors.append("повторяющиеся ID Requirements")
|
||||
capability_path = spec_capability_path(path)
|
||||
for requirement_id in ids:
|
||||
if "." not in requirement_id:
|
||||
continue
|
||||
prefix = capability_codes.get(capability_path or "")
|
||||
if not prefix:
|
||||
errors.append(f"для capability {capability_path or '<не определена>'} нет префикса в capability-codes.md")
|
||||
elif not re.fullmatch(rf"{re.escape(prefix)}-\d{{2,}}", requirement_id):
|
||||
errors.append(f"ID {requirement_id} не соответствует префиксу {prefix} для {capability_path}")
|
||||
errors.extend(check_capability_ids(path, ids, capability_prefixes, base))
|
||||
if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE):
|
||||
errors.append("нет Requirements")
|
||||
for name, block in blocks:
|
||||
@@ -472,14 +610,27 @@ def main() -> int:
|
||||
paths = sorted({file for path in args.paths for file in (path.rglob("spec.md") if path.is_dir() else [path])})
|
||||
if not paths:
|
||||
parser.error("не найдены spec.md")
|
||||
capability_codes, registry_errors = load_capability_codes()
|
||||
prefix_cache: dict[Path, tuple[dict[str, str], list[str]]] = {}
|
||||
reported_roots: set[Path] = set()
|
||||
failed = False
|
||||
for error in registry_errors:
|
||||
print(f"ERROR {CAPABILITY_CODES_PATH}: {error}")
|
||||
failed = True
|
||||
for path in paths:
|
||||
try:
|
||||
errors = validate(path, args.base, args.require_qualified_ids, capability_codes)
|
||||
openspec_root = openspec_root_for(path)
|
||||
if openspec_root not in prefix_cache:
|
||||
prefix_cache[openspec_root] = load_capability_prefixes(openspec_root)
|
||||
capability_prefixes, inventory_errors = prefix_cache[openspec_root]
|
||||
reported_inventory_errors = (
|
||||
inventory_errors if openspec_root not in reported_roots else []
|
||||
)
|
||||
errors = validate(
|
||||
path,
|
||||
args.base,
|
||||
args.require_qualified_ids,
|
||||
capability_prefixes,
|
||||
reported_inventory_errors,
|
||||
)
|
||||
if reported_inventory_errors:
|
||||
reported_roots.add(openspec_root)
|
||||
except OSError as error:
|
||||
errors = [str(error)]
|
||||
for error in errors:
|
||||
@@ -0,0 +1,338 @@
|
||||
# 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<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 зарегистрированы, конфигурация приложения загружена.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
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`.
|
||||
@@ -0,0 +1,103 @@
|
||||
# Capability: Файл технической конфигурации приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Предоставлять приложению загрузчик редко меняемых технических параметров из `config.yaml` с поддержкой перезагрузки без рестарта.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят начальная загрузка технических параметров из корневого config.yaml и атомарное применение валидных изменений без рестарта. Бизнес-настройки и удалённо меняемые runtime-значения относятся к configuration/application-settings.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Загрузка технической конфигурации из файла
|
||||
|
||||
**ID:** `CFG.ACF-01`
|
||||
|
||||
PLBA2 SHALL загружать техническую конфигурацию приложения из `config.yaml` в корне приложения и предоставлять её в типизированном виде до запуска компонентов, которые от неё зависят.
|
||||
|
||||
#### Scenario: Начальная загрузка технической конфигурации
|
||||
|
||||
##### Участники
|
||||
|
||||
- Приложение, загрузчик YAML-конфигурации и файл `config.yaml`.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- В корне приложения находится `config.yaml`; приложение объявило типизированную модель своей конфигурации.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Загрузчик читает `config.yaml` и проверяет его по модели приложения.
|
||||
2. Загрузчик предоставляет приложению типизированную конфигурацию до запуска зависимых компонентов и сообщает `APP_CONFIG_LOADED` по [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Файл отсутствует, содержит некорректный YAML или не соответствует модели — запуск приложения завершается с `APP_CONFIG_LOAD_FAILED` по [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки).
|
||||
|
||||
##### Результат
|
||||
|
||||
Зависимые компоненты получают техническую конфигурацию приложения из валидного файла.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `APP_CONFIG_LOADED` | Файл прочитан, проверен и предоставлен приложению | [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки) |
|
||||
| `APP_CONFIG_LOAD_FAILED` | Файл отсутствует или не соответствует формату либо модели приложения | [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### CFG.ACF-01.FR-01: Файл и модель технической конфигурации
|
||||
|
||||
Стандартный файл называется `config.yaml` и располагается в корне приложения. PLBA2 определяет общее необязательное строковое поле `application_id` и поля workers: `workers.<worker_name>.disabled` (boolean, по умолчанию `false`), `workers.<worker_name>.interval_seconds` и `workers.<worker_name>.pause_seconds`. При `disabled: true` worker не запускается; если поле не задано, worker запускается. Остальные поля YAML и типизированную модель приложения определяет само приложение. В файле находятся редко меняемые технические параметры приложения. Бизнес-параметры, feature toggles и технические значения, которые требуется менять удалённо во время работы приложения, хранятся через capability `configuration/application-settings` в таблице `settings` и не входят в `config.yaml`.
|
||||
|
||||
##### CFG.ACF-01.FR-02: Результат загрузки
|
||||
|
||||
Загрузчик разбирает YAML по типизированной модели приложения и предоставляет проверенную конфигурацию до запуска зависимых компонентов. При отсутствии файла, ошибке разбора или ошибке проверки модели возвращается `APP_CONFIG_LOAD_FAILED`, запуск приложения прекращается. Успешная загрузка завершается с `APP_CONFIG_LOADED`.
|
||||
|
||||
### Requirement: Перезагрузка технической конфигурации без рестарта
|
||||
|
||||
**ID:** `CFG.ACF-02`
|
||||
|
||||
PLBA2 SHALL подхватывать валидные изменения `config.yaml` во время работы приложения без перезапуска процесса.
|
||||
|
||||
#### Scenario: Изменение технической конфигурации во время работы
|
||||
|
||||
##### Участники
|
||||
|
||||
- Приложение, загрузчик YAML-конфигурации и файл `config.yaml`.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Приложение работает с успешно загруженной технической конфигурацией.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Загрузчик обнаруживает изменение `config.yaml` и проверяет новое содержимое по модели приложения.
|
||||
2. Валидная конфигурация заменяет текущую; последующие чтения получают новое значение без рестарта, операция завершается с `APP_CONFIG_RELOADED` по [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Новое содержимое невалидно — приложение продолжает использовать последнюю валидную конфигурацию, а загрузчик сообщает `APP_CONFIG_RELOAD_FAILED` по [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки).
|
||||
|
||||
##### Результат
|
||||
|
||||
После успешной перезагрузки новые чтения используют обновлённую конфигурацию; процесс приложения продолжает работу без рестарта.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `APP_CONFIG_RELOADED` | Новая валидная конфигурация активирована без рестарта | [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки) |
|
||||
| `APP_CONFIG_RELOAD_FAILED` | Изменённый файл не прошёл проверку; активна последняя валидная конфигурация | [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### CFG.ACF-02.FR-01: Замена активной конфигурации
|
||||
|
||||
Загрузчик обнаруживает изменения файла и проверяет их по модели приложения. После успешной проверки он атомарно заменяет текущую конфигурацию; все последующие чтения получают новую конфигурацию, а уже полученные снимки остаются неизменными. Перезапуск приложения не требуется.
|
||||
|
||||
##### CFG.ACF-02.FR-02: Результат перезагрузки
|
||||
|
||||
Успешная проверка и замена завершаются с `APP_CONFIG_RELOADED`. Если файл не читается, YAML не разбирается или новое содержимое не соответствует модели, загрузчик оставляет активной последнюю валидную конфигурацию, сообщает приложению ошибку и завершает попытку с `APP_CONFIG_RELOAD_FAILED`.
|
||||
@@ -0,0 +1,149 @@
|
||||
# Capability: Хранение и чтение настроек приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Давать приложениям общий контракт хранения бизнес-параметров и технических значений, которые должны меняться в runtime без рестарта.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят контракт таблицы settings, начальная загрузка миграцией приложения и типизированное чтение через PostgreSQL adapter. Таблицы и данные принадлежат приложению.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Контракт хранения настроек
|
||||
|
||||
**ID:** `CFG.AS-01`
|
||||
|
||||
PLBA2 SHALL определять назначение полей и структуру таблицы для бизнес-параметров и технических значений, которыми приложение управляет в runtime.
|
||||
|
||||
#### Scenario: Сокращенный use case: структура настроек
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Фиксируем поля таблицы `settings`, их назначение и ограничения по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings).
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings
|
||||
|
||||
Таблица `settings` создаётся в схеме приложения и содержит:
|
||||
|
||||
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- |
|
||||
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки |
|
||||
| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения |
|
||||
| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки |
|
||||
| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки |
|
||||
| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей |
|
||||
| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении |
|
||||
| `description` | `TEXT` | NULL | Пояснение к настройке |
|
||||
|
||||
Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. Приложение владеет DDL, данными и связями `config_key` со своими сущностями.
|
||||
|
||||
В `settings` хранятся бизнес-параметры, feature toggles и технические значения, которые нужно менять удалённо во время работы приложения. Feature toggle хранится в `setting_value`; `is_enabled` только включает или исключает строку из чтения. Редко меняемые технические параметры задаются отдельным файлом `config.yaml`.
|
||||
|
||||
### Requirement: Загрузка настроек
|
||||
|
||||
**ID:** `CFG.AS-02`
|
||||
|
||||
Приложение SHALL загружать начальные настройки в собственную базу данных миграцией при установке или первой раскатке.
|
||||
|
||||
#### Scenario: Загрузка начальных настроек
|
||||
|
||||
##### Участники
|
||||
|
||||
- Миграция приложения и база данных приложения.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- База данных приложения доступна для применения миграции.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Миграция создаёт нужное приложению хранилище по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings).
|
||||
2. Миграция записывает начальные значения непосредственно в базу приложения и завершается с `SETTINGS_LOADED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Миграция не может создать хранилище или записать значения — загрузка завершается с `SETTINGS_LOAD_FAILED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки).
|
||||
|
||||
##### Результат
|
||||
|
||||
Настройки приложения доступны в его базе до запуска использующего их кода.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `SETTINGS_LOADED` | Миграция записала настройки в базу приложения | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) |
|
||||
| `SETTINGS_LOAD_FAILED` | Миграция не создала хранилище или не записала настройки | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### CFG.AS-02.FR-01: Загрузка миграцией
|
||||
|
||||
Приложение создаёт таблицу `settings` и загружает начальные значения собственными миграциями при первой раскатке. Последующие значения бизнес-параметров и технических параметров, меняемых удалённо, могут обновляться в БД без рестарта приложения. PLBA2 не запускает миграции, не управляет изменением строк и не переносит YAML-конфигурацию в `settings`; конфигурация из `config.yaml` является отдельным слоем.
|
||||
|
||||
##### CFG.AS-02.FR-02: Результат загрузки
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `SETTINGS_LOADED` | Сообщение отсутствует | Приложение может запускать компоненты, которым нужны загруженные настройки |
|
||||
| `SETTINGS_LOAD_FAILED` | Исходная ошибка миграции доступна инструменту установки | Раскатка не считается успешной; приложение исправляет причину и повторно применяет миграцию по правилам своего инструмента |
|
||||
|
||||
### Requirement: Чтение настроек
|
||||
|
||||
**ID:** `CFG.AS-03`
|
||||
|
||||
PLBA2 SHALL предоставлять типизированный контракт чтения настроек и PostgreSQL-адаптер, читающий данные из схемы приложения.
|
||||
|
||||
#### Scenario: Чтение настроек приложения
|
||||
|
||||
##### Участники
|
||||
|
||||
- Бизнес-модуль, SettingsReader, PostgreSQL-адаптер и база данных приложения.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Приложение объявило типизированный ключ с decoder и передало адаптеру пул PostgreSQL и имя своей схемы.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Запрашиваем включённые записи по ключу и, если задана, области `config_key` в порядке контракта по [CFG.AS-03.FR-02](#cfgas-03fr-02-postgresql-адаптер).
|
||||
2. Декодируем значения и возвращаем их через SettingsReader с кодом `SETTING_READ` по [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Нет обязательного значения — возвращаем `SETTING_NOT_FOUND`; decoder отклонил значение — `SETTING_INVALID`; PostgreSQL недоступен — `SETTINGS_DATABASE_UNAVAILABLE`, согласно [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения).
|
||||
|
||||
##### Результат
|
||||
|
||||
Бизнес-код использует типизированный контракт независимо от конкретного адаптера хранения.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `SETTING_READ` | Значения прочитаны и декодированы в исходном порядке | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
|
||||
| `SETTING_NOT_FOUND` | Отсутствует обязательная настройка | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
|
||||
| `SETTING_INVALID` | Значение не прошло decoder приложения | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
|
||||
| `SETTINGS_DATABASE_UNAVAILABLE` | Запрос к базе приложения завершился ошибкой | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### CFG.AS-03.FR-01: Контракт SettingsReader
|
||||
|
||||
SettingsReader принимает типизированный ключ настройки и необязательный `config_key`, возвращает упорядоченный список значений типа ключа. Для ключа приложение задаёт decoder и обязательность или default. Каждый вызов использует актуальное значение источника настроек; удалённое изменение применяется при следующем чтении без рестарта приложения. Бизнес-код зависит от контракта, а не от SQL или драйвера БД.
|
||||
|
||||
##### CFG.AS-03.FR-02: PostgreSQL-адаптер
|
||||
|
||||
Адаптер читает `settings` схемы приложения через переданный приложением пул. Он фильтрует по `setting_key`, заданному `config_key` и `is_enabled = TRUE`, сохраняя порядок `sort_order`, затем `id`. Значения запроса параметризуются; имя схемы валидируется и безопасно экранируется. Адаптер не создаёт таблицу, не запускает миграции и не владеет настройками.
|
||||
|
||||
##### CFG.AS-03.FR-03: Результат чтения
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `SETTING_READ` | Сообщение отсутствует | Декодированные значения передаются приложению в порядке контракта |
|
||||
| `SETTING_NOT_FOUND` | Сообщение отсутствует | Для обязательного ключа возвращается типизированная ошибка; default применяется только по настройке ключа |
|
||||
| `SETTING_INVALID` | Сообщение отсутствует; исходная ошибка decoder доступна приложению | Значение не выдаётся как успешно прочитанное |
|
||||
| `SETTINGS_DATABASE_UNAVAILABLE` | Сообщение отсутствует; исходная ошибка драйвера передаётся приложению | PLBA2 не подменяет ошибку default-значением и не выполняет скрытый retry |
|
||||
@@ -0,0 +1,62 @@
|
||||
# Capability: Агрегация health-состояния приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Агрегировать текущий health приложения из runtime, workers и health contributors.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят агрегация lifecycle приложения, состояний workers и health contributors, расчёт общего статуса и формирование отчёта.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Агрегация health-состояния
|
||||
|
||||
**ID:** `HL.AG-01`
|
||||
|
||||
Health aggregator SHALL формировать единый отчёт по lifecycle приложения и текущему состоянию компонентов.
|
||||
|
||||
#### Scenario: Получение health-отчёта
|
||||
|
||||
##### Участники
|
||||
|
||||
- Приложение, runtime, workers и health contributors.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Каждый worker и contributor предоставляет состояние по health-контракту.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Собираем состояния runtime и компонентов — aggregator формирует отчёт по [HL.AG-01.FR-01](#hlag-01fr-01-состав-и-приоритет-статусов).
|
||||
2. Рассчитываем общий статус и завершаем с `HEALTH_REPORT_CREATED` по [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Входной статус не соответствует контракту — возвращаем `HEALTH_INPUT_INVALID` по [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации).
|
||||
|
||||
##### Результат
|
||||
|
||||
Приложение получает единый статус и детализацию состояния каждого запущенного worker.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `HEALTH_REPORT_CREATED` | Отчёт сформирован из валидных состояний | [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации) |
|
||||
| `HEALTH_INPUT_INVALID` | Состояние не соответствует health-контракту | [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### HL.AG-01.FR-01: Состав и приоритет статусов
|
||||
|
||||
Worker сообщает status, critical, detail и meta через health-контракт. Отчёт содержит application_id, lifecycle приложения и состояния каждого запущенного worker/contributor. Worker с `disabled: true` исключён из набора ожидаемых компонентов и не ухудшает health. Статусы упорядочены как `ok < degraded < unhealthy`; применяется худший итоговый статус. Для критичного компонента учитывается переданный status. Для некритичного компонента `unhealthy` ограничивается до `degraded`; отсутствие некритичного worker также даёт не ниже `degraded`. Отсутствующий критичный worker даёт `unhealthy`. Lifecycle `new` и `failed` даёт `unhealthy`, `starting` и `stopping` — не ниже `degraded`. Когда lifecycle приложения `stopped`, общий health status — `stopped` независимо от прежних статусов компонентов.
|
||||
|
||||
##### HL.AG-01.FR-02: Результат агрегации
|
||||
|
||||
Health-статус является данными. Валидные агрегированные `ok`, `degraded`, `unhealthy` и `stopped` возвращаются в отчёте; `stopped` обозначает lifecycle приложения, а статусы запущенных worker/contributor остаются `ok`, `degraded` или `unhealthy`. Ошибка появляется только при нарушении контракта входного состояния.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `HEALTH_REPORT_CREATED` | Сообщение отсутствует | Отчёт возвращается вызывающему коду для представления клиенту |
|
||||
| `HEALTH_INPUT_INVALID` | Сообщение отсутствует; ошибка контракта передаётся вызывающему коду | Отчёт не формируется; приложение исправляет contributor |
|
||||
@@ -0,0 +1,90 @@
|
||||
# Capability: Бизнес-история приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Сохранять ход бизнес-операций в trace_contexts и trace_messages схемы приложения.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят контракты trace_contexts и trace_messages и PostgreSQL adapter для записи в схему приложения. Таблицы и миграции принадлежат приложению; API просмотра истории не входит в capability.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Персистентная бизнес-история
|
||||
|
||||
**ID:** `OBS.BT-01`
|
||||
|
||||
PLBA2 SHALL предоставлять приложению контракт и PostgreSQL-адаптер для записи бизнес-контекстов и сообщений в БД приложения.
|
||||
|
||||
#### Scenario: Запись сообщения бизнес-операции
|
||||
|
||||
##### Участники
|
||||
|
||||
- Прикладной workflow, business trace adapter и схема БД приложения.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Приложение установило business trace context и передало адаптеру пул PostgreSQL и схему приложения.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Создаём контекст — адаптер сохраняет его в `trace_contexts` по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts).
|
||||
2. Записываем шаг операции — адаптер сохраняет сообщение в `trace_messages` по [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages) и завершает с `BUSINESS_TRACE_WRITTEN` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- PostgreSQL недоступен или запись не выполнена — исходная ошибка передаётся приложению с `BUSINESS_TRACE_WRITE_FAILED` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи).
|
||||
|
||||
##### Результат
|
||||
|
||||
Бизнес-события сохранены отдельно от технических JSON-логов.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `BUSINESS_TRACE_WRITTEN` | Контекст или сообщение сохранены | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) |
|
||||
| `BUSINESS_TRACE_WRITE_FAILED` | Запись в бизнес trace хранилище завершилась ошибкой | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### OBS.BT-01.FR-01 [DB]: Таблица хранения trace_contexts
|
||||
|
||||
Таблица `trace_contexts` создаётся в схеме приложения и содержит:
|
||||
|
||||
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- |
|
||||
| `trace_id` | `UUID` | NOT NULL, primary key | Публичный `business_trace_id` контекста |
|
||||
| `parent_id` | `UUID` | NULL | `trace_id` родительского контекста |
|
||||
| `alias` | `TEXT` | NOT NULL | Короткое имя контекста |
|
||||
| `trace_type` | `TEXT` | NOT NULL | Тип бизнес-операции |
|
||||
| `event_time` | `TIMESTAMPTZ` | NOT NULL | Время создания контекста |
|
||||
| `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты контекста, включая `application_id` по RT.AI-01.FR-01 |
|
||||
|
||||
Создаются индексы по `parent_id` и `event_time`. Таблица принадлежит приложению.
|
||||
|
||||
##### OBS.BT-01.FR-02 [DB]: Таблица хранения trace_messages
|
||||
|
||||
Таблица `trace_messages` создаётся в схеме приложения и содержит:
|
||||
|
||||
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- |
|
||||
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор сообщения |
|
||||
| `trace_id` | `UUID` | NOT NULL | `trace_id` контекста |
|
||||
| `event_time` | `TIMESTAMPTZ` | NOT NULL | Время сообщения |
|
||||
| `step` | `TEXT` | NOT NULL | Имя шага бизнес-операции |
|
||||
| `status` | `TEXT` | NOT NULL | Результат шага |
|
||||
| `level` | `TEXT` | NOT NULL | Уровень бизнес-сообщения |
|
||||
| `message` | `TEXT` | NOT NULL | Текст бизнес-сообщения |
|
||||
| `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты сообщения, включая `application_id` по [RT.AI-01.FR-01](../../runtime/application-identity/spec.md#rtai-01fr-01-разрешение-идентификатора) |
|
||||
|
||||
Поле `trace_id` ссылается на `trace_contexts.trace_id` с каскадным удалением. Создаются индексы по `trace_id`, `event_time` и `status`. Таблица принадлежит приложению.
|
||||
|
||||
##### OBS.BT-01.FR-03: Результат записи
|
||||
|
||||
Приложение передаёт адаптеру пул PostgreSQL и имя своей схемы. Адаптер записывает контексты и сообщения по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts) и [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages), добавляя `application_id` в `attrs_json` обоих типов записей. Приложение создаёт таблицы своей миграцией; PLBA2 не запускает миграции, не владеет данными, не публикует события в RabbitMQ и не реализует API истории.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `BUSINESS_TRACE_WRITTEN` | Сообщение отсутствует | Выполнение бизнес-сценария продолжается по решению приложения |
|
||||
| `BUSINESS_TRACE_WRITE_FAILED` | Сообщение отсутствует; исходная ошибка БД передаётся приложению | PLBA2 не выполняет скрытый retry; приложение выбирает политику ошибки |
|
||||
@@ -0,0 +1,44 @@
|
||||
# Capability: Техническое логирование
|
||||
|
||||
## Purpose
|
||||
|
||||
Формировать единые технические JSON-логи в stdout с application_id и business_trace_id.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят контракт JSON-записи технического лога и её вывод через stdlib StreamHandler в stdout. Хранение и доставка логов находятся за пределами capability.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Структурированные технические логи
|
||||
|
||||
**ID:** `OBS.TL-01`
|
||||
|
||||
PLBA2 SHALL задавать контракт технической JSON-записи и передавать её в stdout.
|
||||
|
||||
#### Scenario: Сокращенный use case: техническая запись
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Описываем поля отправляемой записи по [OBS.TL-01.FR-01](#obstl-01fr-01-api-контракт-сообщения-технической-записи).
|
||||
2. Фиксируем контекст и вывод записи в stdout по [OBS.TL-01.FR-02](#obstl-01fr-02-контекст-и-передача-в-stdout).
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### OBS.TL-01.FR-01 [API]: Контракт сообщения технической записи
|
||||
|
||||
Тип контракта: request
|
||||
|
||||
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `timestamp` | `string` | Обязательное | UTC timestamp; null запрещён | Время формирования записи |
|
||||
| `level` | `string` | Обязательное | Null запрещён | Уровень технической записи |
|
||||
| `logger` | `string` | Обязательное | Null запрещён | Имя logger |
|
||||
| `message` | `string` | Обязательное | Null запрещён | Текст записи |
|
||||
| `application_id` | `string` | Обязательное | Null запрещён | Идентификатор приложения |
|
||||
| `attributes` | `object` | Опциональное | Значения должны быть JSON-safe | Структурированные поля записи |
|
||||
| `business_trace_id` | `string` | Опциональное | Передаётся при установленном business trace context | Связь технической записи с бизнес-историей |
|
||||
|
||||
##### OBS.TL-01.FR-02: Контекст и передача в stdout
|
||||
|
||||
При установленном контексте formatter добавляет `business_trace_id`; контекст поддерживает async-задачи и использует то же значение, что business trace adapter. JSON кодируется стандартным сериализатором. Приложение направляет formatter в stdlib StreamHandler для stdout. PLBA2 не отправляет технические логи в БД, RabbitMQ, Loki или Grafana; доставку и просмотр обеспечивает платформа.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Capability: Идентификатор приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Определять `application_id` приложения и предоставлять разрешённое значение runtime-контексту.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входит однократное разрешение application_id из config.yaml, метаданных проекта или UUIDv4 и предоставление значения runtime до запуска зависимых компонентов.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Разрешение идентификатора приложения
|
||||
|
||||
**ID:** `RT.AI-01`
|
||||
|
||||
PLBA2 SHALL разрешать `application_id` до запуска зависящих от него компонентов и предоставлять значение runtime.
|
||||
|
||||
#### Scenario: Определение идентификатора приложения
|
||||
|
||||
##### Участники
|
||||
|
||||
- Файл `config.yaml`, метаданные проекта, загрузчик конфигурации и runtime приложения.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Файл `config.yaml` успешно загружен; поле `application_id` и метаданные проекта могут отсутствовать.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Разрешаем `application_id` по приоритету источников согласно [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора).
|
||||
2. Предоставляем значение runtime-контексту; операция завершается с `APPLICATION_ID_RESOLVED` по [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- `application_id` не задан, а `pyproject.toml` или `[project].name` отсутствует — генерируем UUIDv4; результат тот же.
|
||||
|
||||
##### Результат
|
||||
|
||||
Runtime-контекст содержит один `application_id`, неизменный в течение работы процесса.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `APPLICATION_ID_RESOLVED` | Идентификатор выбран и предоставлен runtime | [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### RT.AI-01.FR-01: Разрешение идентификатора
|
||||
|
||||
В корневом `config.yaml` приложение может задать необязательное строковое поле `application_id`. Непустое значение используется без изменений. Если значение отсутствует или пустое, PLBA2 использует имя проекта из `[project].name` в `pyproject.toml`. Если файл, секция или имя проекта недоступны, PLBA2 генерирует случайный UUIDv4. Идентификатор разрешается один раз до запуска зависящих компонентов, предоставляется runtime-контексту и остаётся неизменным в течение работы процесса; UUIDv4 при новом запуске генерируется заново. Успешное разрешение завершается с `APPLICATION_ID_RESOLVED`.
|
||||
@@ -0,0 +1,110 @@
|
||||
# Capability: Жизненный цикл приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Управлять lifecycle всего приложения через runtime-контракт, сохраняя entrypoint и HTTP host в приложении.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят запуск и остановка приложения, переходы lifecycle status и результаты graceful или принудительной остановки workers. Завершение OS-процесса и принадлежащего приложению HTTP host остаётся ответственностью приложения.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Запуск приложения
|
||||
|
||||
**ID:** `RT.AL-01`
|
||||
|
||||
Runtime SHALL запускать все зарегистрированные и не отключённые workers и предоставлять состояние запуска приложения.
|
||||
|
||||
#### Scenario: Запуск приложения
|
||||
|
||||
##### Участники
|
||||
|
||||
- Приложение, runtime PLBA2 и зарегистрированные workers.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Workers зарегистрированы с уникальными именами.
|
||||
- Приложение подключило runtime control API.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Запрашиваем запуск приложения — runtime запускает workers, не отключённых в конфигурации, по [RT.WK-01.FR-01](../worker/spec.md#rtwk-01fr-01-имя-состояния-и-управление-worker).
|
||||
2. После запуска workers возвращаем `APPLICATION_STARTED` по [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Запуск одного или нескольких workers завершился ошибкой — возвращаем `APPLICATION_START_FAILED`; состояние приложения становится `failed`.
|
||||
|
||||
##### Результат
|
||||
|
||||
Lifecycle приложения и результат запуска workers доступны приложению.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `APPLICATION_STARTED` | Все зарегистрированные и включённые workers запущены | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
|
||||
| `APPLICATION_START_FAILED` | Не удалось запустить один или несколько workers | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### RT.AL-01.FR-01: Запуск и состояния приложения
|
||||
|
||||
При запуске runtime переводит приложение в `starting`, запускает зарегистрированные workers, у которых `workers.<worker_name>.disabled` отсутствует или равно `false`, по их контракту и переводит приложение в `running` после их успешного старта. Ошибка запуска переводит lifecycle в `failed`. Состояния приложения: `new`, `starting`, `running`, `stopping`, `stopped` и `failed`.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `APPLICATION_STARTED` | Сообщение отсутствует | Приложение доступно для control operations |
|
||||
| `APPLICATION_START_FAILED` | Сообщение отсутствует; исходная ошибка доступна приложению | Lifecycle приложения остаётся `failed` |
|
||||
|
||||
### Requirement: Остановка приложения
|
||||
|
||||
**ID:** `RT.AL-02`
|
||||
|
||||
Runtime SHALL останавливать все workers приложения в graceful или принудительном режиме и предоставлять актуальный lifecycle status.
|
||||
|
||||
#### Scenario: Остановка приложения
|
||||
|
||||
##### Участники
|
||||
|
||||
- Клиент control API, runtime PLBA2, supervisor и зарегистрированные workers.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Приложение запущено и его workers зарегистрированы.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Запрашиваем остановку приложения с выбранным режимом — runtime останавливает workers по [RT.AL-02.FR-01](#rtal-02fr-01-режимы-остановки-приложения).
|
||||
2. Дожидаемся завершения workers и возвращаем `APPLICATION_STOPPED` по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Истёк заданный timeout ожидания — возвращаем status `stopping` и `APPLICATION_STOPPING`; runtime продолжает остановку по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
|
||||
|
||||
##### Результат
|
||||
|
||||
Lifecycle становится `stopped` только после остановки всех workers.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `APPLICATION_STOPPED` | Все workers приложения остановлены | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
|
||||
| `APPLICATION_STOPPING` | Остановка продолжается после завершения ожидания API | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### RT.AL-02.FR-01: Режимы остановки приложения
|
||||
|
||||
По умолчанию runtime запрашивает graceful stop у всех workers: каждый worker завершает активный цикл и не начинает следующий. При `force=true` runtime принудительно прерывает активную обработку workers. После любого режима новые циклы не запускаются.
|
||||
|
||||
##### RT.AL-02.FR-02: Ожидание и статус остановки
|
||||
|
||||
Положительный необязательный `timeout_seconds` ограничивает только ожидание ответа на запрос остановки. Если timeout отсутствует, runtime ждёт завершения всех workers без ограничения по времени. По истечении timeout runtime возвращает status `stopping`, продолжая остановку в фоне; timeout не включает принудительный режим. Lifecycle становится `stopped`, когда supervisor подтвердил остановку всех workers по [RT.WK-02.FR-02](../worker/spec.md#rtwk-02fr-02-результат-остановки-группы). Health aggregator возвращает `stopped` по [HL.AG-01.FR-01](../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов). Runtime не завершает принадлежащий приложению OS process или HTTP host; их остановка остаётся решением приложения.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `APPLICATION_STOPPED` | Сообщение отсутствует | Runtime фиксирует lifecycle `stopped` |
|
||||
| `APPLICATION_STOPPING` | Сообщение отсутствует; lifecycle доступен в status | Runtime продолжает остановку workers |
|
||||
@@ -0,0 +1,211 @@
|
||||
# Capability: Workers приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Запускать именованные workers независимо друг от друга, выполнять их процессы по расписанию и формировать их health-состояния.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят регистрация workers, независимые lifecycle и health, последовательное выполнение циклов по расписанию и контролируемая остановка.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Независимые workers
|
||||
|
||||
**ID:** `RT.WK-01`
|
||||
|
||||
Runtime SHALL выполнять каждый зарегистрированный worker независимо от остальных по его стабильному уникальному имени.
|
||||
|
||||
#### Scenario: Работа worker в составе приложения
|
||||
|
||||
##### Участники
|
||||
|
||||
- Приложение, runtime PLBA2, supervisor и зарегистрированный worker.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Composition root зарегистрировал workers с уникальными именами.
|
||||
- Приложение запускает workers через lifecycle приложения.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. При запуске приложения supervisor запускает worker, если `workers.<worker_name>.disabled` отсутствует или равно `false`, с результатом `WORKER_STARTED` по [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker).
|
||||
2. Runtime хранит lifecycle и health каждого запущенного worker отдельно по [RT.WK-01.FR-02](#rtwk-01fr-02-независимость-работы-и-состояния).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Для worker задано `disabled: true` — supervisor пропускает его запуск.
|
||||
- Worker не удалось запустить — runtime сообщает `WORKER_START_FAILED` по [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker), остальные workers сохраняют собственное состояние.
|
||||
|
||||
##### Результат
|
||||
|
||||
Каждый включённый worker выполняется независимо и имеет отдельные имя, lifecycle и health-состояние.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `WORKER_STARTED` | Включённый worker запущен при запуске приложения | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
|
||||
| `WORKER_START_FAILED` | Worker не удалось запустить | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### RT.WK-01.FR-01: Имя, состояния и управление worker
|
||||
|
||||
Каждый worker регистрируется с уникальным стабильным именем. Runtime управляет его внутренним lifecycle через supervisor: запускает worker при запуске приложения, если `workers.<worker_name>.disabled` отсутствует или равно `false`, и останавливает его при остановке приложения. При `disabled: true` worker не запускается. Значение `disabled` применяется при запуске приложения; изменение этого значения во время работы не запускает и не останавливает worker до следующего запуска приложения. Отдельные операции API для запуска или остановки worker не предоставляются. Lifecycle и health запущенных workers доступны в общем health-отчёте. Неудачный внутренний запуск worker фиксируется с `WORKER_START_FAILED`; успешный — с `WORKER_STARTED`.
|
||||
|
||||
##### RT.WK-01.FR-02: Независимость работы и состояния
|
||||
|
||||
Runtime хранит lifecycle и health каждого worker отдельно. Исключение в процессе или состояние одного worker не меняет lifecycle и состояние остальных workers; операции управления приложением применяются ко всем включённым workers. Контракт health определён в [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
|
||||
|
||||
### Requirement: Контролируемая остановка workers
|
||||
|
||||
**ID:** `RT.WK-02`
|
||||
|
||||
Supervisor SHALL запрашивать остановку всех запущенных workers приложения и сообщать, когда каждый из них завершил текущую работу.
|
||||
|
||||
#### Scenario: Остановка группы workers
|
||||
|
||||
##### Участники
|
||||
|
||||
- Runtime PLBA2, supervisor и зарегистрированные workers.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Workers запущены и доступны supervisor.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Передаём всем запущенным workers приложения режим остановки по [RT.WK-02.FR-01](#rtwk-02fr-01-режимы-остановки-worker).
|
||||
2. Сообщаем о результате группы по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы); после завершения возвращаем `WORKERS_STOPPED`.
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Часть workers ещё выполняет работу — сообщаем `WORKERS_STOPPING` и их имена по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы).
|
||||
|
||||
##### Результат
|
||||
|
||||
Для каждого запущенного worker известно, завершена ли его работа.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `WORKERS_STOPPED` | Все запущенные workers приложения остановлены | [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы) |
|
||||
| `WORKERS_STOPPING` | Не все запущенные workers приложения завершили работу | [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### RT.WK-02.FR-01: Режимы остановки worker
|
||||
|
||||
При graceful stop worker завершает текущий цикл и не начинает следующий. При принудительной остановке runtime прерывает активную обработку worker. Supervisor отправляет запрос остановки всем запущенным workers приложения; остановка одного не задерживает отправку запросов остальным.
|
||||
|
||||
##### RT.WK-02.FR-02: Результат остановки группы
|
||||
|
||||
Supervisor возвращает `WORKERS_STOPPED` только после остановки всех запущенных workers приложения. Пока хотя бы один worker работает, результат — `WORKERS_STOPPING` со списком таких workers. Ожидание и таймаут ответа API определяет capability `runtime/application-lifecycle`.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `WORKERS_STOPPED` | Сообщение отсутствует | Supervisor подтверждает завершение группы |
|
||||
| `WORKERS_STOPPING` | Результат содержит имена ещё работающих workers | Supervisor продолжает остановку |
|
||||
|
||||
### Requirement: Периодическое выполнение worker
|
||||
|
||||
**ID:** `RT.WK-03`
|
||||
|
||||
Runtime SHALL выполнять прикладной процесс worker циклами по расписанию, заданному для этого worker в `config.yaml`.
|
||||
|
||||
#### Scenario: Циклическое выполнение процесса
|
||||
|
||||
##### Участники
|
||||
|
||||
- Runtime PLBA2, зарегистрированный worker и конфигурация приложения.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Приложение зарегистрировало worker с уникальным именем и предоставило его прикладной процесс.
|
||||
- Для каждого включённого worker задан ровно один допустимый режим расписания.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Запускаем процесс worker без начальной задержки — runtime принимает расписание с `WORKER_SCHEDULE_STARTED` по [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) и начинает цикл по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
|
||||
2. После завершения цикла планируем следующий запуск по текущей конфигурации и продолжаем последовательное исполнение по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Настройки расписания отсутствуют, заданы вместе или имеют недопустимое значение — worker не запускается с `WORKER_CONFIG_INVALID` по [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания).
|
||||
|
||||
##### Результат
|
||||
|
||||
Worker выполняет прикладной процесс последовательно и повторяет его согласно выбранному режиму расписания.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `WORKER_SCHEDULE_STARTED` | Расписание принято, worker начал циклическое исполнение | [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) |
|
||||
| `WORKER_CONFIG_INVALID` | Расписание отсутствует или некорректно | [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### RT.WK-03.FR-01: Режимы и настройки расписания
|
||||
|
||||
Настройки каждого worker находятся в корневом `config.yaml` по пути `workers.<worker_name>`. Для включённого worker нужно задать ровно одну положительную длительность в секундах: `interval_seconds` или `pause_seconds`. Worker с `disabled: true` не запускается и не требует настроек расписания. Первый цикл начинается сразу после старта worker; циклы одного worker не выполняются параллельно. При `interval_seconds` задан период между началами циклов: после обработки runtime ждёт остаток периода, а если обработка заняла дольше интервала — запускает следующий цикл сразу. При `pause_seconds` runtime ждёт указанную паузу после завершения каждого цикла. При планировании следующего цикла используются активные настройки; валидные изменения файла применяются без рестарта по capability `configuration/application-config-file`.
|
||||
|
||||
##### RT.WK-03.FR-02: Валидация расписания
|
||||
|
||||
Для включённого worker runtime принимает расписание только если задан ровно один ключ — `interval_seconds` или `pause_seconds` — со значением больше нуля. Если оба ключа отсутствуют, заданы вместе или значение некорректно, запуск приложения завершается ошибкой `WORKER_CONFIG_INVALID`; детали доступны приложению. Для worker с `disabled: true` проверка расписания не выполняется. Валидное расписание завершается с `WORKER_SCHEDULE_STARTED`.
|
||||
|
||||
### Requirement: Health worker
|
||||
|
||||
**ID:** `RT.WK-04`
|
||||
|
||||
Runtime SHALL формировать health-состояние каждого worker, продолжая циклическую работу после исключения в прикладном процессе.
|
||||
|
||||
#### Scenario: Обновление health worker
|
||||
|
||||
##### Участники
|
||||
|
||||
- Runtime PLBA2, worker, прикладная health-логика и health aggregator.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Worker запущен и зарегистрирован в health aggregator.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Определяем состояние worker по результату цикла и прикладным условиям по [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
|
||||
2. Передаём status и critical aggregator по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления); обновление завершается с `WORKER_HEALTH_UPDATED`.
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Процесс цикла выбрасывает исключение — фиксируем `unhealthy`, возвращаем `WORKER_PROCESS_FAILED`, сохраняем worker запущенным и планируем следующий цикл по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления).
|
||||
|
||||
##### Результат
|
||||
|
||||
Health-состояние worker доступно aggregator; исключение одного цикла не прекращает последующие циклы.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `WORKER_HEALTH_UPDATED` | Новое health-состояние worker передано aggregator | [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health), [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления) |
|
||||
| `WORKER_PROCESS_FAILED` | Цикл завершился исключением, worker продолжит работу по расписанию | [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### RT.WK-04.FR-01: Контракт и прикладные условия health
|
||||
|
||||
Health worker содержит `status` (`ok`, `degraded` или `unhealthy`), `critical`, `detail` и `meta` по контракту capability `health/aggregation`. Приложение задаёт `critical` при регистрации worker и может предоставить прикладную health-логику, возвращающую один из этих статусов по условиям своей задачи.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `WORKER_HEALTH_UPDATED` | Сообщение отсутствует | Новое состояние worker передаётся health aggregator |
|
||||
|
||||
##### RT.WK-04.FR-02: Правила статуса и восстановления
|
||||
|
||||
Исключение прикладного процесса переводит автоматическое состояние worker в `unhealthy`, но runtime перехватывает исключение и планирует следующий цикл. В режиме `interval_seconds` превышение длительностью цикла заданного интервала переводит автоматическое состояние в `degraded`; в режиме `pause_seconds` этот статус не возникает из-за расписания. Успешный следующий цикл сбрасывает автоматическое состояние в `ok`. Итоговый status — худший по порядку `ok < degraded < unhealthy` из автоматического состояния и результата прикладной health-логики; прикладная логика не маскирует ошибку цикла.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `WORKER_PROCESS_FAILED` | Сообщение отсутствует; исходное исключение доступно приложению | Worker сохраняет работу и запускает следующий цикл по расписанию |
|
||||
@@ -0,0 +1,63 @@
|
||||
# Capability: Оркестрация workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
Выполнять workflow из шагов приложения по явным переходам и сохранять состояние выполнения.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят именованные шаги приложения, явные допустимые переходы и сохранение состояния запуска через переданный persistence-контракт. Бизнес-правила и подключение к БД задаёт приложение.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Workflow engine
|
||||
|
||||
**ID:** `WF.OR-01`
|
||||
|
||||
Workflow engine SHALL выполнять определение из именованных шагов, применять их переходы и сохранять ход запуска через persistence-контракт.
|
||||
|
||||
#### Scenario: Выполнение workflow
|
||||
|
||||
##### Участники
|
||||
|
||||
- Приложение, workflow engine, шаги приложения и persistence adapter.
|
||||
|
||||
##### Предусловия
|
||||
|
||||
- Приложение передало определение workflow, начальный шаг, контекст и адаптер сохранения.
|
||||
|
||||
##### Основной поток
|
||||
|
||||
1. Запускаем workflow — engine сохраняет начало запуска и вызывает объект текущего шага по [WF.OR-01.FR-01](#wfor-01fr-01-определение-и-выполнение).
|
||||
2. Применяем результат шага — engine выбирает только объявленный переход и сохраняет checkpoint по [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки).
|
||||
3. Достигаем конечного шага и завершаем с `WORKFLOW_COMPLETED`.
|
||||
|
||||
##### Альтернативы и ошибки
|
||||
|
||||
- Шаг выбрасывает исключение — engine сохраняет ошибку запуска, прекращает дальнейшие шаги и передаёт исходное исключение с `WORKFLOW_STEP_FAILED` по [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки).
|
||||
|
||||
##### Результат
|
||||
|
||||
Приложение получает результат запуска и актуальный контекст workflow.
|
||||
|
||||
##### Коды завершения
|
||||
|
||||
| Код | Смысл | Связанные FR |
|
||||
| --- | --- | --- |
|
||||
| `WORKFLOW_COMPLETED` | Workflow достиг конечного шага | [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки) |
|
||||
| `WORKFLOW_STEP_FAILED` | Шаг завершился исключением | [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки) |
|
||||
|
||||
#### Функциональные требования
|
||||
|
||||
##### WF.OR-01.FR-01: Определение и выполнение
|
||||
|
||||
Приложение задаёт WorkflowDefinition с именем, начальным шагом и именованными узлами. Узел содержит WorkflowStep и карту переходов; шаг получает WorkflowContext и возвращает StepResult с переходом, обновлениями состояния и статусом. Engine исполняет только объявленные переходы и не содержит бизнес-правил приложения.
|
||||
|
||||
##### WF.OR-01.FR-02: Сохранение и ошибки
|
||||
|
||||
Engine сохраняет начало и итог workflow, старт и завершение каждого шага, snapshot контекста и ошибки через переданный WorkflowPersistence. Ошибка шага сохраняется и передаётся вызывающему коду; скрытые повторы и выполнение следующих шагов не допускаются. Подключение к БД для сохранения задаёт приложение.
|
||||
|
||||
| Код | Текст сообщения | Дальнейшее поведение |
|
||||
| --- | --- | --- |
|
||||
| `WORKFLOW_COMPLETED` | Сообщение отсутствует | Engine возвращает итоговый context и run id |
|
||||
| `WORKFLOW_STEP_FAILED` | Сообщение отсутствует; исходное исключение передаётся вызывающему коду | Engine сохраняет ошибку, прекращает workflow и не повторяет шаг |
|
||||
+1
-1
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "plba-v2"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
description = "Portable application lifecycle and observability components"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.11"
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Check that a change advances the PLBA package version by one SemVer step."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import tomllib
|
||||
from pathlib import Path
|
||||
|
||||
VERSION_PATTERN = re.compile(r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$")
|
||||
PROJECT_ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
def parse_version(raw_version: object, source: str) -> tuple[int, int, int]:
|
||||
if not isinstance(raw_version, str):
|
||||
raise ValueError(f"В {source} поле project.version должно быть строкой")
|
||||
match = VERSION_PATTERN.fullmatch(raw_version)
|
||||
if match is None:
|
||||
raise ValueError(
|
||||
f"Версия {raw_version!r} в {source} должна иметь формат MAJOR.MINOR.PATCH"
|
||||
)
|
||||
return tuple(int(part) for part in match.groups())
|
||||
|
||||
|
||||
def read_version(toml_text: str, source: str) -> tuple[int, int, int]:
|
||||
project = tomllib.loads(toml_text).get("project", {})
|
||||
if not isinstance(project, dict):
|
||||
raise ValueError(f"В {source} отсутствует секция [project]")
|
||||
return parse_version(project.get("version"), source)
|
||||
|
||||
|
||||
def read_base_version(base_ref: str) -> tuple[int, int, int]:
|
||||
result = subprocess.run(
|
||||
["git", "show", f"{base_ref}:pyproject.toml"],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
cwd=PROJECT_ROOT,
|
||||
)
|
||||
return read_version(result.stdout, f"{base_ref}:pyproject.toml")
|
||||
|
||||
|
||||
def allowed_next_versions(base: tuple[int, int, int]) -> set[tuple[int, int, int]]:
|
||||
major, minor, patch = base
|
||||
patch_bump = (major, minor, patch + 1)
|
||||
minor_bump = (major, minor + 1, 0)
|
||||
if major == 0:
|
||||
return {patch_bump, minor_bump, (1, 0, 0)}
|
||||
return {patch_bump, minor_bump, (major + 1, 0, 0)}
|
||||
|
||||
|
||||
def format_version(version: tuple[int, int, int]) -> str:
|
||||
return ".".join(str(part) for part in version)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument(
|
||||
"--base-ref",
|
||||
required=True,
|
||||
help="Git ref целевой ветки pull request, например origin/main",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
try:
|
||||
base = read_base_version(args.base_ref)
|
||||
current_text = (PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8")
|
||||
current = read_version(current_text, "pyproject.toml")
|
||||
except (OSError, ValueError, tomllib.TOMLDecodeError, subprocess.CalledProcessError) as error:
|
||||
print(f"Ошибка проверки версии: {error}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
if current not in allowed_next_versions(base):
|
||||
allowed = ", ".join(
|
||||
format_version(version) for version in sorted(allowed_next_versions(base))
|
||||
)
|
||||
print(
|
||||
f"Версия {format_version(current)} должна быть ровно одним шагом выше "
|
||||
f"{format_version(base)}. Допустимые версии: {allowed}.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
|
||||
print(f"Версия пакета увеличена: {format_version(base)} -> {format_version(current)}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -1,3 +1,4 @@
|
||||
from plba.http.control_api import ControlApi
|
||||
from plba.http.routes import HttpRoute
|
||||
|
||||
__all__ = ["ControlApi"]
|
||||
__all__ = ["ControlApi", "HttpRoute"]
|
||||
|
||||
+103
-28
@@ -1,32 +1,98 @@
|
||||
from collections.abc import Awaitable, Callable, Sequence
|
||||
from typing import Any
|
||||
|
||||
from plba.health.aggregator import HealthAggregator, HealthInputInvalid
|
||||
from plba.http.asgi import ASGIHttpTransport
|
||||
from plba.http.errors import ControlRequestError
|
||||
from plba.http.requests import StopRequest
|
||||
from plba.http.routes import (
|
||||
ASGIScope,
|
||||
ASGIReceive,
|
||||
ASGISend,
|
||||
HttpRoute,
|
||||
HttpRouter,
|
||||
MethodNotAllowed,
|
||||
RouteNotFound,
|
||||
)
|
||||
from plba.http.serialization import health_report_payload
|
||||
from plba.runtime.application import ApplicationRuntime, RuntimeLifecycleError
|
||||
|
||||
_ControlAction = Callable[
|
||||
[ASGIScope, ASGIReceive], Awaitable[tuple[int, dict[str, Any]]]
|
||||
]
|
||||
|
||||
|
||||
class ControlApi:
|
||||
"""ASGI route adapter; it owns no server, socket, or listener."""
|
||||
|
||||
def __init__(
|
||||
self, runtime: ApplicationRuntime, health_aggregator: HealthAggregator
|
||||
self,
|
||||
runtime: ApplicationRuntime,
|
||||
health_aggregator: HealthAggregator,
|
||||
application_routes: Sequence[HttpRoute] = (),
|
||||
) -> None:
|
||||
self._runtime = runtime
|
||||
self._health_aggregator = health_aggregator
|
||||
self._transport = ASGIHttpTransport()
|
||||
routes = (
|
||||
HttpRoute("GET", "/api/v1/health", self._handle_health),
|
||||
HttpRoute("POST", "/api/v1/runtime/start", self._handle_start),
|
||||
HttpRoute("POST", "/api/v1/runtime/stop", self._handle_stop),
|
||||
HttpRoute("GET", "/api/v1/runtime/status", self._handle_status),
|
||||
*application_routes,
|
||||
)
|
||||
self._router = HttpRouter(routes)
|
||||
|
||||
async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
|
||||
async def __call__(self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend) -> None:
|
||||
scope_type = scope.get("type")
|
||||
if scope_type == "lifespan":
|
||||
await self._transport.handle_lifespan(receive, send)
|
||||
return
|
||||
if scope_type != "http":
|
||||
return
|
||||
|
||||
try:
|
||||
status, payload = await self._dispatch(scope, receive)
|
||||
match = self._router.resolve(scope.get("method", ""), scope.get("path", ""))
|
||||
except RouteNotFound:
|
||||
await self._send_routing_error(send, 404, "HTTP_ROUTE_NOT_FOUND")
|
||||
return
|
||||
except MethodNotAllowed:
|
||||
await self._send_routing_error(send, 405, "HTTP_METHOD_NOT_ALLOWED")
|
||||
return
|
||||
|
||||
route_scope = dict(scope)
|
||||
route_scope["path_params"] = match.path_params
|
||||
await match.route.handler(route_scope, receive, send)
|
||||
|
||||
async def _handle_health(
|
||||
self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend
|
||||
) -> None:
|
||||
await self._execute_control_action(self._health_action, scope, receive, send)
|
||||
|
||||
async def _handle_start(
|
||||
self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend
|
||||
) -> None:
|
||||
await self._execute_control_action(self._start_action, scope, receive, send)
|
||||
|
||||
async def _handle_stop(
|
||||
self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend
|
||||
) -> None:
|
||||
await self._execute_control_action(self._stop_action, scope, receive, send)
|
||||
|
||||
async def _handle_status(
|
||||
self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend
|
||||
) -> None:
|
||||
await self._execute_control_action(self._status_action, scope, receive, send)
|
||||
|
||||
async def _execute_control_action(
|
||||
self,
|
||||
action: _ControlAction,
|
||||
scope: ASGIScope,
|
||||
receive: ASGIReceive,
|
||||
send: ASGISend,
|
||||
) -> None:
|
||||
try:
|
||||
status, payload = await action(scope, receive)
|
||||
except HealthInputInvalid as error:
|
||||
status, payload = 500, self._error("HEALTH_INPUT_INVALID", error)
|
||||
except RuntimeLifecycleError as error:
|
||||
@@ -37,45 +103,54 @@ class ControlApi:
|
||||
status, payload = 500, self._error("CONTROL_API_FAILED", error)
|
||||
await self._transport.send_json(send, status, payload)
|
||||
|
||||
async def _dispatch(self, scope: dict[str, Any], receive: Any) -> tuple[int, dict[str, Any]]:
|
||||
method = scope.get("method", "").upper()
|
||||
path = scope.get("path", "")
|
||||
query = scope.get("query_string", b"")
|
||||
if path in {"/health", "/runtime/status", "/runtime/start", "/runtime/stop"} and query:
|
||||
raise ControlRequestError("query parameters are not accepted")
|
||||
if path == "/health":
|
||||
if method != "GET":
|
||||
return 405, self._error("METHOD_NOT_ALLOWED", "GET required")
|
||||
async def _health_action(
|
||||
self, scope: ASGIScope, receive: ASGIReceive
|
||||
) -> tuple[int, dict[str, Any]]:
|
||||
self._require_no_query(scope)
|
||||
await self._require_empty_body(receive)
|
||||
report = await self._health_aggregator.aggregate()
|
||||
return 200, health_report_payload(report)
|
||||
if path == "/runtime/start":
|
||||
if method != "POST":
|
||||
return 405, self._error("METHOD_NOT_ALLOWED", "POST required")
|
||||
|
||||
async def _start_action(
|
||||
self, scope: ASGIScope, receive: ASGIReceive
|
||||
) -> tuple[int, dict[str, Any]]:
|
||||
self._require_no_query(scope)
|
||||
await self._require_empty_body(receive)
|
||||
result = await self._runtime.start()
|
||||
return 200, {"status": result.lifecycle.value}
|
||||
if path == "/runtime/status":
|
||||
if method != "GET":
|
||||
return 405, self._error("METHOD_NOT_ALLOWED", "GET required")
|
||||
await self._require_empty_body(receive)
|
||||
return 200, {"status": self._runtime.lifecycle.value}
|
||||
if path == "/runtime/stop":
|
||||
if method != "POST":
|
||||
return 405, self._error("METHOD_NOT_ALLOWED", "POST required")
|
||||
|
||||
async def _stop_action(
|
||||
self, scope: ASGIScope, receive: ASGIReceive
|
||||
) -> tuple[int, dict[str, Any]]:
|
||||
self._require_no_query(scope)
|
||||
request = StopRequest.parse(await self._transport.read_body(receive))
|
||||
result = await self._runtime.stop(
|
||||
force=request.force, timeout_seconds=request.timeout_seconds
|
||||
)
|
||||
status_code = 200 if result.lifecycle.value == "stopped" else 202
|
||||
return status_code, {"status": result.lifecycle.value}
|
||||
return 404, self._error("NOT_FOUND", "control route not found")
|
||||
status = 200 if result.lifecycle.value == "stopped" else 202
|
||||
return status, {"status": result.lifecycle.value}
|
||||
|
||||
async def _require_empty_body(self, receive: Any) -> None:
|
||||
async def _status_action(
|
||||
self, scope: ASGIScope, receive: ASGIReceive
|
||||
) -> tuple[int, dict[str, Any]]:
|
||||
self._require_no_query(scope)
|
||||
await self._require_empty_body(receive)
|
||||
return 200, {"status": self._runtime.lifecycle.value}
|
||||
|
||||
async def _require_empty_body(self, receive: ASGIReceive) -> None:
|
||||
if await self._transport.read_body(receive):
|
||||
raise ControlRequestError("request body is not accepted")
|
||||
|
||||
@staticmethod
|
||||
def _require_no_query(scope: ASGIScope) -> None:
|
||||
if scope.get("query_string", b""):
|
||||
raise ControlRequestError("query parameters are not accepted")
|
||||
|
||||
async def _send_routing_error(
|
||||
self, send: ASGISend, status: int, code: str
|
||||
) -> None:
|
||||
await self._transport.send_json(send, status, self._error(code, code))
|
||||
|
||||
@staticmethod
|
||||
def _error(code: str, error: Exception | str) -> dict[str, str]:
|
||||
return {"error": code, "message": str(error)}
|
||||
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
"""Typed route definitions and deterministic ASGI path matching."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Sequence
|
||||
from dataclasses import dataclass
|
||||
from typing import Any, Awaitable, Callable
|
||||
|
||||
ASGIScope = dict[str, Any]
|
||||
ASGIMessage = dict[str, Any]
|
||||
ASGIReceive = Callable[[], Awaitable[ASGIMessage]]
|
||||
ASGISend = Callable[[ASGIMessage], Awaitable[None]]
|
||||
ASGIHandler = Callable[[ASGIScope, ASGIReceive, ASGISend], Awaitable[None]]
|
||||
|
||||
_HTTP_METHOD = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Z]+$")
|
||||
_API_VERSION = re.compile(r"^v[1-9][0-9]*$")
|
||||
_PARAMETER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class HttpRoute:
|
||||
"""Application-owned ASGI handler mounted at a versioned path template."""
|
||||
|
||||
method: str
|
||||
path: str
|
||||
handler: ASGIHandler
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if not isinstance(self.method, str) or not _HTTP_METHOD.fullmatch(self.method):
|
||||
raise ValueError("HTTP method must be a non-empty uppercase token")
|
||||
if not callable(self.handler):
|
||||
raise ValueError("HTTP route handler must be callable")
|
||||
_parse_path(self.path)
|
||||
|
||||
@property
|
||||
def segments(self) -> tuple[str, ...]:
|
||||
return tuple(self.path.split("/")[1:])
|
||||
|
||||
@property
|
||||
def static_segment_count(self) -> int:
|
||||
return sum(not _is_parameter(segment) for segment in self.segments)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class RouteMatch:
|
||||
route: HttpRoute
|
||||
path_params: dict[str, str]
|
||||
|
||||
|
||||
class RouteNotFound(LookupError):
|
||||
"""Raised when no registered path template matches a request path."""
|
||||
|
||||
|
||||
class MethodNotAllowed(LookupError):
|
||||
"""Raised when a path matches, but its registered methods do not."""
|
||||
|
||||
def __init__(self, allowed_methods: tuple[str, ...]) -> None:
|
||||
super().__init__("HTTP method is not allowed for this path")
|
||||
self.allowed_methods = allowed_methods
|
||||
|
||||
|
||||
class HttpRouter:
|
||||
"""Immutable route table with static-segment precedence."""
|
||||
|
||||
def __init__(self, routes: Sequence[HttpRoute]) -> None:
|
||||
self._routes = tuple(routes)
|
||||
self._validate_conflicts()
|
||||
|
||||
def resolve(self, method: str, path: str) -> RouteMatch:
|
||||
request_segments = tuple(path.split("/")[1:]) if path.startswith("/") else ()
|
||||
path_matches = [
|
||||
(route, params)
|
||||
for route in self._routes
|
||||
if (params := _match_path(route, request_segments)) is not None
|
||||
]
|
||||
if not path_matches:
|
||||
raise RouteNotFound(path)
|
||||
|
||||
method_matches = [
|
||||
(route, params)
|
||||
for route, params in path_matches
|
||||
if route.method == method
|
||||
]
|
||||
if not method_matches:
|
||||
methods = tuple(sorted({route.method for route, _ in path_matches}))
|
||||
raise MethodNotAllowed(methods)
|
||||
|
||||
highest_specificity = max(
|
||||
route.static_segment_count for route, _ in method_matches
|
||||
)
|
||||
best_match = next(
|
||||
item
|
||||
for item in method_matches
|
||||
if item[0].static_segment_count == highest_specificity
|
||||
)
|
||||
return RouteMatch(*best_match)
|
||||
|
||||
def _validate_conflicts(self) -> None:
|
||||
for index, first in enumerate(self._routes):
|
||||
for second in self._routes[index + 1 :]:
|
||||
if (
|
||||
first.method == second.method
|
||||
and first.static_segment_count == second.static_segment_count
|
||||
and _templates_overlap(first, second)
|
||||
):
|
||||
raise ValueError(
|
||||
f"ambiguous {first.method} routes: {first.path} and {second.path}"
|
||||
)
|
||||
|
||||
|
||||
def _parse_path(path: str) -> tuple[str, ...]:
|
||||
if (
|
||||
not isinstance(path, str)
|
||||
or not path.startswith("/")
|
||||
or path.endswith("/")
|
||||
or "//" in path
|
||||
or "?" in path
|
||||
or "#" in path
|
||||
):
|
||||
raise ValueError("HTTP route path must be a canonical absolute path")
|
||||
segments = tuple(path.split("/")[1:])
|
||||
if len(segments) < 3 or segments[0] != "api":
|
||||
raise ValueError("HTTP route path must start with /api/v{version}/...")
|
||||
if not _API_VERSION.fullmatch(segments[1]):
|
||||
raise ValueError("HTTP route version must be a positive integer, such as v1")
|
||||
|
||||
parameters: set[str] = set()
|
||||
for segment in segments[2:]:
|
||||
if "{" not in segment and "}" not in segment:
|
||||
continue
|
||||
name = segment[1:-1] if segment.startswith("{") and segment.endswith("}") else ""
|
||||
if not _PARAMETER.fullmatch(name) or name in parameters:
|
||||
raise ValueError("path parameters must be unique named segments")
|
||||
parameters.add(name)
|
||||
return segments
|
||||
|
||||
|
||||
def _is_parameter(segment: str) -> bool:
|
||||
return segment.startswith("{") and segment.endswith("}")
|
||||
|
||||
|
||||
def _match_path(
|
||||
route: HttpRoute, request_segments: tuple[str, ...]
|
||||
) -> dict[str, str] | None:
|
||||
route_segments = route.segments
|
||||
if len(route_segments) != len(request_segments):
|
||||
return None
|
||||
parameters: dict[str, str] = {}
|
||||
for template_segment, request_segment in zip(route_segments, request_segments):
|
||||
if _is_parameter(template_segment):
|
||||
if not request_segment:
|
||||
return None
|
||||
parameters[template_segment[1:-1]] = request_segment
|
||||
elif template_segment != request_segment:
|
||||
return None
|
||||
return parameters
|
||||
|
||||
|
||||
def _templates_overlap(first: HttpRoute, second: HttpRoute) -> bool:
|
||||
first_segments = first.segments
|
||||
second_segments = second.segments
|
||||
if len(first_segments) != len(second_segments):
|
||||
return False
|
||||
return all(
|
||||
left == right or _is_parameter(left) or _is_parameter(right)
|
||||
for left, right in zip(first_segments, second_segments)
|
||||
)
|
||||
+45
-12
@@ -12,7 +12,7 @@ from plba.health import (
|
||||
HealthContributorRegistry,
|
||||
RuntimeHealthInputProvider,
|
||||
)
|
||||
from plba.http import ControlApi
|
||||
from plba.http import ControlApi, HttpRoute
|
||||
from plba.runtime import ApplicationLifecycle, ApplicationRuntime, RuntimeContext
|
||||
from plba.runtime.worker import (
|
||||
ComponentHealth,
|
||||
@@ -126,33 +126,65 @@ class ControlApiTests(unittest.IsolatedAsyncioTestCase):
|
||||
provider = RuntimeHealthInputProvider(
|
||||
self.runtime, self.supervisor, HealthContributorRegistry()
|
||||
)
|
||||
self.api = ControlApi(self.runtime, HealthAggregator(provider))
|
||||
self.health_aggregator = HealthAggregator(provider)
|
||||
self.api = ControlApi(self.runtime, self.health_aggregator)
|
||||
|
||||
async def test_status_start_health_and_stop_routes(self) -> None:
|
||||
status = await self.request("GET", "/runtime/status")
|
||||
status = await self.request("GET", "/api/v1/runtime/status")
|
||||
self.assertEqual(status[0], 200)
|
||||
self.assertEqual(status[1], {"status": "new"})
|
||||
|
||||
started = await self.request("POST", "/runtime/start")
|
||||
started = await self.request("POST", "/api/v1/runtime/start")
|
||||
self.assertEqual(started[0], 200)
|
||||
self.assertEqual(started[1], {"status": "running"})
|
||||
|
||||
health = await self.request("GET", "/health")
|
||||
health = await self.request("GET", "/api/v1/health")
|
||||
self.assertEqual(health[0], 200)
|
||||
self.assertEqual(health[1]["application_id"], "service-http")
|
||||
self.assertEqual(health[1]["status"], "ok")
|
||||
|
||||
stopped = await self.request("POST", "/runtime/stop", b"{}")
|
||||
stopped = await self.request("POST", "/api/v1/runtime/stop", b"{}")
|
||||
self.assertEqual(stopped, (200, {"status": "stopped"}))
|
||||
|
||||
async def test_application_route_uses_control_api_and_receives_path_params(self) -> None:
|
||||
async def get_item(scope, receive, send) -> None:
|
||||
body = json.dumps({"item_id": scope["path_params"]["item_id"]}).encode()
|
||||
await send(
|
||||
{
|
||||
"type": "http.response.start",
|
||||
"status": 200,
|
||||
"headers": [(b"content-type", b"application/json")],
|
||||
}
|
||||
)
|
||||
await send({"type": "http.response.body", "body": body})
|
||||
|
||||
self.api = ControlApi(
|
||||
self.runtime,
|
||||
self.health_aggregator,
|
||||
(HttpRoute("GET", "/api/v1/items/{item_id}", get_item),),
|
||||
)
|
||||
|
||||
response = await self.request("GET", "/api/v1/items/sku-42")
|
||||
|
||||
self.assertEqual(response, (200, {"item_id": "sku-42"}))
|
||||
|
||||
async def test_router_errors_use_versioned_api_codes(self) -> None:
|
||||
missing = await self.request("GET", "/api/v1/missing")
|
||||
method_not_allowed = await self.request("POST", "/api/v1/health")
|
||||
|
||||
self.assertEqual(missing[0], 404)
|
||||
self.assertEqual(missing[1]["error"], "HTTP_ROUTE_NOT_FOUND")
|
||||
self.assertEqual(method_not_allowed[0], 405)
|
||||
self.assertEqual(method_not_allowed[1]["error"], "HTTP_METHOD_NOT_ALLOWED")
|
||||
|
||||
async def test_invalid_stop_request_is_http_400(self) -> None:
|
||||
missing = await self.request("POST", "/runtime/stop")
|
||||
malformed = await self.request("POST", "/runtime/stop", b"not-json")
|
||||
missing = await self.request("POST", "/api/v1/runtime/stop")
|
||||
malformed = await self.request("POST", "/api/v1/runtime/stop", b"not-json")
|
||||
invalid_timeout = await self.request(
|
||||
"POST", "/runtime/stop", b'{"timeout_seconds": 0}'
|
||||
"POST", "/api/v1/runtime/stop", b'{"timeout_seconds": 0}'
|
||||
)
|
||||
null_timeout = await self.request(
|
||||
"POST", "/runtime/stop", b'{"timeout_seconds": null}'
|
||||
"POST", "/api/v1/runtime/stop", b'{"timeout_seconds": null}'
|
||||
)
|
||||
|
||||
self.assertEqual(missing[0], 400)
|
||||
@@ -178,12 +210,13 @@ class ControlApiTests(unittest.IsolatedAsyncioTestCase):
|
||||
provider = RuntimeHealthInputProvider(
|
||||
self.runtime, self.supervisor, HealthContributorRegistry()
|
||||
)
|
||||
self.api = ControlApi(self.runtime, HealthAggregator(provider))
|
||||
self.health_aggregator = HealthAggregator(provider)
|
||||
self.api = ControlApi(self.runtime, self.health_aggregator)
|
||||
await self.runtime.start()
|
||||
await asyncio.wait_for(active.wait(), timeout=1)
|
||||
|
||||
result = await self.request(
|
||||
"POST", "/runtime/stop", b'{"timeout_seconds": 0.01}'
|
||||
"POST", "/api/v1/runtime/stop", b'{"timeout_seconds": 0.01}'
|
||||
)
|
||||
|
||||
self.assertEqual(result, (202, {"status": "stopping"}))
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
import unittest
|
||||
|
||||
from plba.http.routes import (
|
||||
HttpRoute,
|
||||
HttpRouter,
|
||||
MethodNotAllowed,
|
||||
RouteNotFound,
|
||||
)
|
||||
|
||||
|
||||
async def unused_handler(scope, receive, send) -> None:
|
||||
return None
|
||||
|
||||
|
||||
class HttpRouteDefinitionTests(unittest.TestCase):
|
||||
def test_requires_versioned_path_with_endpoint_segment(self) -> None:
|
||||
for path in (
|
||||
"/health",
|
||||
"/api/v0/health",
|
||||
"/api/v1",
|
||||
"/api/v1//health",
|
||||
"/api/v1/health/",
|
||||
"/api/v1/{bad-name}",
|
||||
"/api/v1/{item_id}/{item_id}",
|
||||
):
|
||||
with self.subTest(path=path), self.assertRaises(ValueError):
|
||||
HttpRoute("GET", path, unused_handler)
|
||||
|
||||
def test_requires_uppercase_http_method_and_callable_handler(self) -> None:
|
||||
with self.assertRaises(ValueError):
|
||||
HttpRoute("get", "/api/v1/items", unused_handler)
|
||||
with self.assertRaises(ValueError):
|
||||
HttpRoute("GET", "/api/v1/items", None) # type: ignore[arg-type]
|
||||
|
||||
|
||||
class HttpRouterTests(unittest.TestCase):
|
||||
def test_resolves_named_parameters(self) -> None:
|
||||
route = HttpRoute("GET", "/api/v1/items/{item_id}", unused_handler)
|
||||
|
||||
match = HttpRouter((route,)).resolve("GET", "/api/v1/items/sku-42")
|
||||
|
||||
self.assertIs(match.route, route)
|
||||
self.assertEqual(match.path_params, {"item_id": "sku-42"})
|
||||
|
||||
def test_static_path_has_priority_over_parameter_path(self) -> None:
|
||||
parameter_route = HttpRoute(
|
||||
"GET", "/api/v1/items/{item_id}", unused_handler
|
||||
)
|
||||
static_route = HttpRoute("GET", "/api/v1/items/by-id", unused_handler)
|
||||
router = HttpRouter((parameter_route, static_route))
|
||||
|
||||
match = router.resolve("GET", "/api/v1/items/by-id")
|
||||
|
||||
self.assertIs(match.route, static_route)
|
||||
self.assertEqual(match.path_params, {})
|
||||
|
||||
def test_rejects_duplicate_and_ambiguous_routes(self) -> None:
|
||||
routes = (
|
||||
("/api/v1/items/{item_id}", "/api/v1/items/{item_id}"),
|
||||
("/api/v1/{kind}/items", "/api/v1/items/{name}"),
|
||||
)
|
||||
for first_path, second_path in routes:
|
||||
with self.subTest(paths=(first_path, second_path)):
|
||||
first = HttpRoute("GET", first_path, unused_handler)
|
||||
second = HttpRoute("GET", second_path, unused_handler)
|
||||
with self.assertRaises(ValueError):
|
||||
HttpRouter((first, second))
|
||||
|
||||
def test_known_path_with_wrong_method_reports_allowed_methods(self) -> None:
|
||||
router = HttpRouter(
|
||||
(HttpRoute("GET", "/api/v1/items", unused_handler),)
|
||||
)
|
||||
|
||||
with self.assertRaises(MethodNotAllowed) as caught:
|
||||
router.resolve("POST", "/api/v1/items")
|
||||
|
||||
self.assertEqual(caught.exception.allowed_methods, ("GET",))
|
||||
|
||||
def test_unknown_path_is_not_found(self) -> None:
|
||||
router = HttpRouter(
|
||||
(HttpRoute("GET", "/api/v1/items", unused_handler),)
|
||||
)
|
||||
|
||||
with self.assertRaises(RouteNotFound):
|
||||
router.resolve("GET", "/api/v1/unknown")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user