====================================================================
ARR_PUSH_V5_SPEC.txt
Projet : Seedbox Manager
Objet  : Spécification “Autobrr → Sonarr/Radarr v5.0 (release/push)”
Version : 1.0 (2025-10-12)
====================================================================

1) OBJECTIF
-----------
Fiabiliser l’ingestion Sonarr/Radarr depuis des indexers protégés :
Autobrr télécharge le fichier .torrent (cookies côté Autobrr) puis
envoie à Sonarr/Radarr via l’API /api/v3/release/push.

2) ACTEURS & RESPONSABILITÉS
----------------------------
- Autobrr (Filtres + Action Exec) : fournit TorrentUrl/TorrentPath/ReleaseName…
- Moteur (sh + Python fallback)  : télécharge/parse, construit le payload.
- Sonarr/Radarr                  : ingère via /api/v3/release/push.

3) ENTRÉES ATTENDUES (depuis Autobrr)
-------------------------------------
- TorrentUrl     : URL directe du .torrent (avec cookies côté Autobrr)
- TorrentPath    : chemin local du .torrent si déposé par Autobrr (optionnel)
- ReleaseName    : chaîne telle que fournie par l’indexer
- Indexers       : nom logique (ex. autobrr)
- Size           : taille estimée (octets) – optionnel
- InfoUrl        : lien d’info (optionnel)

4) PAYLOAD /release/push (Sonarr/Radarr)
----------------------------------------
{
  "title":        "<ReleaseName or parsed name>",
  "downloadUrl":  "<TorrentUrl>",
  "protocol":     "torrent",
  "indexer":      "<Indexers or 'autobrr'>",
  "size":         <int or 0>,
  "infoUrl":      "<InfoUrl or ''>",
  "publishDate":  "<UTC ISO8601>",
  "guid":         "torrent:<infohash or sanitized_title>"
}

5) RÈGLES DE CONSTRUCTION
-------------------------
- title : ReleaseName ; fallback nom .torrent parsé (bencode).
- guid  : “torrent:<infohash>” si disponible, sinon à partir du titre.
- publishDate : horodatage UTC courant (format ISO 8601 “Z”).
- size : entier ≥ 0 (0 si inconnu).
- indexer : valeur logique homogène (ex. “autobrr”).

6) COMPORTEMENTS D’ERREUR
-------------------------
- HTTP 200/202 = succès d’ingestion.
- HTTP 4xx/5xx = consigner payload et réponse, réessayer (backoff).
- Ne jamais loguer en clair les clés d’API (masquage).

7) JOURNAUX & TRACES
--------------------
- Journal dédié : /scripts/log/arr_push_v5.log
- Inclure : horodatage, cible (sonarr/radarr), HTTP code, durée, taille payload.
- Exclure : clés d’API, cookies.

8) CACHE & FALLBACK (SQLite)
----------------------------
- DB locale (WAL) pour associer release_name ↔ infohash ↔ méta.
- En cas d’absence d’infohash, tenter une récupération par similarité
  sur release_name (entrée la plus récente).

9) PRÉREQUIS & SÉCURITÉ
-----------------------
- Secrets (API keys, cookies) hors logs ; .env séparé en lecture seule.
- Réseau local uniquement entre Autobrr et ARRs.

10) TESTS D’ACCEPTATION (À COMPLÉTER)
-------------------------------------
- T-01 : push succès (200/202).
- T-02 : URL invalide → log + code retour ≠ 0.
- T-03 : absence infohash → fallback DB.
- T-04 : taille non numérique → size=0, pas d’échec.
- T-05 : latence réseau → retry/backoff.

====================================================================
FIN – ARR_PUSH_V5_SPEC.txt
====================================================================
