Architecture et comportement : p2pwatch¶

Une vue d'ensemble lisible du système : sous-systèmes, interactions et cycles de vie à l'exécution. Pour la conception détaillée, voir agents/specs/ (la spec du MVP fait autorité) ; pour exploiter un nœud, voir Faire tourner un nœud ; pour l'état courant et la prochaine étape, voir agents/handoffs/ (le plus récent). Ce document décrit comment ça marche, pas comment le déployer.

1. En une phrase¶

p2pwatch surveille en continu le réseau eMule (eD2k + Kad, via un amuled piloté par l'API REST d'amuleapi) pour retrouver les épisodes perdus du doublage français de Keroro mission Titar, en cataloguant au passage chaque métadonnée croisée. Le catalogue enregistre des fichiers et, là où un protocole en publie un, l'identifiant pseudonyme de la source qui les partageait ; jamais l'adresse réseau d'un pair.

2. Vue d'ensemble des sous-systèmes¶

Un workspace uv de huit paquets, plus des dépendances externes.

Contexte : le nœud et le monde extérieur. Un nœud est deux conteneurs, de deux images. Le cœur, p2pwatch, ne porte que le crawler et sa webui : pas de superviseur, il tourne directement sous PUID:PGID. Le client eMule, ed2k (image p2pwatch-amule), fait tourner s6 (s6-svscan est PID 1), qui en supervise deux services, amuled et le port-sync ; c'est amuled qui démarre amuleapi, et qui l'emporte avec lui en s'arrêtant. Sous la variante VPN, seul ed2k partage le namespace réseau d'ed2k-gluetun : le cœur reste hors du tunnel.

flowchart LR
  subgraph core["p2pwatch · PUID:PGID"]
    crawler["crawler + webui"]
  end
  subgraph client["ed2k · s6"]
    amuled["amuled"]
    amuleapi["amuleapi · REST + web UI"]
    sync["port-sync"]
  end
  gluetun["ed2k-gluetun · VPN"]
  net(("eD2k / Kad"))
  prom["Prometheus · operator's own"]
  notif["Mail / Slack / Discord"]
  out[("ed2k/downloads/incoming")]

  crawler -->|"REST · ed2k:4711"| amuleapi
  amuled -->|"starts, one-off EC token"| amuleapi
  amuleapi -->|"EC · 127.0.0.1:4712"| amuled
  sync -->|"amule.conf + s6-svc"| amuled
  client -->|"all traffic, vpn variant"| gluetun
  gluetun --> net
  amuled -->|"finished files"| out
  crawler -.->|"free space · statvfs, read-only mount"| out
  prom -->|"scrapes /metrics · 8080"| crawler
  crawler -->|"notifications · apprise URL"| notif

Conséquences de cette forme, chacune porteuse ailleurs dans ce document :

• Le point d'accès est une constante de code (ed2k:4711, nom de client amuled), comme le bind 0.0.0.0:8080 de la webui. ed2k est le service d'aMule dans la variante directe, et un alias porté par ed2k-gluetun dans la variante VPN : changer de variante ne touche pas crawler.yml. Celui-ci ne configure que le mot de passe, depuis ${AMULE_API_PASSWORD} : c'est le mot de passe admin d'amuleapi, le même que celui de son interface web. ${AMULE_EC_PASSWORD} ne sert qu'au lien interne amuleapi ↔ amuled, et le cœur ne le voit pas.
• Redémarrer amuled, c'est s6-svc dans ed2k, un redémarrage de processus local, pas un redémarrage de conteneur (§9). amuleapi suit, puisque amuled le relance.
• Les conteneurs démarrent sans ordre (pas de depends_on entre eux), donc le crawler frappe couramment à la porte avant qu'amuled n'ait démarré amuleapi ; « démon injoignable au démarrage » est toléré et absorbé par le backoff.
• Le PID 1 d'ed2k est root (son one-shot python -m p2pwatch_amule boot crée l'utilisateur amule depuis PUID/PGID et prend les bind mounts), puis chaque service abandonne ses privilèges avec setpriv. Le cœur n'a ni point d'entrée ni root : user: dans compose.yml suffit à ce que data/ reste à l'opérateur. Les deux gardent no-new-privileges, pids_limit et mem_limit, sans read_only: ni cap_drop: ALL.
• Docker relance le cœur après toute sortie (restart: unless-stopped), donc une config invalide se voit comme une boucle Restarting. Une sortie propre (le contrôle de redémarrage de la webui) ramène le crawler seul, et amuled garde ses sessions eD2k et Kad.

Aucun conteneur Prometheus ou Grafana n'est livré avec la pile : la webui sert /metrics sur 8080 et un opérateur qui veut des tableaux de bord y pointe son propre Prometheus.

Composants internes et données partagées (le crawler écrit, la webui lit ; matching est une bibliothèque importée) :

flowchart RL
  crawler["Crawler"]
  webui["WebUI · in-process"]
  catalog[("catalog.db")]
  local[("local.db")]
  matching(["matching · lib"])

  crawler -->|writes| catalog
  crawler -->|writes| local
  crawler -->|imports| matching
  webui -->|"read-only"| catalog
  webui -->|imports| matching

Frontières strictes (invariants) : catalog_matching est pur et n'importe jamais p2pwatch ; p2pwatch_amule et p2pwatch ne s'importent jamais l'un l'autre ; pytest_settings, vex_checks, template_checks, coverage_checks et amule_bump ne sont jamais importés par du code livré.

3. Deux modes d'exécution, une seule topologie¶

Le mode découle de la config (crawler.yml, section download), pas d'un flag séparé ni d'un profil compose. Les deux variantes compose assemblent les mêmes services dans les deux cas.

flowchart TB
  app["Supervision · TaskGroup"]
  app --> s["Search"]
  app --> st["Status"]
  app -->|"if download"| d["Download"]

