forge-mvc-iot

Module opt-in pour Forge MVC — réception et exposition de données IoT (capteurs, périphériques connectés) via MQTT. Le module reçoit la télémétrie depuis un broker MQTT, la stocke en base (SQL visible) et l'expose via une API HTTP JSON en lecture seule.

Statut

Beta (Development Status :: 4 - Beta). Le module est fonctionnel de bout en bout pour un usage local et pédagogique. Les briques suivantes sont implémentées :

• subscriber MQTT (paho-mqtt) avec contrat de message validé ;
• stockage des événements dans la table iot_events (migration SQL embarquée) ;
• API HTTP JSON en lecture seule, protection Bearer optionnelle ;
• commandes CLI forge iot:doctor, iot:init, iot:listen, iot:simulate ;
• TLS MQTT optionnel.

Limites assumées : pas de JWT/OAuth/RBAC sur l'API (Bearer global uniquement), pas de politique de rétention sur iot_events, rate-limit non distribué. Voir la section « Limites ».

Décisions verrouillées

• Forge Core reste indépendant. forge-mvc ne dépend jamais de forge-mvc-iot. La présence ou l'absence du module IoT ne change rien au fonctionnement du framework.
• forge-mvc-iot dépend de Forge Core. Le module réutilise routeur, contrôleurs, accès base de données, conventions applicatives.
• MQTT est le protocole d'entrée, pas une API front. Mosquitto est le broker recommandé en environnement local (BTS CIEL, ateliers pédagogiques) ; un broker MQTT cloud reste possible.
• Forge Design IoT consomme l'API HTTP JSON exposée par Forge (via ce module), jamais directement le broker MQTT.

Voir Architecture Forge IoT pour la doctrine complète et les règles de séparation.

Installation

pip install forge-mvc-iot

Depuis le monorepo, en mode développement :

pip install -e packages/forge-mvc-iot

La dépendance paho-mqtt est installée automatiquement.

Configuration

Le module lit sa configuration depuis l'environnement (load_iot_config()), avec des valeurs par défaut adaptées à un broker local :

Commandes CLI

• forge iot:doctor — diagnostic statique par défaut (config, package, présence de la migration). Options explicites : --db (teste iot_events en base) et --mqtt (connexion brève au broker).
• forge iot:init — copie la migration SQL embarquée vers mvc/migrations/ du projet. Aucune exécution SQL, idempotente ; puis lancer forge migration:apply.
• forge iot:listen — relie le flux local broker → MqttSubscriber → IotEventRepository.insert() → iot_events.
• forge iot:simulate — publie des mesures factices conformes au contrat MQTT sur forge/{site}/{device_id}/telemetry, sans capteur physique (pédagogique).

Flux complet de démonstration :

forge iot:doctor --mqtt  →  forge iot:simulate  →  forge iot:listen
  →  iot_events  →  GET /api/iot/events

API HTTP

Branchement explicite dans mvc/routes/__init__.py (jamais automatique) :

from forge_mvc_iot import register_iot_routes

register_iot_routes(router)

Routes exposées (GET, lecture seule, JSON) :

Sécurité : si FORGE_IOT_API_TOKEN est défini, les trois routes exigent Authorization: Bearer <token> (comparaison en temps constant via secrets.compare_digest). Sinon l'API est ouverte — acceptable en atelier local, à proscrire en production publique.

Limites

• Authentification API globale (Bearer unique) : pas de scope par site, par device, ni de rotation de clé.
• Pas de politique de rétention / purge / agrégation sur iot_events.
• Rate-limit non distribué.
• API en lecture seule : aucune écriture/commande device via HTTP.

Licence

LicenseRef-Forge-Proprietary — voir le dépôt Forge pour les conditions complètes.