veza/veza-backend-api/PR5_P1_004_005_006_TIMEOUTS_OBSERVABILITY_REPORT.md

PR5 — Timeouts & Observabilité (handlers + stack traces + readyz)

Résumé

Cette PR corrige les problèmes MOD-P1-004, MOD-P1-005, et MOD-P1-006 :

• MOD-P1-004: Timeouts context systématiques dans handlers
• MOD-P1-005: Stack traces conditionnels (dev/DEBUG seulement)
• MOD-P1-006: /readyz tolérance Redis/RabbitMQ (degraded mode)

Items Corrigés

MOD-P1-004: Pas de Timeout Context dans Tous Handlers

Fichiers:

• internal/api/router.go:83 (déjà implémenté)
• internal/middleware/timeout.go (déjà implémenté)

Problème:

• Handlers peuvent bloquer indéfiniment sans timeout

Fix:

• ✅ Déjà implémenté: Le router utilise middleware.Timeout(r.config.HandlerTimeout) globalement
• ✅ Validation: Tous les handlers passent par le middleware timeout (30s par défaut)

Validation:

# Vérifier que le middleware timeout est appliqué
grep -n "middleware.Timeout" internal/api/router.go
# → ligne 83: router.Use(middleware.Timeout(r.config.HandlerTimeout))

MOD-P1-005: Stack Traces dans Logs Prod

Fichiers:

• internal/api/router.go:62-64 (modifié)
• internal/middleware/error_handler.go:148-151 (déjà implémenté)

Problème:

• Stack traces toujours loggés même en production (peut exposer info sensible)

Fix:

1. Amélioration de la logique: Modifié includeStackTrace pour vérifier APP_ENV=development OU LOG_LEVEL=DEBUG

   • Avant: includeStackTrace := r.config.Env != config.EnvProduction (incluait staging)
   • Après: includeStackTrace := r.config.Env == config.EnvDevelopment || r.config.LogLevel == "DEBUG"

2. Error Handler: Déjà implémenté avec condition if includeStackTrace

Validation:

# Test existant
go test ./internal/middleware -v -count=1 -run TestErrorHandler_StackTrace
# ✅ PASS (2 tests: avec et sans stack trace)

MOD-P1-006: /readyz Échoue si Redis/RabbitMQ Down

Fichiers:

• internal/handlers/health.go:142-184 (déjà implémenté)

Problème:

• /readyz peut échouer si Redis/RabbitMQ down (même si DB OK)

Fix:

• ✅ Déjà implémenté: /readyz retourne status "degraded" si Redis/RabbitMQ down, mais reste 200 OK
• ✅ DB critique: Si DB down → 503 "not_ready"
• ✅ Services optionnels: Si Redis/RabbitMQ down → 200 "degraded"

Validation:

# Tests ajoutés
go test ./internal/handlers -v -count=1 -run TestHealthHandler_Readiness
# ✅ PASS (2 tests: degraded mode et database critical)

Fichiers Modifiés

1. internal/api/router.go

   • Ligne 62-64: Amélioration de la logique includeStackTrace pour MOD-P1-005
   • Commentaire MOD-P1-005 ajouté

2. internal/handlers/health_p1_test.go (nouveau)

   • Test TestHealthHandler_Readiness_DegradedMode: Valide que /readyz retourne "degraded" si Redis/RabbitMQ down
   • Test TestHealthHandler_Readiness_DatabaseCritical: Valide que /readyz retourne "not_ready" si DB down

Commandes de Validation

Build

# Compilation
go build ./internal/api ./internal/middleware ./internal/handlers
# ✅ Succès

# Build complet
go build ./cmd/api/main.go
# ✅ Succès

Tests

# Tests stack traces (MOD-P1-005)
go test ./internal/middleware -v -count=1 -run TestErrorHandler_StackTrace
# ✅ PASS (2 tests: IncludeStackTrace_True, IncludeStackTrace_False)

# Tests health readiness (MOD-P1-006)
go test ./internal/handlers -v -count=1 -run TestHealthHandler_Readiness
# ✅ PASS (2 tests: DegradedMode, DatabaseCritical)

# Tous les tests
go test ./... -count=1 -short
# ✅ Tests unitaires passent

Validation Manuelle

MOD-P1-004 (Timeouts):

