À propos du projet

# IzgoN IzgoN est un serveur de synchronisation delta conçu pour les flottes d'appareils qui signalent de manière répétée un état similaire. Au lieu de téléverser des charges utiles complètes à chaque cycle, chaque nœud envoie son état actuel via POST ; IzgoN le compare au dernier état vu et renvoie soit `NO_CHANGE` (zéro octet de charge utile), un delta JSON minimal, soit l'état complet lorsqu'un delta serait plus volumineux que l'état qu'il remplace. ## Capacités clés - **Synchronisation delta** : Seuls les champs modifiés sont renvoyés à l'appareil, réduisant considérablement les charges utiles de réponse. - **Synchronisation conditionnelle (v1.4.0+)**: Les appareils qui n'ont pas changé peuvent envoyer un court jeton de somme de contrôle au lieu du rapport complet, de sorte que le rapport lui-même ne circule jamais sur le réseau. - **Mesure des économies** : Le tableau de bord et le point de terminaison `/api/metrics` affichent les économies d'octets en direct dans les deux sens (réponse et liaison montante). - **Outil de benchmark** : `benchmark.py` (stdlib uniquement) rejoue vos propres rapports réels pour mesurer les économies sur vos données, avec un mode synthétique pour les tests. - **Suggestions d'interrogation adaptatives** : Le serveur peut suggérer un intervalle de rapport plus long après plusieurs rapports identiques, avec des compromis explicites de fraîcheur. - **Alertes de silence** : Notifications webhook lorsqu'un nœud cesse de signaler et lorsqu'il revient. - **Synchronisation par lots** : Les appareils qui ont mis en mémoire tampon hors ligne peuvent vider une file d'attente en une seule requête. - **Niveau gratuit** : 10 000 synchronisations sans clé de licence, suffisant pour évaluer. ## Comment cela fonctionne Un nœud envoie son état dans `state` (ou simplement un `checksum` s'il est inchangé). Le serveur répond avec l'un des quatre statuts : - `NO_CHANGE` — rien n'a changé, zéro octet envoyé. - `SYNC_REQUIRED` — seules les clés modifiées sont renvoyées ; le client les fusionne. - `FULL_STATE` — l'état complet et nouveau est renvoyé (lorsqu'un delta serait plus volumineux). - `SEND_STATE` — le serveur n'a pas de référence ou la somme de contrôle est inconnue ; le client doit renvoyer l'état complet. Les objets imbriqués sont différenciés de manière récursive ; les listes sont comparées dans leur ensemble (une limitation délibérée). Un jeton `epoch` facultatif force un état complet après un redémarrage du serveur ou une perte de miroir, empêchant une désynchronisation silencieuse. ## Démarrage rapide ```bash docker run -p 8000:8000 -e DATAPULSE_API_KEY=change-me ghcr.io/izgamber/izgon:latest ``` Ou avec Docker Compose (inclut Redis pour les références persistantes) : ```bash git clone https://github.com/izGamber/IZgoN.git cd IZgoN cp .env.example .env docker compose up -d ``` Tableau de bord à `http://localhost:8000`. Envoyez un état : ```bash curl -X POST http://localhost:8000/api/nodes/sensor-01/sync \ -H "Content-Type: application/json" \ -H "X-API-Key: dev-local-key" \ -d '{"state": {"temp": 21.5, "hum": 60, "batt": 98}}' ``` Répétez le même état → `NO_CHANGE` avec zéro octet de delta. Modifiez un champ → seul ce champ est renvoyé. ## Benchmark sur vos propres données ```bash python3 benchmark.py --payload-file my-reports.json ``` Accepte les tableaux JSON ou JSON Lines, détecte automatiquement les champs d'identifiant d'appareil et mesure le taux de changement à partir de vos données. Mode synthétique : `python3 benchmark.py --nodes 50 --rounds 100 --change-rate 0.05`. Économies mesurées (taux de changement de 5 %) : ~94 % sur la réponse, ~40 % sur la liaison montante (par SIM), ~65 % pour les clients d'interrogation. À un taux de changement de 70 %, les économies chutent à ~35 % — la limite honnête. ## Points de terminaison API | Méthode | Chemin | Authentification | Objectif | |---|---|---|---| | POST | `/api/nodes/{id}/sync` | Clé API | Soumettre l'état ou la somme de contrôle, obtenir delta/complet/NO_CHANGE | | POST | `/api/nodes/{id}/sync/batch` | Clé API | Rejouer la file d'attente mise en mémoire tampon en une seule requête | | GET | `/api/nodes` | Clé API | Lister les nœuds et les références (paginé) | | GET | `/api/metrics` | aucune | Totaux d'économies d'octets en direct | | GET | `/api/license` | aucune | Niveau actuel et synchronisations gratuites restantes | | GET | `/healthz` | aucune | Accessibilité Redis, mode de stockage | | GET | `/` | aucune | Tableau de bord | ## Configuration Tous les paramètres via variables d'environnement (voir `.env.example`). Principaux : - `DATAPULSE_REDIS_URL` — Connexion Redis pour les références - `DATAPULSE_API_KEY` — Clé d'authentification (défaut `dev-local-key`, changez-la) - `DATAPULSE_FREE_TIER_LIMIT` — Synchronisations gratuites avant 402 (défaut 10000) - `DATAPULSE_LICENSE_KEY` — Clé de licence payante (signée Ed25519, validation hors ligne) - `DATAPULSE_ALERT_URL` / `DATAPULSE_ALERT_AFTER` — Alertes de silence - `DATAPULSE_ADAPTIVE` — Activer/désactiver les suggestions d'intervalle d'interrogation - `DATAPULSE_MAX_STATE_DEPTH` / `DATAPULSE_MAX_STATE_BYTES` — Limites de charge utile ## Notes de sécurité - La clé API protège toutes les écritures ; comparaison à temps constant. - `/api/metrics` et `/healthz` ne sont pas authentifiés par conception. - CORS par défaut à `*` ; restreignez-le en production. - Pas de limitation de débit intégrée ; placez derrière un proxy inverse. - L'état est limité en profondeur (32) et en taille (1 Mo). ## Limitations - Les listes ne sont pas différenciées élément par élément ; changer un élément envoie la liste entière. - La réduction des charges utiles peut déclencher `FULL_STATE` (aucune économie sur cette synchronisation). - Le premier rapport de tout nœud est toujours complet. - Les références vivent dans Redis ; si elles sont effacées, les nœuds se resynchronisent une fois. - Instance unique, pas de regroupement. - Pas encore de SDK client ; l'intégration est un simple POST HTTP. ## Licence et tarification Source disponible, pas open source. Niveau gratuit : 10 000 synchronisations. Licence commerciale : paiement unique, sans abonnement, validation de signature Ed25519 hors ligne. Pas de rappel à la maison. ## Statut Version 1.4.2. Construit et maintenu par une personne. Démo en direct à `https://izgon-api.onrender.com` (la première requête peut prendre 20 à 40 secondes pour se réveiller).