Pipeline (10 etapes)

Le pipeline est le coeur du proxy. Toute requete — GET sync, POST async (worker), polling, bulk sync — passe par le meme pipeline.

Flowchart

Detail de chaque etape

1. Resolve adapter

Cherche le OpcoAdapter pour l'opcoId demande. Chaque OPCO (opco-ep, atlas, constructys...) a un profil DSL declaratif qui definit ses routes, transforms et rate limits.

Si l'OPCO est inconnu : 404 NOT_FOUND.

2. Check capability

Verifie que l'endpoint demande (GET /dossiers, POST /factures...) est supporte par cet OPCO. Chaque route est declaree dans le profil avec supported: true/false.

Si non supporte : 501 NOT_SUPPORTED.

3. Cache check (GET uniquement)

Pour les GET, genere une cle cache incluant opcoId, tenantHash, method, path et un hash des query params. Cherche dans Redis.

• Cache hit : retour immediat, pas d'appel upstream
• Cache miss : continue le pipeline

Les POST ne sont jamais caches.

4. Rate limit

Trois modes de fonctionnement selon la disponibilite du hub :

Situation	Mecanisme	Comportement
Hub connecte	hubClient.acquire()	Attend le grant du hub (le hub controle le rythme)
Hub deconnecte	localRateLimiter.acquire()	Token bucket local, attend si necessaire (ne rejette jamais)
Pas de hub	rateLimiter.acquire()	Token bucket Redis, rejette si budget epuise (429)

Voir Rate Limiting pour le detail.

5. Transform request

Le DSL adapter applique les transformations sur le body et les query params :

• trim(), uppercase() sur les champs texte
• dateFormat('YYYY-MM-DD') pour normaliser les dates
• stripNulls() pour retirer les champs null
• Mapping de noms de champs entre le schema Opcovia et le schema OPCO

6. Call OPCO (http-client)

Appel HTTP upstream vers l'API Convergence. Deux formats :

• JSON : Content-Type: application/json (GET params, POST dossier)
• Multipart : multipart/form-data (factures, conventions, certificats — metadata JSON + fichier PDF)

Headers injectes : Authorization: Bearer {token}, X-API-KEY, EDITEUR, LOGICIEL, VERSION.

Si le hub a delivre un grant, le header Opcovia-Hub-Token contient le JWT. Si le hub est deconnecte : Opcovia-Hub-Token: DISCONNECTED.

7. Transform response

Le DSL adapter applique les transformations inverses sur la reponse OPCO :

• Correction de typos (RUTPURE -> RUPTURE)
• Normalisation des noms de champs
• Mapping de valeurs

8. Validate response (2 niveaux)

La validation a deux niveaux de severite :

Niveau	Condition	Action
unusable	Reponse null, non-objet, ou champs racines manquants (status, cerfa...)	Pipeline throw — la reponse est inutilisable
warnings	Drift tolerable (champs optionnels manquants, types inexacts)	Ajoutes au PipelineResult.warnings, logges

Philosophie best-effort : on prefere retourner une reponse avec des warnings plutot que de bloquer. L'API Convergence n'est pas fiable sur la conformite de ses schemas.

9. Record metrics

Enregistre dans une fenetre glissante de 60s : nombre de requetes, erreurs, latence, 429s. Ces metriques sont utilisees par le hub pour ajuster le rate limiting.

10. Cache store (GET uniquement)

Si c'est un GET avec cacheTtl > 0, stocke la reponse transformee dans Redis avec le TTL defini par le profil OPCO.

Flux GET (synchrone) vs POST (asynchrone)

GET /opco-ep/dossiers?siren=123
  → Pipeline complet (10 etapes)
  → Reponse JSON directe au client

POST /opco-ep/factures (multipart)
  → Route Hono parse le multipart
  → enqueueJob() insere en DB + Redis
  → Reponse 202 { jobId } immediate
  → Worker dequeue le job
  → Pipeline complet (10 etapes) dans le worker
  → Resultat stocke en DB (job_results)
  → Webhook job.completed au client

Le pipeline est identique dans les deux cas. La seule difference : le GET l'execute de maniere synchrone dans la route HTTP, le POST l'execute de maniere asynchrone dans un worker BullMQ.

Flux GET synchrone

Flux POST asynchrone