@amsom-habitat/nest-socle

Socle d'une api NestJS 11 + Fastify de la plateforme API Métier V2 : câblage des modules transverses, démarrage, env, tracing du profiler, /health, filtre d'erreurs { statusCode, message }.

// main.ts
import '@amsom-habitat/nest-socle/tracing'; // toujours en première ligne : charge l'env et instrumente
import { bootstrap } from '@amsom-habitat/nest-socle';
import { AppModule } from './app.module';
void bootstrap(AppModule, { name: `api-metier-v2-${process.env.API_NOM}` });

// app.module.ts
SocleModule.forRoot()

• Env : /tracing appelle loadEnv() une seule fois (.env < .env.custom < .env.local, le dernier gagne) ; ConfigModule lit process.env sans relire les fichiers. Ne pas rappeler loadEnv() dans main.ts.
• Tracing : actif seulement si le profiler l'est (PROFILER_ENABLED). Instrumente http, undici, Nest, oracledb et redis ; les spans vont au store du profiler (/_profiler), aucun export OTLP.
• Erreurs : HttpExceptionFilter rend { statusCode, message }, traduit les ORA- (cf. nest-oracle) et journalise toute 5xx avec méthode et URL, sans en exposer le détail. Sortent telles quelles : RawBodyHttpException(body, status) (449 { token }, /health/bdd), JsonErrorException(message, status) ({ "error": message }, la forme que lisent les fronts) et l'échec métier d'une fonction Oracle (OracleCallException : texte de la fonction, {"error": …}, en 400 application/json).
• Routage (posé par createApp avant configureFastify) : verbe absent d'un chemin connu → 405 + Allow au lieu de 404, comme Symfony.
• Santé : GET /health (sans clé de gateway ni base, sonde Docker) rend le contrat v1 { status, service, version, timestamp } ; GET /health/bdd teste Oracle (503 { status: 'error', response_time_ms, error }).

| SocleModule.forRoot | Défaut | |---|---| | oracle | cf. nest-oracle (ORACLE_*) | | auth | cf. nest-auth (GATEWAY_API_KEYS, JWT_KEYS_DIR) | | cache | cf. nest-cache (CACHE_STORE, REDIS_URL) ; false : pas de cache | | profiler | cf. nest-devtools (PROFILER_*) ; false : pas de profiler | | exceptionFilter | HttpExceptionFilter | | health | { service: 'API Metier', version: VERSION ?? '1.0.0' } |

| bootstrap(module, …) | Défaut | |---|---| | name | obligatoire (journal de démarrage) | | port | APP_PORT, sinon 3000 (valeur illisible → erreur) | | host | 0.0.0.0 | | bodyLimit | MAX_FILE_SIZE, sinon 20 Mo | | trustProxy | true (derrière la gateway) | | cors | false : la gateway sert le CORS ; V1_CORS_OPTIONS pour une api jointe en direct | | validation | { whitelist: true, transform: true } (exige class-validator / class-transformer) ; false le retire | | configureFastify | hook sur l'instance Fastify avant Nest |

Un échec au démarrage est journalisé et arrête le process (code 1).

Migration 1.x → 2.0

| 1.x | 2.0 | |---|---| | demarrer(module, { nom, tailleMaxCorps, configurerFastify, … }) | bootstrap(module, { name, bodyLimit, configureFastify, host, validation, … }) | | cors : contrat v1 par défaut | cors: false par défaut ; cors: V1_CORS_OPTIONS pour le garder | | CORS_OPTIONS | V1_CORS_OPTIONS | | chargerEnv() / FICHIERS_ENV | loadEnv() / ENV_FILES ; plus d'appel dans main.ts | | filtreErreurs | exceptionFilter | | oracle: { mapError } | oracle: { functions: { mapError } } (nest-oracle 2) | | HttpException({ token }, 449) renvoyé tel quel | new RawBodyHttpException({ token }, 449) | | fetchOk | @amsom-habitat/nest-http-client | | HealthModule (statique) | HealthModule.forRoot({ service, version }), monté par SocleModule | | initialiserClientOracle() dans main.ts | supprimé : OracleModule initialise le client |