@aventii/db (1.3.0)
Installation
@aventii:registry=npm install @aventii/db@1.3.0"@aventii/db": "1.3.0"About this package
@aventii/db
Primitives génériques de connexion aux bases de données pour les services Aventii.
Le package fournit une abstraction légère du cycle de vie des connexions sans imposer un moteur de base de données, une méthode de récupération de l'URI ou une organisation des bases, collections et modèles. Il prend actuellement en charge MongoDB natif et Mongoose.
Installation
Le package est distribué sur le registre npm privé Aventii :
npm install @aventii/db
Une configuration npm Aventii valide est nécessaire.
Principes
@aventii/db sépare trois responsabilités :
- Le gestionnaire de connexion (
createDatabaseManager). - L'adapter du moteur (
createMongoAdapteroucreateMongooseAdapter). - Le secret provider qui fournit l'URI (
createHttpSecretProvideroucreateDirectSecretProvider).
Le service consommateur reste responsable de ses bases, collections, modèles et règles métier.
Gestionnaire de connexion
const { createDatabaseManager } = require('@aventii/db');
const database = createDatabaseManager({
adapter,
secretProvider
});
await database.initialize();
Le gestionnaire récupère l'URI, établit la connexion, conserve son état, réessaie au démarrage, peut contrôler périodiquement si l'URI a changé et permet une fermeture propre.
Initialisation et politique d'échec
const database = createDatabaseManager({
adapter,
secretProvider,
retry: {
attempts: 3,
delayMs: 1000,
timeoutMs: 20000
}
});
Les valeurs ci-dessus sont les valeurs par défaut. Si aucune connexion ne peut être établie, initialize() rejette sa promesse. Le délai timeoutMs limite l'attente de initialize() mais n'annule pas les opérations sous-jacentes déjà lancées ; elles peuvent continuer après expiration du délai.
État et accès à la connexion
const status = database.getStatus();
const connection = database.getConnection();
const db = database.getDb('Auth');
L'état contient connected, lastAttempt, lastSuccess, lastError et attempts. getConnection() échoue avant l'initialisation. getDb() requiert un adapter qui expose cette méthode.
MongoDB natif
const { createDatabaseManager, createMongoAdapter } = require('@aventii/db');
const database = createDatabaseManager({
adapter: createMongoAdapter(),
secretProvider
});
await database.initialize();
const users = database.getDb('Auth').collection('Users');
Des options MongoClient peuvent être fournies :
const { ServerApiVersion } = require('mongodb');
const adapter = createMongoAdapter({
clientOptions: {
serverApi: {
version: ServerApiVersion.v1,
strict: true,
deprecationErrors: true
}
}
});
Mongoose
const { createDatabaseManager, createMongooseAdapter } = require('@aventii/db');
const database = createDatabaseManager({
adapter: createMongooseAdapter(),
secretProvider
});
await database.initialize();
const authDb = database.getDb('Auth');
const User = authDb.model('User', userSchema, 'Users');
const users = authDb.collection('Users');
L'adapter Mongoose utilise useDb(name, { useCache: true }) pour les bases nommées.
Secret provider HTTP et serveur de secours
createHttpSecretProvider récupère l'URI depuis un service HTTP de secrets. Il accepte un serveur principal (baseUrl) et, facultativement, un serveur de secours (fallbackBaseUrl).
const { createHttpSecretProvider } = require('@aventii/db');
const secretProvider = createHttpSecretProvider({
baseUrl: process.env.KEY_API_URL,
...(process.env.FALLBACK_KEY_API_URL && {
fallbackBaseUrl: process.env.FALLBACK_KEY_API_URL
}),
secretName: {
production: 'MONGO_URI',
staging: 'MONGO_URI_STAGING',
local: 'MONGO_URI_LOCAL'
},
environment: process.env.NODE_ENV,
getAuthToken
});
Règles de bascule
- Chaque appel à
getSecret()commence par le serveur principal. - Tout échec pendant la tentative principale entraîne une tentative sur le secours, s'il est configuré : réseau, timeout, statut HTTP
4xxou5xx, JSON invalide, secret absent ou invalide, ou erreur de construction des en-têtes d'authentification. - Les en-têtes, notamment le token obtenu par
getAuthToken(), sont reconstruits pour chaque tentative. - Chaque requête utilise
AbortSignal.timeout(5000); ce délai s'applique aufetchet aux opérations qui respectent son signal d'annulation. - Si le secours réussit, son secret est retourné. Le prochain appel repart néanmoins du principal.
- Sans secours, l'erreur principale est propagée. Si les deux tentatives échouent, une
AggregateErrorcontenant les deux erreurs est levée. - Les erreurs de résolution du nom du secret (
secretName) ou de construction du chemin (pathBuilder) surviennent avant la tentative principale et ne déclenchent pas de bascule.
Par défaut, une requête GET est envoyée vers key/<nom-du-secret-encodé> ; la réponse JSON doit contenir une propriété key non vide. Le token facultatif est transmis via x-auth-token.
Les options pathBuilder, headers, responseExtractor et fetchImpl permettent de personnaliser le provider. Les deux serveurs utilisent le même chemin, la même extraction de réponse et le même mécanisme d'authentification. Le package ne connaît ni l'adresse réelle du service de secrets ni sa logique métier.
Attention : le fallback concerne la récupération de l'URI, et non une bascule automatique entre serveurs MongoDB. Une URI différente renvoyée par le secours peut provoquer un remplacement de connexion lors du rafraîchissement.
URI fournie directement
Le service de secrets est facultatif :
const { createDirectSecretProvider } = require('@aventii/db');
const secretProvider = createDirectSecretProvider({
uri: process.env.MONGO_URI
});
Rafraîchissement de la chaîne de connexion
const database = createDatabaseManager({
adapter,
secretProvider,
refreshIntervalMs: 15 * 60 * 1000
});
Le rafraîchissement (15 minutes par défaut) compare l'URI récupérée avec l'URI courante. Si elle change, une nouvelle connexion est établie et validée avant la fermeture de l'ancienne. Si la récupération du secret ou la nouvelle connexion échoue, l'ancienne connexion reste active et refresh() renvoie false.
Pour désactiver le rafraîchissement :
refreshIntervalMs: 0
Cette option est utile lorsqu'un consommateur conserve des objets liés à une connexion particulière, notamment certains modèles Mongoose. Le rafraîchissement ne constitue pas un contrôle de santé permanent de la base : une URI inchangée n'entraîne pas de reconnexion.
Hook de connexion
const database = createDatabaseManager({
adapter,
secretProvider,
onConnected: async connection => {
// Initialisation propre au consommateur (par exemple, index).
}
});
Si le hook échoue, la nouvelle connexion est fermée et n'est pas adoptée.
Fermeture propre
await database.close();
Par exemple :
async function gracefulShutdown() {
await database.close();
process.exit(0);
}
process.on('SIGINT', gracefulShutdown);
process.on('SIGTERM', gracefulShutdown);
Plusieurs moteurs dans un même service
Plusieurs gestionnaires indépendants peuvent coexister. Un microservice peut utiliser MongoDB natif, Mongoose ou d'autres adapters futurs, chacun avec son propre cycle de vie.
API
Le package exporte :
createDatabaseManager
createMongoAdapter
createMongooseAdapter
createHttpSecretProvider
createDirectSecretProvider
Une instance createDatabaseManager expose :
initialize
refresh
close
getStatus
getConnection
getDb
Le provider HTTP expose getSecret() et resolveSecretName().
Hors périmètre
@aventii/db ne décide pas quelles bases, collections, modèles ou schémas utiliser, comment structurer les données métier, quelles routes accèdent aux données, quel moteur choisir, ni si le rafraîchissement dynamique convient au consommateur. Il ne fournit pas non plus de bascule automatique de serveur MongoDB ni de surveillance de santé de la base.
Tests
npm test
La suite de tests couvre le gestionnaire, les adapters MongoDB et Mongoose, les providers HTTP et direct, ainsi que les politiques d'initialisation et d'échec. La couverture effective des nouveaux scénarios de fallback doit être vérifiée ou complétée (erreurs 4xx/5xx, réseau, timeout, JSON invalide, absence de fallback et double échec).
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| jest | ^30.0.0 |
| mongodb | ^6.0.0 |
| mongoose | ^8.0.0 |
Peer Dependencies
| ID | Version |
|---|---|
| mongodb | >=6 |
| mongoose | >=8 |