lightweight-sdk/packages/server/service-discovery

@lightweight-sdk/service-discovery

Agrégateur d'API reverse-proxy avec enregistrement et découverte de services au runtime. Package server : deux points d'entrée séparés (./client et ./aggregator), zéro dépendance framework (node:http/node:https/fetch uniquement).

Installation

pnpm add @lightweight-sdk/service-discovery

Usage

Un service qui s'enregistre

import { DiscoveryClient } from '@lightweight-sdk/service-discovery/client';

const client = new DiscoveryClient({
	aggregatorUrl: 'http://aggregator.internal:8080',
	serviceName: 'my-service',
	baseUrl: 'http://my-service.internal:3000',
	endpoints: [{ method: 'GET', path: '/users' }],
	sharedSecret: process.env.DISCOVERY_SECRET!,
});

await client.start(); // enregistrement initial + heartbeat périodique

process.on('SIGTERM', () => {
	void client.stop(); // désinscription best-effort, arrête le heartbeat
});

L'agrégateur

import { ServiceAggregator } from '@lightweight-sdk/service-discovery/aggregator';

const aggregator = new ServiceAggregator({ sharedSecret: process.env.DISCOVERY_SECRET! });
aggregator.start(); // démarre le balayage d'expiration (TTL)

Le cœur s'expose comme des handlers Node natifs ((req: IncomingMessage, res: ServerResponse) => void | Promise<void>) — à monter toi-même dans ton serveur existant :

Express (req/res Express sont des IncomingMessage/ServerResponse) :

app.post('/discovery/register', aggregator.registrationHandler);
app.post('/discovery/deregister', aggregator.deregistrationHandler);
app.all('*', aggregator.proxyHandler); // monté en dernier, après tes propres routes

⚠️ '*' seul est spécifique à Express 4. Express 5 a cassé ce wildcard non-nommé (path-to-regexp v8) — il faut '/*splat'.

Fastify (reply.hijack() indique à Fastify de ne plus toucher reply après cet appel) :

fastify.post('/discovery/register', async (request, reply) => {
	reply.hijack();
	await aggregator.registrationHandler(request.raw, reply.raw).catch((e) => request.log.error(e));
});
fastify.all('/*', async (request, reply) => {
	reply.hijack();
	await aggregator.proxyHandler(request.raw, reply.raw).catch((e) => request.log.error(e));
});

node:http brut :

const server = http.createServer((req, res) => {
	if (req.method === 'POST' && req.url === '/discovery/register') return void aggregator.registrationHandler(req, res);
	if (req.method === 'POST' && req.url === '/discovery/deregister') return void aggregator.deregistrationHandler(req, res);
	void aggregator.proxyHandler(req, res);
});

Une requête GET http://aggregator.internal:8080/my-service/users est alors relayée vers http://my-service.internal:3000/users.

Concepts

• Enregistrement = heartbeat : DiscoveryClient.start() envoie un enregistrement initial puis répète le même appel à intervalle régulier (heartbeatIntervalMs). C'est aussi le mécanisme de retry : un échec (agrégateur pas encore démarré, panne transitoire) est juste loggé, le prochain tick réessaie — pas de logique de retry séparée.
• TTL côté agrégateur : chaque enregistrement expire après ttlMs (par défaut 3x l'intervalle de heartbeat par défaut, pour tolérer 1-2 heartbeats manqués) sans renouvellement. Un balayage périodique (sweepIntervalMs) évince les entrées expirées. Pas de persistance : si l'agrégateur redémarre, chaque service se réenregistre au heartbeat suivant.
• Routage par préfixe de nom de service : GET /mon-service/users est matché contre l'endpoint GET /users déclaré par le service mon-service, puis relayé vers ${baseUrl}/users.
• Secret partagé : toute requête d'enregistrement/désinscription doit présenter Authorization: Bearer <secret>. Comparaison en temps constant (crypto.timingSafeEqual).

Options

DiscoveryClientOptions

Option	Défaut	Description
heartbeatIntervalMs	15000	Intervalle entre deux heartbeats
requestTimeoutMs	5000	Timeout de chaque requête d'enregistrement/heartbeat/désinscription
registerPath	/discovery/register	Chemin d'enregistrement sur l'agrégateur
deregisterPath	/discovery/deregister	Chemin de désinscription sur l'agrégateur

ServiceAggregatorOptions

Option	Défaut	Description
ttlMs	45000	Durée de validité d'un enregistrement sans heartbeat
sweepIntervalMs	10000	Fréquence du balayage d'éviction
proxyTimeoutMs	10000	Timeout d'inactivité socket (pas une durée totale) vers le backend
maxRegistrationBodyBytes	65536	Taille max acceptée pour un payload d'enregistrement/désinscription

Limites connues

• Pas de matching :param — le routage fait un match exact du chemin (/users ≠ /users/:id). Une vraie API REST a presque toujours ce genre de routes ; l'ajout d'un matching segment par segment façon Express est une extension future volontairement différée.
• Pas de secret par service — un seul secret partagé pour toute la registry.
• Pas de persistance — décision assumée, voir "Concepts" ci-dessus.
• Collision de nom — un service enregistré sous un nom identique au segment de chemin où tu montes les routes de contrôle (ex. un service nommé discovery si tu montes sous /discovery/*) verrait ses propres endpoints inaccessibles, la route de contrôle étant toujours prioritaire. À éviter par convention de nommage.
• Risque à connaître (pas corrigé) : dans le threat model visé (homelab, services de confiance), un service compromis pourrait déclarer un baseUrl arbitraire et transformer l'agrégateur en proxy ouvert vers ce point (SSRF-like). Aucun enforcement n'est prévu — à garder en tête si le threat model change.

API

• @lightweight-sdk/service-discovery (racine) — protocole partagé uniquement : RegistrationPayload, ServiceEndpoint, HttpMethod, RegistrationAck, DeregistrationPayload.
• @lightweight-sdk/service-discovery/client — DiscoveryClient, DiscoveryClientOptions.
• @lightweight-sdk/service-discovery/aggregator — ServiceAggregator (registrationHandler, deregistrationHandler, proxyHandler, start(), stop(), getRegisteredServiceNames()), ServiceAggregatorOptions.