Compare commits

..
3 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
32 changed files with 1766 additions and 608 deletions
+26 -5
View File
@@ -13,7 +13,17 @@ jobs:
runs-on: cloud-build runs-on: cloud-build
steps: steps:
- name: Check out repository - name: Check out repository
uses: actions/checkout@v4 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 - name: Check Python version
run: | run: |
@@ -39,13 +49,24 @@ jobs:
runs-on: cloud-build runs-on: cloud-build
steps: steps:
- name: Check out repository and target branch history - name: Check out repository and target branch history
uses: actions/checkout@v4 env:
with: GITEA_SERVER_URL: ${{ gitea.server_url }}
fetch-depth: 0 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 - name: Check package version increment
env: env:
BASE_REF: ${{ github.base_ref }} BASE_REF: ${{ gitea.base_ref }}
run: | run: |
test -n "$BASE_REF" test -n "$BASE_REF"
python3 scripts/check_package_version.py --base-ref "origin/${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/worker` регистрирует worker-ы с уникальными именами, применяет флаг `disabled`, выполняет последовательные циклы по расписанию, объединяет прикладное и автоматическое состояние health и поддерживает штатную и принудительную остановку.
- `runtime/application-lifecycle` запускает и останавливает все включённые worker-ы и сообщает состояние жизненного цикла приложения. - `runtime/application-lifecycle` запускает и останавливает все включённые worker-ы и сообщает состояние жизненного цикла приложения.
- `health/aggregation` объединяет состояния 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-config-file` загружает типизированную конфигурацию приложения из корневого `config.yaml` и атомарно применяет корректные обновления без перезапуска.
- `configuration/application-settings` предоставляет типизированный `SettingsReader` и PostgreSQL-адаптер для принадлежащей приложению таблицы `settings`. - `configuration/application-settings` предоставляет типизированный `SettingsReader` и PostgreSQL-адаптер для принадлежащей приложению таблицы `settings`.
- `workflow/orchestration` выполняет именованные шаги по объявленным переходам и сохраняет снимки запуска и шагов через порт, реализуемый приложением. - `workflow/orchestration` выполняет именованные шаги по объявленным переходам и сохраняет снимки запуска и шагов через порт, реализуемый приложением.
@@ -79,7 +79,7 @@ supervisor = WorkerSupervisor(workers, config_manager)
runtime = ApplicationRuntime(runtime_context, supervisor) 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. Уже выданные снимки конфигурации остаются неизменными; при некорректном обновлении активным остаётся последний корректный снимок. Чтобы применять изменения конфигурации, запустите `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` `ApplicationRuntime`. Register non-worker checks in `HealthContributorRegistry`
and connect it to `HealthAggregator` with `RuntimeHealthInputProvider`. and connect it to `HealthAggregator` with `RuntimeHealthInputProvider`.
Mount `ControlApi(runtime, health_aggregator)` in the application's ASGI host. Register application endpoints as typed `HttpRoute` values when composing the
The host owns the socket and listener; the adapter contributes `/health`, ASGI application. The built-in routes and application handlers share the same
`/runtime/start`, `/runtime/stop`, and `/runtime/status` to that same listener. `ControlApi` router and listener:
The application chooses when to start and stop the runtime.
```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 ## Configuration and settings
@@ -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 -38
View File
@@ -1,43 +1,21 @@
schema: function-driven schema: use-case-driven
context: | context: |
Актуальные спецификации проекта находятся в openspec/specs/. ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и
Старые документы spec/specs/ устарели и не подтверждают текущее поведение. реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если
Capability имеет отдельную бизнес-функцию или понятный результат и живёт запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о
в иерархии доменов, например orders/snapshot-sync. конфликте пользователю; не обходи решение молча. Новые ADR оформляй по
Requirement описывает одну завершённую техническую функцию. шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом
Формат требований определяется локальной схемой function-driven. Proposed; не помечай решение Accepted без явного принятия владельцем решения.
Включай только сведения, влияющие на наблюдаемое поведение, устойчивый
контракт или обязательное техническое ограничение; не добавляй повторы и
пояснительный текст без такого влияния.
Пиши по-русски весь пояснительный текст каждого изменения OpenSpec:
в proposal.md, design.md, specs/**/*.md и tasks.md. Сохраняй обязательные
заголовки и синтаксис OpenSpec, имена API, SQL-полей, кодов, файлов,
инструментов, команд и идентификаторы без перевода.
rules: rules:
specs:
- Пиши пояснительный текст спецификаций по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы.
- Каждый 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.
- Пиши пояснительный текст proposal по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы.
design:
- Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований.
- Пиши пояснительный текст design по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы.
tasks: tasks:
- Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты. - >-
- Пиши названия групп и формулировки задач по-русски; сохраняй команды, пути, API, коды и идентификаторы без перевода. Завершай каждый реализуемый change отдельной последней задачей на
- Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в pyproject.toml. Выполняй её после реализации и проверок; один change повышает версию ровно один раз. увеличение версии пакета в `pyproject.toml`; один change повышает версию
- До версии 1.0.0 используй PATCH для исправлений, рефакторинга и документации; MINOR для новых возможностей и любых изменений публичного контракта, включая несовместимые. Переход на 1.0.0 означает начало стабильного публичного контракта. ровно один раз. До 1.0.0 используй PATCH для исправлений, рефакторинга и
- Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей и MAJOR для несовместимых изменений публичного контракта. документации, 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,281 +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: |
Пиши весь пояснительный текст артефакта изменения по-русски. Сохраняй
обязательные заголовки OpenSpec и технические идентификаторы, названия
API, файлов, инструментов, команд и коды без перевода.
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: |
Пиши весь пояснительный текст спецификаций по-русски. Сохраняй
обязательные заголовки OpenSpec, идентификаторы, названия API и коды
без перевода.
Создай спецификации наблюдаемого поведения и устойчивых контрактов.
Правила ниже применяются к 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: |
Пиши весь пояснительный текст design по-русски. Сохраняй обязательные
заголовки OpenSpec и технические идентификаторы, названия файлов,
инструментов и команд без перевода.
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: |
Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные
идентификаторы, пути файлов, названия API, коды и команды без перевода.
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,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,30 +1,36 @@
# Схема function-driven # Схема use-case-driven
Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на `use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на
`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`. `spec-driven`. Она задаёт workflow `proposal → specs / design → tasks`;
Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему; с явно указанной `schema: spec-driven` продолжают использовать свою схему.
их миграция не является частью изменения формата master spec.
## Уровни спецификации ## Уровни спецификации
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario. - Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы. - Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
- FR — подробные правила и контракты сообщений за пределами Scenario; - FR — подробные правила и контракты сообщений за пределами Scenario;
контракт HTTP endpoint размещается в завершающем CONTRACT. контракт HTTP endpoint размещается в завершающем CONTRACT.
В спецификацию включаются только сведения, влияющие на наблюдаемое поведение, Requirements и FR включают только сведения, влияющие на наблюдаемое поведение,
устойчивый контракт или обязательное техническое ограничение. Повторы и устойчивый контракт или обязательное техническое ограничение. Раздел «Границы»
пояснения без такого влияния удаляются. кратко фиксирует ответственность и владение capability, не повторяя Requirements.
Повторы и пояснения без такого влияния удаляются.
Для каждой capability зарегистрируй стабильный уникальный префикс в Составной префикс Requirement строится из сокращений сегментов пути capability:
[`capability-codes.md`](capability-codes.md). Его сегменты отражают путь для однословного сегмента используй первые три буквы, для сегмента с дефисами —
capability: например, `configuration/application-settings` получает `CFG.AS`. первые буквы его частей. Приводи сокращения к верхнему регистру. Например,
ID Requirement имеет вид `CFG.AS-01`; его номер уникален внутри capability. `domain/capability-name` получает `DOM.CN`. Если префикс уже занят, удлиняй
В сочетании с уникальным префиксом это даёт уникальный ID в проекте. сокращения новых сегментов до уникальности; ранее назначенные префиксы не меняй.
ID FR включает ID Requirement и локальный номер: `CFG.AS-01.FR-01`, Сохраняй префикс при переименовании capability. Валидатор проверяет уникальность
`CFG.AS-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement. по 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 В новых и изменяемых Requirements используй составные ID. Неизменённые legacy
specs могут сохранять прежние ID до отдельного рефакторинга. specs могут сохранять прежние ID до отдельного рефакторинга.
@@ -58,7 +64,7 @@ Markdown-рендерер автоматически создаёт якоря
В Scenario «Назначение» опционально и добавляется только при наличии сведений, В Scenario «Назначение» опционально и добавляется только при наличии сведений,
которых нет в заголовке. «Контекст» в 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 ## Форматы Use case
@@ -124,12 +130,17 @@ FR, описывающий таблицу БД, оформляется по
В response-таблице также указывается источник или правило формирования каждого поля. В response-таблице также указывается источник или правило формирования каждого поля.
Другие паттерны добавляются отдельными файлами по мере появления потребности. Другие паттерны добавляются отдельными файлами по мере появления потребности.
## Шаблоны и delta specs ## Форматы master и delta specs
- `templates/main-spec.md` — постоянная спецификация capability. - `templates/main-spec.md` — краткая схема постоянной master spec: Purpose, Границы и Requirements; это не артефакт change.
- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`. - `templates/spec.md` — полный шаблон delta для change, предоставляемый `openspec instructions specs`.
- `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow. - `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow.
В master spec раздел `## Границы` располагается между Purpose и Requirements.
Он описывает ответственность capability, её включённую область и явные
исключения или передачу ответственности другим capabilities и приложению.
В delta spec этот раздел не повторяется: delta меняет отдельные Requirements.
ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration, ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration,
RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный
Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и
@@ -140,12 +151,44 @@ Scenario в таких операциях не создаётся. В delta со
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes. фиксируется в 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 ```sh
openspec schema validate function-driven openspec schema validate use-case-driven
openspec validate orders/snapshot-sync --type spec --strict --no-interactive openspec validate domain/capability-name --type spec --strict --no-interactive
python3 openspec/schemas/function-driven/validate_format.py --require-qualified-ids openspec/specs/orders/snapshot-sync/spec.md 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/`. Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`.
@@ -158,7 +201,7 @@ python3 openspec/schemas/function-driven/validate_format.py --require-qualified-
неизменённые legacy specs. Проверка охватывает один Scenario, неизменённые legacy specs. Проверка охватывает один Scenario,
обычную структуру use case или формат сокращенного use case, ссылки шагов на FR, обычную структуру use case или формат сокращенного use case, ссылки шагов на FR,
форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков
в Scenario, ID из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки, в Scenario, префиксы из ID master specs, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
таблицу кодов и её связь с FR. таблицу кодов и её связь с FR.
Семантическую завершённость функции и понятность кода оценивает автор/reviewer. Семантическую завершённость функции и понятность кода оценивает автор/reviewer.
Схема требует от автора запускать обе проверки; автоматического hook в CLI нет. Схема требует от автора запускать обе проверки; автоматического hook в CLI нет.
@@ -19,19 +19,17 @@
## Пример ## Пример
```markdown ```markdown
##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings ##### AREA.CAP-01.FR-01 [DB]: Таблица хранения записей
Таблица `settings` создаётся в схеме приложения и содержит: Таблица `example_records` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение | | Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки | | `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки |
| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения | | `external_id` | `VARCHAR(64)` | NOT NULL | Идентификатор записи во внешней системе |
| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки | | `status` | `VARCHAR(32)` | NOT NULL | Текущее состояние записи |
| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки | | `created_at` | `TIMESTAMP` | NOT NULL | Время создания записи |
| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей | | `updated_at` | `TIMESTAMP` | NULL | Время последнего изменения записи |
| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении |
| `description` | `TEXT` | 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,16 @@
# Capability: <название>
## Purpose
<Бизнес-функция capability и понятный результат, не менее 50 знаков.>
## Границы
<!-- Кратко опиши ответственность capability: что входит в её область,
что остаётся за её пределами и кому это принадлежит. Не дублируй Requirements. -->
## Requirements
<!-- Полный актуальный набор Requirements capability. Оформляй Requirements
по правилам schema.yaml. Не используй заголовки операций delta:
ADDED, MODIFIED, REMOVED или RENAMED. -->
@@ -101,7 +101,7 @@ HTTP status: <код и условие возврата>.
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД; <!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
[API] — контракт сообщения или технического лога; [UI] — требования к UI. [API] — контракт сообщения или технического лога; [UI] — требования к UI.
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md. [DB] с таблицей оформляй по openspec/schemas/use-case-driven/patterns/database-table.md.
Сериализуемый контракт FR [API] оформляй по Сериализуемый контракт FR [API] оформляй по
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице openspec/schemas/use-case-driven/patterns/message-contract.md. В response-таблице
добавь колонку «Формирование значения» для каждого поля. --> добавь колонку «Формирование значения» для каждого поля. -->
@@ -9,7 +9,3 @@
- [ ] 2.1 <!-- Формулировка задачи --> - [ ] 2.1 <!-- Формулировка задачи -->
- [ ] 2.2 <!-- Формулировка задачи --> - [ ] 2.2 <!-- Формулировка задачи -->
## 3. Обновление версии
- [ ] 3.1 Последней задачей увеличь версию пакета в `pyproject.toml` по правилам `openspec/config.yaml` и проверь изменение скриптом `scripts/check_package_version.py`.
@@ -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 from __future__ import annotations
@@ -27,8 +27,6 @@ HTML_ANCHOR = re.compile(r"<a\b[^>]*\bid\s*=", re.IGNORECASE)
DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение") DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение")
CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение") CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение")
RESPONSE_CONTRACT_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: def plain_text(value: str) -> str:
@@ -65,27 +63,165 @@ def parse_fr_reference(label: str) -> tuple[str | None, str] | None:
return None return None
def load_capability_codes() -> tuple[dict[str, str], list[str]]: def openspec_root_for(path: Path) -> Path:
codes: dict[str, str] = {} """Find the OpenSpec root containing a master or change spec."""
errors: list[str] = [] resolved = path.resolve()
try: for parent in (resolved, *resolved.parents):
lines = CAPABILITY_CODES_PATH.read_text(encoding="utf-8").splitlines() if parent.name == "openspec":
except OSError as error: return parent
return {}, [f"не удалось прочитать реестр capability codes: {error}"] return (Path.cwd() / "openspec").resolve()
prefixes: dict[str, str] = {}
for line in lines: def load_capability_prefixes(openspec_root: Path) -> tuple[dict[str, str], list[str]]:
match = CAPABILITY_CODE_ROW.match(line) """Read the active path-to-prefix mapping from master specs."""
if not match: 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 continue
capability_path, prefix = match.groups() prefixes = {
if capability_path in codes: requirement_id.rsplit("-", 1)[0]
errors.append(f"путь capability повторяется в реестре: {capability_path}") for requirement_id in ids
if prefix in prefixes: if "." in requirement_id
errors.append(f"префикс {prefix} повторяется для {prefixes[prefix]} и {capability_path}") }
codes[capability_path] = prefix if prefixes:
prefixes[prefix] = capability_path prefixes_by_capability.setdefault(capability_path, set()).update(prefixes)
return codes, errors
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: 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 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]]]: def heading_targets(text: str) -> tuple[set[str], dict[str, tuple[str, str]]]:
"""Return generated heading fragments and fragments that target FR headings.""" """Return generated heading fragments and fragments that target FR headings."""
targets: set[str] = set() targets: set[str] = set()
@@ -258,7 +401,7 @@ def check_requirement(
requirement_id = ids[0] requirement_id = ids[0]
is_qualified = "." in requirement_id is_qualified = "." in requirement_id
if require_qualified_ids and not is_qualified: 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) level_four = re.findall(r"^#### (.+)$", block, re.MULTILINE)
has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT" has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT"
expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"] expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"]
@@ -423,7 +566,8 @@ def validate(
path: Path, path: Path,
base: Path | None = None, base: Path | None = None,
require_qualified_ids: bool = False, 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]: ) -> list[str]:
text = path.read_text(encoding="utf-8") text = path.read_text(encoding="utf-8")
if HTML_ANCHOR.search(text): if HTML_ANCHOR.search(text):
@@ -435,23 +579,17 @@ def validate(
targets.update(base_targets) targets.update(base_targets)
fr_targets.update(base_fr_targets) fr_targets.update(base_fr_targets)
errors = [] errors = list(capability_inventory_errors or [])
if capability_codes is None: if capability_prefixes is None:
capability_codes, registry_errors = load_capability_codes() capability_prefixes, inventory_errors = load_capability_prefixes(
errors.extend(registry_errors) openspec_root_for(path)
)
errors.extend(inventory_errors)
blocks = list(requirement_blocks(text)) blocks = list(requirement_blocks(text))
ids = REQUIREMENT_ID.findall(text) ids = REQUIREMENT_ID.findall(text)
if len(ids) != len(set(ids)): if len(ids) != len(set(ids)):
errors.append("повторяющиеся ID Requirements") errors.append("повторяющиеся ID Requirements")
capability_path = spec_capability_path(path) errors.extend(check_capability_ids(path, ids, capability_prefixes, base))
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}")
if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE): if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE):
errors.append("нет Requirements") errors.append("нет Requirements")
for name, block in blocks: 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])}) paths = sorted({file for path in args.paths for file in (path.rglob("spec.md") if path.is_dir() else [path])})
if not paths: if not paths:
parser.error("не найдены spec.md") 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 failed = False
for error in registry_errors:
print(f"ERROR {CAPABILITY_CODES_PATH}: {error}")
failed = True
for path in paths: for path in paths:
try: 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: except OSError as error:
errors = [str(error)] errors = [str(error)]
for error in errors: for error in errors:
+74 -20
View File
@@ -2,11 +2,12 @@
## Purpose ## Purpose
Объединить health и управление lifecycle приложения в одном HTTP API, подключаемом к host приложения. Объединить health, управление lifecycle приложения и endpoints приложения в одном HTTP API, подключаемом к host приложения.
## Границы ## Границы
- В capability входят маршруты /health, /runtime/start, /runtime/stop и /runtime/status, подключаемые к HTTP host приложения. - В capability входят встроенные маршруты `/api/v1/health`, `/api/v1/runtime/start`, `/api/v1/runtime/stop` и `/api/v1/runtime/status`, а также регистрация прикладных endpoints в том же HTTP host и listener.
- Приложение владеет HTTP host, listener и логикой собственных endpoints; Caddy отвечает за внешний service-prefix и маршрутизацию к сервису.
## Requirements ## Requirements
@@ -14,7 +15,7 @@
**ID:** `API.HTTP.CA-01` **ID:** `API.HTTP.CA-01`
PLBA2 SHALL предоставлять один route adapter для всех HTTP endpoints управления приложением; adapter подключается к host приложения и использует его единственный listener. PLBA2 SHALL предоставлять единую точку маршрутизации для встроенных HTTP endpoints PLBA и endpoints, зарегистрированных приложением; adapter подключается к host приложения и использует его единственный listener.
#### Scenario: Сокращенный use case: подключение control API #### Scenario: Сокращенный use case: подключение control API
@@ -26,13 +27,13 @@ PLBA2 SHALL предоставлять один route adapter для всех HT
##### API.HTTP.CA-01.FR-01: Подключение к host приложения ##### API.HTTP.CA-01.FR-01: Подключение к host приложения
Приложение подключает route adapter к собственному HTTP host. Все endpoints control API используют его listener и порт. PLBA2 не запускает HTTP server и не открывает отдельный порт; adapter делегирует обработку соответствующим capabilities. Приложение подключает один ASGI adapter к собственному HTTP host. Adapter маршрутизирует встроенные endpoints PLBA и endpoints приложения через общий route registry и тот же listener. PLBA2 не запускает HTTP server и не открывает отдельный порт.
### Requirement: Health через GET /health ### Requirement: Health через GET /api/v1/health
**ID:** `API.HTTP.CA-02` **ID:** `API.HTTP.CA-02`
PLBA2 SHALL возвращать агрегированный health report приложения через GET /health. PLBA2 SHALL возвращать агрегированный health report приложения через GET /api/v1/health.
#### Scenario: Получение health-отчёта через GET /health #### Scenario: Получение health-отчёта через GET /health
@@ -47,7 +48,7 @@ PLBA2 SHALL возвращать агрегированный health report пр
##### Основной поток ##### Основной поток
1. Клиент вызывает GET /health; adapter получает запрос. 1. Клиент вызывает GET /api/v1/health; adapter получает запрос.
2. Adapter запрашивает агрегированный health report по [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов). 2. Adapter запрашивает агрегированный health report по [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов).
3. Adapter сериализует report по [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) и завершает с HEALTH_RESPONSE_RETURNED. 3. Adapter сериализует report по [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) и завершает с HEALTH_RESPONSE_RETURNED.
@@ -80,7 +81,7 @@ Adapter возвращает без пересчёта агрегированн
##### Request ##### Request
Метод: `GET`; путь: `/health`. Тело запроса и query-параметры отсутствуют. Метод: `GET`; путь: `/api/v1/health`. Тело запроса и query-параметры отсутствуют.
##### Response ##### Response
@@ -98,11 +99,11 @@ HTTP status: 200 при успешной сериализации health report.
| `components[].detail` | `string or null` | Обязательное | null допустим | Краткое пояснение состояния | Копируется из detail health-состояния; при отсутствии передаётся null | | `components[].detail` | `string or null` | Обязательное | null допустим | Краткое пояснение состояния | Копируется из detail health-состояния; при отсутствии передаётся null |
| `components[].meta` | `object` | Обязательное | null запрещён | Дополнительные структурированные данные | Копируется из meta health-состояния; при отсутствии передаётся пустой объект | | `components[].meta` | `object` | Обязательное | null запрещён | Дополнительные структурированные данные | Копируется из meta health-состояния; при отсутствии передаётся пустой объект |
### Requirement: Запуск приложения через POST /runtime/start ### Requirement: Запуск приложения через POST /api/v1/runtime/start
**ID:** `API.HTTP.CA-03` **ID:** `API.HTTP.CA-03`
PLBA2 SHALL запускать приложение по запросу POST /runtime/start и возвращать итоговый lifecycle status. PLBA2 SHALL запускать приложение по запросу POST /api/v1/runtime/start и возвращать итоговый lifecycle status.
#### Scenario: Запуск приложения через POST /runtime/start #### Scenario: Запуск приложения через POST /runtime/start
@@ -116,7 +117,7 @@ PLBA2 SHALL запускать приложение по запросу POST /ru
##### Основной поток ##### Основной поток
1. Клиент вызывает POST /runtime/start без тела запроса. 1. Клиент вызывает POST /api/v1/runtime/start без тела запроса.
2. Adapter запускает приложение по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения). 2. Adapter запускает приложение по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения).
3. Adapter возвращает итоговый lifecycle status по [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) и завершает с APPLICATION_STARTED. 3. Adapter возвращает итоговый lifecycle status по [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) и завершает с APPLICATION_STARTED.
@@ -149,7 +150,7 @@ Adapter делегирует запуск runtime по [RT.AL-01](../../../runti
##### Request ##### Request
Метод: `POST`; путь: `/runtime/start`. Тело запроса отсутствует. Метод: `POST`; путь: `/api/v1/runtime/start`. Тело запроса отсутствует.
##### Response ##### Response
@@ -159,11 +160,11 @@ HTTP status: 200 после обработки запроса запуска; р
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | running или failed; null запрещён | Итоговый lifecycle status после запуска | running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED | | `status` | `string` | Обязательное | running или failed; null запрещён | Итоговый lifecycle status после запуска | running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED |
### Requirement: Остановка приложения через POST /runtime/stop ### Requirement: Остановка приложения через POST /api/v1/runtime/stop
**ID:** `API.HTTP.CA-04` **ID:** `API.HTTP.CA-04`
PLBA2 SHALL останавливать приложение через POST /runtime/stop и возвращать его актуальный lifecycle status. PLBA2 SHALL останавливать приложение через POST /api/v1/runtime/stop и возвращать его актуальный lifecycle status.
#### Scenario: Остановка приложения через POST /runtime/stop #### Scenario: Остановка приложения через POST /runtime/stop
@@ -177,7 +178,7 @@ PLBA2 SHALL останавливать приложение через POST /run
##### Основной поток ##### Основной поток
1. Клиент передаёт параметры остановки в теле POST /runtime/stop. 1. Клиент передаёт параметры остановки в теле POST /api/v1/runtime/stop.
2. Adapter валидирует запрос и делегирует остановку по [RT.AL-02.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-02fr-01-режимы-остановки-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки). 2. Adapter валидирует запрос и делегирует остановку по [RT.AL-02.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-02fr-01-режимы-остановки-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки).
3. Adapter возвращает stopped или stopping по [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) с кодом APPLICATION_STOPPED или APPLICATION_STOPPING. 3. Adapter возвращает stopped или stopping по [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) с кодом APPLICATION_STOPPED или APPLICATION_STOPPING.
@@ -212,7 +213,7 @@ Adapter принимает объект запроса по контракту
##### Request ##### Request
Метод: `POST`; путь: `/runtime/stop`. Тело запроса — JSON object. Метод: `POST`; путь: `/api/v1/runtime/stop`. Тело запроса — JSON object.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | | Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
@@ -227,11 +228,11 @@ HTTP status: 200, если остановка завершена; 202, если
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | Для HTTP 200 — stopped; для HTTP 202 — stopping; null запрещён | Текущий lifecycle status приложения | Берётся из runtime: stopped после остановки всех workers; stopping, пока их остановка продолжается | | `status` | `string` | Обязательное | Для HTTP 200 — stopped; для HTTP 202 — stopping; null запрещён | Текущий lifecycle status приложения | Берётся из runtime: stopped после остановки всех workers; stopping, пока их остановка продолжается |
### Requirement: Lifecycle status через GET /runtime/status ### Requirement: Lifecycle status через GET /api/v1/runtime/status
**ID:** `API.HTTP.CA-05` **ID:** `API.HTTP.CA-05`
PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /runtime/status. PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /api/v1/runtime/status.
#### Scenario: Чтение lifecycle status через GET /runtime/status #### Scenario: Чтение lifecycle status через GET /runtime/status
@@ -245,7 +246,7 @@ PLBA2 SHALL возвращать текущее lifecycle status приложе
##### Основной поток ##### Основной поток
1. Клиент вызывает GET /runtime/status. 1. Клиент вызывает GET /api/v1/runtime/status.
2. Adapter читает lifecycle status без запуска или остановки компонентов по [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status). 2. Adapter читает lifecycle status без запуска или остановки компонентов по [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status).
3. Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED. 3. Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED.
@@ -273,7 +274,7 @@ Adapter читает status без побочных действий и заве
##### Request ##### Request
Метод: `GET`; путь: `/runtime/status`. Тело запроса и query-параметры отсутствуют. Метод: `GET`; путь: `/api/v1/runtime/status`. Тело запроса и query-параметры отсутствуют.
##### Response ##### Response
@@ -282,3 +283,56 @@ HTTP status: 200 при успешном чтении lifecycle status.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения | | Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Текущее lifecycle status приложения | Копируется без пересчёта из runtime state по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки) | | `status` | `string` | Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Текущее lifecycle status приложения | Копируется без пересчёта из runtime state по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки) |
### Requirement: Регистрация прикладных HTTP endpoints
**ID:** `API.HTTP.CA-06`
PLBA2 SHALL позволять приложению регистрировать собственные HTTP endpoints в общей маршрутизации и передавать им запросы через listener приложения.
#### Scenario: Регистрация и вызов прикладного HTTP endpoint
##### Участники
- Composition root приложения, общий HTTP adapter PLBA2, обработчик приложения и HTTP-клиент.
##### Предусловия
- Приложение создало HTTP adapter PLBA2.
- Обработчик приложения реализует ASGI callable для требуемых HTTP-запросов.
##### Основной поток
1. Приложение регистрирует endpoint по [API.HTTP.CA-06.FR-01](#apihttpca-06fr-01-регистрация-endpoint-приложения).
2. Клиент вызывает зарегистрированный путь, а adapter выбирает обработчик по методу и пути по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика).
3. Adapter передаёт запрос обработчику и возвращает созданный им HTTP-ответ.
4. Завершаем с `APPLICATION_ENDPOINT_DISPATCHED` — обработчик получил запрос по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика).
##### Альтернативы и ошибки
- Регистрация содержит невалидный или конфликтующий метод и путь — приложение получает `APPLICATION_ENDPOINT_REGISTRATION_REJECTED` по [API.HTTP.CA-06.FR-01](#apihttpca-06fr-01-регистрация-endpoint-приложения).
- Путь не зарегистрирован — adapter возвращает HTTP 404 и `HTTP_ROUTE_NOT_FOUND` по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика).
- Путь зарегистрирован, но для метода нет обработчика — adapter возвращает HTTP 405 и `HTTP_METHOD_NOT_ALLOWED` по [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика).
##### Результат
Запросы к endpoint приложения обслуживаются через общий API и listener сервиса.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_ENDPOINT_DISPATCHED` | Запрос передан зарегистрированному обработчику приложения | [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика) |
| `APPLICATION_ENDPOINT_REGISTRATION_REJECTED` | Регистрация endpoint отклонена из-за невалидного или повторяющегося маршрута | [API.HTTP.CA-06.FR-01](#apihttpca-06fr-01-регистрация-endpoint-приложения) |
| `HTTP_ROUTE_NOT_FOUND` | Для пути нет зарегистрированного endpoint | [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика) |
| `HTTP_METHOD_NOT_ALLOWED` | Для пути нет обработчика указанного HTTP-метода | [API.HTTP.CA-06.FR-02](#apihttpca-06fr-02-сопоставление-маршрута-и-вызов-обработчика) |
#### Функциональные требования
##### API.HTTP.CA-06.FR-01: Регистрация endpoint приложения
Приложение передаёт adapter-у типизированное описание endpoint, содержащее HTTP-метод, шаблон пути и ASGI callable обработчика. Регистрация выполняется до запуска HTTP host. Шаблон должен начинаться с `/api/v{version}/...`, где `{version}` — положительное целое число, и содержать хотя бы один сегмент после версии; параметры пути задаются отдельным именованным сегментом `{parameter_name}`. Невалидный HTTP-метод, шаблон без версии, повторяющаяся пара метода и шаблона или два маршрута одного метода с одинаковой специфичностью, способные совпасть с одним путём, отклоняются с `APPLICATION_ENDPOINT_REGISTRATION_REJECTED`; регистрация не создаёт HTTP response.
##### API.HTTP.CA-06.FR-02: Сопоставление маршрута и вызов обработчика
Adapter сопоставляет запросы по HTTP-методу и пути в общей таблице встроенных и прикладных endpoints. Маршрут с большим числом точных сегментов имеет приоритет над маршрутом с параметрами; неоднозначные шаблоны равной специфичности отклоняются при регистрации. Значения именованных сегментов передаются обработчику в `scope["path_params"]` как строки. Adapter передаёт обработчику ASGI `scope`, `receive` и `send`, добавляя `path_params` в копию scope; обработчик формирует HTTP status, headers и body ответа, а adapter завершает с `APPLICATION_ENDPOINT_DISPATCHED`. При отсутствии совпадающего пути adapter возвращает HTTP 404 с `HTTP_ROUTE_NOT_FOUND`; если путь совпадает, но метод не разрешён, возвращает HTTP 405 с `HTTP_METHOD_NOT_ALLOWED`.
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project] [project]
name = "plba-v2" name = "plba-v2"
version = "0.1.1" version = "0.2.0"
description = "Portable application lifecycle and observability components" description = "Portable application lifecycle and observability components"
readme = "README.md" readme = "README.md"
requires-python = ">=3.11" requires-python = ">=3.11"
+2 -1
View File
@@ -1,3 +1,4 @@
from plba.http.control_api import ControlApi 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 typing import Any
from plba.health.aggregator import HealthAggregator, HealthInputInvalid from plba.health.aggregator import HealthAggregator, HealthInputInvalid
from plba.http.asgi import ASGIHttpTransport from plba.http.asgi import ASGIHttpTransport
from plba.http.errors import ControlRequestError from plba.http.errors import ControlRequestError
from plba.http.requests import StopRequest 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.http.serialization import health_report_payload
from plba.runtime.application import ApplicationRuntime, RuntimeLifecycleError from plba.runtime.application import ApplicationRuntime, RuntimeLifecycleError
_ControlAction = Callable[
[ASGIScope, ASGIReceive], Awaitable[tuple[int, dict[str, Any]]]
]
class ControlApi: class ControlApi:
"""ASGI route adapter; it owns no server, socket, or listener.""" """ASGI route adapter; it owns no server, socket, or listener."""
def __init__( def __init__(
self, runtime: ApplicationRuntime, health_aggregator: HealthAggregator self,
runtime: ApplicationRuntime,
health_aggregator: HealthAggregator,
application_routes: Sequence[HttpRoute] = (),
) -> None: ) -> None:
self._runtime = runtime self._runtime = runtime
self._health_aggregator = health_aggregator self._health_aggregator = health_aggregator
self._transport = ASGIHttpTransport() 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") scope_type = scope.get("type")
if scope_type == "lifespan": if scope_type == "lifespan":
await self._transport.handle_lifespan(receive, send) await self._transport.handle_lifespan(receive, send)
return return
if scope_type != "http": if scope_type != "http":
return return
try: 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: except HealthInputInvalid as error:
status, payload = 500, self._error("HEALTH_INPUT_INVALID", error) status, payload = 500, self._error("HEALTH_INPUT_INVALID", error)
except RuntimeLifecycleError as error: except RuntimeLifecycleError as error:
@@ -37,45 +103,54 @@ class ControlApi:
status, payload = 500, self._error("CONTROL_API_FAILED", error) status, payload = 500, self._error("CONTROL_API_FAILED", error)
await self._transport.send_json(send, status, payload) await self._transport.send_json(send, status, payload)
async def _dispatch(self, scope: dict[str, Any], receive: Any) -> tuple[int, dict[str, Any]]: async def _health_action(
method = scope.get("method", "").upper() self, scope: ASGIScope, receive: ASGIReceive
path = scope.get("path", "") ) -> tuple[int, dict[str, Any]]:
query = scope.get("query_string", b"") self._require_no_query(scope)
if path in {"/health", "/runtime/status", "/runtime/start", "/runtime/stop"} and query: await self._require_empty_body(receive)
raise ControlRequestError("query parameters are not accepted") report = await self._health_aggregator.aggregate()
if path == "/health": return 200, health_report_payload(report)
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 _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): if await self._transport.read_body(receive):
raise ControlRequestError("request body is not accepted") 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 @staticmethod
def _error(code: str, error: Exception | str) -> dict[str, str]: def _error(code: str, error: Exception | str) -> dict[str, str]:
return {"error": code, "message": str(error)} 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, HealthContributorRegistry,
RuntimeHealthInputProvider, RuntimeHealthInputProvider,
) )
from plba.http import ControlApi from plba.http import ControlApi, HttpRoute
from plba.runtime import ApplicationLifecycle, ApplicationRuntime, RuntimeContext from plba.runtime import ApplicationLifecycle, ApplicationRuntime, RuntimeContext
from plba.runtime.worker import ( from plba.runtime.worker import (
ComponentHealth, ComponentHealth,
@@ -126,33 +126,65 @@ class ControlApiTests(unittest.IsolatedAsyncioTestCase):
provider = RuntimeHealthInputProvider( provider = RuntimeHealthInputProvider(
self.runtime, self.supervisor, HealthContributorRegistry() 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: 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[0], 200)
self.assertEqual(status[1], {"status": "new"}) 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[0], 200)
self.assertEqual(started[1], {"status": "running"}) 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[0], 200)
self.assertEqual(health[1]["application_id"], "service-http") self.assertEqual(health[1]["application_id"], "service-http")
self.assertEqual(health[1]["status"], "ok") 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"})) 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: async def test_invalid_stop_request_is_http_400(self) -> None:
missing = await self.request("POST", "/runtime/stop") missing = await self.request("POST", "/api/v1/runtime/stop")
malformed = await self.request("POST", "/runtime/stop", b"not-json") malformed = await self.request("POST", "/api/v1/runtime/stop", b"not-json")
invalid_timeout = await self.request( 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( 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) self.assertEqual(missing[0], 400)
@@ -178,12 +210,13 @@ class ControlApiTests(unittest.IsolatedAsyncioTestCase):
provider = RuntimeHealthInputProvider( provider = RuntimeHealthInputProvider(
self.runtime, self.supervisor, HealthContributorRegistry() 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 self.runtime.start()
await asyncio.wait_for(active.wait(), timeout=1) await asyncio.wait_for(active.wait(), timeout=1)
result = await self.request( 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"})) 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()