Résoudre des métadonnées de session
Vue d'ensemble
resolveMetadata est une fonction de rappel optionnelle passée en paramètre de la fonction start via l'option session.resolveMetadata dans le fichier server/index.mjs. Elle est exécutée lors de la résolution de l'entité Project, au moment du décrochage sur l'OAV.
Elle permet de résoudre des métadonnées arbitraires qui seront enregistrées dans la session. Une fois stockées, ces métadonnées sont accessibles depuis n'importe quel middleware ou route personnalisée via req.session.projects.
Prérequis
- Un projet utilisant le framework OIP
- Version 4.1.0 ou supérieure de la bibliothèque @fasstech/oip-starter-utils
La fonction de rappel session.resolveMetadata
Signature
resolveMetadata est une propriété optionnelle de ServerConfig.session dont la signature est la suivante :
Elle reçoit en argument un objet contenant :
- projectId : l'identifiant de l'entité Project résolue
- sessionId : l'identifiant de session courant
- clientId : l'identifiant de la connexion client (disponible à partir de la version 4.3.0)
La fonction doit retourner un objet dont la valeur résolue sera enregistrée dans req.session.projects[i].metadata.
Flux d'exécution
- Lors du décrochage sur l'OAV, la résolution de l'entité Project est déclenchée.
- L'entité Project est résolue : le projectId est validé.
- resolveMetadata est appelée avec { projectId, sessionId, clientId }.
- La valeur retournée est enregistrée dans req.session.projects[i].metadata.
- Les métadonnées sont ensuite accessibles depuis tout middleware ou route personnalisée via req.session.projects.
Implémentation
Déclarer resolveMetadata dans la configuration serveur et créer le fichier de rappel dédié. Les arguments projectId, sessionId et clientId sont disponibles pour effectuer les appels nécessaires (base de données, API tierce, etc.) et construire l'objet de métadonnées à retourner.
import { start } from "@fasstech/oip-starter-utils/server";
import { resolveMetadata } from "./resolve-metadata.mjs";
const serverConfig = {
session: {
// ...
resolveMetadata
}
// ...
};
const { app } = await start(serverConfig);
// init your business logic here
void app;Accéder aux métadonnées depuis un middleware
Structure de req.session.projects
Une fois resolveMetadata exécutée, l'objet session expose la structure suivante :
req.session.projects: {
projectId: string;
clientId: string;
metadata?: unknown;
}[]Récupérer les métadonnées du projet courant
Le projet courant est identifié via le header HTTP x-fasst-project-id, transmis automatiquement par le framework à chaque requête. Pour accéder aux métadonnées associées depuis un middleware ou une route personnalisée :
const myMiddleware = (req, res, next) => {
const projectId = req.get("x-fasst-project-id");
const project = req.session.projects?.find((p) => p.projectId === projectId);
const metadata = project?.metadata;
// use metadata here
next();
};Ce pattern permet de cibler précisément le projet actif parmi l'ensemble des projets enregistrés en session.
Résumé
- resolveMetadata est une fonction de rappel optionnelle à déclarer dans ServerConfig.session.
- Elle est appelée automatiquement lors de la résolution de l'entité Project au décrochage sur l'OAV.
- Elle reçoit { projectId, sessionId, clientId } et doit retourner un objet.
- La valeur retournée est enregistrée dans req.session.projects[i].metadata et persiste pour la durée de la session.
- Les métadonnées sont accessibles depuis n'importe quel middleware ou route via req.session.projects, en filtrant sur le projectId transmis par le header x-fasst-project-id.
- Nécessite la version 4.1.0 ou supérieure de @fasstech/oip-starter-utils.