Nouveau paquet hub (Java pur) : envoi asynchrone des franchissements de palier (alerte, setback, expulsion) vers POST /internal/detections du Hub, selon la conception du bloc 2 (section 2) et les contraintes de la revue de securite du Hub. - fil d'envoi a part, file bornee sans verrou, copie sur disque, nouvelles tentatives exponentielles (1 s a 5 min), Retry-After, identifiant d'idempotence conserve ; - le tick serveur n'ajoute qu'un objet en file : aucune entree-sortie, aucune attente ; - cle de la source lue dans un fichier, jamais en dur, jamais journalisee ; - champs conformes au Hub (controle, dimension, version_mod, exemptions), aucune IP ; - reglages [hub] (envoi = false par defaut), commande /garde hub, ANNEXE-HUB.md ; - 55 tests unitaires hors ligne (faux serveur HTTP local). Non compile avec NeoForge ici (Garde, GardeSpec, GardeCommands) : a verifier au build. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
4.9 KiB
4.9 KiB
Annexe : contrat d'envoi des détections au Hub (GastinelGarde, branche feat/signalement-hub)
Source du contrat : conception-hub-bloc2-20261019.md §2, plus la revue de sécurité du Hub (branche feat/sanctions-bloc2,
fichier stacks/accounts/internal/sanctions/ingest.go). Aucune valeur secrète dans ce fichier.
Ce que fait GastinelGarde
- Désactivé par défaut :
[hub] envoi = false. Sans cela,Signalement.surVerdictne fait qu'une lecture de variable. - Quoi : un franchissement de palier (ALERTE, SETBACK ou EXPULSION) par joueur et par contrôle, pas chaque infraction, et jamais un bannissement. Un même palier n'est pas répété pendant
episodeMinutes(10) ; seul un palier plus haut repart. - ENFORCE seulement par défaut. OBSERVE seulement si
envoyerObserve = true; ces détections portentmode = observe(le Hub ne doit jamais les compter). - Gravité : ALERTE = 1, SETBACK = 2, EXPULSION = 3. En ENFORCE, c'est la sanction réellement appliquée ; en OBSERVE, le palier mérité.
- Quand : dans un fil à part (
GastinelGarde-Hub, priorité basse). Le tick ajoute un objet dans une file sans verrou. - Où :
POST <url>/internal/detections,Content-Type: application/json, en-têteX-Source-Cle: <clé>. Pas de redirection suivie. - Clé : lue dans
fichierCle(une ligne, 32 à 256 caractères ASCII visibles, droits 600 conseillés). Jamais dans la configuration, jamais journalisée, jamais écrite dans la file sur disque. - Reprise sur panne : file bornée (
fileMax= 10 000, les plus anciennes sont abandonnées), copie sur disque à l'arrêt et en panne, relue au démarrage ; attente 1 s, 2 s, 4 s … 5 min (+ 25 % au hasard) ;Retry-Afterrespecté (5 min au plus) ; 401 / 403 : nouvel essai toutes les 5 min ; 400 : lot abandonné ; 413 : lot divisé par deux ; détections de plus de 23 h abandonnées (le Hub refuse au-delà de 24 h). - Débit :
debitMaxParMinute= 50 (le Hub accepte 60 par défaut) ; lots de 50 au plus et 15 000 octets (le Hub refuse 16 Kio).
Corps envoyé
{"detections":[{
"id_externe":"<uuid joueur>:<contrôle>:<palier>:<ms>",
"sujet":{"type":"uuid_minecraft","valeur":"<uuid joueur>"},
"type":"<contrôle>", "gravite":1, "mode":"enforce", "points":9.5,
"survenue_le":"2026-10-19T10:00:00Z",
"details":{"controle":"…","palier":3,"exemptions":["…"],"version_mod":"0.3.2","x":0,"y":0,"z":0,"dimension":"minecraft:overworld"}
}]}
Aucun champ service ni source (le Hub les déduit de la clé). id_externe est fixé à la création : toutes les tentatives
d'une même détection portent le même identifiant (idempotence côté Hub).
Conformité aux contraintes du Hub
| Champ | Motif Hub | Côté mod |
|---|---|---|
type |
^[a-z0-9_-]{1,48}$, dans types_autorises de la source |
identifiants des contrôles (killaura-angle, no-fall…) |
id_externe |
^[A-Za-z0-9:._-]{8,128}$ |
vérifié à la création |
details.controle, details.dimension |
^[a-z0-9_.:-]{1,64}$ |
minuscules, autre caractère remplacé par _, 64 au plus |
details.version_mod |
^[0-9A-Za-z.+-]{1,32}$ |
autre caractère remplacé par -, « inconnue » si impossible |
details.exemptions |
10 au plus, chacune ^[a-z0-9_.-]{1,32}$ |
nettoyées, doublons retirés |
details.palier |
entier 0 à 100 | rang de la sanction (ALERTE 2, SETBACK 3, EXPULSION 4) |
details.x/y/z |
entiers ±30 000 000 | position arrondie au bloc, seulement si coordonnees = true |
| texte | aucune adresse IPv4 / IPv6 / préfixe | mêmes motifs que le Hub ; une valeur qui en ressemble est omise |
points |
0 à 99 999 | borné |
survenue_le |
RFC 3339, de −24 h à +5 min | heure serveur, secondes |
autre clé de details |
retirée par le Hub | liste blanche appliquée aussi à la création et à la relecture du disque |
Le texte libre du moteur (Verdict.details(), qui peut contenir un pseudo) n'est jamais envoyé.
À aligner avec le Hub (hypothèses du mod, à confirmer quand la route HTTP du Hub sera écrite)
- Enveloppe :
{"detections":[…]}. Le Hub (Service.Ingerer) prend un tableau de détections mais la route HTTP n'était pas encore écrite à la lecture ; si elle attend un tableau nu, changerEnvoiHub.envoyer(une ligne). - Réponse 200 : tableau d'objets
{id_externe, statut: cree|doublon|refuse, code}; le mod accepte un tableau à la racine ou sousresultats/results/detections/items. Une réponse 200 illisible est tenue pour acceptée. details.palier: le Hub veut un entier ; le mod envoie le rang de l'énumérationSanction. À confirmer.types_autorisesde la sourcegastinelgarde: doit contenir les 15 contrôles (Signalement.typesAttendus()donne la liste).gravite_max≥ 3.- Restriction réseau (D5-B) : côté Hub, par réseau Docker du conteneur Minecraft ; rien à faire dans le mod.