Плагіни і middleware в API Gateway

1) Навіщо потрібні плагіни і middleware

• стандартизує безпеку (authN/authZ, WAF, CORS),
• захищає стійкість (rate limit, circuit breaker, retry-policies),
• управляє контрактом (валідація схем, трансформації),
• дає спостережуваність (метрики, логи, трасування),
• знижує вартість (кешування, дедуплікація, канарські правила).

Ключ: мінімальна латентність і чітка послідовність застосування.

2) Класи плагінів і що вони роблять

1. Ідентифікація/автентифікація

JWT/JWKS-провайдери, OAuth2/OIDC, API-ключі, mTLS (client cert).
HMAC-підписи (вебхуки/партнери), DPoP/PoP на краю.

2. Авторизація

RBAC/ABAC/OPA/Cedar (PDP) з локальним кешем рішень.
BOLA-guard: перевірка'tenant '/' owner'в заголовках/контексті.

3. Мережеві та протокольні захисту

WAF (OWASP CRS), антибот (rate/behavioral), Geo/IP/ASN-фільтри, TLS-профілі.
CORS, CSP-заголовки, Fetch-Metadata фільтри, CORP/COOP/COEP.

4. Стійкість

Rate limiting (token bucket/GCRA), квоти і конкурентність.
Circuit breaker, таймаути, adaptive concurrency, load shedding.
Retry-policy з per-try timeout і джитером.

5. Трансформації та валідація

Перепис шляхів/заголовків, body-rewrite, JSON/XML ↔, gRPC ↔ HTTP.
Валідація схем (OpenAPI/JSON Schema/Protobuf), нормалізація ID.

6. Кешування та продуктивність

Response/fragment cache, ETag/If-None-Match, компресія, brotli.
Request collapsing (coalescing) для однакових ключів.

7. Спостережуваність і аудит

Метрики RED/USE, логування рішень (429/403/5xx), трасування (W3C Trace-Context/OpenTelemetry), семплінг (tail/adaptive).
Аудит заголовків безпеки і версій політик.

8. Життєвий цикл та експлуатація

Canary/blue-green, feature-flags, shadow-рішення (логувати, не застосовувати), міграції версій.

3) Порядок застосування (рекомендований ланцюжок)

[Ingress TLS]
→ Early-Deny (ASN/Geo, IP allow/deny)
→ mTLS / Client Cert Auth
→ JWT/OAuth2 AuthN (JWKS cache)
→ OPA/ABAC AuthZ (solution cache)
→ Rate Limit / Concurrency
→ Circuit / Timeout / Retries (пер-try)
→ Schema Validation (request)
→ Transform (headers/path/body) / CORS
→ Caching (lookup)
→ Upstream Proxy (app)
← Caching (store) / Compression
← Response Transform / Schema Validation (response)
← Logging / Tracing / Metrics / Security Headers

Принцип: раніше - дешевше/фатальніше (deny, auth, ліміти), пізніше - «косметика» (трансформації, кеш).

4) Продуктивність і кардинальність

Дотримуйтесь O (1) кроків без зовнішніх запитів у гарячому шляху.
Всі «зовнішні дзвінки» плагінів (PDP/JWKS) - через короткі TTL і asynchronous refresh.
Мітки/лейбли для метрик - обмежена кардинальність ('tenant','plan','route', але не'user _ id').
«Важкі» плагіни (WAF, body-transform) - включати селективно per-route.

5) Приклади конфігурацій

5. 1 Envoy: JWT + RateLimit + OPA + Retries (псевдо)

yaml static_resources:
listeners:
- name: public_listener filter_chains:
- filters:
- name: envoy. filters. network. http_connection_manager typed_config:
route_config:
name: main virtual_hosts:
- name: api domains: ["api. example. com"]
routes:
- match: { prefix: "/v1/payments" }
route:
cluster: payments timeout: 350ms retry_policy:
retry_on: connect-failure,reset,5xx,gateways num_retries: 1 per_try_timeout: 200ms http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
providers:
oidc:
issuer: https://auth. example. com/
remote_jwks:
http_uri: { uri: https://auth. example. com/.well-known/jwks. json, cluster: jwks, timeout: 2s }
cache_duration: 300s forward: true
- name: envoy. filters. http. ext_authz  # OPA/Cedar PDP typed_config:
http_service:
server_uri: { uri: http://opa:8181, cluster: opa, timeout: 50ms }
authorization_request: { allowed_headers: { patterns: [{ exact: "authorization" }, { exact: "x-tenant" }] } }
- name: envoy. filters. http. ratelimit typed_config:
domain: public-api rate_limit_service:
grpc_service: { envoy_grpc: { cluster_name: rl } }
- name: envoy. filters. http. router

5. 2 NGINX/OpenResty: HMAC + Lua + Redis (псевдо)

nginx lua_shared_dict jwks 10m;
lua_shared_dict limits 10m;

server {
listen 443 ssl http2;

Early deny by ASN/Geo if ($bad_asn) { return 403; }

HMAC signature check (webhooks/partners)
set_by_lua_block $sig_ok {
return verify_hmac_signature(ngx. var. http_x_signature, ngx. var. request_time, ngx. var. request_body)
}
if ($sig_ok = 0) { return 401; }

Token bucket in Redis access_by_lua_block {
local key = ngx. var. binary_remote_addr.. ":".. ngx. var. request_uri local allowed, retry_after = ratelimit_allow(key, 50, 100)
if not allowed then ngx. header["Retry-After"] = retry_after return ngx. exit(429)
end
}

proxy_read_timeout 300ms;
proxy_connect_timeout 100ms;
proxy_pass http://app_backend;
}

5. 3 Kong: плагіни за маршрутом

yaml services:
- name: payments url: http://payments:8080 routes:
- service: payments paths: ["/v1/payments"]
plugins:
- name: jwt config: { key_claim_name: kid, secret_is_base64: false, run_on_preflight: false }
- name: opa config: { server_url: "http://opa:8181/v1/data/authz/allow", timeout: 50 }
- name: rate-limiting config: { second: 50, policy: redis, redis_host: redis, fault_tolerant: true }
- name: correlation-id config: { header_name: "traceparent" }
- name: response-transformer config: { add: { headers: ["Strict-Transport-Security:max-age=31536000"] } }

5. 4 Apache APISIX: JWT + Limit + Proxy-Mirror (shadow)

yaml routes:
- uri: /v1/wallets/
plugins:
openid-connect:
client_id: wallet discovery: "https://auth. example. com/.well-known/openid-configuration"
scope: "openid"
limit-count:
count: 100 time_window: 60 key_type: "var"
key: "remote_addr"
proxy-mirror:          # shadow traffic host: "http://shadow-backend:8080"
upstream_id: 1

5. 5 Traefik: Middleware-ланцюжок

yaml http:
middlewares:
hsts-headers:
headers:
stsSeconds: 31536000 stsIncludeSubdomains: true ratelimit:
rateLimit:
average: 50 burst: 100 routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: app middlewares:
- hsts-headers
- ratelimit

6) Багатоарендність і версії політик

Ключ маршрутизації: `{tenant, plan, region, route, version}`.
Плагіни читають'tenant'з mTLS SAN/JWT-клейма/заголовка → застосовують пер-тенант ліміти/квоти/правила.
Версіонуйте політики ('policy _ version'), ведіть changelog і канарний rollout.

7) Тестування і rollout

