Конфигурация

Полный справочник по всем секциям и полям, которые читает код api-gateway. Для каждого поля указаны тип, значение по умолчанию, допустимые значения и короткий пример. Значения по умолчанию применяются, когда ключ не задан в YAML; явно заданные значения имеют приоритет.

Общая структура

Конфиг — один YAML-файл. Путь задаётся флагом -config (по умолчанию /etc/proxy/config.yaml). Секции верхнего уровня:

Длительности записываются строками Go duration: 500ms, 5s, 5m, 1h.

Переменные, флаги и сигналы

Подстановка ${VAR}. Перед разбором YAML шлюз раскрывает ${VAR} и $VAR из окружения. Если переменная не задана или пуста, литерал ${VAR} остаётся в тексте как есть — конфиг не «молча» подставит пустоту.

jwt:
  secret_key: "${JWT_SECRET}"
permissions:
  service_url: "${PERMISSIONS_URL}"

Переменные окружения. Их читает не конфиг, а сам процесс:

Флаги. -config <path> — путь к файлу конфигурации.

Сигналы. SIGHUP перечитывает конфиг и применяет его атомарно (старое состояние сохраняется при ошибке). SIGINT и SIGTERM запускают graceful shutdown с таймаутом 30 секунд.

Неизвестные ключи. Ключи, которых нет в структуре конфига, не считаются ошибкой: шлюз пишет в лог предупреждение Unknown config key с точечным путём (например headers.forward_headers). Строгий режим намеренно не включён.

application

Общие настройки процесса.

Метрики выключены по умолчанию, потому что их сбор добавляет работу на каждый запрос. Включайте metrics_enabled осознанно; metrics_allowed_ips ограничивает доступ к /metrics, если эндпоинт смотрит наружу.

server

HTTP-сервер.

Семантика max_request_body_size. Различаются «ключ не задан» и «явный ноль»: не задан — 10 MiB, 0 — без ограничения, положительное число — точный лимит. Тот же лимит применяется к чтению тела для аудита, чтобы вебхуки не вычитывали тело неограниченно.

tls

HTTPS с автоматическими сертификатами Let's Encrypt (ACME).

При включённом TLS запускаются два сервера: HTTPS на port и HTTP на http_port для ACME-challenge и редиректа. staging: true использует реальный staging CA и отдельный подкаталог кеша, чтобы staging-сертификаты не смешивались с production.

static

Раздача статики и SPA-приложений. Обрабатывается до проксирования, но после глобального лимита.

Поля элемента apps:

static:
  skip_prefixes: ["/api"]
  apps:
    - path_prefix: "/"
      root_dir: "/app/static"
      index_file: "index.html"
      max_age: 3600

Если маршрут совпадает с правилом, у которого задан Host, статика пропускается — так host-based роутинг работает при смонтированной статике. Для несуществующих путей отдаётся index_file (SPA fallback); поддерживаются и плоские .html-файлы (about.html для /about).

targets

Список бэкендов. Имя и URL обязательны; имена уникальны.

Семантика weight. Таргеты, чьи правила совпадают по (host, path_prefix, methods), образуют один пул и распределяются взвешенным round-robin по здоровым кандидатам. Отсутствие ключа weight — это вес 1, а явный weight: 0 (или отрицательный) исключает таргет из выбора. Различайте эти два случая.

jwt

Проверка JWT. Токен берётся из Authorization: Bearer … или из cookie cml_access.

Глобальный required перекрывается настройкой маршрута auth.required. Предъявленный токен всегда проверяется криптографически: на маршруте без требования невалидный токен игнорируется (запрос идёт как анонимный), на требующем — возвращается 401.

basic_auth

Basic Auth для служебных путей. Проверка — constant-time по SHA-256 от логина и пароля.

Basic Auth стоит во внешнем слое цепочки и защищает всё, включая /metrics и статику, кроме skip_paths. При успехе заголовок Authorization удаляется перед проксированием.

logging

Неверный format не «молча» превращается в консоль: загрузка конфига завершается ошибкой logging.format must be one of console, text, json.

headers

Поля cors:

headers:
  strip_authorization: true
  claim_to_header:
    id: "X-User-ID"
    roles: "X-User-Roles"
  add_headers:
    X-Gateway-Version: "1.0.0"
  sign_header: "X-User-Signature"
  cors:
    enabled: true
    allowed_origins: ["https://app.example"]
    max_age: 86400