• Téléchargement (download.enabled: true, le défaut livré) : recherche plus téléchargement.
• Catalogue seul (download absent ou enabled: false) : seule la boucle de recherche tourne, avec celle du statut. Le nœud catalogue et notifie, et ne télécharge rien.

Le port-sync n'est pas une boucle du crawler : il tourne dans le conteneur ed2k (§9), et crawler.yml refuse une section port_sync:.

Chaque boucle est une itération suivie d'un sommeil (*_interval_seconds depuis la config), supervisée par un TaskGroup : une boucle qui crashe bruyamment annule ses sœurs (fail-fast), mais les erreurs d'I/O attendues sont absorbées à l'intérieur d'un cycle (voir §10, discipline de frontière).

4. Architecture interne : six hexagones (Clean / Hexagonal)¶

Le dépôt compte six hexagones : six applications, chacune avec son cœur et ses adaptateurs, qui ne s'importent jamais l'une l'autre. Les trois outils de contrôle et amule_bump ne tournent qu'en développement et en CI, jamais dans une image.

Chaque hexagone se découpe en quatre anneaux, lus dans le chemin : domain/, application/, adapters/ et composition/, les ports et adapters/ séparés en driving/ (ce qui appelle le cœur : la ligne de commande, la webui) et driven/ (ce que le cœur appelle : SQLite, amuleapi). Les ports, les cas d'usage, les étapes et le cycle de vie sont les couches de tach dans l'anneau application/. Un __main__.py racine appartient à la composition. Le graphe des imports est un DAG qui pointe vers le domaine pur.

flowchart TB
  comp["composition/ · __main__.py"]
  drivingAdp["adapters/driving/"]
  appl["application/ · cycle de vie, étapes, cas d'usage"]
  ports["application/ports/ · ABC"]
  dom["domain/ · pure"]
  drivenAdp["adapters/driven/ · I/O"]

  comp --> drivingAdp
  comp --> appl
  comp -->|injecte| drivenAdp
  drivingAdp -->|appelle| ports
  appl -.->|implémente| ports
  drivenAdp -.->|implémente| ports
  ports --> dom
  appl --> dom

• Un adaptateur n'importe jamais un autre adaptateur ; un adaptateur pilotant ne dépend que des ports pilotants, un adaptateur piloté que des ports pilotés qu'il implémente ou consomme.
• application/ range ses ports (ports/, un port par fichier, nommé d'après lui), ses cas d'usage (use_cases/), ses étapes (steps/) et au plus un cycle de vie (<x>_lifecycle.py). Un cas d'usage est appelé du dehors, par un port pilotant qu'il implémente sur des ports pilotés. Une étape est un stade du graphe du cycle de vie, appelée seulement par lui ou par une autre étape : une classe, une par module, nommé d'après elle (steps/node_id_resolver.py contient NodeIdResolver), qui reçoit ses dépendances à sa construction et les valeurs du run (le node_id, un fichier) à l'appel. Le cycle de vie (CrawlerLifecycle, PortSyncLifecycle) est le programme de son démarrage à son arrêt, que la composition lance ; il n'a pas de port. Cas d'usage et étapes ne s'importent pas entre eux, ni le cycle de vie. Ce qui n'appelle aucun port va au domaine.
• Chaque hexagone expose build_command_line(...) dans composition/command_line.py, qui construit les adaptateurs, les cas d'usage et la ligne de commande ; __main__.py lit l'état du processus et appelle build_command_line(...).run(argv). La composition construit chaque graphe quand ce qu'il lui faut existe : au démarrage, dans build_command_line ; pendant un appel, en implémentant le port pilotant qui le fait (CrawlerComposition, BootComposition, PortSyncComposition, UnitCoverageComposition).
• Seul un __main__.py lit l'état du processus (argv, l'environnement, le répertoire courant, le logger racine, le répertoire temporaire) et le passe en valeurs ; un adaptateur reçoit de la composition ce qu'il pilote (un répertoire, une URL, un exécutable). Aucun test ne patche un module : monkeypatch et unittest.mock.patch sont refusés par code-pattern-check.
• Un contrôle rend un rapport, un <Thing>Report et ses problems, que la ligne de commande imprime.
• tach check tient ces règles sur tach.toml, où chaque module est déclaré avec ses dépendances ; les règles ast-grep *-imports.yml gardent le cœur sans I/O.

Le crawler¶

