From d46993a092ebc76e3182576d91bd4ff59b6921d6 Mon Sep 17 00:00:00 2001 From: zosimovaa Date: Sun, 11 Oct 2026 10:44:59 +0300 Subject: [PATCH] =?UTF-8?q?PLBA2-4.=20=D0=94=D0=BE=D1=80=D0=B0=D0=B1=D0=BE?= =?UTF-8?q?=D1=82=D0=BA=D0=B0=20=D1=80=D0=B5=D0=B3=D0=B8=D1=81=D1=82=D1=80?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D0=B8=20http=20=D1=8D=D0=BD=D0=B4=D0=BF?= =?UTF-8?q?=D0=BE=D0=B8=D0=BD=D1=82=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 +- docs/integration.md | 53 ++- .../.openspec.yaml | 2 + .../versioned-extensible-http-api/design.md | 52 +++ .../versioned-extensible-http-api/proposal.md | 27 ++ .../specs/api/http/control-api/spec.md | 357 ++++++++++++++++++ .../versioned-extensible-http-api/tasks.md | 16 + openspec/config.yaml | 54 +-- ...i-path-naming-and-caddy-ingress-routing.md | 55 +++ .../function-driven/capability-codes.md | 19 - openspec/schemas/function-driven/schema.yaml | 281 -------------- .../function-driven/templates/main-spec.md | 106 ------ .../README.md | 91 +++-- .../validate_format.cpython-312.pyc | Bin .../patterns/database-table.md | 16 +- .../patterns/message-contract.md | 0 openspec/schemas/use-case-driven/schema.yaml | 351 +++++++++++++++++ .../schemas/use-case-driven/templates/adr.md | 36 ++ .../templates/design.md | 0 .../use-case-driven/templates/main-spec.md | 16 + .../templates/proposal.md | 0 .../templates/spec.md | 4 +- .../templates/tasks.md | 4 - .../validate_format.py | 235 +++++++++--- pyproject.toml | 2 +- src/plba/http/__init__.py | 3 +- src/plba/http/control_api.py | 151 ++++++-- src/plba/http/routes.py | 168 +++++++++ tests/test_health_http.py | 57 ++- tests/test_http_routes.py | 89 +++++ 30 files changed, 1666 insertions(+), 583 deletions(-) create mode 100644 openspec/changes/versioned-extensible-http-api/.openspec.yaml create mode 100644 openspec/changes/versioned-extensible-http-api/design.md create mode 100644 openspec/changes/versioned-extensible-http-api/proposal.md create mode 100644 openspec/changes/versioned-extensible-http-api/specs/api/http/control-api/spec.md create mode 100644 openspec/changes/versioned-extensible-http-api/tasks.md create mode 100644 openspec/context/adr/ADR-0001-api-path-naming-and-caddy-ingress-routing.md delete mode 100644 openspec/schemas/function-driven/capability-codes.md delete mode 100644 openspec/schemas/function-driven/schema.yaml delete mode 100644 openspec/schemas/function-driven/templates/main-spec.md rename openspec/schemas/{function-driven => use-case-driven}/README.md (63%) rename openspec/schemas/{function-driven => use-case-driven}/__pycache__/validate_format.cpython-312.pyc (100%) rename openspec/schemas/{function-driven => use-case-driven}/patterns/database-table.md (68%) rename openspec/schemas/{function-driven => use-case-driven}/patterns/message-contract.md (100%) create mode 100644 openspec/schemas/use-case-driven/schema.yaml create mode 100644 openspec/schemas/use-case-driven/templates/adr.md rename openspec/schemas/{function-driven => use-case-driven}/templates/design.md (100%) create mode 100644 openspec/schemas/use-case-driven/templates/main-spec.md rename openspec/schemas/{function-driven => use-case-driven}/templates/proposal.md (100%) rename openspec/schemas/{function-driven => use-case-driven}/templates/spec.md (98%) rename openspec/schemas/{function-driven => use-case-driven}/templates/tasks.md (55%) rename openspec/schemas/{function-driven => use-case-driven}/validate_format.py (74%) create mode 100644 src/plba/http/routes.py create mode 100644 tests/test_http_routes.py diff --git a/README.md b/README.md index a681e8a..58e1e2c 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ PLBA v2 — независимая от транспорта библиотек - `runtime/worker` регистрирует worker-ы с уникальными именами, применяет флаг `disabled`, выполняет последовательные циклы по расписанию, объединяет прикладное и автоматическое состояние health и поддерживает штатную и принудительную остановку. - `runtime/application-lifecycle` запускает и останавливает все включённые worker-ы и сообщает состояние жизненного цикла приложения. - `health/aggregation` объединяет состояния worker-ов и дополнительных компонентов с учётом критичности, отсутствующих компонентов и состояния приложения. -- `api/http/control-api` — подключаемый ASGI-адаптер для `GET /health`, `POST /runtime/start`, `POST /runtime/stop` и `GET /runtime/status`. +- `api/http/control-api` — подключаемый ASGI-адаптер для `GET /api/v1/health`, `POST /api/v1/runtime/start`, `POST /api/v1/runtime/stop` и `GET /api/v1/runtime/status`; приложение может передать ему собственные `HttpRoute` для той же маршрутизации. - `configuration/application-config-file` загружает типизированную конфигурацию приложения из корневого `config.yaml` и атомарно применяет корректные обновления без перезапуска. - `configuration/application-settings` предоставляет типизированный `SettingsReader` и PostgreSQL-адаптер для принадлежащей приложению таблицы `settings`. - `workflow/orchestration` выполняет именованные шаги по объявленным переходам и сохраняет снимки запуска и шагов через порт, реализуемый приложением. @@ -79,7 +79,7 @@ supervisor = WorkerSupervisor(workers, config_manager) runtime = ApplicationRuntime(runtime_context, supervisor) ``` -Приложение создаёт собственный HTTP host и подключает `ControlApi` к тому же listener. `RuntimeHealthInputProvider` связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с `HealthAggregator`. Приложение само запускает сервер и определяет, когда вызвать `runtime.start()` и `runtime.stop()`. +Приложение создаёт собственный HTTP host и подключает `ControlApi` к тому же listener. Встроенные endpoints PLBA и переданные через `application_routes` прикладные `HttpRoute` доступны через общий API; каждый путь начинается с `/api/v{version}/`. `RuntimeHealthInputProvider` связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с `HealthAggregator`. Приложение само запускает сервер и определяет, когда вызвать `runtime.start()` и `runtime.stop()`. Чтобы применять изменения конфигурации, запустите `config_manager.watch(...)` как задачу приложения и обработайте ошибки перезагрузки в переданном callback. Уже выданные снимки конфигурации остаются неизменными; при некорректном обновлении активным остаётся последний корректный снимок. diff --git a/docs/integration.md b/docs/integration.md index 293cdd8..9d0847b 100644 --- a/docs/integration.md +++ b/docs/integration.md @@ -12,10 +12,55 @@ Register `WorkerDefinition` objects in a `WorkerRegistry`, pass the registry and `ApplicationRuntime`. Register non-worker checks in `HealthContributorRegistry` and connect it to `HealthAggregator` with `RuntimeHealthInputProvider`. -Mount `ControlApi(runtime, health_aggregator)` in the application's ASGI host. -The host owns the socket and listener; the adapter contributes `/health`, -`/runtime/start`, `/runtime/stop`, and `/runtime/status` to that same listener. -The application chooses when to start and stop the runtime. +Register application endpoints as typed `HttpRoute` values when composing the +ASGI application. The built-in routes and application handlers share the same +`ControlApi` router and listener: + +```python +import json + +from plba.http import ControlApi, HttpRoute + + +async def get_order(scope, receive, send): + body = json.dumps({"order_id": scope["path_params"]["order_id"]}).encode() + await send( + { + "type": "http.response.start", + "status": 200, + "headers": [(b"content-type", b"application/json")], + } + ) + await send({"type": "http.response.body", "body": body}) + + +api = ControlApi( + runtime, + health_aggregator, + application_routes=( + HttpRoute("GET", "/api/v1/orders/{order_id}", get_order), + ), +) +``` + +The built-in API paths are: + +- `GET /api/v1/health` +- `POST /api/v1/runtime/start` +- `POST /api/v1/runtime/stop` +- `GET /api/v1/runtime/status` + +Application route templates must also start with `/api/v{version}/`, where +`{version}` is a positive integer such as `v1`. Named path segments are +available in `scope["path_params"]`, and the application handler owns its +response. + +For platform access, the public request path is +`/{service-name}/api/v{version}/...`. Caddy selects the service upstream and +removes `/{service-name}` before proxying, so the application receives the +internal `/api/v{version}/...` path. The application host still owns one +socket and listener; PLBA does not start a separate HTTP server. The +application chooses when to start and stop the runtime. ## Configuration and settings diff --git a/openspec/changes/versioned-extensible-http-api/.openspec.yaml b/openspec/changes/versioned-extensible-http-api/.openspec.yaml new file mode 100644 index 0000000..97fb4ad --- /dev/null +++ b/openspec/changes/versioned-extensible-http-api/.openspec.yaml @@ -0,0 +1,2 @@ +schema: use-case-driven +created: 2026-10-11 diff --git a/openspec/changes/versioned-extensible-http-api/design.md b/openspec/changes/versioned-extensible-http-api/design.md new file mode 100644 index 0000000..7fb0072 --- /dev/null +++ b/openspec/changes/versioned-extensible-http-api/design.md @@ -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. Выпустить новую версию пакета после обновления интеграций. Откат к предыдущей версии вернёт старые пути; интеграции на новые пути при таком откате потребуется вернуть к прежним путям одновременно с пакетом. diff --git a/openspec/changes/versioned-extensible-http-api/proposal.md b/openspec/changes/versioned-extensible-http-api/proposal.md new file mode 100644 index 0000000..15e79c6 --- /dev/null +++ b/openspec/changes/versioned-extensible-http-api/proposal.md @@ -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` до явного принятия владельцем решения. diff --git a/openspec/changes/versioned-extensible-http-api/specs/api/http/control-api/spec.md b/openspec/changes/versioned-extensible-http-api/specs/api/http/control-api/spec.md new file mode 100644 index 0000000..4936af5 --- /dev/null +++ b/openspec/changes/versioned-extensible-http-api/specs/api/http/control-api/spec.md @@ -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` | Обязательное | 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`. diff --git a/openspec/changes/versioned-extensible-http-api/tasks.md b/openspec/changes/versioned-extensible-http-api/tasks.md new file mode 100644 index 0000000..02c4eec --- /dev/null +++ b/openspec/changes/versioned-extensible-http-api/tasks.md @@ -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 `. diff --git a/openspec/config.yaml b/openspec/config.yaml index 95d1b50..9fb0945 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,43 +1,21 @@ -schema: function-driven +schema: use-case-driven context: | - Актуальные спецификации проекта находятся в openspec/specs/. - Старые документы spec/specs/ устарели и не подтверждают текущее поведение. - Capability имеет отдельную бизнес-функцию или понятный результат и живёт - в иерархии доменов, например orders/snapshot-sync. - Requirement описывает одну завершённую техническую функцию. - Формат требований определяется локальной схемой function-driven. - Включай только сведения, влияющие на наблюдаемое поведение, устойчивый - контракт или обязательное техническое ограничение; не добавляй повторы и - пояснительный текст без такого влияния. - Пиши по-русски весь пояснительный текст каждого изменения OpenSpec: - в proposal.md, design.md, specs/**/*.md и tasks.md. Сохраняй обязательные - заголовки и синтаксис OpenSpec, имена API, SQL-полей, кодов, файлов, - инструментов, команд и идентификаторы без перевода. + ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и + реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если + запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о + конфликте пользователю; не обходи решение молча. Новые ADR оформляй по + шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом + Proposed; не помечай решение Accepted без явного принятия владельцем решения. 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 . - proposal: - - Сохраняй полные иерархические пути capabilities. - - Пиши пояснительный текст proposal по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. - design: - - Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований. - - Пиши пояснительный текст design по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. tasks: - - Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты. - - Пиши названия групп и формулировки задач по-русски; сохраняй команды, пути, API, коды и идентификаторы без перевода. - - Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в pyproject.toml. Выполняй её после реализации и проверок; один change повышает версию ровно один раз. - - До версии 1.0.0 используй PATCH для исправлений, рефакторинга и документации; MINOR для новых возможностей и любых изменений публичного контракта, включая несовместимые. Переход на 1.0.0 означает начало стабильного публичного контракта. - - Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей и MAJOR для несовместимых изменений публичного контракта. + - >- + Завершай каждый реализуемый change отдельной последней задачей на + увеличение версии пакета в `pyproject.toml`; один change повышает версию + ровно один раз. До 1.0.0 используй PATCH для исправлений, рефакторинга и + документации, MINOR для новых возможностей и изменений публичного + контракта, в том числе несовместимых; переход на 1.0.0 начинает стабильный + публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений, + рефакторинга и документации, MINOR для обратно совместимых возможностей, + MAJOR для несовместимых изменений публичного контракта. diff --git a/openspec/context/adr/ADR-0001-api-path-naming-and-caddy-ingress-routing.md b/openspec/context/adr/ADR-0001-api-path-naming-and-caddy-ingress-routing.md new file mode 100644 index 0000000..273286a --- /dev/null +++ b/openspec/context/adr/ADR-0001-api-path-naming-and-caddy-ingress-routing.md @@ -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 из конфигурации. + +## Связанные решения + +- Нет. diff --git a/openspec/schemas/function-driven/capability-codes.md b/openspec/schemas/function-driven/capability-codes.md deleted file mode 100644 index 14c0c2f..0000000 --- a/openspec/schemas/function-driven/capability-codes.md +++ /dev/null @@ -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` | - diff --git a/openspec/schemas/function-driven/schema.yaml b/openspec/schemas/function-driven/schema.yaml deleted file mode 100644 index b5c88d5..0000000 --- a/openspec/schemas/function-driven/schema.yaml +++ /dev/null @@ -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//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 "" --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 ""` 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 "" --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 и локальный номер: .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-якоря вида . 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//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 . - - Не создавай 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 . Для неизменённых 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. diff --git a/openspec/schemas/function-driven/templates/main-spec.md b/openspec/schemas/function-driven/templates/main-spec.md deleted file mode 100644 index 7dd2f81..0000000 --- a/openspec/schemas/function-driven/templates/main-spec.md +++ /dev/null @@ -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. Явно отметь коды и тексты, которые ещё не реализованы.> - - - - - - diff --git a/openspec/schemas/function-driven/README.md b/openspec/schemas/use-case-driven/README.md similarity index 63% rename from openspec/schemas/function-driven/README.md rename to openspec/schemas/use-case-driven/README.md index f33b9fd..c739b1f 100644 --- a/openspec/schemas/function-driven/README.md +++ b/openspec/schemas/use-case-driven/README.md @@ -1,30 +1,36 @@ -# Схема function-driven +# Схема use-case-driven -Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на -`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`. -Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes -с явно указанной `schema: spec-driven` продолжают использовать свою схему; -их миграция не является частью изменения формата master spec. +`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на +`spec-driven`. Она задаёт workflow `proposal → specs / design → tasks`; +формат требований определён в `schema.yaml` и шаблонах. Существующие changes +с явно указанной `schema: spec-driven` продолжают использовать свою схему. ## Уровни спецификации - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. +- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности. - Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario. - Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы. - FR — подробные правила и контракты сообщений за пределами Scenario; контракт HTTP endpoint размещается в завершающем CONTRACT. -В спецификацию включаются только сведения, влияющие на наблюдаемое поведение, -устойчивый контракт или обязательное техническое ограничение. Повторы и -пояснения без такого влияния удаляются. +Requirements и FR включают только сведения, влияющие на наблюдаемое поведение, +устойчивый контракт или обязательное техническое ограничение. Раздел «Границы» +кратко фиксирует ответственность и владение capability, не повторяя Requirements. +Повторы и пояснения без такого влияния удаляются. -Для каждой capability зарегистрируй стабильный уникальный префикс в -[`capability-codes.md`](capability-codes.md). Его сегменты отражают путь -capability: например, `configuration/application-settings` получает `CFG.AS`. -ID Requirement имеет вид `CFG.AS-01`; его номер уникален внутри capability. -В сочетании с уникальным префиксом это даёт уникальный ID в проекте. -ID FR включает ID Requirement и локальный номер: `CFG.AS-01.FR-01`, -`CFG.AS-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement. +Составной префикс Requirement строится из сокращений сегментов пути capability: +для однословного сегмента используй первые три буквы, для сегмента с дефисами — +первые буквы его частей. Приводи сокращения к верхнему регистру. Например, +`domain/capability-name` получает `DOM.CN`. Если префикс уже занят, удлиняй +сокращения новых сегментов до уникальности; ранее назначенные префиксы не меняй. +Сохраняй префикс при переименовании capability. Валидатор проверяет уникальность +по ID в master specs и активных changes; отдельный реестр кодов не ведётся. + +ID Requirement имеет вид `AREA.CAP-01`; его номер уникален внутри capability. +Полный ID уникален в проекте благодаря уникальному префиксу и номеру. +ID FR включает ID Requirement и локальный номер: `AREA.CAP-01.FR-01`, +`AREA.CAP-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement. В новых и изменяемых Requirements используй составные ID. Неизменённые legacy specs могут сохранять прежние ID до отдельного рефакторинга. @@ -58,7 +64,7 @@ Markdown-рендерер автоматически создаёт якоря В Scenario «Назначение» опционально и добавляется только при наличии сведений, которых нет в заголовке. «Контекст» в Scenario отсутствует. Основной поток — нумерованные короткие шаги «Что делаем — как делаем», например: -«Получаем клиентов — вызываем GET /cp/users по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)». +«Получаем данные — вызываем GET /api/resources по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)». ## Форматы Use case @@ -124,12 +130,17 @@ FR, описывающий таблицу БД, оформляется по В response-таблице также указывается источник или правило формирования каждого поля. Другие паттерны добавляются отдельными файлами по мере появления потребности. -## Шаблоны и delta specs +## Форматы master и delta specs -- `templates/main-spec.md` — постоянная спецификация capability. -- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`. +- `templates/main-spec.md` — краткая схема постоянной master spec: Purpose, Границы и Requirements; это не артефакт change. +- `templates/spec.md` — полный шаблон delta для change, предоставляемый `openspec instructions specs`. - `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow. +В master spec раздел `## Границы` располагается между Purpose и Requirements. +Он описывает ответственность capability, её включённую область и явные +исключения или передачу ответственности другим capabilities и приложению. +В delta spec этот раздел не повторяется: delta меняет отдельные Requirements. + ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration, RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и @@ -140,12 +151,44 @@ Scenario в таких операциях не создаётся. В delta со фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes. Форматирование спецификации само по себе не реализует этот контракт в приложении. +## Архитектурные решения (ADR) + +Храни ADR проекта в `openspec/context/adr/` и называй файлы +`ADR-<номер>-<краткое-описание>.md`, например +`ADR-0001-use-postgresql.md`. Используй четырёхзначную последовательную +нумерацию: новый номер на единицу больше максимального номера в каталоге. +Номер не переиспользуется, даже если решение отклонено или заменено. Краткое +описание в имени файла пиши в `kebab-case`. + +Создавай ADR для долгосрочных архитектурных решений с последствиями для +будущих изменений: выбора между значимыми вариантами, общих ограничений, +границ компонентов и решений, которые иначе пришлось бы повторно принимать. +Не создавай ADR для каждого change, деталей реализации, уже полностью заданных +спецификацией, или временных задач. + +В ADR фиксируй контекст и проблему, факторы решения, рассмотренные варианты, +выбранное решение и его последствия. Используй статусы `Proposed`, `Accepted`, +`Rejected` и `Superseded`. Предложенный ADR становится действующим только после +явного принятия владельцем решения. Отклонённые и заменённые ADR сохраняй как +историю. Не меняй принятое решение задним числом: при пересмотре создай новый +ADR со ссылкой на заменяемый и обнови его статус на `Superseded`. В новом ADR +укажи заменяемый ID в `supersedes`, а в прежнем — новый ID в `superseded-by`. + +Перед проектированием и реализацией агент читает применимые принятые ADR. +Изменение должно ссылаться на относящиеся к нему ADR в `design.md`. При +противоречии между запросом и принятым ADR агент явно сообщает о конфликте и +получает решение пользователя, а не обходит ADR молча. Агент может подготовить +ADR со статусом `Proposed`, но не принимает его самостоятельно. + +Шаблон нового решения находится в +[`templates/adr.md`](templates/adr.md). + ## Проверки ```sh -openspec schema validate function-driven -openspec validate orders/snapshot-sync --type spec --strict --no-interactive -python3 openspec/schemas/function-driven/validate_format.py --require-qualified-ids openspec/specs/orders/snapshot-sync/spec.md +openspec schema validate use-case-driven +openspec validate domain/capability-name --type spec --strict --no-interactive +python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids openspec/specs/domain/capability-name/spec.md ``` Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`. @@ -158,7 +201,7 @@ python3 openspec/schemas/function-driven/validate_format.py --require-qualified- неизменённые legacy specs. Проверка охватывает один Scenario, обычную структуру use case или формат сокращенного use case, ссылки шагов на FR, форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков -в Scenario, ID из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки, +в Scenario, префиксы из ID master specs, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки, таблицу кодов и её связь с FR. Семантическую завершённость функции и понятность кода оценивает автор/reviewer. Схема требует от автора запускать обе проверки; автоматического hook в CLI нет. diff --git a/openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc b/openspec/schemas/use-case-driven/__pycache__/validate_format.cpython-312.pyc similarity index 100% rename from openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc rename to openspec/schemas/use-case-driven/__pycache__/validate_format.cpython-312.pyc diff --git a/openspec/schemas/function-driven/patterns/database-table.md b/openspec/schemas/use-case-driven/patterns/database-table.md similarity index 68% rename from openspec/schemas/function-driven/patterns/database-table.md rename to openspec/schemas/use-case-driven/patterns/database-table.md index cb0d5a9..9f78462 100644 --- a/openspec/schemas/function-driven/patterns/database-table.md +++ b/openspec/schemas/use-case-driven/patterns/database-table.md @@ -19,19 +19,17 @@ ## Пример ```markdown -##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings +##### AREA.CAP-01.FR-01 [DB]: Таблица хранения записей -Таблица `settings` создаётся в схеме приложения и содержит: +Таблица `example_records` создаётся в схеме приложения и содержит: | Поле | Тип | Ограничения и значение по умолчанию | Назначение | | --- | --- | --- | --- | | `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки | -| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения | -| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки | -| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки | -| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей | -| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении | -| `description` | `TEXT` | NULL | Пояснение к настройке | +| `external_id` | `VARCHAR(64)` | NOT NULL | Идентификатор записи во внешней системе | +| `status` | `VARCHAR(32)` | NOT NULL | Текущее состояние записи | +| `created_at` | `TIMESTAMP` | NOT NULL | Время создания записи | +| `updated_at` | `TIMESTAMP` | NULL | Время последнего изменения записи | -Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. +Индекс поддерживает выборку по `external_id` и `status`. Ограничение уникальности на `external_id` устанавливается, если внешняя система гарантирует его уникальность. ``` diff --git a/openspec/schemas/function-driven/patterns/message-contract.md b/openspec/schemas/use-case-driven/patterns/message-contract.md similarity index 100% rename from openspec/schemas/function-driven/patterns/message-contract.md rename to openspec/schemas/use-case-driven/patterns/message-contract.md diff --git a/openspec/schemas/use-case-driven/schema.yaml b/openspec/schemas/use-case-driven/schema.yaml new file mode 100644 index 0000000..f45f106 --- /dev/null +++ b/openspec/schemas/use-case-driven/schema.yaml @@ -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//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 "" --type spec --json --no-scenarios`. + Команда вернёт назначение capability и тексты требований, не загружая + целые файлы спецификаций. Добавляй `--store ""` к обеим командам + только для зарегистрированного отдельного хранилища и сохраняй + `--type spec`: если артефакт `change` и спецификация имеют одинаковое имя, + без этого параметра возникнет неоднозначность при выборе. Команда + `openspec list` без `--specs` показывает активные изменения (`changes`), + а не спецификации, поэтому не отражает уже описанное в проекте поведение. + Используй точный путь + существующей capability, не создавай похожее имя. + Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже + описано и что нужно изменить, прочитай каждую подходящую спецификацию + целиком, включая сценарии, командой `openspec show "" --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 и локальный номер: .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-якоря вида . Markdown генерирует + якоря из заголовков Requirement и FR. + - Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его + заголовка, например + [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID + используется и для ссылки внутри Requirement, и для ссылки на другой + Requirement. + - Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки. + - Сохраняй существующие ID. При изменении FR сохраняй его номер; + новые FR добавляй в конец. Порядок первого документа последовательный. + - Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие + сообщения/действия, если это часть контракта. Параметры сообщений + являются данными, а не скрытым значением кода. + - Если смысловой код спецификации отличается от текущего поведения системы, + явно опиши соответствие и статус реализации в FR. Не утверждай, + что новый код или текст уже возвращается приложением. + + Работа с OpenSpec: + - Создай specs//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 `. + - Не создавай 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 . Для неизменённых спецификаций + со старыми 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: | + Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их + выполненными по мере работы. Остановись, если столкнёшься с препятствием или + потребуется уточнение. diff --git a/openspec/schemas/use-case-driven/templates/adr.md b/openspec/schemas/use-case-driven/templates/adr.md new file mode 100644 index 0000000..abeb532 --- /dev/null +++ b/openspec/schemas/use-case-driven/templates/adr.md @@ -0,0 +1,36 @@ +--- +status: Proposed +date: YYYY-MM-DD +decision-makers: + - <имя или роль владельца решения> +supersedes: [] +superseded-by: +--- + +# ADR-<номер>: <Краткое название решения> + +## Контекст и проблема + +Какую проблему нужно решить и какие ограничения важны для выбора? + +## Факторы решения + +- <Требование или ограничение, влияющее на решение> + +## Рассмотренные варианты + +- **<Вариант>** — преимущества и недостатки. + +## Решение + +Какой вариант выбран и почему? Заполняется при принятии ADR; до этого раздел +может содержать предлагаемое решение. + +## Последствия + +- Положительные: <результаты и преимущества>. +- Отрицательные или компромиссы: <цена решения, ограничения, риски>. + +## Связанные решения + +- diff --git a/openspec/schemas/function-driven/templates/design.md b/openspec/schemas/use-case-driven/templates/design.md similarity index 100% rename from openspec/schemas/function-driven/templates/design.md rename to openspec/schemas/use-case-driven/templates/design.md diff --git a/openspec/schemas/use-case-driven/templates/main-spec.md b/openspec/schemas/use-case-driven/templates/main-spec.md new file mode 100644 index 0000000..45dd7b0 --- /dev/null +++ b/openspec/schemas/use-case-driven/templates/main-spec.md @@ -0,0 +1,16 @@ +# Capability: <название> + +## Purpose + +<Бизнес-функция capability и понятный результат, не менее 50 знаков.> + +## Границы + + + +## Requirements + + diff --git a/openspec/schemas/function-driven/templates/proposal.md b/openspec/schemas/use-case-driven/templates/proposal.md similarity index 100% rename from openspec/schemas/function-driven/templates/proposal.md rename to openspec/schemas/use-case-driven/templates/proposal.md diff --git a/openspec/schemas/function-driven/templates/spec.md b/openspec/schemas/use-case-driven/templates/spec.md similarity index 98% rename from openspec/schemas/function-driven/templates/spec.md rename to openspec/schemas/use-case-driven/templates/spec.md index 29d1784..9ffe135 100644 --- a/openspec/schemas/function-driven/templates/spec.md +++ b/openspec/schemas/use-case-driven/templates/spec.md @@ -101,7 +101,7 @@ HTTP status: <код и условие возврата>. diff --git a/openspec/schemas/function-driven/templates/tasks.md b/openspec/schemas/use-case-driven/templates/tasks.md similarity index 55% rename from openspec/schemas/function-driven/templates/tasks.md rename to openspec/schemas/use-case-driven/templates/tasks.md index 427379c..b9353ca 100644 --- a/openspec/schemas/function-driven/templates/tasks.md +++ b/openspec/schemas/use-case-driven/templates/tasks.md @@ -9,7 +9,3 @@ - [ ] 2.1 - [ ] 2.2 - -## 3. Обновление версии - -- [ ] 3.1 Последней задачей увеличь версию пакета в `pyproject.toml` по правилам `openspec/config.yaml` и проверь изменение скриптом `scripts/check_package_version.py`. diff --git a/openspec/schemas/function-driven/validate_format.py b/openspec/schemas/use-case-driven/validate_format.py similarity index 74% rename from openspec/schemas/function-driven/validate_format.py rename to openspec/schemas/use-case-driven/validate_format.py index 04115da..ed2bde4 100644 --- a/openspec/schemas/function-driven/validate_format.py +++ b/openspec/schemas/use-case-driven/validate_format.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 @@ -27,8 +27,6 @@ HTML_ANCHOR = re.compile(r"]*\bid\s*=", re.IGNORECASE) DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение") CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение") RESPONSE_CONTRACT_COLUMNS = (*CONTRACT_COLUMNS, "Формирование значения") -CAPABILITY_CODES_PATH = Path(__file__).with_name("capability-codes.md") -CAPABILITY_CODE_ROW = re.compile(r"^\|\s*`([^`]+)`\s*\|\s*`([^`]+)`\s*\|$") def plain_text(value: str) -> str: @@ -65,27 +63,165 @@ def parse_fr_reference(label: str) -> tuple[str | None, str] | None: return None -def load_capability_codes() -> tuple[dict[str, str], list[str]]: - codes: dict[str, str] = {} - errors: list[str] = [] - try: - lines = CAPABILITY_CODES_PATH.read_text(encoding="utf-8").splitlines() - except OSError as error: - return {}, [f"не удалось прочитать реестр capability codes: {error}"] +def openspec_root_for(path: Path) -> Path: + """Find the OpenSpec root containing a master or change spec.""" + resolved = path.resolve() + for parent in (resolved, *resolved.parents): + if parent.name == "openspec": + return parent + return (Path.cwd() / "openspec").resolve() - prefixes: dict[str, str] = {} - for line in lines: - match = CAPABILITY_CODE_ROW.match(line) - if not match: + +def load_capability_prefixes(openspec_root: Path) -> tuple[dict[str, str], list[str]]: + """Read the active path-to-prefix mapping from master specs.""" + specs_root = openspec_root / "specs" + spec_paths = set(specs_root.rglob("spec.md")) + prefixes_by_capability: dict[str, set[str]] = {} + errors: list[str] = [] + for spec_path in sorted(spec_paths): + capability_path = spec_path.parent.relative_to(specs_root).as_posix() + try: + ids = REQUIREMENT_ID.findall(spec_path.read_text(encoding="utf-8")) + except OSError as error: + errors.append(f"не удалось прочитать спецификацию {spec_path}: {error}") continue - capability_path, prefix = match.groups() - if capability_path in codes: - errors.append(f"путь capability повторяется в реестре: {capability_path}") - if prefix in prefixes: - errors.append(f"префикс {prefix} повторяется для {prefixes[prefix]} и {capability_path}") - codes[capability_path] = prefix - prefixes[prefix] = capability_path - return codes, errors + prefixes = { + requirement_id.rsplit("-", 1)[0] + for requirement_id in ids + if "." in requirement_id + } + if prefixes: + prefixes_by_capability.setdefault(capability_path, set()).update(prefixes) + + prefix_owners: dict[str, set[str]] = {} + mappings: dict[str, str] = {} + for capability_path, prefixes in prefixes_by_capability.items(): + if len(prefixes) != 1: + errors.append( + f"capability {capability_path} использует несколько префиксов: " + f"{', '.join(sorted(prefixes))}" + ) + continue + prefix = next(iter(prefixes)) + mappings[capability_path] = prefix + prefix_owners.setdefault(prefix, set()).add(capability_path) + + for prefix, owners in prefix_owners.items(): + if len(owners) > 1: + errors.append( + f"префикс {prefix} используется несколькими capabilities: " + f"{', '.join(sorted(owners))}" + ) + return mappings, errors + + +def load_active_change_prefixes( + openspec_root: Path, + exclude_path: Path, +) -> dict[str, set[str]]: + """Read prefixes declared by other in-flight changes.""" + changes_root = openspec_root / "changes" + excluded = exclude_path.resolve() + prefixes_by_capability: dict[str, set[str]] = {} + if not changes_root.is_dir(): + return prefixes_by_capability + + for change_dir in changes_root.iterdir(): + if not change_dir.is_dir() or change_dir.name == "archive": + continue + for spec_path in change_dir.rglob("spec.md"): + if spec_path.resolve() == excluded: + continue + capability_path = spec_capability_path(spec_path) + if not capability_path: + continue + try: + ids = REQUIREMENT_ID.findall(spec_path.read_text(encoding="utf-8")) + except OSError: + continue + prefixes = { + requirement_id.rsplit("-", 1)[0] + for requirement_id in ids + if "." in requirement_id + } + if prefixes: + prefixes_by_capability.setdefault(capability_path, set()).update(prefixes) + return prefixes_by_capability + + +def check_capability_ids( + path: Path, + requirement_ids: list[str], + known_prefixes: dict[str, str], + base: Path | None = None, +) -> list[str]: + """Check that a spec uses one stable, project-unique capability prefix.""" + prefixes = { + requirement_id.rsplit("-", 1)[0] + for requirement_id in requirement_ids + if "." in requirement_id + } + if not prefixes: + return [] + + capability_path = spec_capability_path(path) + if not capability_path: + return ["по пути файла не удалось определить capability для составного Requirement ID"] + + errors: list[str] = [] + if len(prefixes) > 1: + errors.append( + f"capability {capability_path} использует несколько префиксов: " + f"{', '.join(sorted(prefixes))}" + ) + + base_capability_path = spec_capability_path(base) if base else None + owners_by_prefix: dict[str, set[str]] = {} + for known_path, known_prefix in known_prefixes.items(): + owners_by_prefix.setdefault(known_prefix, set()).add(known_path) + + expected_prefix = known_prefixes.get(capability_path) + if expected_prefix is None and base_capability_path: + expected_prefix = known_prefixes.get(base_capability_path) + active_change_prefixes: dict[str, set[str]] = {} + if is_change_spec(path): + active_change_prefixes = load_active_change_prefixes( + openspec_root_for(path), path + ) + + for prefix in prefixes: + if expected_prefix and prefix != expected_prefix: + errors.append( + f"ID использует префикс {prefix}, но для capability {capability_path} " + f"уже назначен {expected_prefix}" + ) + owners = owners_by_prefix.get(prefix, set()) + if owners and capability_path not in owners and base_capability_path not in owners: + errors.append( + f"префикс {prefix} уже используется capability " + f"{', '.join(sorted(owners))}" + ) + for active_path, active_prefixes in active_change_prefixes.items(): + if active_path == capability_path and len(active_prefixes) > 1: + errors.append( + f"активные changes для capability {capability_path} используют " + f"несколько префиксов: {', '.join(sorted(active_prefixes))}" + ) + if active_path == capability_path and prefix not in active_prefixes: + errors.append( + f"change для capability {capability_path} использует другой префикс: " + f"{', '.join(sorted(active_prefixes))}" + ) + elif ( + prefix in active_prefixes + and active_path != capability_path + and active_path != base_capability_path + ): + errors.append( + f"префикс {prefix} уже используется активным change " + f"для capability {active_path}" + ) + return errors def spec_capability_path(path: Path) -> str | None: @@ -97,6 +233,13 @@ def spec_capability_path(path: Path) -> str | None: return "/".join(capability_parts) if capability_parts else None +def is_change_spec(path: Path) -> bool: + parts = path.parts + changes_indexes = [index for index, part in enumerate(parts) if part == "changes"] + specs_indexes = [index for index, part in enumerate(parts) if part == "specs"] + return bool(changes_indexes and specs_indexes and specs_indexes[-1] > changes_indexes[-1]) + + def heading_targets(text: str) -> tuple[set[str], dict[str, tuple[str, str]]]: """Return generated heading fragments and fragments that target FR headings.""" targets: set[str] = set() @@ -258,7 +401,7 @@ def check_requirement( requirement_id = ids[0] is_qualified = "." in requirement_id if require_qualified_ids and not is_qualified: - errors.append("новый или изменённый Requirement должен иметь составной ID capability, например CFG.AS-01") + errors.append("новый или изменённый Requirement должен иметь составной ID capability, например AREA.CAP-01") level_four = re.findall(r"^#### (.+)$", block, re.MULTILINE) has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT" expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"] @@ -423,7 +566,8 @@ def validate( path: Path, base: Path | None = None, require_qualified_ids: bool = False, - capability_codes: dict[str, str] | None = None, + capability_prefixes: dict[str, str] | None = None, + capability_inventory_errors: list[str] | None = None, ) -> list[str]: text = path.read_text(encoding="utf-8") if HTML_ANCHOR.search(text): @@ -435,23 +579,17 @@ def validate( targets.update(base_targets) fr_targets.update(base_fr_targets) - errors = [] - if capability_codes is None: - capability_codes, registry_errors = load_capability_codes() - errors.extend(registry_errors) + errors = list(capability_inventory_errors or []) + if capability_prefixes is None: + capability_prefixes, inventory_errors = load_capability_prefixes( + openspec_root_for(path) + ) + errors.extend(inventory_errors) blocks = list(requirement_blocks(text)) ids = REQUIREMENT_ID.findall(text) if len(ids) != len(set(ids)): errors.append("повторяющиеся ID Requirements") - capability_path = spec_capability_path(path) - for requirement_id in ids: - if "." not in requirement_id: - continue - prefix = capability_codes.get(capability_path or "") - if not prefix: - errors.append(f"для capability {capability_path or '<не определена>'} нет префикса в capability-codes.md") - elif not re.fullmatch(rf"{re.escape(prefix)}-\d{{2,}}", requirement_id): - errors.append(f"ID {requirement_id} не соответствует префиксу {prefix} для {capability_path}") + errors.extend(check_capability_ids(path, ids, capability_prefixes, base)) if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE): errors.append("нет Requirements") for name, block in blocks: @@ -472,14 +610,27 @@ def main() -> int: paths = sorted({file for path in args.paths for file in (path.rglob("spec.md") if path.is_dir() else [path])}) if not paths: parser.error("не найдены spec.md") - capability_codes, registry_errors = load_capability_codes() + prefix_cache: dict[Path, tuple[dict[str, str], list[str]]] = {} + reported_roots: set[Path] = set() failed = False - for error in registry_errors: - print(f"ERROR {CAPABILITY_CODES_PATH}: {error}") - failed = True for path in paths: try: - errors = validate(path, args.base, args.require_qualified_ids, capability_codes) + openspec_root = openspec_root_for(path) + if openspec_root not in prefix_cache: + prefix_cache[openspec_root] = load_capability_prefixes(openspec_root) + capability_prefixes, inventory_errors = prefix_cache[openspec_root] + reported_inventory_errors = ( + inventory_errors if openspec_root not in reported_roots else [] + ) + errors = validate( + path, + args.base, + args.require_qualified_ids, + capability_prefixes, + reported_inventory_errors, + ) + if reported_inventory_errors: + reported_roots.add(openspec_root) except OSError as error: errors = [str(error)] for error in errors: diff --git a/pyproject.toml b/pyproject.toml index 94046d7..b0b8153 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "plba-v2" -version = "0.1.1" +version = "0.2.0" description = "Portable application lifecycle and observability components" readme = "README.md" requires-python = ">=3.11" diff --git a/src/plba/http/__init__.py b/src/plba/http/__init__.py index b8a44f6..d9a9e01 100644 --- a/src/plba/http/__init__.py +++ b/src/plba/http/__init__.py @@ -1,3 +1,4 @@ from plba.http.control_api import ControlApi +from plba.http.routes import HttpRoute -__all__ = ["ControlApi"] +__all__ = ["ControlApi", "HttpRoute"] diff --git a/src/plba/http/control_api.py b/src/plba/http/control_api.py index c941726..355de57 100644 --- a/src/plba/http/control_api.py +++ b/src/plba/http/control_api.py @@ -1,32 +1,98 @@ +from collections.abc import Awaitable, Callable, Sequence from typing import Any from plba.health.aggregator import HealthAggregator, HealthInputInvalid from plba.http.asgi import ASGIHttpTransport from plba.http.errors import ControlRequestError from plba.http.requests import StopRequest +from plba.http.routes import ( + ASGIScope, + ASGIReceive, + ASGISend, + HttpRoute, + HttpRouter, + MethodNotAllowed, + RouteNotFound, +) from plba.http.serialization import health_report_payload from plba.runtime.application import ApplicationRuntime, RuntimeLifecycleError +_ControlAction = Callable[ + [ASGIScope, ASGIReceive], Awaitable[tuple[int, dict[str, Any]]] +] + class ControlApi: """ASGI route adapter; it owns no server, socket, or listener.""" def __init__( - self, runtime: ApplicationRuntime, health_aggregator: HealthAggregator + self, + runtime: ApplicationRuntime, + health_aggregator: HealthAggregator, + application_routes: Sequence[HttpRoute] = (), ) -> None: self._runtime = runtime self._health_aggregator = health_aggregator self._transport = ASGIHttpTransport() + routes = ( + HttpRoute("GET", "/api/v1/health", self._handle_health), + HttpRoute("POST", "/api/v1/runtime/start", self._handle_start), + HttpRoute("POST", "/api/v1/runtime/stop", self._handle_stop), + HttpRoute("GET", "/api/v1/runtime/status", self._handle_status), + *application_routes, + ) + self._router = HttpRouter(routes) - async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None: + async def __call__(self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend) -> None: scope_type = scope.get("type") if scope_type == "lifespan": await self._transport.handle_lifespan(receive, send) return if scope_type != "http": return + try: - status, payload = await self._dispatch(scope, receive) + match = self._router.resolve(scope.get("method", ""), scope.get("path", "")) + except RouteNotFound: + await self._send_routing_error(send, 404, "HTTP_ROUTE_NOT_FOUND") + return + except MethodNotAllowed: + await self._send_routing_error(send, 405, "HTTP_METHOD_NOT_ALLOWED") + return + + route_scope = dict(scope) + route_scope["path_params"] = match.path_params + await match.route.handler(route_scope, receive, send) + + async def _handle_health( + self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend + ) -> None: + await self._execute_control_action(self._health_action, scope, receive, send) + + async def _handle_start( + self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend + ) -> None: + await self._execute_control_action(self._start_action, scope, receive, send) + + async def _handle_stop( + self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend + ) -> None: + await self._execute_control_action(self._stop_action, scope, receive, send) + + async def _handle_status( + self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend + ) -> None: + await self._execute_control_action(self._status_action, scope, receive, send) + + async def _execute_control_action( + self, + action: _ControlAction, + scope: ASGIScope, + receive: ASGIReceive, + send: ASGISend, + ) -> None: + try: + status, payload = await action(scope, receive) except HealthInputInvalid as error: status, payload = 500, self._error("HEALTH_INPUT_INVALID", error) except RuntimeLifecycleError as error: @@ -37,45 +103,54 @@ class ControlApi: status, payload = 500, self._error("CONTROL_API_FAILED", error) await self._transport.send_json(send, status, payload) - async def _dispatch(self, scope: dict[str, Any], receive: Any) -> tuple[int, dict[str, Any]]: - method = scope.get("method", "").upper() - path = scope.get("path", "") - query = scope.get("query_string", b"") - if path in {"/health", "/runtime/status", "/runtime/start", "/runtime/stop"} and query: - raise ControlRequestError("query parameters are not accepted") - if path == "/health": - if method != "GET": - return 405, self._error("METHOD_NOT_ALLOWED", "GET required") - await self._require_empty_body(receive) - report = await self._health_aggregator.aggregate() - return 200, health_report_payload(report) - if path == "/runtime/start": - if method != "POST": - return 405, self._error("METHOD_NOT_ALLOWED", "POST required") - await self._require_empty_body(receive) - result = await self._runtime.start() - return 200, {"status": result.lifecycle.value} - if path == "/runtime/status": - if method != "GET": - return 405, self._error("METHOD_NOT_ALLOWED", "GET required") - await self._require_empty_body(receive) - return 200, {"status": self._runtime.lifecycle.value} - if path == "/runtime/stop": - if method != "POST": - return 405, self._error("METHOD_NOT_ALLOWED", "POST required") - request = StopRequest.parse(await self._transport.read_body(receive)) - result = await self._runtime.stop( - force=request.force, timeout_seconds=request.timeout_seconds - ) - status_code = 200 if result.lifecycle.value == "stopped" else 202 - return status_code, {"status": result.lifecycle.value} - return 404, self._error("NOT_FOUND", "control route not found") + async def _health_action( + self, scope: ASGIScope, receive: ASGIReceive + ) -> tuple[int, dict[str, Any]]: + self._require_no_query(scope) + await self._require_empty_body(receive) + report = await self._health_aggregator.aggregate() + return 200, health_report_payload(report) - async def _require_empty_body(self, receive: Any) -> None: + async def _start_action( + self, scope: ASGIScope, receive: ASGIReceive + ) -> tuple[int, dict[str, Any]]: + self._require_no_query(scope) + await self._require_empty_body(receive) + result = await self._runtime.start() + return 200, {"status": result.lifecycle.value} + + async def _stop_action( + self, scope: ASGIScope, receive: ASGIReceive + ) -> tuple[int, dict[str, Any]]: + self._require_no_query(scope) + request = StopRequest.parse(await self._transport.read_body(receive)) + result = await self._runtime.stop( + force=request.force, timeout_seconds=request.timeout_seconds + ) + status = 200 if result.lifecycle.value == "stopped" else 202 + return status, {"status": result.lifecycle.value} + + async def _status_action( + self, scope: ASGIScope, receive: ASGIReceive + ) -> tuple[int, dict[str, Any]]: + self._require_no_query(scope) + await self._require_empty_body(receive) + return 200, {"status": self._runtime.lifecycle.value} + + async def _require_empty_body(self, receive: ASGIReceive) -> None: if await self._transport.read_body(receive): raise ControlRequestError("request body is not accepted") + @staticmethod + def _require_no_query(scope: ASGIScope) -> None: + if scope.get("query_string", b""): + raise ControlRequestError("query parameters are not accepted") + + async def _send_routing_error( + self, send: ASGISend, status: int, code: str + ) -> None: + await self._transport.send_json(send, status, self._error(code, code)) + @staticmethod def _error(code: str, error: Exception | str) -> dict[str, str]: return {"error": code, "message": str(error)} - diff --git a/src/plba/http/routes.py b/src/plba/http/routes.py new file mode 100644 index 0000000..d5d1e71 --- /dev/null +++ b/src/plba/http/routes.py @@ -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) + ) diff --git a/tests/test_health_http.py b/tests/test_health_http.py index 7c35f76..55dc724 100644 --- a/tests/test_health_http.py +++ b/tests/test_health_http.py @@ -12,7 +12,7 @@ from plba.health import ( HealthContributorRegistry, RuntimeHealthInputProvider, ) -from plba.http import ControlApi +from plba.http import ControlApi, HttpRoute from plba.runtime import ApplicationLifecycle, ApplicationRuntime, RuntimeContext from plba.runtime.worker import ( ComponentHealth, @@ -126,33 +126,65 @@ class ControlApiTests(unittest.IsolatedAsyncioTestCase): provider = RuntimeHealthInputProvider( self.runtime, self.supervisor, HealthContributorRegistry() ) - self.api = ControlApi(self.runtime, HealthAggregator(provider)) + self.health_aggregator = HealthAggregator(provider) + self.api = ControlApi(self.runtime, self.health_aggregator) async def test_status_start_health_and_stop_routes(self) -> None: - status = await self.request("GET", "/runtime/status") + status = await self.request("GET", "/api/v1/runtime/status") self.assertEqual(status[0], 200) self.assertEqual(status[1], {"status": "new"}) - started = await self.request("POST", "/runtime/start") + started = await self.request("POST", "/api/v1/runtime/start") self.assertEqual(started[0], 200) self.assertEqual(started[1], {"status": "running"}) - health = await self.request("GET", "/health") + health = await self.request("GET", "/api/v1/health") self.assertEqual(health[0], 200) self.assertEqual(health[1]["application_id"], "service-http") self.assertEqual(health[1]["status"], "ok") - stopped = await self.request("POST", "/runtime/stop", b"{}") + stopped = await self.request("POST", "/api/v1/runtime/stop", b"{}") self.assertEqual(stopped, (200, {"status": "stopped"})) + async def test_application_route_uses_control_api_and_receives_path_params(self) -> None: + async def get_item(scope, receive, send) -> None: + body = json.dumps({"item_id": scope["path_params"]["item_id"]}).encode() + await send( + { + "type": "http.response.start", + "status": 200, + "headers": [(b"content-type", b"application/json")], + } + ) + await send({"type": "http.response.body", "body": body}) + + self.api = ControlApi( + self.runtime, + self.health_aggregator, + (HttpRoute("GET", "/api/v1/items/{item_id}", get_item),), + ) + + response = await self.request("GET", "/api/v1/items/sku-42") + + self.assertEqual(response, (200, {"item_id": "sku-42"})) + + async def test_router_errors_use_versioned_api_codes(self) -> None: + missing = await self.request("GET", "/api/v1/missing") + method_not_allowed = await self.request("POST", "/api/v1/health") + + self.assertEqual(missing[0], 404) + self.assertEqual(missing[1]["error"], "HTTP_ROUTE_NOT_FOUND") + self.assertEqual(method_not_allowed[0], 405) + self.assertEqual(method_not_allowed[1]["error"], "HTTP_METHOD_NOT_ALLOWED") + async def test_invalid_stop_request_is_http_400(self) -> None: - missing = await self.request("POST", "/runtime/stop") - malformed = await self.request("POST", "/runtime/stop", b"not-json") + missing = await self.request("POST", "/api/v1/runtime/stop") + malformed = await self.request("POST", "/api/v1/runtime/stop", b"not-json") invalid_timeout = await self.request( - "POST", "/runtime/stop", b'{"timeout_seconds": 0}' + "POST", "/api/v1/runtime/stop", b'{"timeout_seconds": 0}' ) null_timeout = await self.request( - "POST", "/runtime/stop", b'{"timeout_seconds": null}' + "POST", "/api/v1/runtime/stop", b'{"timeout_seconds": null}' ) self.assertEqual(missing[0], 400) @@ -178,12 +210,13 @@ class ControlApiTests(unittest.IsolatedAsyncioTestCase): provider = RuntimeHealthInputProvider( self.runtime, self.supervisor, HealthContributorRegistry() ) - self.api = ControlApi(self.runtime, HealthAggregator(provider)) + self.health_aggregator = HealthAggregator(provider) + self.api = ControlApi(self.runtime, self.health_aggregator) await self.runtime.start() await asyncio.wait_for(active.wait(), timeout=1) result = await self.request( - "POST", "/runtime/stop", b'{"timeout_seconds": 0.01}' + "POST", "/api/v1/runtime/stop", b'{"timeout_seconds": 0.01}' ) self.assertEqual(result, (202, {"status": "stopping"})) diff --git a/tests/test_http_routes.py b/tests/test_http_routes.py new file mode 100644 index 0000000..442c262 --- /dev/null +++ b/tests/test_http_routes.py @@ -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()