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

4.9 KiB
Raw Permalink Blame History

status, date, decision-makers, supersedes, superseded-by
status date decision-makers supersedes superseded-by
Proposed 2026-10-11
Владелец проекта
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 из конфигурации.

Связанные решения

  • Нет.