# didiKong - Index

API Gateway pentru platforma DIDI. Toate requesturile externe trec prin Kong inainte sa ajunga la serviciile backend. Gestioneaza rutare, rate limiting, CORS, SSL si headere.

**Imagine**: didi-kong:latest (Kong 3.9.1)
**Container**: didi-kong (activ, pe masina de deployment)

**Mod**: DB-less declarativ (`KONG_DATABASE=off`)
**Porturi** (doar loopback `127.0.0.1`): 18000 (proxy HTTP -> container 8000), 18001 (admin API -> 8001), 18443 (proxy TLS -> 8443 ssl)

---

## Deployment: container local DB-less (activ)

Kong ruleaza ca un singur container `didi-kong` pe masina de deployment, in mod **DB-less** (`KONG_DATABASE=off`). Nu exista Kong Cluster, Control Plane, Data Planes sau HAProxy, si nu exista PostgreSQL pentru Kong.

- Config declarativa din `declarative/kong.yml.didi11-local`, montata in container la `/kong/declarative/kong.yml`.
- Porturile sunt legate exclusiv pe loopback (`127.0.0.1`): proxy `18000`, admin API `18001`, proxy TLS `18443`. Kong nu e expus public direct; traficul extern intra prin edge/tunel catre proxy-ul local.
- Single source of truth = fisierul declarativ `kong.yml.didi11-local`. Orice modificare de rute/plugin-uri se face in acest fisier + reload.

---

## Mod de operare: DB-less (declarativ)

Configuratia vine integral din fisierul `declarative/kong.yml.didi11-local`. Kong nu are baza de date proprie.
```
KONG_DATABASE=off
KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml
```

Nu exista mod PostgreSQL / productie separata pentru Kong: acelasi fisier declarativ este sursa unica de adevar.

---

## Servicii inregistrate

Kong ruteaza catre 2 servicii backend (conform `kong.yml.didi11-local`):

| Serviciu | Target | Status |
|----------|--------|--------|
| didi-agent-v3 | http://didi-agent-v3:24803 | activ |
| didi-framework | http://didi-framework:3005 | activ |

Nota: rutele agent-v3 au timeout mare (660s = 11 min) pentru procesarea video.

---

## Rute definite

### Agent service (activ)

