PLBA2-4. Доработка регистрации http эндпоинтов
PLBA package CI / Python tests (push) Successful in 23s
PLBA package CI / Package version increment (push) Skipped

This commit is contained in:
2026-10-11 10:44:59 +03:00
parent a0d2db6bd0
commit d46993a092
30 changed files with 1666 additions and 583 deletions
@@ -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 из конфигурации.
## Связанные решения
- Нет.