Add config validation and dashboard

Add YAML config loading with validation, env overrides for secrets, and a web dashboard exposing health, stats, and recent events.
2026-08-03 12:12:12 -04:00
parent 3f48912ad7
commit 4e1d7cd94a
29 changed files with 2344 additions and 55 deletions
@@ -0,0 +1,94 @@
+# Contributing to ntfy-bridge
+
+## Stack
+
+- **Langage** : [V](https://vlang.io/) — compilé, rapide, syntaxe proche de Go
+- **Dépendances** : Zéro dépendance externe (stdlib V uniquement)
+- **Build** : `v .` → binaire natif statique
+
+## Setup développement
+
+```bash
+# Installer V
+curl -s https://github.com/vlang/v/releases/latest/download/v_linux.zip -o /tmp/v.zip
+unzip /tmp/v.zip -d /tmp && sudo /tmp/v/v symlink
+
+# Cloner
+git clone https://git.dracodev.net/bruno/ntfy-bridge.git
+cd ntfy-bridge
+
+# Compiler (mode dev avec hot reload)
+v watch run .
+
+# Tests
+v test .
+
+# Build production
+v -prod .
+```
+
+## Structure du code
+
+```
+.
+├── main.v          # Entrypoint, flag parsing, orchestration
+├── config.v        # Config loading + validation
+├── server.v        # HTTP server, webhook routing
+├── ntfy.v          # Ntfy HTTP client
+├── dedup.v         # Deduplication + rate limiting
+├── template.v      # Mini template engine
+├── log.v           # Structured logging
+├── docker_watcher.v # Docker socket watcher (Unix)
+├── sources/        # Event types + source-specific transformers
+│   ├── event.v
+│   ├── gitea.v
+│   ├── uptime_kuma.v
+│   ├── docker.v
+│   ├── http_poll.v
+│   ├── generic.v
+│   └── cron.v
+└── *_test.v        # Unit tests
+```
+
+## Ajouter une nouvelle source
+
+1. Créer `sources/ma_source.v`
+2. Implémenter la fonction `transform(raw string, source MaSource) ?Event`
+3. Déclarer le type source dans `sources/event.v`
+4. Référencer le type dans `config.v` (`SourcesConfig`)
+5. Router l'endpoint dans `server.v`
+6. Ajouter un test dans `ma_source_test.v`
+
+## Conventions de code
+
+- **Nommage** : snake_case pour les fonctions/variables, PascalCase pour les structs
+- **Gestion d'erreurs** : utiliser le type `?` (Option/Result) de V
+- **Logging** : `log.info()`, `log.warn()`, `log.error()` avec contexte
+- **Messages de commit** : [Conventional Commits](https://www.conventionalcommits.org/)
+  - `feat: add Gitea webhook transformer`
+  - `fix: handle Docker socket disconnect`
+  - `docs: update ARCHITECTURE.md`
+
+## Tests
+
+```bash
+# Tous les tests
+v test .
+
+# Test spécifique
+v test gitea_test.v
+
+# Avec verbose
+v test . -stats
+```
+
+## CI/CD
+
+Le repo utilise Gitea Actions. Le workflow dans `.gitea/workflows/ci.yml` :
+- Compile en mode `-prod`
+- Lance `v test .`
+- Vérifie le formatting (`v fmt -verify`)
+
+## Questions ?
+
+Ouvrir une issue sur https://git.dracodev.net/bruno/ntfy-bridge/issues