@aventii/link (1.1.1)

Published 2026-11-06 11:17:27 +00:00 by Valentin

Installation

@aventii:registry=
npm install @aventii/link@1.1.1
"@aventii/link": "1.1.1"

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.

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,
    endpoint: 'auto'
});
// result = { status, headers, data }

Options : method (défaut GET), path, query, body, context, headers, timeoutMs, stream (défaut false) et endpoint (défaut auto). 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

La bascule est facultative et ne change pas les clients sans fallbackBaseUrl.

endpoint Comportement
auto Tente le principal, puis le secondaire en cas d'échec pour GET, HEAD ou OPTIONS.
primary Utilise uniquement le principal.
fallback Utilise uniquement le secondaire ; nécessite sa configuration.

En mode auto, la bascule intervient sur erreur réseau, timeout ou réponse HTTP non-2xx, y compris 401 et 403. Les deux serveurs doivent donc appliquer les mêmes contrôles d'accès. Chaque tentative possède son propre timeout ; la durée totale peut approcher le double. Le principal est retenté à chaque nouvelle requête : il n'existe pas de sélection persistante du secondaire.

Les méthodes POST, PUT, PATCH et DELETE ne sont pas rejouées automatiquement : une opération peut avoir été exécutée par le serveur principal avant la défaillance réseau. Les corps de requête Node streamés ne sont pas rejoués non plus.

Si les deux serveurs échouent, le client lève un AggregateError dont errors[0] correspond au principal et errors[1] au secondaire. Sans fallback, une erreur d'appel reste une ServiceRequestError.

Cohérence de plusieurs requêtes

Deux requêtes auto parallèles peuvent aboutir sur des serveurs différents. Pour récupérer une paire de clés cohérente, il faut tenter l'ensemble des requêtes sur un seul serveur, puis rejouer l'ensemble sur l'autre en cas d'échec :

async function readPair(endpoint, id) {
    const [pub, priv] = await Promise.all([
        keysClient.request({ path: `/crypto/public/${id}`, endpoint }),
        keysClient.request({ path: `/crypto/private/${id}`, endpoint })
    ]);
    if (pub.data.version !== priv.data.version) {
        throw new Error('Inconsistent key versions');
    }
    return { publicKey: pub.data.publicKey, privateKey: priv.data.privateKey,
        version: pub.data.version };
}

async function getKeys(id) {
    try {
        return await readPair('primary', id);
    } catch (primaryError) {
        try {
            return await readPair('fallback', id);
        } catch (fallbackError) {
            throw new AggregateError([primaryError, fallbackError], 'Key pair unavailable');
        }
    }
}

Cet exemple suppose un secondaire configuré ; sans celui-ci, il faut propager directement l'erreur du principal. La correspondance des versions ne garantit pas à elle seule la validité cryptographique de la paire. Les deux instances doivent être synchronisées.

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
Details
npm
2026-11-06 11:17:27 +00:00
5
UNLICENSED
11 KiB
Assets (1)
Versions (5) View all
1.2.0 2026-11-06
1.1.1 2026-11-06
1.1.0 2026-11-06
1.0.1 2026-10-12
1.0.0 2026-08-19