v2.3.0 : Moteur Pingora, Paramètres Chat, Bootstrap Zero-Config

Le moteur de connexion éprouvé de Pingora rencontre la gestion d'API AI-native — avec bootstrap zero-config, contrôles chat par tenant, et APIs de démo prêtes à l'emploi.

Points forts

Moteur de connexion Pingora (ADR-058)

STOA Gateway intègre désormais Pingora, le framework proxy de Cloudflare qui gère plus de 1 000 milliards de requêtes par jour. Plutôt qu'une migration complète (55+ pts), nous avons opté pour l'approche connecteur embarqué (13 pts) : le pool de connexions partagé de Pingora réside dans le binaire axum existant, derrière un feature flag pingora.

• Pool de connexions partagé — conçu pour 1 000 milliards de requêtes/jour, remplace les pools reqwest par client à l'échelle
• Zéro changement d'architecture — même binaire, même routage, même surface d'API
• Feature-gated — FEATURES=kafka,pingora dans les builds de production (cmake requis)
• Pérennité — le trait ProxyPhase correspond 1:1 au ProxyHttp de Pingora pour une éventuelle migration complète en v2.0

Argument marketing : "STOA Gateway — propulsé par le moteur de connexion Pingora"

Consultez ADR-058 pour l'enregistrement de décision complet.

Paramètres chat par tenant et suivi de la source

Les administrateurs peuvent désormais contrôler indépendamment l'assistant chat IA dans la Console et le Portal, avec un suivi de l'utilisation par application.

• Bascules par tenant — activer/désactiver le chat séparément pour la Console et le Portal
• Budget journalier de tokens — définir des limites de dépenses par tenant pour éviter les dépassements
• Suivi de la source — chaque message chat est étiqueté avec l'en-tête X-Chat-Source (console ou portal)
• Ventilation par usage — GET /v1/chat/usage?group_by=source affiche la consommation de tokens par application
• RBAC enforced — seuls cpi-admin et tenant-admin peuvent modifier les paramètres ; viewer reçoit un 403
• 25 scénarios E2E — CRUD, RBAC, application de l'en-tête source, intégration cross-app

Nouveaux endpoints :

Méthode	Chemin	Description
GET	/v1/chat/settings	Lire la configuration chat du tenant
PUT	/v1/chat/settings	Mettre à jour les bascules et le budget chat

Bootstrap Helm zero-config

Les installations initiales sont désormais entièrement automatisées. Un seul helm install avec le bootstrap activé provisionne l'ensemble de la plateforme :

• Realm Keycloak — création du realm avec inscription activée
• 4 rôles RBAC — cpi-admin, tenant-admin, devops, viewer
• 3 client scopes — stoa:read, stoa:write, stoa:admin
• 4 clients OIDC — Console, Portal, Gateway, API (tous préconfigurés)
• Utilisateur admin — créé avec le rôle cpi-admin si adminEmail est défini
• Tenant par défaut — provisionné via le Control Plane API

helm install stoa-platform ./charts/stoa-platform \
  --set stoa.bootstrap.enabled=true \
  --set stoa.domain=example.com \
  --set stoa.adminEmail=admin@example.com

Le job de bootstrap est idempotent — l'exécuter deux fois est sans risque (409 = déjà existant = OK).

Gestion des secrets partagés

Les clés internes de communication entre services sont désormais auto-générées et stables entre les mises à niveau :

Clé	Utilisation
gateway-consumer-key	Authentification Gateway ↔ API
chat-internal-key	Appels internes du service chat
jwt-signing-key	Signature des tokens JWT
anthropic-api-key	API Anthropic (optionnel)

Les clés persistent entre les helm upgrade via la fonction lookup de Helm. Lorsque la clé API Anthropic n'est pas fournie, le chat se désactive proprement via CHAT_KILL_SWITCH.

APIs de démo avec données réelles

Le portail développeur est désormais livré avec 5 APIs publiques réelles préconfigurées pour des tests immédiats :

API	Authentification	Limite de taux	Cas d'usage
Exchange Rate API	Aucune	Illimitée	Taux de change (180+ devises)
CoinGecko	Aucune	30 req/min	Prix des cryptomonnaies et capitalisation boursière
OpenWeatherMap	Clé API	1 000/jour	Données météo en temps réel
NewsAPI	Clé API	100/jour	Titres de 80+ sources d'information
Alpha Vantage	Clé API	5/min	Cours des actions et indicateurs techniques

