@aventii/link (1.2.0)
Installation
@aventii:registry=npm install @aventii/link@1.2.0"@aventii/link": "1.2.0"About this package
@aventii/link
Utilitaires de communication HTTP entre les microservices Aventii. Paquet CommonJS sans dépendance d'exécution obligatoire. Axios est facultatif et injecté par le consommateur ; Fetch utilise l'API native de Node.js.
@aventii/link fournit des clients HTTP inter-MS, la propagation et la validation d'un contexte interne de confiance, un proxy gateway Express et des transports HTTP interchangeables. Le paquet ne stocke pas les secrets et ne dépend pas de pmc-keys.
Installation
npm install @aventii/link
Pour utiliser le transport Axios :
npm install axios
API publique
const {
createServiceClient,
ServiceRequestError,
createInternalContextMiddleware,
requireUserContext,
requireCountryContext,
createGatewayProxy,
createFetchTransport,
createAxiosTransport
} = require('@aventii/link');
Client inter-MS : createServiceClient(options)
Crée un client associé à une URL de base principale et, facultativement, une URL secondaire de secours. Il injecte le token interne, protège les headers d'identité, gère le contexte, les paramètres d'URL, les corps JSON et les réponses streamées, puis délègue l'exécution à un transport injecté.
const { createServiceClient, createFetchTransport } = require('@aventii/link');
const keysClient = createServiceClient({
baseUrl: process.env.KEY_API_URL,
fallbackBaseUrl: process.env.FALLBACK_KEY_API_URL || undefined,
getAuthToken,
transport: createFetchTransport(),
timeoutMs: 5000
});
const response = await keysClient.request({
method: 'GET',
path: '/crypto/public/pmc-user-dev'
});
console.log(response.data);
Options de construction
| Option | Type | Description |
|---|---|---|
baseUrl |
string |
URL HTTP(S) principale, obligatoire. |
fallbackBaseUrl |
string |
URL HTTP(S) secondaire, facultative. |
getAuthToken |
function |
Fonction synchrone ou asynchrone produisant le token inter-MS. |
transport |
object |
Objet exposant request(options). |
timeoutMs |
number |
Timeout par tentative, 5 000 ms par défaut. |
logger |
object ou null |
Journalisation des basculements (par défaut console, null pour désactiver). |
Les URLs sont normalisées avec un / final. Un chemin relatif tel que /crypto/public/id est résolu en conservant le préfixe éventuel /api/ de l'URL de base.
client.request(options)
const result = await keysClient.request({
method: 'GET',
path: '/crypto/public/pmc-user-dev',
query: { version: 1 },
context: { userId: '123', country: 'CM' },
headers: { 'x-custom-header': 'value' },
timeoutMs: 3000,
stream: false
});
// result = { status, headers, data }
Options : method (défaut GET), path, query, body, context, headers, timeoutMs, stream (défaut false). Le token authorization est injecté sans ajout automatique de Bearer. Les valeurs de host, authorization, x-user-id et x-country fournies directement dans headers sont ignorées puis reconstruites depuis les sources de confiance.
Bascule vers le serveur secondaire
Un seul client est nécessaire. fallbackBaseUrl est facultatif et n'a aucun effet sur les clients qui ne le fournissent pas. Aucune option endpoint n'est exposée dans client.request() : la destination est déterminée par la bibliothèque.
Chaque appel commence par le serveur principal, même si l'appel précédent a utilisé le secondaire. Si le principal échoue, la bibliothèque effectue au maximum une tentative sur le secours, sous les conditions ci-dessous.
| Événement sur le principal | Bascule automatique ? |
|---|---|
Échec DNS / connexion (ex. EAI_AGAIN, ENOTFOUND, ECONNREFUSED) |
Oui, pour GET/HEAD/OPTIONS sans corps |
| Timeout | Oui, pour GET/HEAD/OPTIONS sans corps |
| HTTP 502, 503 ou 504 | Oui, pour GET/HEAD/OPTIONS sans corps |
| HTTP 400, 401, 403, 404, 409, 429, 500 | Non |
Échec local de getAuthToken, contexte pays invalide, erreur de sérialisation |
Non |
| POST/PUT/PATCH/DELETE (même sur panne de connexion) | Non : risque de doublon d'écriture |
| Réponse invalide / erreur de parsing du transport | Non |
Chaque tentative dispose de son propre timeout : avec deux serveurs, la durée totale peut approcher deux fois la valeur configurée. Le token et le corps de la requête sont préparés une seule fois avant les tentatives.
Les logs sont gérés directement dans @aventii/link : warn au déclenchement du fallback, info en cas de succès du secondaire et error si les deux serveurs échouent. Aucun log supplémentaire n'est émis quand le principal répond normalement. Un logger injectable permet d'intégrer un outil de journalisation existant ou de couper ces logs avec logger: null. Les logs ne contiennent pas d'URL, de secret, de token ni de corps HTTP.
En cas d'échec unique, le client lève ServiceRequestError. Si les deux tentatives échouent, il lève AggregateError, avec errors[0] pour le principal et errors[1] pour le secours.
Cohérence de plusieurs requêtes
La bascule est décidée indépendamment pour chaque client.request(). Deux requêtes parallèles, par exemple la lecture de la clé publique et de la clé privée d'un même service, peuvent être servies par des instances différentes. Comparer uniquement version n'est pas suffisant pour garantir que les clés forment une paire.
Pour récupérer une paire de clés de façon cohérente sans réintroduire une sélection manuelle de serveur, la solution recommandée est une seule route authentifiée côté pmc-keys qui renvoie les deux clés et leur version dans une même réponse HTTP. @aventii/link fera alors basculer l'appel entier vers le secondaire en cas de panne. Cette route atomique est à créer côté pmc-keys : le présent correctif ne la fournit pas.
Le fallback ne fait ni découverte de service ni équilibrage de charge. Il ne garantit pas que les instances disposent de la même base de données ou des mêmes clés ; ces garanties appartiennent au déploiement des services.
Contexte inter-MS
Le protocole utilise authorization (token brut), et éventuellement x-user-id et x-country. Ces deux derniers headers ne sont fiables que lorsqu'ils sont reconstruits par une source de confiance. x-country est normalisé en code pays à deux lettres majuscules (CM, MG, FR).
createInternalContextMiddleware({ isValidToken })
app.use(createInternalContextMiddleware({
isValidToken: checkInternalToken
}));
Le middleware valide req.headers.authorization via isValidToken(token, req), puis renseigne req.internalContext = { userId?, country? }. Un token invalide ou absent renvoie 403 INVALID_INTERNAL_TOKEN, un contexte utilisateur invalide 400 INVALID_USER_CONTEXT, un pays invalide 400 INVALID_COUNTRY_CONTEXT, et une erreur interne 500 INTERNAL_CONTEXT_ERROR.
requireUserContext et requireCountryContext
app.get('/private', requireUserContext, handler);
app.get('/country-specific', requireCountryContext, handler);
requireUserContext renvoie 401 MISSING_USER_CONTEXT en l'absence d'utilisateur ; requireCountryContext renvoie 400 MISSING_COUNTRY_CONTEXT en l'absence de pays.
Gateway : createGatewayProxy(options)
Crée un middleware Express relayant les requêtes vers les microservices selon une table de routes. Il remplace le token d'autorisation, retire les headers d'identité non fiables et peut injecter un utilisateur et un pays depuis des fonctions de confiance. Les statuts et headers de réponse autorisés sont relayés ; les erreurs internes sont masquées au client public.
const proxy = createGatewayProxy({
routes: [
{ prefix: '/di', target: process.env.DI_URL },
{ prefix: '/pics', target: process.env.PICS_URL }
],
getAuthToken,
getUserId: req => req.user?._id,
getCountry: req => req.country,
transport: createFetchTransport(),
timeoutMs: 5000
});
app.use(proxy);
Le premier préfixe correspondant est choisi ; l'ordre des routes est important. Le préfixe est conservé dans le chemin transmis. Le gateway renvoie 404 NOT_FOUND si aucune route ne correspond, 504 SERVICE_UNAVAILABLE pour les timeouts reconnus et 502 SERVICE_UNAVAILABLE pour les autres erreurs de transport.
La bascule fallbackBaseUrl concerne createServiceClient, pas createGatewayProxy.
Transports HTTP
Le contrat d'un transport est :
transport.request({ method, url, headers, body, timeoutMs, stream });
// Promise<{ status, headers, body, raw?, stream? }>
createFetchTransport({ fetchImpl })
Utilise globalThis.fetch par défaut. Prend en charge JSON, texte, réponses sans contenu, timeout et flux. En mode stream, les ReadableStream Web sont convertis en streams Node.js.
const transport = createFetchTransport();
createAxiosTransport({ axios })
Axios est injecté et n'est pas une dépendance obligatoire du paquet.
const axios = require('axios');
const transport = createAxiosTransport({ axios });
Les transports retournent les réponses HTTP même non-2xx ; c'est createServiceClient qui applique la politique d'erreur. Le gateway relaie directement les statuts distants.
Streams
const response = await pics.request({
method: 'GET',
path: '/image/123',
stream: true
});
response.data.pipe(destination);
La bascule automatique peut intervenir avant qu'une réponse streamée ne soit retournée ; elle ne reprend pas un téléchargement déjà commencé sur un autre serveur.
Erreurs
ServiceRequestError expose name, code, status, data, method, url et cause. Les erreurs réseau sont normalisées avec NETWORK_ERROR, les timeouts avec TIMEOUT. Les réponses non-2xx conservent leur status et data.
try {
await keysClient.request({ path: '/health' });
} catch (err) {
if (err instanceof AggregateError) {
console.error('Principal:', err.errors[0]);
console.error('Secondaire:', err.errors[1]);
} else if (err instanceof ServiceRequestError) {
console.error(err.code, err.status, err.url);
} else {
throw err;
}
}
Les messages générés par le paquet sont préfixés par [link].
Sécurité et limites
Le paquet ne stocke pas de secrets maîtres et ne valide pas lui-même les droits métier. Les headers de contexte ne sont fiables qu'après authentification interne et reconstruction depuis des sources de confiance. Le gateway ne divulgue pas les détails techniques des erreurs au client public.
Le fallback n'est ni un circuit breaker, ni un mécanisme de découverte de services, ni un équilibreur de charge. Il ne garantit pas la cohérence de plusieurs requêtes indépendantes. Les opérations non idempotentes doivent faire l'objet d'une stratégie de reprise explicite.
Philosophie
@aventii/link définit les primitives communes de communication inter-MS sans connaître les métiers des services, leurs bases de données ni la façon dont leurs secrets sont stockés. Les consommateurs peuvent créer autant de clients nommés qu'ils le souhaitent.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| jest | ^30.0.0 |