До релізу

Контрактні тести ланцюжка (таблиця «якщо-то»): auth→deny, auth→allow, rate→429, schema→422.
Навантажувальні: бурсти × 10, довгі плато, «брудні» патерни (slow-POST).
Chaos: деградація PDP/JWKS/Redis - повинні бути fail-closed/деградація до мінімально безпечного.

Реліз

'Report-Only '/shadow-mode (логуємо рішення без застосування).
Canary 1-5% трафіку + порівняння метрик (p95/p99, 4xx/5xx/429).
Автоматичний rollback по SLO/алертам.

8) Спостережуваність і метрики

• `http_requests_total{route,tenant,plan,status}`
• `request_duration_seconds_bucket{route}` (p95/p99)
• `rate_limited_total{policy}`, `retry_total{reason}`, `circuit_state`
• `authn_fail_total{reason}`, `authz_denied_total{action}`
• `schema_validation_fail_total{route}`
• Трейси: спані per-filter, атрибути'policy _ version','tenant','limit _ key'.
• Логи (семпльовано): рішення deny/429/5xx з причинами і'trace _ id'.
• Дашборди: Exec-зведення, per-route, per-tenant, «гарячі» політики.

9) Безпека та експлуатація

Всі секрети (HMAC, JWKS private, API-ключі) - в KMS/Vault, не в конфіг-файлах.
Політика deny-by-default для чутливих маршрутів.
Короткі TTL JWKS/кешу PDP, асинхронні оновлення з backoff.
Міграції схем трансформацій - versioned; «ламаючі» - через dual-write.
Обмежуйте body-size (DoS) і глибину JSON.

10) Антипатерни

Універсальний «все включено» набір плагінів на кожному маршруті → зайві мілісекунди і рахунки.
Зовнішні залежності плагінів без кеша/таймаутів → каскадні таймаути.
Відсутність порядку фільтрів: спочатку трансформації/логіка, потім ліміти - невірно.
Висока кардинальність лейблів метрик (raw'user _ id '/' ip').
Змішування authN/authZ в шаблонах трансформації (неявні рішення в Lua/Jinja).
Логування секретів/токенів.
Один глобальний Redis/кластер для всіх лімітів без шардування/резерву.

11) Специфіка iGaming/фінансів

Пер-тенант/пер-юрисдикція правила: KYC/AML, санкції, ліміти відповідальних платежів.
Жорсткі політики для платіжних маршрутів: короткі таймаути, один повтор, ідемпотентність ('Idempotency-Key').
Розділення периметрів для PSP/KYC SDK (окремі домени/ланцюжки плагінів).
Аудит незмінних логів рішень (висновки, блокування, санкційна відмова).

12) Чек-лист prod-готовності

• Визначено порядок фільтрів: authN → authZ → limits → circuit/timeout → schema → transform → cache.
• Пер-маршрутний набір плагінів; важкі - тільки там, де потрібно.
• JWKS/PDP з коротким TTL і кешем; таймаути і fallback-стратегії.
• Rate/Quota/Concurrency - спроектовані ключі, шардування сховища.
• Набір метрик RED/USE, трасування OTel, семплінг tail/adaptive.
• Canary + shadow-режим, auto-rollback по SLO.
• Секрети в KMS/Vault; конфіги - версіоновані, з міграціями.
• Ліміти body/headers; захист від oversize/slow-POST.
• Документація для клієнтів: коди 401/403/409/422/429/5xx,'Retry-After', приклади заголовків.

13) TL; DR

Будуйте ланцюжок «рання відмова → автентифікація/авторизація → ліміти/стійкість → валідація → трансформації/кеш → телеметрія». Вмикайте тільки потрібні плагіни per-route, кешуйте зовнішні рішення (JWKS/PDP), задавайте таймаути і retry-політики, контролюйте кардинальність метрик. Релізуйте через shadow/canary, тримайте секрети в KMS/Vault і вимірюйте вплив кожного плагіна на p95/p99.