Services annexes

12 min

Vue d'ensemble

Un OAV n'est jamais exécuté seul : il s'appuie sur des services annexes, démarrés localement par Docker Compose en développement, et déployés aux côtés de l'OAV en production.

Service	Rôle
OIP Headless	Persistance, historisation, ordonnancement des tâches et règles RGPD.
Fasst Sessions	Émission et validation des jetons de décrochage.
PostgreSQL	Données d'OIP Headless et magasin des sessions de l'OAV.
RabbitMQ	Acheminement des évènements entre OIP Headless et l'OAV.

flowchart LR
    Client[App React] -->|GraphQL| Server[App Express]
    Server -->|REST| Headless[OIP Headless]
    Server -->|HTTP| Sessions[Fasst Sessions]
    Headless --> DB[(PostgreSQL)]
    Server --> DB
    Headless <-->|AMQP| MQ[RabbitMQ]
    Server <-->|AMQP| MQ

OIP Headless

OIP Headless est le service de persistance de l'OIP. Il expose une API REST consommée par le serveur Express de l'OAV, authentifiée par clé d'API.

Il assure :

la persistance des entités et du Process ;

l'historisation de toutes les écritures et leur annulation par transaction ;

la programmation des tâches et des workflows de tâches ;

l'application des règles RGPD de chiffrement au repos et de purge automatique ;

la publication d'évènements vers l'OAV.

Il nécessite une instance PostgreSQL et une instance RabbitMQ.

Configuration

Variable	Statut	Description
DATABASE_URL	Obligatoire	URL PostgreSQL, au format ecto://[USER]:[PASS]@[HOST]:[PORT]/[DATABASE].
AMQP_URL	Obligatoire	URL RabbitMQ, au format amqp://[USER]:[PASS]@[HOST]:[PORT]/[VHOST].
SECRET_KEY_BASE	Obligatoire	Clé de chiffrement et de signature des cookies.
CIPHER_SECRET_KEY_BASE	Obligatoire	Clé de chiffrement des données, de 256 bits encodée en base64.
PHX_HOST	Obligatoire	URL du tableau de bord du service.
ECTO_SSL_CERT_PATH	Optionnelle	Chemin du certificat racine, requis pour activer SSL sur la connexion PostgreSQL.
LOGGER_LEVEL	Optionnelle	Niveau de journalisation du service.

Côté OAV, le dialogue avec ce service est configuré par les variables OIP_API_URL, OIP_API_KEY et OAV_ID.

[info] Ces variables configurent le service OIP Headless, et non l'OAV. Elles sont renseignées dans le fichier docker-compose.yml en développement, ou par l'orchestrateur en production.

Fasst Sessions

Fasst Sessions résout le contexte client à l'entrée du parcours : il émet des jetons de décrochage et les valide.

Le serveur Express lui transmet le jeton reçu en paramètre d'URL, et reçoit en retour le contexte client résolu, qui est ensuite passé à resolveProjectFromContext.

Élément	Valeur
Port par défaut en développement	3005
Route d'émission d'un jeton	POST /api/sessions/tokens
Variable de configuration côté OAV	SESSION_SERVICE_URL

Émission d'un jeton en développement :

curl --request POST \
  --url http://localhost:3005/api/sessions/tokens \
  --header 'Content-Type: application/json' \
  --data '{"applicant":"magic","metadata":{"externalId":"project-AAA"}}'

Le service dispose de sa propre base de données.

[info] Ce service est remplaçable. La fonction de rappel session.resolveContext permet de résoudre le contexte client auprès d'un service tiers, ou selon une logique métier spécifique.

PostgreSQL

PostgreSQL héberge deux jeux de données distincts :

Base	Contenu	Variable
Base d'OIP Headless	Entités, historique des écritures, Process, tâches.	DATABASE_URL du service OIP Headless.
Base des sessions de l'OAV	Sessions de navigation HTTP.	SESSION_STORE_URL de l'OAV.

Les migrations du modèle de données de l'OAV sont appliquées sur la base d'OIP Headless, par le script scripts/run-migrations.sh appelé par la commande migrate:dev en développement, et exécuté au démarrage du conteneur en production.

RabbitMQ

RabbitMQ achemine les évènements entre OIP Headless et l'OAV, et permet de servir plusieurs instances de l'OAV.

File	Sens	Contenu
<OAV_ID>.events	OIP Headless → OAV	Déclenchement des tâches à échéance.
<OAV_ID>.entities	OIP Headless → OAV	Instantanés de trame projet.
oip.api.events	OAV → OIP Headless	Remontée des statuts de tâches.

Côté OAV, la connexion est configurée par les variables RABBIT_MQ_HOST, RABBIT_MQ_USER, RABBIT_MQ_PASSWORD et RABBIT_MQ_VHOST.

[warn] L'écoute de la file <OAV_ID>.events n'est pas automatique : le consommateur doit être enregistré explicitement (par exemple dans server/index.mjs). Sans cet enregistrement, les tâches sont programmées mais jamais exécutées.

Exploitation en développement

Commande	Effet
docker compose up -d	Démarre l'ensemble des services annexes.
docker compose ps	Liste les services et leur état.
docker compose logs -f	Suit les journaux de tous les services.
docker compose stop	Arrête les services en conservant les données.
docker compose down -v	Arrête les services et supprime les volumes, donc les données.

[warn] docker compose down -v est destructif et réservé au poste de développement.

Déploiement

Un OAV en production mobilise cinq services :

l'OAV lui-même, distribué sous forme d'image Docker ;

le service de sessions et sa base de données ;

OIP Headless ;

PostgreSQL, hébergeant les données d'OIP Headless et les sessions de l'OAV ;

RabbitMQ.

Résumé

Quatre services annexes entourent l'OAV : OIP Headless, Fasst Sessions, PostgreSQL et RabbitMQ ;

OIP Headless porte les données, l'historisation, l'ordonnancement des tâches et les règles RGPD ;

Fasst Sessions n'intervient qu'au décrochage, et peut être remplacé par un service tiers ;

trois files RabbitMQ structurent les échanges asynchrones.