• domain/ est pur : pas d'I/O, pas de yaml/DB/réseau/horloge/logging, aucune lecture d'env. L'adapter de config résout ${VAR} dans toute valeur texte de crawler.yml avant que quoi que ce soit n'atteigne le domaine.
• application/ orchestre les cas d'usage asynchrones en parlant à des ports (des ABC). Ses journaux passent eux aussi par un port, Logger, que StdlibLogger implémente sous le nom que la composition dérive du code qui journalise, celui de son module (p2pwatch.application.steps.search_worker), que filtre un opérateur.
• adapters/ portent toutes les I/O et héritent des ports qu'ils implémentent.
• composition/ (CrawlerComposition) charge la config par l'adapter de config, le domaine la valide fail-fast (domain/crawler_config.py), câble les adapters concrets qu'elle décrit, puis lance CrawlerLifecycle (application/crawler_lifecycle.py), la racine du graphe : il résout le node_id, annonce le démarrage, réévalue le catalogue si la politique a changé, puis supervise les boucles.
• composition/command_line.py (build_command_line) construit les ports crawl, validate-config et merge (le cas d'usage MergeCatalogs) et les passe à la ligne de commande, adapters/driving/cli/, qui lit la sous-commande et rend son code de sortie ; python -m p2pwatch lit l'état du processus et la lance.

5. Les tâches de recherche¶

C'est le cœur du système et sa raison d'être : être là 24/7 pour attraper un fichier rare à l'instant où une source le partage. Une tâche par (client, canal, mot-clé) cherche en boucle, toutes en même temps (application/steps/search_task_runner.py).

flowchart TD
  gate["Wait while paused"]
  backoff["Sleep until the backoff ends"]
  search["search(keyword, channel, budget)"]
  record["Record each observation"]
  persist["Persist the backoff<br/>if it changed"]

  gate --> backoff --> search --> record --> persist --> gate

Points clés en chemin :

• Deux canaux par mot-clé : ed2k (multi-serveurs eD2k) et kad. Les noms de canaux sont opaques pour le cœur, qui ne teste jamais leur valeur.
• Pas d'intervalle dans le cœur : un canal cherche aussi souvent que les règles de son réseau le permettent, et c'est l'adaptateur qui les applique dans search(). Pour aMule : deux départs ed2k à 60 s d'écart au moins, un seul en vol ; deux départs Kad sur un même mot Kad (le premier mot de 3 octets du mot-clé) à 60 s d'écart au moins. Un canal lent ne retient jamais un canal rapide.
• Mots-clés minimaux, depuis la config : search.keywords, obligatoire et sans défaut dans le code (keroro + titar dans le crawler.yml livré). keroro ratisse large ; titar est une sentinelle française rare et non saturable (voir le handoff de simplification de la recherche pour le pourquoi : les données réelles ont montré que chercher davantage n'aide pas). La génération de mots-clés par cible a été supprimée.
• Une tâche en backoff dort jusqu'à la fin de son backoff (celui du client ou celui du canal), elle ne boucle jamais à vide. L'attente se mesure sur l'horloge monotone ; backoff_states en garde le début et le délai, et au démarrage suivant le temps écoulé est borné à [0, délai] par remaining_wait, si bien qu'une horloge reculée pendant l'arrêt n'allonge jamais l'attente. La redondance multi-nœuds est entièrement affaire de faire tourner plusieurs nœuds et de fusionner leurs catalogues.
• Le statut n'est pas la liveness : « le processus est vivant » n'implique pas « on peut trouver quelque chose là, maintenant ». Une boucle lit le statut de chaque client toutes les minutes, par canal (connected, connectable), et alerte sur un état dégradé qui dure : 5 min pour un canal, 2 min pour l'API injoignable, puis envoie son rétablissement.
• Résilience : une StoreError à l'écriture du backoff est journalisée, et l'écriture retentée après la recherche suivante.

5.1 Une tâche de recherche, de bout en bout¶

sequenceDiagram
  participant W as SearchWorker
  participant A as amuled
  participant C as catalog.db
  participant E as MatchingEngine
  participant D as Waker

  W->>A: search(keyword, channel, budget)
  A-->>W: SearchAnswer (reported files, skipped results)
  loop each reported file
    W->>C: record_observation(FileObservation)
    W->>C: read_known_filenames(file)
    W->>E: evaluate_file(candidates)
    E-->>W: list[MatchDecision]
    loop each changed decision
      W->>C: record_decision(DatedDecision)
      W-)D: wake (if download tier)
    end
  end

• Un résultat devient un ReportedFile via adapters/driven/amule_api/mapping.py (capture exhaustive : l'identité du fichier, une FileKey dont le hash MD4 est l'identifiant natif sur le réseau ed2k, le nom, la taille, le nombre de sources, plus chaque clé non mappée). La durée, le débit et le codec arrivent maintenant avec le résultat, quand le serveur qui répond les annonce : c'est une déclaration du réseau, jamais une mesure locale, et le champ vaut null sur la plupart des résultats globaux et Kad. Rien n'ouvre jamais le fichier pour en savoir plus. Un fichier annoncé sous plusieurs noms arrive replié en un seul résultat ; le mapper le redéplie en un ReportedFile par nom, comme l'EC en produisait un par entrée. Un résultat sans hash, sans taille exploitable, sans aucun nom ou qui n'est pas un objet est écarté et compté : la SearchAnswer porte ce compte jusqu'à SearchExecuted, qui l'ajoute à p2pwatch_search_results_skipped.
• amuleapi ne date pas ses résultats : Cataloguer (application/steps/cataloguer.py) fait de chaque ReportedFile un FileObservation daté par wall_clock.now() juste avant l'écriture, l'instant où le crawler a appris l'existence du fichier, et marqué du nœud qui l'observe.
• search() rend la main quand amuled signale la fin de la recherche, au plus tard 120 s (le budget, constante du cœur) après son départ réseau. Attendre est l'affaire de l'adaptateur.
• Dans l'adaptateur, une recherche Kad est élargie à chaque tour de sondage à partir du deuxième (POST /search/{id}/more, le bouton « More » d'aMule) jusqu'à ce que Kad réponde 409 kad_more_exhausted. Au premier tour, Kad n'a encore interrogé personne : relancer gaspillerait l'une de ses 4 relances. Un échec de cet appel n'arrête jamais la recherche : on cesse simplement de l'élargir.
• L'observation est écrite (files, observation_variants, observations) puis matchée. La décision (target_id, rule_name, tier) va dans match_decisions. En mode téléchargement, un tier download pousse la boucle de téléchargement pour qu'elle réagisse sans attendre son intervalle.
• Une opération que le démon refuse (400 amuled_rejected) met ce canal en backoff (base × factor^échecs + jitter), persisté à chaque changement.

6. Du fichier à la décision : le moteur de matching¶

Maintenant que la recherche est « bête » (2 mots-clés), c'est le matcher qui porte toute la précision. C'est un moteur fixe minimal plus une politique 100 % YAML (des données validées fail-fast, pas de code par cible).

