Compare commits

..
5 Commits
Author SHA1 Message Date
alex 2f47fc74cf PLBA2-4. Архивация спеки
PLBA package CI / Python tests (push) Successful in 8s
PLBA package CI / Package version increment (push) Skipped
2026-10-11 11:01:02 +03:00
alex d46993a092 PLBA2-4. Доработка регистрации http эндпоинтов
PLBA package CI / Python tests (push) Successful in 23s
PLBA package CI / Package version increment (push) Skipped
2026-10-11 10:44:59 +03:00
alex a0d2db6bd0 PLBA2-3. Правки CI воркфлоу
PLBA package CI / Python tests (push) Successful in 20s
PLBA package CI / Package version increment (push) Skipped
2026-10-10 21:53:18 +03:00
alex d517820088 PLBA2-2. Архивация спек
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped
2026-10-10 20:55:13 +03:00
alex 19fa591c31 PLBA2-3. CI процесс 2026-10-10 20:54:54 +03:00
63 changed files with 3206 additions and 617 deletions
+72
View File
@@ -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}"
+2 -2
View File
@@ -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
View File
@@ -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` до явного принятия владельцем решения.
@@ -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
View File
@@ -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 -->
@@ -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 нет.
@@ -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, зависимости и системы -->
@@ -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 <!-- Формулировка задачи -->
@@ -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:
+338
View File
@@ -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 |
+62
View File
@@ -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 |
+211
View File
@@ -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
View File
@@ -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"
+92
View File
@@ -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())
+2 -1
View File
@@ -1,3 +1,4 @@
from plba.http.control_api import ControlApi
from plba.http.routes import HttpRoute
__all__ = ["ControlApi"]
__all__ = ["ControlApi", "HttpRoute"]
+113 -38
View File
@@ -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")
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")
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")
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")
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)
async def _require_empty_body(self, receive: Any) -> None:
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}
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 = 200 if result.lifecycle.value == "stopped" else 202
return status, {"status": result.lifecycle.value}
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)}
+168
View File
@@ -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
View File
@@ -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"}))
+89
View File
@@ -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()