Files
plba_v2/openspec/context/adr/ADR-0001-api-path-naming-and-caddy-ingress-routing.md
alex d46993a092
PLBA package CI / Python tests (push) Successful in 23s
PLBA package CI / Package version increment (push) Skipped
PLBA2-4. Доработка регистрации http эндпоинтов
2026-10-11 10:44:59 +03:00

56 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 из конфигурации.
## Связанные решения
- Нет.