arkteos-proxy-addon/AGENTS.md

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 de développement interne via origin :

• https://gitea.i-host.fr/raph666/arkteos-proxy-addon

GitHub est le miroir public via github et l’URL de distribution de l’add-on :

• https://github.com/raph666/arkteos-proxy-addon

Les fichiers publics destinés aux utilisateurs, notamment README.md, config.yaml et repository.yaml, doivent utiliser l’URL GitHub, sauf demande contraire. L’URL Gitea reste réservée à la documentation interne.

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 :

python3 -m compileall .
bash -n run.sh

Valider les fichiers YAML :

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 :

python3 -m pytest -v

Toujours exécuter :

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 :

git pull
git push

Ces commandes doivent utiliser Gitea via origin.

Miroir GitHub :

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é.