| Path | Metode | Destinatie |
|------|--------|------------|
| /agent/health | GET | agent-api |
| /agent/status | GET | agent-api |
| /api/pipelines | GET | agent-api |
| /api/analyze | POST | agent-api |
| /api/sessions | GET | agent-api |
| /api/upload | POST | agent-api |
| /api/abort | POST | agent-api |
| /api/v3/* | toate | agent-api (acopera si /api/v3/moderation/*) |

### didiFramework (config + HIL moderation)

| Path | Metode | Destinatie |
|------|--------|------------|
| /api/* | toate | didiFramework (acopera /api/moderation-config, /api/sensitive-topics, /api/moderation-roles) |

Nota: rutele de moderatie (HIL) calatoresc pe regulile generale `/api/v3/*` (agent-v3) si `/api/*` (didiFramework) — nu sunt necesare reguli Kong dedicate.

> Notă: serviciile Python legacy `orchestrator-api` și `analysis-api` (rute `/api/v1/catalog|pipelines|runs/*`,
> `/analysis/*`) NU mai există în config-ul local — au fost eliminate odată cu migrarea pe agent-v3. Config-ul
> `kong.yml.didi11-local` rutează exclusiv către `didi-agent-v3` și `didi-framework`.

### Admin dashboard

| Path | Metode | Destinatie |
|------|--------|------------|
| /admin | toate | admin-dashboard |
| /admin/api | toate | admin-dashboard |

---

## Plugin-uri globale

5 plugin-uri active pe toate rutele:

### 1. CORS
- Origins: localhost:3000, localhost:3001, localhost:8100, * (wildcard)
- Metode: GET, POST, PUT, DELETE, OPTIONS, PATCH
- Headere: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Authorization, X-Request-ID
- Exposed headers: X-Auth-Token, X-Request-ID
- Credentials: activat
- Max age: 3600s
- Preflight continue: nu

### 2. Rate Limiting
- 100 requests/minut per consumer
- 2000 requests/ora per consumer
- 10000 requests/zi per consumer
- Politica: local (fara state distribuit)
- Fault tolerant: da

### 3. Correlation ID (Request ID Tracking)
- Header: X-Request-ID
- Generator: UUID
- Echo downstream: da (returnat in raspuns)

### 4. Request Size Limiting
- Max payload: 100MB (pentru upload media)
- Require content-length: nu

### 5. Response Transformer
- Adauga: X-Gateway: DIDI-Kong, X-API-Version: 2.0
- Sterge: Server, Via (ascunde detalii interne)

---

## Upstreams (load balancing)

Config-ul local (`kong.yml.didi11-local`) NU definește upstream-uri — rutarea se face
direct către serviciile `didi-agent-v3:24803` și `didi-framework:3005`. Scalarea orizontală
a workerilor se face la nivel de agent-v3 (`scale-workers.sh`), nu prin upstream-uri Kong.

---

## SSL/TLS

- Certificat self-signed pentru <host-local>
- Locatie: certs/server.crt, certs/server.key
- Valabil: feb 2026 - feb 2027
- Emitent: DIDI, Bucharest, RO
- Servit pe proxy-ul TLS local `127.0.0.1:18443`

---

## Integrare Keycloak (LOCAL) + enforcement JWT (Modul 4 Gateway)

Kong valideaza token-urile emise de instanta Keycloak **locala** (`didi-keycloak`, port `28080`, servita sub `/auth`). Realm-urile locale sunt `didi-clients` (useri finali) si `didi-admins` (operatori). Issuer-ele locale au forma `http://localhost:28080/auth/realms/didi-clients` si `.../didi-admins`.

Enforcement-ul se face prin pluginul Kong `jwt` (nu OIDC/introspection): validare de semnatura **RS256** cu chei publice statice, `key_claim_name: iss` (Kong potriveste tokenul dupa claim-ul `iss` cu un `jwt_secret` inregistrat pe consumer).

Consumer: **`didi-keycloak-users`** — detine `jwt_secrets` (RS256, `rsa_public_key`) pentru toate issuer-ele acceptate, cheia fiind chiar valoarea `iss`:
- local: `http://localhost:28080/realms/didi-clients`, `http://localhost:28080/realms/didi-admins`
- plus issuer-ele externe/edge folosite in fata proxy-ului: `https://didi365.eu/auth/realms/{didi-clients,didi-admins}`, `https://<sso-extern>/realms/...`, `https://<sso-extern>/realms/...`, `https://<host-local>/auth/realms/...`, `https://10.11.10.11:{3001,8443}/auth/realms/...`

Pluginul `jwt` este activ pe **16 rute protejate** de pe cele doua servicii (`didi-agent-v3` si `didi-framework`), incluzand ruta **`/framework`** (route `didi-framework-direct`, jwt adaugat 2026-07-08). Rutele publice raman fara jwt (health/status, media public, verify-email, waitlist), iar rutele de extensie folosesc autentificare separata prin `X-API-Key` + rate-limiting.

JWT validation flow:
1. Clientul (SPA/extensie) obtine token JWT de la Keycloak local (`/auth/realms/didi-clients` sau `/auth/realms/didi-admins`).
2. Trimite request cu `Authorization: Bearer {token}`.
3. Kong potriveste `iss` cu `jwt_secret`-ul consumer-ului `didi-keycloak-users` si valideaza semnatura RS256; token invalid/lipsa -> `401`.
4. Daca valid, ruteaza requestul catre serviciul backend local (`didi-agent-v3:24803` / `didi-framework`).
5. Serviciul backend decodeaza tokenul pentru `user_id`/`email`/`realm_access.roles` (fara re-validare — Kong a validat deja).

---

## Configurare performanta

```
KONG_NGINX_WORKER_PROCESSES=auto
KONG_MEM_CACHE_SIZE=256m
KONG_NGINX_PROXY_PROXY_BUFFER_SIZE=128k
KONG_NGINX_PROXY_PROXY_BUFFERS=4 256k
KONG_NGINX_PROXY_PROXY_BUSY_BUFFERS_SIZE=256k
KONG_NGINX_HTTP_LARGE_CLIENT_HEADER_BUFFERS=4 64k
```

Buffer-urile mari sunt necesare pentru headerele JWT de la Keycloak (token-urile pot fi foarte mari).

---

## Fisiere

```
Dockerfile                       -- Imagine didi-kong (Kong 3.9), instaleaza curl, entrypoint
entrypoint.sh                    -- Pornire Kong DB-less + wait for ready + log servicii
declarative/
  kong.yml.didi11-local          -- Configurare declarativa activa (single source of truth, montata la /kong/declarative/kong.yml)
certs/
  server.crt                     -- Certificat SSL self-signed
  server.key                     -- Cheie privata SSL
```

Zero cod custom. Zero plugin-uri Lua custom. Doar configurare declarativa si certificat SSL.

---

## Health check

```
kong health (interval 30s, timeout 10s, retries 3, start period 60s)
```

---

## Consumers

Configuratia declarativa defineste un singur consumer Kong: **`didi-keycloak-users`** (username + custom_id `didi-keycloak-users`), care detine `jwt_secrets`-urile RS256 pentru toate issuer-ele Keycloak locale/edge acceptate (vezi sectiunea Integrare Keycloak). Acest consumer este cel pe care pluginul `jwt` il rezolva la validarea tokenului.

Limitele per-tier (free/paid/enterprise) provin din atributele de grup Keycloak (realm-urile locale `didi-clients` / `didi-admins`) si sunt disponibile in claim-urile JWT pentru rate limiting; rutele de extensie au propriul rate-limiting per `X-API-Key` (30/min).

## Recent Changes

- **2026-07-08 — jwt pe `/framework`**: pluginul `jwt` (RS256, `key_claim_name: iss`) adaugat pe ruta `didi-framework-direct` (path `/framework`). Enforcement JWT acum activ pe 16 rute protejate pe `didi-agent-v3` + `didi-framework`.
- **jwt_secrets pentru issuer-ele locale** pe consumer `didi-keycloak-users`: `http://localhost:28080/realms/didi-clients` + `.../didi-admins`, alaturi de issuer-ele edge (`didi365.eu/auth`, `<sso-extern>`, `<sso-extern>`, `<host-local>/auth`, `10.11.10.11:{3001,8443}/auth`) pentru realm-urile `didi-clients` si `didi-admins`.
- **Rute de extensie** (`didi-agent-extension-analyze`, `-async`, `-status`, `-upload`): autentificare `X-API-Key` + `rate-limiting` 30/min + `request-transformer`; CORS extins cu origins `chrome-extension://[a-z]+`, `moz-extension://[a-z0-9-]+` + header `X-API-Key`.
- **Single source of truth** = `declarative/kong.yml.didi11-local` (DB-less). Fara cluster, fara decK sync.