release: prepare arkteos proxy addon 1.0.0
This commit is contained in:
@@ -0,0 +1,306 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Objet du projet
|
||||
|
||||
Ce dépôt contient l’add-on Home Assistant `arkteos-proxy-addon`.
|
||||
|
||||
Son rôle est de maintenir une connexion TCP unique vers une PAC Arkteos et de
|
||||
mettre ce flux à disposition de plusieurs clients TCP.
|
||||
|
||||
Gitea est le dépôt principal :
|
||||
|
||||
- https://gitea.i-host.fr/raph666/arkteos-proxy-addon
|
||||
|
||||
GitHub est uniquement un miroir secondaire :
|
||||
|
||||
- https://github.com/raph666/arkteos-proxy-addon
|
||||
|
||||
## Architecture
|
||||
|
||||
Le proxy comporte deux côtés distincts :
|
||||
|
||||
- côté PAC :
|
||||
- connexion sortante vers `pac_host:pac_port` ;
|
||||
- port par défaut : `9641` ;
|
||||
- côté clients :
|
||||
- écoute sur `0.0.0.0:proxy_port` ;
|
||||
- port par défaut : `9641`.
|
||||
|
||||
Le proxy distribue les données reçues de la PAC vers tous les clients connectés.
|
||||
|
||||
Le proxy peut aussi relayer les données envoyées par les clients vers la PAC
|
||||
lorsque cette fonctionnalité est explicitement activée.
|
||||
|
||||
## Contraintes importantes
|
||||
|
||||
### Connexion PAC unique
|
||||
|
||||
La PAC ne doit avoir qu’une seule connexion TCP active.
|
||||
|
||||
Ne jamais ajouter une seconde connexion concurrente vers la PAC.
|
||||
|
||||
Tous les clients Home Assistant, outils de diagnostic ou autres consommateurs
|
||||
doivent passer par le proxy.
|
||||
|
||||
### Compatibilité protocolaire
|
||||
|
||||
Ne pas inventer de protocole, checksum ou validation non observée.
|
||||
|
||||
Ne modifier ni le contenu ni l’ordre des octets transmis sans preuve issue :
|
||||
|
||||
- d’une capture réelle ;
|
||||
- du comportement actuel ;
|
||||
- ou d’une documentation fiable.
|
||||
|
||||
### Keepalive
|
||||
|
||||
Le proxy envoie actuellement un octet nul toutes les 300 secondes.
|
||||
|
||||
Le rôle exact de ce keepalive côté PAC n’est pas confirmé.
|
||||
|
||||
Ne pas modifier :
|
||||
|
||||
- sa valeur ;
|
||||
- sa fréquence ;
|
||||
- son activation ;
|
||||
|
||||
sans test préalable et justification documentée.
|
||||
|
||||
### Écritures vers la PAC
|
||||
|
||||
Le proxy peut fonctionner en mode bidirectionnel.
|
||||
|
||||
Les données envoyées par les clients peuvent atteindre la PAC si le mode
|
||||
d’écriture est activé.
|
||||
|
||||
Règles :
|
||||
|
||||
- lecture seule par défaut ;
|
||||
- aucune écriture client ne doit être autorisée implicitement ;
|
||||
- toute option d’écriture doit être explicite ;
|
||||
- les écritures vers la PAC doivent être sérialisées ;
|
||||
- utiliser `writer.drain()` après une écriture ;
|
||||
- ne jamais journaliser les données brutes envoyées par un client ;
|
||||
- ne jamais exposer le port du proxy sur Internet ;
|
||||
- aucune authentification réseau ne doit être supposée si elle n’existe pas.
|
||||
|
||||
## Sécurité
|
||||
|
||||
Ne jamais ajouter au dépôt :
|
||||
|
||||
- mot de passe ;
|
||||
- token ;
|
||||
- clé API ;
|
||||
- secret Home Assistant ;
|
||||
- clé privée ;
|
||||
- adresse IP personnelle inutile ;
|
||||
- flow Node-RED contenant des identifiants réels ;
|
||||
- contenu issu d’un autre projet sans rapport avec Arkteos.
|
||||
|
||||
Les exemples doivent utiliser des valeurs neutres :
|
||||
|
||||
- `192.168.1.100`
|
||||
- `PAC_IP`
|
||||
- `CHANGEME`
|
||||
- `example.local`
|
||||
|
||||
Ne jamais afficher une valeur sensible dans les rapports ou les logs.
|
||||
|
||||
## Fichiers principaux
|
||||
|
||||
Vérifier en priorité :
|
||||
|
||||
- `config.yaml`
|
||||
- `repository.yaml`
|
||||
- `Dockerfile`
|
||||
- `run.sh`
|
||||
- `arkteos_proxy.py`
|
||||
- `README.md`
|
||||
- `CHANGELOG.md`
|
||||
- `.gitignore`
|
||||
- `AGENTS.md`
|
||||
|
||||
Le point d’entrée réel doit toujours être confirmé depuis `run.sh` et le
|
||||
Dockerfile.
|
||||
|
||||
## Règles de modification
|
||||
|
||||
Avant toute modification :
|
||||
|
||||
1. afficher l’état Git ;
|
||||
2. inspecter le code existant ;
|
||||
3. distinguer les faits observés des hypothèses ;
|
||||
4. présenter le plan si la modification touche le réseau ou le protocole.
|
||||
|
||||
Ne jamais :
|
||||
|
||||
- supprimer une fonction utile sans accord ;
|
||||
- modifier un port par défaut sans demande ;
|
||||
- modifier le protocole silencieusement ;
|
||||
- remplacer une logique existante par une implémentation supposée ;
|
||||
- modifier plusieurs sujets sans rapport dans le même changement ;
|
||||
- réécrire l’historique Git sans accord explicite ;
|
||||
- utiliser `git push --force` ;
|
||||
- créer un commit, un tag ou un push sans demande explicite.
|
||||
|
||||
## Style Python
|
||||
|
||||
- utiliser `asyncio` lorsque pertinent ;
|
||||
- gérer explicitement les déconnexions ;
|
||||
- fermer proprement les writers ;
|
||||
- utiliser `await writer.wait_closed()` lorsque possible ;
|
||||
- annuler proprement les tâches ;
|
||||
- éviter les tâches asyncio résiduelles après arrêt ;
|
||||
- journaliser les exceptions réseau sans arrêter définitivement le proxy ;
|
||||
- temporiser les boucles de reconnexion ;
|
||||
- éviter les variables globales mutables non protégées ;
|
||||
- utiliser un verrou dédié pour les écritures vers la PAC ;
|
||||
- ne pas réutiliser le verrou de la liste des clients pour les écritures réseau.
|
||||
|
||||
## Journalisation
|
||||
|
||||
Les logs doivent indiquer clairement :
|
||||
|
||||
- connexion à la PAC ;
|
||||
- déconnexion de la PAC ;
|
||||
- tentative de reconnexion ;
|
||||
- connexion d’un client ;
|
||||
- déconnexion d’un client ;
|
||||
- mode lecture seule ou bidirectionnel ;
|
||||
- erreur réseau utile au diagnostic.
|
||||
|
||||
Ne pas journaliser :
|
||||
|
||||
- secrets ;
|
||||
- mots de passe ;
|
||||
- contenu brut des commandes clients ;
|
||||
- flux binaires complets en fonctionnement normal.
|
||||
|
||||
Les logs fréquents doivent éviter de saturer le journal Home Assistant.
|
||||
|
||||
## Tests
|
||||
|
||||
Toute modification fonctionnelle doit être accompagnée de tests lorsque
|
||||
possible.
|
||||
|
||||
Tester au minimum les zones concernées :
|
||||
|
||||
- connexion à la PAC ;
|
||||
- reconnexion après coupure ;
|
||||
- connexion et déconnexion des clients ;
|
||||
- distribution PAC vers plusieurs clients ;
|
||||
- blocage des écritures en mode lecture seule ;
|
||||
- relais client vers PAC en mode autorisé ;
|
||||
- sérialisation des écritures concurrentes ;
|
||||
- keepalive ;
|
||||
- fermeture propre ;
|
||||
- absence de vraie connexion à une PAC pendant les tests.
|
||||
|
||||
Les tests doivent utiliser des mocks, des serveurs asyncio locaux ou des writers
|
||||
simulés.
|
||||
|
||||
## Validations obligatoires
|
||||
|
||||
Avant de proposer un commit :
|
||||
|
||||
```bash
|
||||
python3 -m compileall .
|
||||
bash -n run.sh
|
||||
```
|
||||
|
||||
Valider les fichiers YAML :
|
||||
|
||||
```bash
|
||||
python3 - <<'PY'
|
||||
from pathlib import Path
|
||||
import yaml
|
||||
|
||||
for filename in ("config.yaml", "repository.yaml"):
|
||||
with Path(filename).open(encoding="utf-8") as file:
|
||||
data = yaml.safe_load(file)
|
||||
|
||||
if not isinstance(data, dict):
|
||||
raise SystemExit(f"ERREUR : {filename}")
|
||||
|
||||
print(f"OK YAML : {filename}")
|
||||
PY
|
||||
```
|
||||
|
||||
S’il existe des tests :
|
||||
|
||||
```bash
|
||||
python3 -m pytest -v
|
||||
```
|
||||
|
||||
Toujours exécuter :
|
||||
|
||||
```bash
|
||||
git diff --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
## Versionnement
|
||||
|
||||
La version de l’add-on est définie dans `config.yaml`.
|
||||
|
||||
Avant une release :
|
||||
|
||||
- vérifier la cohérence avec `CHANGELOG.md` ;
|
||||
- vérifier la documentation ;
|
||||
- vérifier que les tests passent ;
|
||||
- vérifier l’absence de secret ;
|
||||
- vérifier les URLs Gitea et GitHub ;
|
||||
- créer le commit avant le tag ;
|
||||
- créer un tag au format `vX.Y.Z`.
|
||||
|
||||
Ne jamais déplacer ou recréer un tag déjà publié.
|
||||
|
||||
## Workflow Git
|
||||
|
||||
Dépôt principal :
|
||||
|
||||
```bash
|
||||
git pull
|
||||
git push
|
||||
```
|
||||
|
||||
Ces commandes doivent utiliser Gitea via `origin`.
|
||||
|
||||
Miroir GitHub :
|
||||
|
||||
```bash
|
||||
git push github main
|
||||
git push github --tags
|
||||
```
|
||||
|
||||
Les remotes attendus sont :
|
||||
|
||||
- `origin` → Gitea ;
|
||||
- `github` → GitHub.
|
||||
|
||||
Ne jamais inverser ces rôles sans demande explicite.
|
||||
|
||||
## Documentation
|
||||
|
||||
Toute modification fonctionnelle doit être reflétée dans :
|
||||
|
||||
- `README.md` ;
|
||||
- `CHANGELOG.md` ;
|
||||
- `config.yaml` si une option est ajoutée ou modifiée.
|
||||
|
||||
La documentation doit décrire le comportement réel du code.
|
||||
|
||||
Ne jamais présenter le proxy comme strictement passif si les clients peuvent
|
||||
écrire vers la PAC.
|
||||
|
||||
## Rapport attendu après modification
|
||||
|
||||
À la fin d’une tâche, indiquer :
|
||||
|
||||
- fichiers modifiés ;
|
||||
- fichiers ajoutés ;
|
||||
- comportement modifié ;
|
||||
- validations exécutées ;
|
||||
- résultats des tests ;
|
||||
- avertissements restants ;
|
||||
- confirmation de l’absence de commit, push ou tag si cela n’était pas demandé.
|
||||
Reference in New Issue
Block a user