(doc) : ajout et modification de docs après arbitrage

2026-01-31 21:09:59 +01:00
parent f99fb3c614
commit 841028d1b2
24 changed files with 3081 additions and 301 deletions
--- a/docs/adr/020-librairies-go.md
+++ b/docs/adr/020-librairies-go.md
@@ -0,0 +1,124 @@
+# ADR-020 : Librairies Go du Backend
+
+**Statut** : Accepté
+**Date** : 2026-01-31
+
+## Contexte
+
+Le backend Go de RoadWave nécessite des librairies tierces pour HTTP, base de données, tests, streaming, etc. Le choix doit privilégier :
+- **Licences permissives** (MIT, Apache-2.0, BSD) sans restrictions commerciales
+- **Performance** (10M utilisateurs, 100K RPS, p99 < 100ms)
+- **Maturité** et maintenance active
+- **Compatibilité** avec PostGIS, HLS, WebRTC
+
+## Décision
+
+Utilisation de **16 librairies open-source** avec licences permissives.
+
+### Core Stack
+
+| Catégorie | Librairie | Licence | Justification |
+|-----------|-----------|---------|---------------|
+| **HTTP Framework** | `gofiber/fiber/v3` | MIT | 36K RPS, WebSocket natif, Express-like |
+| **PostgreSQL** | `jackc/pgx/v5` | MIT | 30-50% plus rapide, PostGIS natif |
+| **Redis** | `redis/rueidis` | Apache-2.0 | Client-side caching, GEORADIUS |
+| **SQL Codegen** | `sqlc-dev/sqlc` | MIT | Type-safe, zero overhead (ADR-013) |
+| **Migrations** | `golang-migrate/migrate` | MIT | Standard, CLI + library |
+
+### Tests
+
+| Catégorie | Librairie | Licence | Justification |
+|-----------|-----------|---------|---------------|
+| **Unitaires** | `stretchr/testify` | MIT | Standard Go (27% adoption) |
+| **BDD** | `cucumber/godog` | MIT | Gherkin natif (ADR-007) |
+| **Intégration** | `testcontainers/testcontainers-go` | MIT | PostGIS réel dans Docker |
+| **Load** | `grafana/k6` | AGPL-3.0 | Performant (OK usage interne) |
+
+### Services Externes
+
+| Catégorie | Librairie | Licence | Justification |
+|-----------|-----------|---------|---------------|
+| **Auth JWT** | `zitadel/zitadel-go/v3` | Apache-2.0 | SDK Zitadel officiel (ADR-008) |
+| **WebRTC** | `pion/webrtc/v4` | MIT | Pure Go, radio live (ADR-002) |
+| **WebSocket** | `coder/websocket` | ISC | Minimal, notifications (ADR-019) |
+| **FCM Push** | `firebase.google.com/go` | BSD-3 | SDK Google officiel (ADR-019) |
+| **HLS/FFmpeg** | `asticode/go-astiav` | MIT | Bindings FFmpeg n8.0 |
+
+### Utilitaires
+
+| Catégorie | Librairie | Licence | Justification |
+|-----------|-----------|---------|---------------|
+| **Config** | `spf13/viper` | MIT | Multi-format, env vars |
+| **Logging** | `rs/zerolog` | MIT | Zero allocation, le plus rapide |
+
+## Alternatives considérées
+
+Voir [analyse détaillée](../ANALYSE_LIBRAIRIES_GO.md) pour comparatifs complets :
+- Framework : Fiber vs Gin vs Echo vs Chi
+- PostgreSQL : pgx vs GORM vs database/sql
+- Redis : rueidis vs go-redis vs redigo
+- Codegen : sqlc vs SQLBoiler vs Ent
+- Logging : zerolog vs zap vs slog
+
+## Justification
+
+### Licences
+- **15/16 librairies** : MIT, Apache-2.0, BSD, ISC (permissives)
+- **1/16** : AGPL-3.0 (k6 load testing, OK usage interne)
+- **Compatibilité totale** : Aucun conflit de licence
+
+### Performance
+- **Fiber** : 36K RPS (5% plus rapide que Gin/Echo)
+- **pgx** : 30-50% plus rapide que GORM
+- **rueidis** : Client-side caching automatique
+- **zerolog** : Zero allocation, benchmarks 2025
+
+### Maturité
+- **Standards** : testify (27% adoption), golang-migrate, viper
+- **Production** : Fiber (33K stars), pgx (10K stars), pion (13K stars)
+- **Maintenance** : Toutes actives (commits 2025-2026)
+
+## Conséquences
+
+### Positives
+- ✅ Aucune restriction licence commerciale
+- ✅ Stack cohérent avec ADR existants (001, 002, 007, 008, 013, 015, 019)
+- ✅ Performance validée (benchmarks publics)
+- ✅ Écosystème mature et documenté
+
+### Négatives
+- ⚠️ **k6 (AGPL-3.0)** : Copyleft, mais OK pour tests internes (pas de SaaS k6 prévu)
+- ⚠️ **Firebase FCM** : Dépendance Google (mitigation via abstraction layer, ADR-019)
+- ❌ Courbe d'apprentissage : 16 librairies à maîtriser (doc nécessaire)
+
+### Dépendances go.mod
+
+```go
+require (
+    github.com/gofiber/fiber/v3 latest
+    github.com/jackc/pgx/v5 latest
+    github.com/redis/rueidis latest
+    github.com/sqlc-dev/sqlc latest
+    github.com/golang-migrate/migrate/v4 latest
+    github.com/stretchr/testify latest
+    github.com/cucumber/godog latest
+    github.com/testcontainers/testcontainers-go latest
+    github.com/zitadel/zitadel-go/v3 latest
+    github.com/pion/webrtc/v4 latest
+    github.com/coder/websocket latest
+    firebase.google.com/go/v4 latest
+    github.com/asticode/go-astiav latest
+    github.com/spf13/viper latest
+    github.com/rs/zerolog latest
+    grafana/k6 latest  // dev only
+)
+```
+
+## Références
+
+- [Analyse complète des librairies](../ANALYSE_LIBRAIRIES_GO.md) (tableaux comparatifs, sources)
+- ADR-001 : Langage Backend (Fiber, pgx, go-redis)
+- ADR-007 : Tests BDD (Godog)
+- ADR-013 : Accès données (sqlc)
+- ADR-015 : Stratégie tests (testify, testcontainers, k6)
+- ADR-019 : Notifications (WebSocket, FCM)