Правила CORS: при точном совпадении origin он отражается и выставляется Access-Control-Allow-Credentials; при * возвращается * без credentials; не попавший в allowlist origin CORS-заголовков не получает. Любой OPTIONS обрабатывается как preflight и возвращает 200. В env: "dev" при отсутствии секции cors включается мягкий режим с отражением origin.

sign_header вычисляется только если заданы и sign_header, и permissions.api_key, и в токене есть claim id.

routing

Поля правила rules[]:

auth: required (bool, по умолчанию наследует глобальный jwt.required), roles ([]string, должны присутствовать все), strip_token (bool, наследует headers.strip_authorization).

rate_limit: requests_per_second (float, token bucket), burst (int). global_limit имеет те же поля, но применяется ко всем запросам процесса, а не на IP.

routing:
  global_limit:
    requests_per_second: 1000
    burst: 2000
  rules:
    - path_prefix: "/api"
      target_name: "api"
      strip_path: true
      auth:
        required: true
        roles: ["user"]
      rate_limit:
        requests_per_second: 50
        burst: 100

Выбирается правило с самым длинным совпадающим path_prefix среди тех, у кого совпали host и methods. Если ничего не совпало — 404. Правила, совпадающие по (host, path_prefix, methods), делят один пул балансировки и обязаны совпадать по auth, strip_path и rate_limit, иначе запуск завершается ошибкой.

permissions

Интеграция с внешним permission-сервисом. Требует JWT с claim id, приводимым к целому.

Заголовок выставляется, только если у пользователя есть непустой список разрешений. Инвалидация: POST /_cache/permissions/invalidate с заголовком X-Invalidate-Token; параметр user_id инвалидирует одного пользователя, без него — весь кеш.

webhooks

Публикация событий на каждый запрос или ответ. Транспорты — HTTP webhook и NATS.

Событие содержит method, path, query, user_id, user_email, user_roles, request_id, status_code, timestamp, changes и response_body. Батчинг (batch_size > 1) шлёт один POST с телом {"count":N,"events":[...]}. Очередь батчера ограничена (8192 события); при переполнении постановка блокируется — события не теряются, но запросы замедляются (backpressure). Соединение NATS устанавливается по nats_url первого вебхука, поэтому у всех NATS-вебхуков URL должен совпадать.

discovery

Обнаружение бэкендов по labels контейнеров Docker/Podman. Обнаруженные таргеты и правила дополняют статические; при конфликте имени таргета побеждает статика. Если обнаруженный сервис описывает тот же маршрут (host, path_prefix, methods), он попадает в общий пул с статикой.

Если discovery.enabled: true, статические targets и routing.rules можно не заполнять. При включённом discovery достаточно даже пустой секции discovery: { enabled: true } — остальные поля подставятся.

Аварийный фолбэк. Последний удачный результат discovery атомарно пишется в state_file и применяется при старте, поэтому маршруты переживают рестарт при недоступном Docker/Podman. Каталог state_file должен быть writable (смонтируйте volume). Ограничение: первый холодный старт без файла состояния и с недоступным Docker останется без обнаруженных маршрутов.

Labels

Маркер контейнера — gateway.enable: "true" (принимаются true/1/yes, регистр не важен).

Роутеры задаются коротко (gateway.<field> → роутер default) или именованно (gateway.router.<id>.<field>): host, path_prefix, methods, strip_path, auth.required, auth.roles, auth.strip_token, rate_limit.rps, rate_limit.burst. Роутер без host и path_prefix пропускается.

Поведение и оговорки

• Порядок middleware. Снаружи внутрь: инвалидация кеша permissions, Basic Auth, recovery, request id, tracing, метрики активных запросов, /metrics, глобальный лимит, статика, CORS-preflight, проксирование. Поэтому Basic Auth защищает и /metrics, и статику.
• Рейт-лимиты. Per-route лимит — token bucket на IP клиента; IP берётся из последнего непустого значения X-Forwarded-For, иначе из RemoteAddr. Глобальный лимит — один на процесс. Per-route отдаёт 429 без Retry-After; глобальный — 429 с Retry-After: 1. Лимитеры по IP очищаются после часа простоя.
• Access log. Выключен по умолчанию: каждая запись — это аллокации на горячем пути. Включайте для отладки, а не в проде под нагрузкой.
• Тело запроса для аудита. Читается только для POST, PUT, PATCH, QUERY и ограничено max_request_body_size; в событие попадает только JSON-объект короче 64 KiB.
• Метрики. /metrics в формате expvar; при metrics_allowed_ips доступ ограничен по IP.