Plus un backend echo de secours pour les cas où les APIs externes sont inaccessibles — les démos ne tombent jamais.

---

Gateway (Rust)

Capacité	Description
Moteur Pingora	Pool de connexions partagé embarqué derrière le feature flag pingora
Correctif OAuth Hairpin	URL Keycloak interne pour le proxy DCR/token — corrige les erreurs 502 sur les clusters K8s
Tracing du mode de déploiement	Attribut de span stoa.deployment_mode pour le service graph Tempo
En-tête source chat	Propagation et application de X-Chat-Source

Correctif NAT hairpin OAuth

Les endpoints du proxy OAuth (token, DCR, PAR) utilisaient l'URL Keycloak externe. Sur les clusters K8s avec des problèmes de NAT hairpin (ex. OVH MKS), cela provoquait des erreurs 502 à l'étape d'enregistrement DCR — interrompant les connexions MCP de Claude.ai.

Correctif : La nouvelle méthode Config::keycloak_backend_url() préfère STOA_KEYCLOAK_INTERNAL_URL (DNS de service K8s) pour les appels backend, tout en conservant l'URL externe pour les champs de découverte exposés aux navigateurs.

Control Plane API (Python/FastAPI)

Capacité	Description
Paramètres chat	GET/PUT /v1/chat/settings — bascules par tenant + budget
Suivi de la source	Enum ChatSource, en-tête X-Chat-Source, group_by=source
Amorçage des APIs	Migration Alembic 074 — 5 APIs réelles + backend echo
Budget chat	Limites journalières de tokens par tenant avec application

Console & Portal (React/TypeScript)

• Page Paramètres chat — bascule du chat par application, définition du budget journalier, flux de sauvegarde
• Injection de l'en-tête source — le hook useChatService envoie X-Chat-Source sur toutes les requêtes
• Gates RBAC — le rôle viewer est bloqué pour la modification des paramètres

Chart Helm

Nouvelles valeurs :

Clé	Défaut	Description
stoa.domain	—	Domaine de base pour tous les services
stoa.adminEmail	—	Email de l'utilisateur admin (bootstrap)
stoa.anthropicApiKey	—	Clé API Anthropic (optionnelle, active le chat)
stoa.bootstrap.enabled	false	Activer le provisionnement initial de la plateforme

---

Correctifs

• Portal 502 — Correction de API_BACKEND_URL et ajout de DNS_RESOLVER dans le manifeste de déploiement (#1813)
• OAuth DCR 502 — Le Gateway utilise désormais l'URL Keycloak interne pour les appels de proxy backend (#1814)
• Service graph Tempo — Mode de déploiement comme attribut de span (et non attribut de ressource) pour une extraction correcte (#1811)

Changements incompatibles

Aucun. Tous les changements sont rétrocompatibles.

Guide de mise à niveau

# Mise à niveau Helm standard (sans bootstrap)
helm upgrade stoa-platform ./charts/stoa-platform -n stoa-system

# Installation initiale avec bootstrap
helm install stoa-platform ./charts/stoa-platform -n stoa-system \
  --set stoa.bootstrap.enabled=true \
  --set stoa.domain=yourdomain.com \
  --set stoa.adminEmail=admin@yourdomain.com

Les images Docker du Gateway nécessitent désormais cmake au moment du build (dépendance Pingora). Les images préconstruites depuis GHCR l'incluent déjà — aucune action requise pour les déploiements standards.

Et ensuite ?

• Parsing HTTP au niveau noyau eBPF — inspection des requêtes sans copie (CAB-1841/1843)
• Application des politiques UAC au niveau noyau — évaluation des politiques basée sur eBPF (CAB-1848)
• Runtime de plugins WASM — plugins définis par l'utilisateur en WebAssembly (CAB-1644)
• Fédération MCP — découverte d'outils cross-gateway (ADR-046)

Consultez la feuille de route complète pour les fonctionnalités planifiées et les jalons.

Ressources

• Documentation
• GitHub
• ADR-058 : Intégration Pingora
• Discord