• ✅ Middleware timeout appliqué globalement dans router.go:83
• ✅ Timeout par défaut: 30s (configurable via HANDLER_TIMEOUT)
• ✅ Tous les handlers passent par le middleware timeout

MOD-P1-005 (Stack Traces):

# En production (APP_ENV=production, LOG_LEVEL=INFO)
# → Stack traces NE sont PAS loggés ✅

# En development (APP_ENV=development)
# → Stack traces SONT loggés ✅

# En DEBUG (LOG_LEVEL=DEBUG)
# → Stack traces SONT loggés ✅

MOD-P1-006 (Health Readiness):

# DB OK, Redis/RabbitMQ down
curl http://localhost:8080/api/v1/readyz
# → Status: 200 OK, body: {"status": "degraded", ...} ✅

# DB down
# → Status: 503 Service Unavailable, body: {"status": "not_ready", ...} ✅

Détails Techniques

Corrections Apportées

1. MOD-P1-004 (Timeouts):

   • ✅ Déjà implémenté: Middleware timeout global dans router.go:83
   • ✅ Timeout par défaut: 30s (configurable via HANDLER_TIMEOUT)
   • ✅ Comportement: Handlers timeout après 30s, retourne 504 Gateway Timeout

2. MOD-P1-005 (Stack Traces):

   • Avant: includeStackTrace := r.config.Env != config.EnvProduction (incluait staging)
   • Après: includeStackTrace := r.config.Env == config.EnvDevelopment || r.config.LogLevel == "DEBUG"
   • Comportement: Stack traces seulement en development ou si LOG_LEVEL=DEBUG

3. MOD-P1-006 (Health Readiness):

   • ✅ Déjà implémenté: /readyz retourne "degraded" si Redis/RabbitMQ down
   • ✅ DB critique: Si DB down → 503 "not_ready"
   • ✅ Services optionnels: Si Redis/RabbitMQ down → 200 "degraded"

Endpoints Vérifiés

• ✅ Tous les handlers: Passent par middleware.Timeout() global
• ✅ /api/v1/readyz: Retourne "degraded" si Redis/RabbitMQ down, "not_ready" si DB down
• ✅ Error Handler: Stack traces conditionnels selon env/LOG_LEVEL

Risques / Limitations

1. Timeouts globaux: Le middleware timeout est appliqué globalement

   • Impact: Tous les handlers ont le même timeout (30s)
   • Mitigation: Timeout configurable via HANDLER_TIMEOUT env var

2. Stack traces en staging: Stack traces ne sont plus loggés en staging (seulement dev/DEBUG)

   • Impact: Debugging plus difficile en staging
   • Mitigation: Utiliser Sentry pour les erreurs en staging/prod

3. Health checks: Tests utilisent SQLite en mémoire

   • Impact: Tests ne reflètent pas exactement le comportement avec PostgreSQL
   • Mitigation: Tests d'intégration avec PostgreSQL pourraient valider le comportement réel

Tests Ajoutés/Modifiés

• ✅ TestErrorHandler_StackTrace (existant): Valide stack traces conditionnels
• ✅ TestHealthHandler_Readiness_DegradedMode (nouveau): Valide degraded mode
• ✅ TestHealthHandler_Readiness_DatabaseCritical (nouveau): Valide DB critique

Documentation

Comportement attendu:

• Timeouts: Tous les handlers timeout après 30s (configurable)
• Stack traces: Loggés seulement si APP_ENV=development OU LOG_LEVEL=DEBUG
• Health readiness:
  • DB down → 503 "not_ready"
  • Redis/RabbitMQ down → 200 "degraded"
  • Tout OK → 200 "ready"

Configuration:

• HANDLER_TIMEOUT: Timeout pour handlers (défaut: 30s)
• APP_ENV: Environnement (development, staging, production)
• LOG_LEVEL: Niveau de log (DEBUG, INFO, WARN, ERROR)

Prochaines Étapes

• ✅ PR5 complétée
• ⏭️ PR6: Quick wins (MOD-P2-004, MOD-P2-010, MOD-P3-001, MOD-P3-002)

---

Statut: ✅ READY FOR REVIEW

Effort: ~6h (comme estimé dans audit: 4h + 1h + 1h)

Breaking Changes: Aucun