ntfy-bridge/docs/ROADMAP.md

ntfy-bridge — Roadmap

Phase 1 : MVP (core engine) — v0.1.0 ✓ DONE

Objectif : daemon qui compile, lit une config, écoute des webhooks et envoie vers Ntfy.

• main.v — CLI args (--config, --version, --validate, --quiet, --help)
• config.v — Chargement + validation du YAML (env overrides NTFY_TOKEN, NTFY_HMAC_SECRET, détection de chemins dupliqués)
• server.v — HTTP server sur :9090 avec routing O(1), dashboard, health/stats endpoints
• event.v — Types de données : Event, Config, Source + template engine render_source_template
• ntfy.v — Client HTTP POST vers Ntfy (topic, message, priority, tags) + retry avec backoff exponentiel (3 tentatives)
• sources/generic.v — Webhook passe-partout (POST raw → Ntfy)
• log.v — Logging structuré (timestamp, level, message) — dual mode: human-readable + JSON
• ntfy-bridge.example.yaml — Config d'exemple complète et commentée

Sortie : ntfy-bridge compile, accepte un webhook générique et l'envoie vers Ntfy. ✅

Phase 2 : Sources spécialisées — v0.2.0 ✓ DONE

• sources/gitea.v — Transformer Gitea (push, PR, issues, releases)
  • Parse le JSON webhook Gitea
  • Template configurable avec variables {repo}, {user}, {action}, {title}, {sha}
  • Priority map par type d'événement
• sources/uptime_kuma.v — Transformer Uptime Kuma
  • Parse le JSON webhook Kuma (heartbeat)
  • state_map pour configurer priority/tags par état (up/down)
  • Template configurable avec variables {monitor}, {status}, {msg}, {ping}, {time}
• sources/docker.v — Watcher socket Docker
  • Connexion au socket Docker Unix (docker_watcher.v)
  • Filtrage par événements (die, health_status, oom)
  • Template de message configurable
  • Multi-hôtes (plusieurs sockets dans la config)
• sources/http_poll.v — Poller HTTP
  • Goroutine de polling périodique (intervalle configurable)
  • Vérification status code + timeout
  • State machine up/down avec notification uniquement au changement
  • Template configurable avec variables {url}, {error}, {status}
• dedup.v — Déduplication + rate limiting
  • Cache avec TTL (5 min par défaut) basé sur hash du message
  • Clé de déduplication : source + type + topic + hash(message)
  • Rate limiting par topic et par source

Bonus (non planifié) :

• sources/cron.v — Webhook pour scripts cron (pass-through)
• webhook.v — Route dispatch O(1) via map[string]WebhookRoute

Sortie : Toutes les sources majeures sont intégrées et fonctionnelles. ✅

Phase 3 : Robustesse — v0.3.0 ✅ DONE

• dedup.v amélioré — Rate limiting déjà intégré dans la phase 2
• Signature webhooks — Vérification HMAC-SHA256 (appliquée à tous les webhooks, pas seulement Gitea)
• Retry logic — Retry avec backoff exponentiel vers Ntfy (3 tentatives, 1s/2s/4s)
• Graceful shutdown — SIGTERM/SIGINT → drain des événements en cours (Linux/macOS)
• Health endpoint — GET /health → 200 + uptime + stats basiques
• Stats endpoint — GET /stats → compteurs par source
• Config reload — SIGHUP → reload config sans redémarrage
• Tests unitaires — config_test.v, gitea_test.v, uptime_kuma_test.v, dedup_test.v

Sortie : Le daemon est prêt pour la production homelab. ✅

Phase 4 : Qualité de vie — v0.4.0 ✅ DONE

• Template engine — Support des variables {key} dans les messages (toutes les sources)

  "🐳 {container_name} → {status} (exit: {exit_code}) on {host}"
  

• Silence rules — POST /api/silence?duration=30m + GET /api/silence + DELETE /api/silence
• Grouping — Regrouper N notifications similaires (buffer 10s, flush avec ×N)
• Webhook secret validation — HMAC global (tous les webhooks, pas seulement Gitea)
• CI/CD via Gitea Actions — .gitea/workflows/ci.yml

Sortie : Expérience utilisateur complète. ✅