flowchart LR
  yaml["YAML policy"]
  tgt["targets"]
  eng["MatchingEngine"]
  cand["FileCandidate"]
  dec{"decision?"}

  yaml --> eng
  tgt --> eng
  cand --> eng --> dec
  dec -->|download| a1["download"]
  dec -->|notify| a2["alert"]
  dec -->|catalog| a3["catalog"]
  dec -->|None| a4["discard"]

• Deux natures de tokens : les identifiants d'épisode (spécifiques à une cible : numéro de segment, couverture du titre) face aux marqueurs de source (agnostiques : teletoon, idf1, vf). Un marqueur seul n'identifie aucun épisode, donc il ne fait que rehausser une identification faible (notify -> download), il n'en porte jamais une à lui seul.
• Vetos : ce que le fichier n'est pas. La section vetoes: liste des tokens jugés sur tous les noms connus d'un fichier : un seul nom qui déclenche un veto exclut la cible pour tout le fichier, à tous les tiers. foreign_lang (version étrangère, écritures chinoise, japonaise ou coréenne) et not_episode (film, générique, extrait) excluent toutes les cibles ; other_episode (un numéro d'épisode explicite de 1 à 3 chiffres, comme N°065A, #065, ep 65 ou S02E14, qui n'est pas celui de la cible) n'exclut que les autres épisodes. Le nom de la série n'annonce pas de numéro : Titar 2008 ou keroro 1080p n'excluent rien. Les règles restent positives : elles disent ce que le fichier est.
• Fragments : fragments: nomme des morceaux de regex bruts (le repère d'un numéro d'épisode, la garde contre les dates), substitués en {nom} dans les tokens regex au chargement. Un fragment ne peut ni porter le nom d'un champ de cible (absolute_number, title…) ni en citer un autre.
• Portée des règles : chaque règle déclare un scope obligatoire. segment désigne un segment (un titre, un numéro lettré), episode désigne l'épisode entier (un numéro nu, donc chacun de ses segments), unattributed ne désigne rien. Un matcher.yml sans scope est refusé au démarrage.
• Séparation des formats en trois : la vidéo obtient les tiers actionnables ; une archive obtient notify (pour revue) ; tout le reste (mp3, pdf et compagnie) n'obtient que le tier catalogue permissif (l'invariant « cataloguer chaque métadonnée »).
• Décision déterministe : par cible, la meilleure règle sur tous les noms (le tier le plus haut, download > notify > catalog, puis l'index de règle). Les règles segment et episode donnent une décision par segment désigné ; sans elles, une seule décision unattributed (même ordre, puis le plus petit target_id). L'explication est retournée (pour la webui), jamais loggée.

7. Du téléchargement à la complétion¶

Actif en mode téléchargement seulement. Une itération de DownloadCycle.run, que DownloadLoop répète, enchaîne trois étapes sur une seule session amuleapi, puis, toutes les download.sources_interval_seconds, relève les sources des téléchargements du crawler (§8.3).

flowchart TD
  dec["Decision<br/>download tier"]
  cand["New candidates"]
  pol["decide_download"]
  add["start · amuled"]
  mon["Monitor"]
  comp["Completion<br/>completed flag"]
  done["state = completed<br/>+ notification"]

  dec --> cand --> pol --> add
  add --> mon --> comp --> done

Invariants porteurs (à ne pas violer) :

• Le crawler PROD ne lit jamais les octets téléchargés, et ne touche jamais au répertoire de sortie du tout. La complétion est un signal positif du client, jamais un compte d'octets : chez aMule, une entrée de la file au statut completed (déplacée, en attente de retrait), ou un fichier présent dans les fichiers partagés d'amuled et absent de la file (terminé puis retiré). Une entrée encore en file n'est pas complète, même listée dans les partagés : amuled partage aussi les téléchargements partiels. Ce n'est jamais une inférence sur le contenu.
• Rien ne déplace le fichier terminé. amuled écrit directement dans son propre IncomingDir, bind-mounté sur ed2k/downloads/incoming côté hôte ; le crawler enregistre le changement d'état et notifie, rien de plus.
• Rien n'inspecte le fichier. Il n'y a pas de sniffing de type, pas d'ffprobe, pas d'analyse antivirus : depuis la réduction de périmètre du 2026-09-13, juger si un téléchargement terminé est réellement l'épisode est une étape manuelle effectuée par l'opérateur sur le répertoire de sortie.
• La décision (decide_download) est conservatrice : on saute si tier != download, si la cible est complete, si le hash a déjà été téléchargé (dédup), ou si admettre le fichier casserait le plancher disque. Un épisode déjà found est retéléchargé quand un nouveau hash lui correspond (redondance d'archivage délibérée).
• Le plancher disque (download.min_free_bytes) est mesuré, pas comptabilisé (2026-09-13) : un candidat n'est admis que quand free - outstanding - size >= min_free, où free est un seul appel shutil.disk_usage sur download.output_dir et outstanding ce qu'il reste à transférer à la file d'amuled, pris dans l'instantané de file déjà présent dans le cycle. Le cœur monte le répertoire de sortie en lecture seule, et n'y ouvre aucun fichier : statvfs lit des métadonnées de système de fichiers, jamais des octets. Le ed2k/downloads de l'hôte est monté en entier, pas comme ses deux sous-répertoires, précisément pour que ce statvfs mesure le système de fichiers qui se remplit plutôt que la couche inscriptible du conteneur. Le cœur ne mesure qu'un répertoire de sortie, celui d'aMule. L'espace libre seul serait faux, puisque le système de fichiers ne sait rien des octets encore à venir.
• Un téléchargement que le client ne liste plus est relancé, d'un start() par cycle, tant qu'il est queued ou downloading et jusqu'à ce que le client le liste de nouveau : aMule garde ses téléchargements à travers un redémarrage, slskd non. amuled ne refuse jamais un fichier qu'il détient encore, donc relancer coûte une requête. Au-delà de download.lost_after_seconds (24 h par défaut) sans apparaître, la ligne devient failed avec la raison lost. L'absence se mesure en mémoire, sur l'horloge monotone : DownloadTracker tient l'échéance de chaque téléchargement queued ou downloading, repoussée à chaque cycle où le client le liste. Chaque cycle estampille aussi latest_seen_at pour chaque fichier que downloads() liste, en file ou partagé : au démarrage suivant, l'échéance repart de cette date, le temps écoulé borné à [0, lost_after] par remaining_wait (domain/persisted_wait.py), si bien qu'une horloge reculée pendant l'arrêt n'allonge jamais l'attente au-delà de sa durée. C'est sûr parce qu'une entrée reste dans la file d'amuled même avec zéro source : une absence signifie vraiment disparu. Le client reste l'autorité : une ligne failed qui réapparaît dans sa liste repasse en downloading, sauf s'il y signale lui-même une erreur (raison error), et une ligne qui se complète notifie, même failed.
• Le plancher ne supprime jamais rien, et is_tracked() reste aveugle à l'état : une ligne failed continue de bloquer la remise en file automatique, donc les fichiers terminés s'accumulent toujours sans borne et une nouvelle tentative manuelle passe par la suppression de la ligne.

DownloadState est une enum fermée : queued -> downloading -> completed, ou failed. completed est terminal ; failed n'est terminal que jusqu'à ce qu'amuled en décide autrement.

8. Persistance : deux bases, deux rôles¶

flowchart LR
  subgraph cat["catalog.db · append-only"]
    f["files"]
    ov["observation_variants"]
    o["observations"]
    md["match_decisions"]
    s["sources"]
    sv["source_variants"]
    so["source_observations"]
  end
  subgraph loc["local.db · per node"]
    ni["node_identity"]
    dl["downloads"]
    bs["backoff_states"]
    rs["reevaluation_state"]
  end

• catalog.db (version de schéma 15) : la connaissance accumulée, append-only, chaque table (triggers BEFORE UPDATE/DELETE -> ABORT), pour que N nœuds fusionnent en un seul catalogue (python -m p2pwatch merge). Les insertions sont idempotentes (ON CONFLICT DO NOTHING), donc sans danger en cas de redémarrage en pleine écriture ; jamais INSERT OR IGNORE, qui avalerait aussi une violation de NOT NULL ou de CHECK.
• local.db (version de schéma 15) : l'état d'exécution du nœud (identité, suivi des téléchargements et de leur progression, backoff des recherches, empreinte de la politique réévaluée). Jamais fusionnée : elle appartient à un seul nœud.

La migration catalog/0005 a supprimé file_verifications et local/0004 a supprimé verification_tasks, en réécrivant en completed toute ligne de téléchargement quarantined survivante (cette valeur a quitté DownloadState, et la relire lèverait une erreur). local/0005 a ajouté downloads.last_seen_at, rempli avec queued_at pour qu'aucune ligne antérieure à la mise à niveau ne soit condamnée au premier démarrage. catalog/0006 a supprimé sources, source_observations et file_observation_ranges, que plus rien n'écrit ; un catalogue dont file_observation_ranges contient une ligne refuse de migrer, car un jour compacté ne redevient pas des observations.

catalog/0007 stocke les observations en variantes plus horodatages : une variante (observation_variants) porte ce qui se répète d'une observation à l'autre (nom, durée, débit, raw_meta, mot-clé, nœud ; la taille reste dans files, une seule par fichier, un hash eD2k nommant un seul contenu), et observations ne garde par ligne que l'instant, en microsecondes, et le nombre de sources. raw_meta devient un objet JSON : codec, file_type et complete_source_count à son premier niveau, le reste sous unmapped. catalog/0008 identifie un fichier par (network, native_id), avec pour clé file_id, un UUID v5 de ce couple, identique sur tous les nœuds ; aich_hash disparaît. catalog/0009 rend au disque, par un VACUUM, la place que ces réécritures ont libérée. catalog/0010 crée l'historique des sources en plages de présence. catalog/0011 le refait en points (§8.3) : il supprime source_ranges et source_variants, et recrée la seconde avec node_id, vide, à côté de source_observations. Aucune version livrée n'avait écrit ces plages. catalog/0012 donne à trois colonnes le nom du code (duration_seconds, connectable, session_received_bytes) : un RENAME COLUMN réécrit le schéma, aucune ligne. local/0006 efface l'état du cycle de recherche, qui n'existe plus, et la carte des backoffs. local/0007 identifie un téléchargement par le même file_id que le catalogue, et garde (network, native_id) : file_id est à sens unique, et la boucle doit retrouver le fichier. local/0008 ajoute le cycle de vie d'un téléchargement : octets reçus, dernier progrès, raison d'attente et raison d'échec. bytes_done reste NULL sur les lignes existantes, dont on ignore la progression passée, pour que la première lecture n'invente pas un progrès. local/0009 renomme la table et la colonne de l'empreinte de la politique, désormais reevaluation_state.policy_fingerprint, sans toucher à sa valeur. local/0010 renomme la clé de la carte des backoffs, désormais backoff_states, et la raison d'attente d'un fichier qu'aMule vérifie ou alloue, désormais local_processing. local/0011 remplace scheduler_state par la table backoff_states, STRICT, une ligne par client ou canal en backoff : ses tentatives, le début de son attente en microsecondes et son délai. Les attentes en cours à la mise à niveau sont perdues, et chaque backoff repart de sa base. catalog/0013 renomme raw_meta en raw_metadata dans observation_variants et source_variants, local/0012 downloads.last_seen_at et last_progress_at en latest_seen_at et latest_progress_at : des RENAME COLUMN, comme catalog/0012, qui ne réécrivent aucune ligne. catalog/0014 renomme observed_at en observed_at_micros dans observations et source_observations, local/0013 backoff_states.started_at en started_at_micros : un instant stocké en entier de microsecondes porte son unité dans son nom, par des RENAME COLUMN eux aussi. catalog/0015 reconstruit match_decisions pour stocker l'instant d'une décision en microsecondes, decided_at_micros, au lieu du texte ISO-8601 ; chaque ligne garde son id, qui départage deux décisions du même instant. local/0014 reconstruit downloads en table STRICT, ses quatre instants en microsecondes : queued_at_micros, completed_at_micros, latest_seen_at_micros et latest_progress_at_micros. local/0015 remplace la table clé-valeur node_runtime par node_identity, une seule ligne typée : node_id et created_at_micros. Une base dont node_runtime porte un node_id sans son created_at refuse de migrer plutôt que de perdre l'identité du nœud. reevaluation_state est reconstruite elle aussi, si bien que chaque table de local.db est désormais STRICT. Chaque table du catalogue l'est aussi, déclarée ainsi là où catalog/0008, 0010, 0011 et 0015 la créent, avec un CHECK sur chaque quantité (>= 0), sur tier et connectable, et sur chaque *_micros, entre datetime.min et datetime.max en UTC.

8.1 Écrire une migration¶

À chaque ouverture d'une base, au démarrage du crawler comme pour la destination de merge, l'ouvreur (SqliteDatabaseOpener, dans adapters/driven/persistence_sqlite/sqlite_database_opener.py) applique dans l'ordre chaque script NNNN_*.sql de migrations/catalog/ ou migrations/local/ dont le numéro dépasse le PRAGMA user_version de la base, puis y inscrit ce numéro. Une base plus récente que le code est refusée. Les règles d'écriture :

• Le nom. Un préfixe à quatre chiffres, strictement croissant ; les trous sont permis. Une migration ne s'insère jamais sous un numéro déjà livré : une base inscrite plus haut ne la verrait pas.
• Une transaction par script. L'ouvreur ouvre la transaction, inscrit la version dedans et la valide : un échec annule le script entier et laisse la version inchangée. Le script n'écrit donc ni BEGIN, ni COMMIT, ni ROLLBACK ; un COMMIT égaré lève MigrationError.
• Pas de CREATE TEMP TABLE. L'ouvreur change temp_store autour des migrations, ce qui détruit toute table temporaire.
• foreign_keys reste actif. PRAGMA foreign_keys = OFF est ignoré dans une transaction, sans erreur : la recette ci-dessous s'en passe.

• Remplacer une table, dans cet ordre :

  1. supprimer les triggers et les index des anciennes tables ;
  2. renommer les anciennes tables ;
  3. créer les nouvelles sous leur nom définitif ;
  4. copier ;
  5. supprimer les anciens enfants avant l'ancien parent ;
  6. recréer les triggers append-only.

  Trois comportements de SQLite dictent cet ordre. Renommer une table réécrit les REFERENCES de ses enfants vers le nouveau nom : un enfant qui doit désigner la nouvelle table est donc reconstruit lui aussi. Un index garde son nom quand sa table est renommée, et entrerait en collision avec celui de la nouvelle table. Enfin, chaque enfant d'un parent supprimé doit être supprimé aussi, même vide : il garderait un REFERENCES vers une table absente, et toute insertion échouerait ensuite sur no such table. - Les grosses réécritures posent en tête de script PRAGMA secure_delete = OFF et PRAGMA cache_size = -262144 (256 Mo). Là où SQLite est compilé avec SECURE_DELETE, comme dans l'image, le DROP d'une grosse table garde tout son contenu dans le journal de l'instruction, en mémoire, jusqu'au manque de mémoire ; le cache plus grand accélère une copie limitée par les entrées-sorties. L'ouvreur relit ces deux pragmas avant chaque script et les rétablit après : un script règle ce dont il a besoin et ne remet jamais rien en place. - Les tris passent par des fichiers temporaires (temp_store = FILE) dans le dossier temporaire du conteneur, pas dans /data : un tri en mémoire n'a pas de plafond. - La directive -- migration: no-transaction, seule et exacte en première ligne, fait exécuter le script hors transaction, pour ce qui l'exige comme VACUUM ; la version est inscrite après son succès. Le script doit alors pouvoir être rejoué, car un arrêt entre sa fin et l'inscription le relance au démarrage suivant. - La directive -- migration: copy-before, seule et exacte en première ligne, marque un script qui supprime ou réécrit des lignes : un DELETE, un UPDATE, un DROP TABLE, un INSERT ... SELECT, un INSERT OR REPLACE, un REPLACE INTO, un INSERT ... ON CONFLICT DO UPDATE ou un ALTER TABLE ... DROP COLUMN. Le corps d'un CREATE TRIGGER ne compte pas : il ne s'exécute pas quand le script crée le trigger. Avant d'appliquer des migrations dont une au moins la porte, l'ouvreur copie la base à côté d'elle (la copie d'avant migration). test_migration_directives.py analyse chaque script livré avec sqlfluff et exige la directive exactement quand le script contient l'une de ces instructions : un script qui l'oublie fait échouer la gate. - Une directive au plus par script, aucun n'ayant besoin des deux. Toute autre première ligne commençant par -- migration: est refusée au chargement des scripts.

8.2 Ce qui mérite un CHECK¶

SQLite ne sait pas modifier un CHECK : en changer un reconstruit la table (la recette de §8.1). Une colonne reçoit donc un CHECK seulement si les trois conditions tiennent :

1. Quelque chose en dépend : une règle, une jointure, une unicité ou une route la lit, et une mauvaise valeur la casserait, au lieu de seulement paraître étrange.
2. La ligne seule l'énonce : un CHECK ne voit aucune autre table.
3. Elle ne change qu'avec le schéma (un nouveau réseau, un nouveau rôle), jamais avec la version d'un client ni un détail d'adaptateur.

Sinon, le domaine la valide, et lui seul. Le CHECK n'est jamais la seule défense : le domaine valide d'abord, car son erreur nomme la valeur fautive, là où celle du CHECK ne nomme que son expression. Le CHECK arrête les écrivains qui contournent le domaine : merge, une migration. Par exemple, sources.native_id en 32 caractères hexadécimaux minuscules sur eD2k en a un (une majuscule ferait une seconde identité de la même source), mais pas source_variants.contact_point, dont le format dépend d'un réseau que la ligne ne porte pas.

8.3 L'historique des sources¶

La dernière étape du cycle de téléchargement lit les sources de chaque téléchargement du crawler que l'instantané de file liste sans le dire terminé (SourceClient.sources : GET /downloads/{hash}/clients en pages, puis un GET /clients/{ecid} par source), et les écrit en une transaction par téléchargement. Elle vient après les étapes qui font avancer les téléchargements, pour qu'une erreur en lisant des sources n'en saute aucune. Elle tourne au premier tour après un démarrage, puis au premier tour qui suit download.sources_interval_seconds (300 s par défaut) depuis son dernier départ, que la lecture ait abouti ou non : deux lectures sont donc espacées de l'intervalle, plus un tour au plus. SourceWatcher tient cet instant en mémoire, sur l'horloge monotone.

flowchart LR
  s["sources<br/>network, native_id"] --> v["source_variants<br/>file_id, name, software, role,<br/>contact_point, connectable,<br/>raw_metadata, node_id"]
  v --> o["source_observations<br/>observed_at_micros, session_received_bytes"]

• sources, l'identité : source_id est un UUID v5 de network:native_id, comme file_id mais sous son propre espace de noms. Sur eD2k, native_id est le user hash en minuscules ; un hash de 32 zéros, celui d'un pair qui ne l'a pas encore envoyé, ne fait pas une identité.
• source_variants, un jeu de propriétés qu'un nœud a vu sur un fichier, node_id compris, dédupliqué par content_hash, comme observation_variants. source_id est NULL sans user hash. raw_metadata ne garde que les clés stables que l'adaptateur choisit : une vitesse, un rang de file ou un compteur ferait une variante à chaque lecture. Aucune colonne ne porte l'adresse d'un pair ; contact_point est celle du serveur eD2k de la source.
• source_observations, un point par variante et par lecture, en microsecondes, avec session_received_bytes, le compteur d'octets qu'aMule tient pour ce client (reçus de lui tous fichiers confondus, remis à zéro quand aMule recrée le client). La clé primaire (variant_id, observed_at_micros) refuse un second point au même instant ; l'écrivain l'insère avec ON CONFLICT DO NOTHING, jamais OR IGNORE, qui avalerait aussi le CHECK du compteur (§8.2).

Un état qu'aMule traverse de lui-même (idle, connecting...) prend l'utilité du dernier point de la source sur ce fichier et ce nœud (par source_id, ou par nom sans user hash), si ce point tombe dans les 3 x (download.sources_interval_seconds + download.poll_interval_seconds) qui précèdent la lecture et que son compteur ne dépasse pas celui de la lecture ; sinon le rôle est undetermined. Le délai tolère une lecture manquée.

Toutes ces tables sont append-only, comme le reste du catalogue. merge copie sources et source_variants comme les autres tables, et les points comme observations, la variante retrouvée par son content_hash : une union, indépendante de l'ordre et rejouable.

La webui ne stocke aucune période : elle les calcule à l'affichage, en SQL, par des fonctions de fenêtre sur les seuls points de l'intervalle de la page, 7 jours au plus. Une période réunit les points consécutifs d'une source sur un fichier et un nœud, et se coupe quand la variante change, quand l'écart entre deux points passe webui.source_period_gap_seconds, ou quand le compteur baisse. Seule une période sending montre des octets reçus : la croissance du compteur entre son premier et son dernier point.

Les alertes first_useful et reappeared se décident pour chaque lecture utile d'un téléchargement, une fois sa transaction validée, d'après les points de la source antérieurs au début du tour (Historique des sources). Le dernier point de chaque variante avant ce début coûte une recherche sur la clé primaire, quelle que soit la longueur de l'historique.

9. Port-sync High-ID (optionnel)¶

Derrière un VPN, le port entrant change ; sans High-ID, la connectabilité (et donc la couverture) se dégrade. Le port-sync appartient au client : c'est un service s6 du conteneur ed2k (python -m p2pwatch_amule port-sync, sous l'utilisateur amule), et le cœur n'en sait rien. Toutes les PORT_SYNC_POLL_SECONDS (60 s par défaut), il compare le port forwardé de gluetun au [eMule] Port d'amule.conf. S'ils diffèrent, et si le dernier redémarrage date de plus de PORT_SYNC_RESTART_MIN_SECONDS (300 s) :

flowchart LR
  g["gluetun's port<br/>differs"] --> d["s6-svc -wD -d amuled"]
  d -->|"exit 0"| w["write Port + UDPPort"]
  d -->|"failed or 60 s timeout"| u
  w --> u["s6-svc -u amuled<br/>(always)"]

• amuled n'est jamais laissé arrêté. Un -d laisse le service voulu arrêté : le -u est dans un finally, et le port-sync en envoie aussi un à son démarrage, qui répare un port-sync tué entre les deux.
• L'écriture n'est jamais perdue. amuled écrit toute sa config en sortant : le fichier n'est lu et écrit qu'une fois l'arrêt confirmé par -wD, puis remplacé d'un bloc (fichier temporaire et rename), jamais réécrit sur place.
• Les deux ports reçoivent la même valeur (Port en TCP, UDPPort en UDP pour Kad) : un tunnel ne forwarde qu'un port. amuled ne les lit qu'au démarrage, d'où le redémarrage.
• Les droits. s6 réserve le pilotage d'un service à root, et l'abonnement à ses événements (dont -wD a besoin) au groupe de root. Le script run du port-sync, en root, attend le superviseur d'amuled, lui accorde s6-svperms -G amule -E amule, puis descend vers amule.
• Interrupteur. PORT_SYNC reçoit VPN_PORT_FORWARDING tel quel ; éteint, le one-shot de démarrage pose le fichier down du service, et s6 ne le lance jamais. Allumé, il valide les réglages (Devenir High-ID) avant tout, et sort en nommant une valeur invalide.
• Aucun événement, aucune métrique. Le port-sync journalise chaque changement et chaque échec, rien de plus. Le Low-ID se lit dans le cœur, par la boucle de statut : la jauge p2pwatch_channel_connectable et l'alerte sur un canal non joignable depuis 5 minutes.

Risque accepté : un High-ID augmente l'exposition, voir Devenir High-ID.

10. Observabilité¶

flowchart LR
  uc["étape<br/>dispatch(Event)"]
  desc["plan_observability()<br/>→ ObservabilityPlan"]
  disp["Dispatcher"]
  log["logs"]
  store[("InMemoryNodeMetricStore")]
  prom["webui /metrics"]
  notif["Notifications<br/>apprise URL"]

  uc --> desc --> disp
  disp --> log
  disp -->|NodeMetricWriter| store
  prom -->|"ListNodeMetrics · NodeMetricReader"| store
  disp -->|best-effort| notif

Le domaine émet des Event purs ; une politique pure (plan_observability) les route vers des ObservabilityPlan (sévérité de log + CounterIncrement et GaugeSetting des métriques du nœud + notification, dont le genre donne l'audience COMMUNITY ou OPERATIONS) ; l'étape ObservabilityDispatcher (application/steps/observability_dispatcher.py) les applique. Une notification à la communauté y est une valeur typée (TierRise, SourceAlert, CompletedDownload) : le domaine n'écrit que du texte brut, l'adaptateur AppriseNotifier en écrit le Markdown. Aux opérations, la notification relaie la ligne de log (RelayedLogLine). Un événement qui notifie porte son node_id, que sa notification reprend. Les métriques du nœud sont un état à nous : le dispatcher les écrit par le NodeMetricWriter d'InMemoryNodeMetricStore, et la route /metrics de la webui les lit par le cas d'usage ListNodeMetrics, derrière son port pilotant NodeMetricLister, puis écrit elle-même le format texte 0.0.4 de Prometheus. Le domaine porte le catalogue des métriques, compteurs NodeCounter et jauges NodeGauge, chacun avec sa description et sa classe de labels (ChannelLabels, ClientLabels, DecisionLabels, SourceAlertLabels, ou aucune) : un CounterIncrement ne prend qu'un compteur, un GaugeSetting qu'une jauge, et des labels d'une autre classe que celle de la métrique lèvent une erreur à la construction. Chaque classe écrit ses paires (nom, texte), que le store garde telles quelles pour l'exposition. Rien ne scrape /metrics par défaut : pointez-y votre propre Prometheus si vous voulez des tableaux de bord.

Discipline de frontière (E-D13) : les échecs de notifieur (apprise) et les échecs d'appel au démon sont absorbés (dégradation) ; un échec dans un composant in-process testé à 100 % (par exemple InMemoryNodeMetricStore) crashe bruyamment, parce que c'est un bug, pas un transitoire.

11. Invariants de conception (récapitulatif)¶

• Le catalogue enregistre des fichiers et, là où un protocole en publie un, l'identifiant pseudonyme de la source qui les partageait ; il ne stocke jamais l'adresse réseau d'un pair (IP, port, pays), et ne relie jamais des identifiants d'un réseau à l'autre.
• Le crawler PROD ne lit jamais les octets et ne touche jamais au répertoire de sortie ; la complétion est un signal positif.
• Frontières de paquets : catalog_matching n'importe jamais p2pwatch ; p2pwatch_amule et p2pwatch ne s'importent jamais ; pytest_settings, vex_checks, template_checks, coverage_checks et amule_bump ne sont jamais importés par du code livré.
• Deux modes d'exécution pilotés par la config (téléchargement / catalogue seul), une seule topologie compose par variante.
• Politique de matching 100 % en YAML ; le moteur reste fixe et minimal.
• domain/ est pur ; toutes les I/O vivent dans adapters/ ; le graphe de dépendances est un DAG.
• catalog.db est append-only, chaque table, et fusionnable ; local.db n'est jamais fusionnée.
• Discipline de frontière : absorber les échecs d'I/O externes attendus, laisser crasher le code interne testé.

12. Repères dans le code¶

13. Le healthcheck lit la sortie de s6-svstat, pas son code de retour¶

Si vous écrivez une sonde autour de s6-svstat (un contrôle de supervision, un healthcheck: maison), testez la valeur qu'elle imprime, pas son code de retour : sinon elle déclarera sain un amuled arrêté.

s6-svstat sort en 0 même pour un service arrêté ; avec -u, il imprime false sur la sortie standard. Un code de retour non nul signifie tout autre chose : c'est s6-supervise lui-même qui ne tourne pas pour ce répertoire de service. Le healthcheck livré teste donc la valeur imprimée :

test: ["CMD-SHELL", 'test "$$(s6-svstat -u /etc/services.d/amuled)" = true']

(le $$ est l'échappement compose d'un $ littéral ; dans le conteneur, la commande est test "$(s6-svstat -u /etc/services.d/amuled)" = true).

Ce que unhealthy signifie, et ne signifie pas. Le healthcheck est celui du conteneur ed2k, qui ne passe unhealthy que quand amuled est arrêté. Le cœur n'en a pas : Docker le relance déjà après toute sortie, et l'état d'amuled qu'un healthcheck lui aurait fait rapporter, sa boucle de statut le rapporte et l'alerte.