fix(xmpp): corriger le timeout XMPP — TLS mode + timeouts de connexion/cleanup (#25) (#26)

GUIDE_DEV_PYTHON.md

@@ -275,7 +275,8 @@ Le projet utilise **`pydantic-settings`** pour valider et charger la configurati
 
 > ⚠️ **Décision d'implémentation** :
 > `XMPP_RECIPIENT` a été renommé en `XMPP_TO` dans l'implémentation (aligné avec §10.2.1).
-> Des variables XMPP supplémentaires ont été ajoutées : `XMPP_ENABLED`, `XMPP_HOST`, `XMPP_PORT`, `XMPP_RESOURCE`, `XMPP_USE_TLS`, `XMPP_TIMEOUT`.
+> Des variables XMPP supplémentaires ont été ajoutées : `XMPP_ENABLED`, `XMPP_HOST`, `XMPP_PORT`, `XMPP_RESOURCE`, `XMPP_TLS_MODE`, `XMPP_TIMEOUT`, `XMPP_CONNECT_TIMEOUT`, `XMPP_CLEANUP_TIMEOUT`.
+> `XMPP_USE_TLS` reste supporté mais est **obsolète** (remplacé par `XMPP_TLS_MODE`).
 > Une section `BLOG_ENABLED` et `BLOG_RSS_URL` a été ajoutée dans `.env.example`.
 
 Les variables Pronote sont obligatoires selon les sources activées :
@@ -4066,7 +4067,9 @@ Si le besoin évolue (ex: **plusieurs destinataires**), les étapes suivantes so
 | `XMPP_PORT`                | Port XMPP (5222 pour STARTTLS, 5223 pour TLS direct).                           | `5222`               | `int`             | ❌ Non           |
 | `XMPP_TO`                  | Destinataire unique (ex: `parent@exemple.org`).                             | `None`                | `str`             | ✅ Oui           |
 | `XMPP_RESOURCE`            | Ressource XMPP (ex: `pronote-sync`).                                         | `"pronote-sync"`     | `str`             | ❌ Non           |
-| `XMPP_USE_TLS`             | Utiliser TLS pour la connexion.                                              | `True`                | `bool`            | ❌ Non           |
+| `XMPP_TLS_MODE`            | Mode TLS : `starttls` (défaut), `direct` ou `disabled` (localhost uniquement). | `"starttls"`          | `Literal`         | ❌ Non           |
+| `XMPP_CONNECT_TIMEOUT`     | Timeout de connexion (secondes).                                              | `15`                  | `float`           | ❌ Non           |
+| `XMPP_CLEANUP_TIMEOUT`     | Timeout de nettoyage (secondes).                                              | `10`                  | `float`           | ❌ Non           |
 | `XMPP_TIMEOUT`             | Timeout de connexion (secondes).                                             | `30`                 | `int`             | ❌ Non           |
 
 **⚠️ Notes** :
@@ -4074,6 +4077,7 @@ Si le besoin évolue (ex: **plusieurs destinataires**), les étapes suivantes so
 - **Pas de variables PubSub** : `XMPP_PUBSUB_NODE`, `XMPP_ROOM`, `XMPP_SUBSCRIBERS` **ne doivent pas être introduites** pour l'instant.
 - **Sécurité** : `XMPP_JID`, `XMPP_PASSWORD` et `XMPP_TO` **ne doivent jamais apparaître** dans les logs, erreurs ou fixtures.
 - **Standardisation** : `XMPP_TO` est mappé sur le champ `to` dans le modèle Pydantic.
+- **`XMPP_USE_TLS` obsolète** : remplacée par `XMPP_TLS_MODE` (`starttls`, `direct` ou `disabled`) ; `XMPP_USE_TLS=true` → `direct` et `XMPP_USE_TLS=false` → `starttls`, avec un `DeprecationWarning`.
 
 #### 10.2.2 Exemple de configuration dans `.env`
 
@@ -4086,13 +4090,19 @@ XMPP_HOST=exemple.org
 XMPP_PORT=5222
 XMPP_TO=parent@exemple.org
 XMPP_RESOURCE=pronote-digest
-XMPP_USE_TLS=true
+# XMPP_TLS_MODE : "starttls" (défaut), "direct" (port 5223) ou "disabled" (localhost uniquement)
+XMPP_TLS_MODE=starttls
+# XMPP_USE_TLS=true/false est obsolète mais encore supporté (alias de XMPP_TLS_MODE)
+XMPP_CONNECT_TIMEOUT=15
+XMPP_CLEANUP_TIMEOUT=10
 XMPP_TIMEOUT=30
 ```
 
 #### 10.2.3 Modèle Pydantic pour la configuration XMPP
 
 ```python
+from typing import Literal
+
 from pydantic import SecretStr, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -4118,14 +4128,22 @@ class XmppSettings(BaseSettings):
     port: int = Field(default=5222, ge=1, le=65535)
     to: str | None = None
     resource: str = "pronote-sync"
-    use_tls: bool = True
-    timeout: int = Field(default=30, gt=0)
+    tls_mode: Literal["direct", "starttls", "disabled"] = "starttls"
+    use_tls: bool | None = Field(
+        default=None,
+        deprecated="Utiliser tls_mode à la place (XMPP_USE_TLS obsolète).",
+    )
+    timeout: float = Field(default=30, gt=0)
+    connect_timeout: float = Field(default=15, gt=0)
+    cleanup_timeout: float = Field(default=10, gt=0)
 ```
 
 > **⚠️ Mapping TLS** :
-> - `use_tls=True` → **TLS direct** (port 5223, `enable_direct_tls=True`, `enable_starttls=False`).
-> - `use_tls=False` → **STARTTLS** (port 5222, `enable_starttls=True`, `enable_direct_tls=False`).
-> La validation refuse `use_tls=False` si `host` n'est pas un hôte de boucle locale (`localhost`, `127.0.0.1`, `::1`).
+> - `tls_mode="starttls"` (défaut) → **STARTTLS** (port 5222, `enable_starttls=True`, `enable_direct_tls=False`).
+> - `tls_mode="direct"` → **TLS direct** (port 5223, `enable_direct_tls=True`, `enable_starttls=False`).
+> - `tls_mode="disabled"` → TLS désactivé ; **uniquement** autorisé sur un hôte de boucle locale (`localhost`, `127.0.0.1`, `::1`).
+> - `XMPP_USE_TLS` (`use_tls`) est **obsolète** : `use_tls=True` → `tls_mode="direct"` et
+>   `use_tls=False` → `tls_mode="starttls"` (avec `DeprecationWarning`).
 
 ---