307 lines
7.4 KiB
Markdown
307 lines
7.4 KiB
Markdown
# 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é.
|