Phase 4.5 : Déploiement multi-plateforme — v0.4.5 🔜

Objectif : un seul binaire, une seule commande pour installer/désinstaller le service sur tous les OS supportés.

• service.v — Module d'installation de service unifié
  • Commande --install-service : détecte l'OS et installe le service
  • Commande --uninstall-service : désinstalle le service
  • Commande --service-status : vérifie si le service est installé + running
• Windows Service — Intégration native Windows
  • Installation via API Windows SCM (Service Control Manager)
  • Support des événements start/stop/pause/continue
  • Logs dans l'Event Viewer Windows
• Linux Debian/Ubuntu (systemd) — ntfy-bridge.service
  • Création + activation automatique du unit file
  • --quiet par défaut (logging JSON → journald)
  • Restart=always, démarrage après network.target
• Linux Alpine (openrc) — Script init.d
  • /etc/init.d/ntfy-bridge généré automatiquement
  • Commandes start/stop/restart/status
  • Ajout au runlevel default
• Raspberry Pi (Debian aarch64) — Support confirmé
  • Cross-compilation v -os linux -arch arm64
  • Même unit systemd que Debian x86_64
  • Testé sur Raspberry Pi OS (arm64)
• Docker image multi-arch — docker-compose.yml
  • Build multi-arch : linux/amd64, linux/arm64, linux/arm/v7
  • Image minimale basée sur alpine:latest (~15 MB)
  • docker-compose.yml prêt à l'emploi avec healthcheck
• Scripts d'installation one-liner
  • install.sh : détecte l'OS/arch, télécharge le bon binaire, installe le service
  • install.ps1 : équivalent Windows PowerShell
  • curl -fsSL https://.../install.sh | bash

Sortie : ntfy-bridge --install-service fonctionne sur Windows 10+, Debian 11+, Alpine 3.18+, Raspberry Pi OS (arm64). Un seul flux d'installation quelle que soit la plateforme.

Phase 5 : Futures idées — v0.5.0+

• Web UI minimale — Dashboard HTML avec stats, status, historique (+ API /api/config, /api/status, /api/history)
• Filtres avancés — Expressions conditionnelles par source

  filters:
    - match: { container_name: "test-*" }
      action: drop
  

• Notifications structurées — Support des actions Ntfy (boutons click)
• Intégration Prometheus — Métriques exposées au format OpenMetrics
• Webhook sortant — Forwarder les événements vers un autre webhook (Slack, Discord)
• Support multi-utilisateurs — ACLs par webhook_path
• Fichier d'état — Persistance de l'état up/down des health checks
• Plugin system — Sources customisables via dll/.so (futur lointain)

Fonctionnalités non planifiées mais implémentées

Ces features ont été ajoutées en cours de route :

Feature	Fichier	Description
Source Cron	sources/cron.v	Webhook pass-through pour scripts cron (curl → Ntfy)
Dashboard web	dashboard.html	Interface avec stats, statut des health checks, historique récent
Logging JSON	log.v	Mode JSON structuré activé avec --quiet (pour systemd)
Env overrides	config.v	NTFY_TOKEN et NTFY_HMAC_SECRET depuis l'environnement
Validation dupplicates	config.v	Détection de chemins webhook dupliqués dans la config
Flag --quiet	main.v	Supprime la bannière ASCII au démarrage
Flag -V (version)	main.v	Version courte en plus de --version
API endpoints	server.v	/api/config, /api/status, /api/history pour le dashboard

Suivi des versions

Version	Statut	Contenu
v0.1.0	✅ Terminé	Moteur core + webhook générique + logging
v0.2.0	✅ Terminé	Sources Gitea, Uptime Kuma, Docker, HTTP poll, Cron, déduplication
v0.3.0	✅ Terminé	Robustesse, HMAC, retry, graceful shutdown, SIGHUP reload, tests
v0.4.0	✅ Terminé	Templates, silence, grouping, HMAC global, CI/CD
v0.4.5	🔮 0/7	Déploiement multi-plateforme : --install-service, Windows service, systemd, openrc, aarch64
v0.5.0+	🔮 1/8	Dashboard web — reste filtres, actions Ntfy, Prometheus, etc.