@amsom-habitat/nest-devtools

Outils de développement d'une api : le profiler (/_profiler, traces OpenTelemetry de chaque requête) et GET /coverage (routes couvertes par la collection Postman).

Profiler

Le tracing est démarré par @amsom-habitat/nest-socle/tracing avant Nest, d'après PROFILER_ENABLED ; il lit la config par le sous-chemin ./profiler-config et alimente traceStore (./trace-store), sans Nest. L'interface est montée par ProfilerModule.forRoot(options) (en général via SocleModule.forRoot({ profiler })), qui rend un module vide quand PROFILER_ENABLED est faux. Toute valeur invalide fait échouer le démarrage.

| Option | Variable | Défaut | |---|---|---| | — | PROFILER_ENABLED | false : ni tracing, ni routes | | password | PROFILER_PASSWORD | vide : liste et détail fermés (404) | | allowIps | PROFILER_ALLOW_IPS (virgules) | vide : toutes les IP ; sinon IP exactes ou plages CIDR | | publicDetail | PROFILER_PUBLIC_DETAIL | false : le détail d'une trace exige aussi le mot de passe | | redactedHeaders | — | DEFAULT_REDACTED_HEADERS (noms ou RegExp) | | store | PROFILER_STORE | memory ; redis pour partager les traces entre répliques | | redisUrl | PROFILER_REDIS_URL, puis REDIS_URL | obligatoire avec store: 'redis' | | memoryMaxTraces | PROFILER_MEM_MAX | 100, entre 10 et 2000 | | ttlSec | PROFILER_TTL_SEC | 3600, entre 60 et 604800 ; null (env : -1) = sans expiration | | maxTraces | PROFILER_MAX_TRACES | 200, entre 10 et 10000 ; null (env : -1) = sans limite | | title | PROFILER_TITLE | API Métier V2 (titre de la liste) |

• L'IP testée est req.ip : derrière un proxy, activer trustProxy de Fastify (défaut de bootstrap), jamais l'en-tête X-Forwarded-For brut.
• Masqués par défaut : authorization, cookie, set-cookie, proxy-authorization, x-gateway-key, x-api-key et tout en-tête dont le nom contient token, secret, password ou key.
• Les requêtes vers /_profiler ne sont pas tracées : le tracing branche shouldIgnoreIncomingRequest(url) en ignoreIncomingRequestHook, et le store les écarte de toute façon.
• Les pages (src/profiler/pages/) sont copiées dans dist par npm run build (et prepack).

ProfilerModule.forRoot({ store: 'redis', allowIps: ['10.0.0.0/8'], redactedHeaders: [...DEFAULT_REDACTED_HEADERS, 'x-office'] })

Coverage

CoverageModule.forRoot(options) monte GET /coverage (public) : 200 si chaque route de l'api a une requête dans la collection, 422 sinon (payload identique à la v1). ?scope=all (défaut) inclut aussi les routes hors sourceRoot (socle) ; tout autre scope s'en tient à sourceRoot. ?folder=, ?strict=1, ?verbose=1, ?host=.

| Option | Défaut | |---|---| | collection | COVERAGE_COLLECTION, sinon tests/collection.json (relatif à projectRoot) | | sourceRoot | src | | projectRoot | process.cwd() |

Migration 1.x → 2.0

| 1.x | 2.0 | |---|---| | imports: [CoverageModule] | CoverageModule.forRoot() | | OptionsCoverage | CoverageOptions (+ sourceRoot, projectRoot) | | ProfilerModule (statique) | ProfilerModule.forRoot(options?) | | profilerEnabled(), profilerAllowIps(), profilerPassword() | readProfilerConfig(env), isProfilerEnabled(env) | | Redis si CACHE_STORE=redis et REDIS_URL | PROFILER_STORE=redis (+ PROFILER_REDIS_URL ou REDIS_URL) | | PROFILER_MEM_MAX=-1 (illimité) | refusé : 10 à 2000 | | IP lue dans X-Forwarded-For, comparaison par suffixe | req.ip, IP exacte ou CIDR | | détail d'une trace public | protégé, sauf PROFILER_PUBLIC_DETAIL=true | | ProfilerStoreLifecycle, CoverageController exportés | internes | | ProfSpan, ProfTrace, ProfException, SpanParse (./trace-store) | ProfiledSpan, ProfiledTrace, ProfiledException, ParsedSpan |