01 Deux services, un seul lien

Le jeu lui-même est une application Python (FastAPI et Django) : c'est elle qui connaît les joueurs, les ami⁠·⁠es, les parties et les équipes, dans PostgreSQL. Le temps réel est confié à un second service, écrit en Rust avec axum et tokio : il garde les connexions WebSocket ouvertes, sait qui regarde quelle grille et distribue les messages. Les deux ne s'appellent jamais. Leur seul lien, c'est Redis.

Browser HTTPS · /api/… WebSocket · /live/ws Python application FastAPI + Django • decides • signs the ticket • publishes Real-time server Rust · axum • checks the ticket • tracks presence • distributes never a direct call PostgreSQL “the truth” Redis bus + presence PUBLISH PSUBSCRIBE presence
Python décide et publie, Rust distribue : Redis est le seul fil entre les deux.

Ce découpage tient à une règle : Python reste la seule source de vérité. Le serveur Rust ne lit aucune base de données, n'appelle jamais l'API et ne peut rien changer à une partie. Il vérifie qui est au bout de chaque connexion et fait suivre les messages, rien de plus. Les deux services ne partagent qu'un secret, la SECRET_KEY de Django, dont chacun dérive les mêmes clés HMAC.

Ce temps réel sert à trois choses :

  • la rangée au-dessus de la grille, qui montre quel⁠·⁠les ami⁠·⁠es ont la même grille ouverte en ce moment, leurs scores et leurs fins de partie au fil de l'eau ;
  • les réactions rapides entre ami⁠·⁠es (applaudir, une flamme, une fusée…) ;
  • le jeu en équipe en direct : plusieurs ami⁠·⁠es jouent la même grille, chacun⁠·⁠e sur son téléphone, et voient les coups des autres et la case que chacun⁠·⁠e a ouverte.

02 Des signaux, pas des données

Avant le code, le principe qui rend tout le reste simple : un message temps réel n'est jamais la vérité. Il dit « quelque chose a changé », et la page sait toujours retrouver l'état exact en rechargeant la grille depuis l'API.

Information Où elle vit Survit à un redémarrage ?
Parties, réponses, scores, équipes, invitations PostgreSQL oui, c'est la vérité
Qui a la grille ouverte en ce moment un ensemble trié Redis, entrées valables 60 s non, et ce n'est pas grave
La case qu'un⁠·⁠e coéquipier⁠·⁠ère a ouverte nulle part : relayée puis oubliée non
Les messages (« Alice a marqué ») nulle part : relayés puis oubliés non

Un message perdu coûte donc un petit retard, jamais une grille fausse. C'est aussi pour ça que Redis tourne sans persistance ni volume (--save "" --appendonly no) : rien de ce qui y passe ne mérite d'être gardé.

03 Le ticket signé

Pour savoir qui est au bout d'une connexion sans interroger la base, le serveur Rust reçoit un ticket. Quand ta page charge la grille, l'API y joint un petit document signé :

JSON
{
  "v": 2,
  "grid": 42,
  "player": "<ta clé de présence>",
  "friends": [["<clé>", "ABCD2345EFGH"]],
  "team": {"key": "<clé d'équipe>", "members": [["<clé>", "K7MP3QRS9TUV"]]},
  "exp": 1762297200
}
  • player n'est pas ton identifiant de joueur. Cet identifiant est ta seule preuve d'identité sur l'API : qui le connaît joue à ta place. Le ticket porte à la place une clé de présence, un HMAC-SHA256 de ton identifiant tronqué à 32 caractères : la même pour toi à chaque fois, impossible à remonter sans le secret, inutile sur l'API.
  • friends liste les joueurs que tu suis, chacun⁠·⁠e en paire [clé de présence, code ami]. Le serveur se sert de la clé pour reconnaître les connexions, et ne renvoie au navigateur que le code ami, celui que vous vous échangez déjà pour vous ajouter (12 caractères pris dans 23456789ABCDEFGHJKMNPQRSTUVWXYZ, sans 0, O, 1, I ni L).
  • team n'apparaît que si tu joues en équipe sur cette grille. Deux connexions sont coéquipières quand leurs tickets portent la même clé d'équipe.
  • exp : 12 heures après la signature, ou la fermeture de la grille de la semaine si elle vient avant.

Le format est celui de salted_hmac de Django : le JSON compact encodé en base64url, un point, puis la signature. Chaque usage a son propre sel, donc sa propre clé : une valeur fabriquée pour un usage ne peut pas passer pour une autre.

TEXT
ticket      = payload_b64 "." signature
signature   = base64url(HMAC-SHA256(clé, payload_b64))
clé         = SHA-256("stationdoku.live.ticket" + SECRET_KEY)

La page envoie le ticket dans le premier message de la WebSocket, jamais dans l'URL où il finirait dans les journaux d'un proxy. Côté Rust, la signature est vérifiée avant de lire le moindre octet du contenu, et en temps constant :

RUST
// ticket.rs : la signature d'abord, le contenu ensuite.
let (payload_b64, signature) = token.split_once('.').ok_or(TicketError::Shape)?;
let signature = URL_SAFE_NO_PAD
    .decode(signature)
    .map_err(|_| TicketError::Base64)?;
let mut mac = mac(salt, secret);
mac.update(payload_b64.as_bytes());
// Comparaison en temps constant : sa durée ne dit rien de la bonne signature.
mac.verify_slice(&signature)
    .map_err(|_| TicketError::Signature)?;

Une comparaison ordinaire s'arrête au premier octet faux : en chronométrant beaucoup de requêtes, un attaquant pourrait deviner une signature octet par octet. verify_slice prend toujours le même temps. Une fois la signature validée, le contenu est encore vérifié champ par champ (clés de 32 caractères hexadécimaux, codes de 12 caractères de l'alphabet), même si Python l'a signé : un bogue d'un côté ne doit pas devenir un comportement bizarre de l'autre.

Qui vole un ticket peut, jusqu'à son expiration, paraître présent sur cette grille sous ton nom et voir lesquel⁠·⁠les de tes ami⁠·⁠es y sont. Rien d'autre : pas d'identifiant, pas d'autre grille, aucune action sur une partie.

Seuls les joueurs qui ont une raison d'être en direct reçoivent un ticket : ceux qui suivent au moins un⁠·⁠e ami⁠·⁠e, qui sont suivis, ou qui jouent en équipe. La plupart des joueurs n'ont pas d'ami⁠·⁠es sur le site : pas de ticket pour eux, donc pas de WebSocket ni de trafic Redis. La charge du serveur suit la partie sociale du jeu, pas le nombre de visiteurs.

04 La vie d'une connexion

Une WebSocket n'est pas couverte par CORS : sans précaution, n'importe quel site pourrait en ouvrir une vers /live/ws depuis le navigateur d'un visiteur. La première vérification porte donc sur l'en-tête Origin, comparé à la liste des origines autorisées. Ensuite :

  1. le serveur attend au plus 10 secondes un message {"type":"hello","ticket":…} d'au plus 16 Kio ; signature fausse : bad_ticket et fermeture ; ticket expiré : expired et fermeture ;
  2. il enregistre la connexion dans le registre du processus ;
  3. ensuite seulement, il annonce sa présence dans Redis ;
  4. il envoie la liste des ami⁠·⁠es présent⁠·⁠es, et celle des coéquipier⁠·⁠ères si le ticket a une équipe ;
  5. il entre dans sa boucle principale.

L'ordre des étapes 2 et 3 compte. Annoncer d'abord, c'est risquer qu'un⁠·⁠e ami⁠·⁠e arrive dans l'instant où la connexion n'est pas encore enregistrée : ce réveil-là ne trouverait personne, et la liste partirait périmée.

Chaque connexion est une tâche tokio qui attend plusieurs choses à la fois dans une seule boucle select! :

RUST
// ws.rs : la boucle d'une connexion (simplifiée).
let recompute = tokio::select! {
    incoming = socket.recv() => /* un message du navigateur : focus, réaction */,
    Some(message) = queue.recv() => { send_to_client(socket, connection, &message).await?; false }
    () = connection.notified() => true,     // un⁠·⁠e ami⁠·⁠e est arrivé⁠·⁠e ou parti⁠·⁠e
    _ = ticker.tick() => {                  // toutes les 20 s
        send_message(socket, Message::Ping(Bytes::new())).await?;
        state.presence.touch(grid, player, connection_id).await?;
        true
    }
    () = &mut expiry => { /* {"type":"expired"} puis fermeture */ }
    () = shutdown_requested(&mut shutdown) => return Ok(close_code::AWAY),
};
if recompute {
    // relit la présence dans Redis et n'envoie la liste que si elle a changé
}

Le réveil notified() repose sur un tokio::sync::Notify, qui garde au plus un jeton quand personne n'attend. Dix arrivées d'ami⁠·⁠es pendant que la tâche envoie un message se fondent en un seul réveil : la tâche ne rejoue pas les événements, elle relit l'état complet dans Redis, et une relecture suffit pour tous.

À la fermeture, la connexion retire sa présence et, si elle montrait une case à son équipe, publie un « plus de case » pour qu'aucune surbrillance ne reste coincée. Ce nettoyage est une fonction asynchrone appelée explicitement : en Rust, un destructeur (Drop) ne peut pas attendre une opération réseau.

05 Redis comme bus

Chaque grille a six canaux Redis. Chaque processus Rust s'abonne à toutes les grilles d'un coup avec PSUBSCRIBE stationdoku:live:grid:*, reconnaît le canal à son nom et range ses connexions par grille. Quand un message arrive, il ne le donne qu'aux connexions concernées.

Python application PUBLISH Redis stationdoku:live: grid:42:scores grid:42:finished grid:42:notices grid:42 grid:42:reactions grid:42:focus Rust process PSUBSCRIBE stationdoku:live:grid:* A B C delivered to A only Rust process PSUBSCRIBE stationdoku:live:grid:* D E delivered to D only message message published by Python published by Rust 16-message queue per connection
Le bus : Python et Rust publient sur les canaux d'une grille, chaque processus Rust filtre et livre à ses propres connexions.
Canal Ce qu'il porte Publié par
grid:{g} la présence de tel joueur a peut-être changé le serveur Rust
grid:{g}:scores une bonne réponse Python
grid:{g}:finished une partie terminée (gagnée, perdue, abandonnée) Python
grid:{g}:notices un coup d'équipe, une invitation, une disponibilité Python
grid:{g}:reactions une réaction d'un⁠·⁠e ami⁠·⁠e à un⁠·⁠e autre le serveur Rust
grid:{g}:focus la case qu'un⁠·⁠e coéquipier⁠·⁠ère a ouverte le serveur Rust

Le tri se fait avec ce que chaque connexion sait de son propre ticket :

Message Livré aux connexions qui… Jamais à
score, fin de partie de K suivent K K lui-même
réaction de A vers B appartiennent à B et suivent A A
case ouverte par A ont la même clé d'équipe et listent A parmi leurs coéquipier⁠·⁠ères A
notice pour une équipe ont cette clé d'équipe personne n'est exclu

Le destinataire nomme l'expéditeur en cherchant sa clé dans son propre ticket : le serveur n'a besoin d'aucune table globale des joueurs, et un destinataire n'apprend jamais un code qu'il ne connaissait pas déjà. Une réaction exige en plus que le destinataire suive l'expéditeur en retour : un inconnu qui te suit ne peut pas t'en envoyer.

Les notices d'équipe ont un contenu (data, 4 096 octets au plus) que le serveur Rust ne lit jamais : il vérifie l'enveloppe (version, clés, destinataires) et fait suivre le reste tel quel. Ajouter un nouveau type de notice ne demande donc aucune modification du code Rust. Les messages que Python publie sont tout de même validés à la réception : un message mal formé n'est livré à personne et laisse un avertissement dans les journaux, signe que les deux côtés ne sont plus d'accord sur le format.

Plusieurs processus Rust peuvent tourner côte à côte, chacun avec ses propres connexions : Redis est le seul lien entre eux aussi. Si l'abonnement tombe, le processus se reconnecte avec une attente qui double à chaque échec, de 1 à 30 secondes, puis réveille toutes ses connexions pour qu'elles relisent l'état.

Un client lent ne ralentit personne

Chaque connexion a une file de 16 messages, et la livraison n'attend jamais :

RUST
// hub.rs : livrer sans jamais attendre un client lent.
fn push(&self, message: ServerMessage) -> bool {
    match self.queue.try_send(message) {
        Ok(()) => true,
        Err(TrySendError::Full(_)) => {
            self.dropped_count.fetch_add(1, Ordering::Relaxed);
            // compté, signalé au plus une fois par minute, puis oublié
            false
        }
        Err(TrySendError::Closed(_)) => false,
    }
}

Si un téléphone sur une mauvaise connexion ne lit pas assez vite, les messages en trop sont jetés pour lui seul. Comme ce sont des signaux, le prochain rechargement de la grille rattrape ce qui manque.

06 Publier depuis Python

Côté Python, la publication a lieu après la validation de la transaction qui rend le message vrai, sur le canal de la grille concernée, en JSON compact. Les messages d'une même requête partent ensemble, dans un seul pipeline Redis :

PYTHON
# game/live_bus.py
async def publish(*messages: Message | None) -> bool:
    pending = [message for message in messages if message is not None]
    if not pending:
        return True
    if not is_enabled():
        return False
    try:
        async with _redis().pipeline(transaction=False) as pipeline:
            for message in pending:
                pipeline.publish(message.channel, message.payload)
            await pipeline.execute()
    except Exception:
        logger.warning("Publishing live messages failed", exc_info=True)
        return False
    return True

Le client Redis a un délai de 200 ms, et la fonction ne lève jamais d'erreur : un coup ne dépend jamais de Redis. Si Redis ou le serveur Rust tombent, le jeu continue exactement comme avant, seuls les extras du temps réel disparaissent.

Alice's page Python Redis / Rust server Bob's page 1 POST …/guesses locks the team saves the move COMMIT 2 3 PUBLISH notice 4 notice found applies the delta 5 6 response {cell, counters}
Un coup en équipe : la base d'abord, le message ensuite.

Dans une équipe, chaque coup verrouille la ligne de l'équipe en base et relit l'état sous ce verrou. Deux coéquipier⁠·⁠ères qui jouent la même case au même instant passent l'un⁠·⁠e après l'autre : le second reçoit « case déjà prise », sans pénalité. La base n'est écrite qu'une fois par coup, quelle que soit la taille de l'équipe.

La notice d'un coup transporte ce qu'il a changé, un delta : le score, les compteurs d'erreurs et d'indices, le nombre de réponses ouvertes de chaque case, la case trouvée. La page de Bob l'applique sans rien demander à l'API, avec l'animation qui va avec. Mais elle vérifie d'abord que les compteurs se suivent : exactement une case trouvée, une erreur ou un indice de plus que ce qu'elle affiche. Sinon, c'est qu'un message s'est perdu ou est arrivé dans le désordre, et elle recharge la grille. Un delta trop gros pour la notice (au-delà de 4 096 octets) est simplement omis : la page recharge aussi.

07 La présence, un bail qui expire

Savoir qui a la grille ouverte repose sur un ensemble trié Redis par grille, stationdoku:live:grid:{g}:presence.

stationdoku:live:grid:42:presence sorted set member · key:connection score = expiry time d41e:c77 12:03:41 lease expired a3b9:c05 12:04:31 k7f2:c91 12:04:48 k7f2:c14 12:05:02 60 s lease expires if not renewed renewed every 20 s sweep every 15 s 0 s 20 s 40 s 60 s 80 s
Une entrée par onglet ouvert : un processus qui plante cesse de renouveler ses baux, et ses joueurs disparaissent d'eux-mêmes.
  • Une entrée par connexion, pas par joueur (clé:connexion) : avec deux onglets ouverts, tu restes présent⁠·⁠e tant que l'un des deux l'est.
  • Le score est l'heure d'expiration, en millisecondes, une minute plus tard : c'est un bail, que la connexion renouvelle toutes les 20 secondes. Un processus qui plante cesse de renouveler, et ses entrées meurent d'elles-mêmes.
  • La clé expire 2 minutes après la dernière écriture : la présence d'une grille abandonnée disparaît entièrement.

Chaque écriture modifie l'ensemble et publie un événement : pour qu'aucun plantage ni aucun autre processus ne se glisse entre les deux, ce sont des scripts Lua, que Redis exécute d'un bloc. Celui qui annonce une arrivée ne publie que si l'entrée est nouvelle, pour qu'un simple renouvellement ne réveille personne :

LUA
-- touch.lua
local added = redis.call('ZADD', KEYS[1], ARGV[2], ARGV[3])
redis.call('EXPIRE', KEYS[1], ARGV[4])
if added == 1 then
    redis.call('PUBLISH', ARGV[1], ARGV[5])
end
return added

Les scripts sont embarqués dans le binaire et envoyés par EVALSHA, avec repli sur EVAL si Redis les a oubliés. Un balayage, toutes les 15 secondes et dans chaque processus, retire les baux expirés et prévient une seule fois par joueur, même si plusieurs processus balaient en même temps.

Le calcul de la liste à afficher est une fonction pure, facile à tester : garder les entrées non expirées, traduire chaque clé en code ami grâce au ticket, retirer la sienne, dédoublonner, trier. Et comme le pub/sub de Redis ne garde pas les messages publiés pendant une reconnexion, chaque connexion refait ce calcul toutes les 20 secondes : un événement perdu coûte au plus 20 secondes de retard. La liste n'est renvoyée au navigateur que si elle a changé, donc ce battement ne coûte aucun trafic.

08 Ce que le navigateur peut envoyer

Après le hello, la page n'envoie que deux choses, et Python n'y est pour rien :

  • la case ouverte, {"type":"focus","cell":[3,12]}, ou null quand elle se referme. Passer par l'API coûterait une requête, une transaction et une publication à chaque tap, pour une information sans valeur une seconde plus tard ;
  • une réaction, {"type":"react","to":"ABCD2345EFGH","reaction":"clap"}, parmi cinq possibles (clap, fire, wow, muscle, rocket), jamais de texte libre.

Les deux passent par un seau à jetons par connexion : 10 cases d'avance et un jeton de plus toutes les 100 ms pour le focus, 3 réactions d'avance et une de plus toutes les 2 secondes pour les réactions. Le seau prend l'heure en paramètre au lieu de la lire lui-même, ce qui le rend testable sans attendre :

RUST
// reaction.rs
pub fn try_take(&mut self, now: Instant) -> bool {
    let elapsed = now.saturating_duration_since(self.refilled_at);
    let earned = elapsed.as_nanos() / self.refill.as_nanos();
    // … ajoute les jetons gagnés, plafonnés à `burst`, puis en prend un s'il en reste
}

Tout message mal formé ou refusé est ignoré sans réponse : renvoyer une erreur n'aiderait que quelqu'un qui sonde le serveur, un client honnête n'en envoie jamais.

09 Les tickets changent, les connexions restent

L'API signe un nouveau ticket à chaque chargement de la grille, et son exp avance à chaque fois : deux tickets pris à quelques secondes d'écart sont toujours différents. En équipe, la page recharge la grille après certaines notices : se reconnecter à chaque nouveau ticket ferait clignoter la présence de toute l'équipe à chaque coup.

Le ticket arrive donc avec une clé de connexion, un SHA-256 de son contenu sans exp, tronqué à 16 caractères. Elle change quand la grille, les ami⁠·⁠es ou l'équipe changent, jamais quand seule l'expiration avance. La page ne se reconnecte que si elle change ; sinon, elle garde le nouveau ticket pour la prochaine reconnexion, qui a lieu une fois toutes les 12 heures.

Quand Bob rejoint l'équipe d'Alice en cours de partie, sa réponse contient un ticket avec l'équipe : sa page se reconnecte. Le ticket d'Alice, signé avant, ne le connaît pas encore ; mais la notice joined est adressée à la clé d'équipe, qu'Alice possède déjà. Sa page recharge la grille, reçoit un ticket qui liste Bob et se reconnecte à son tour. Pendant cette fraction de seconde, Alice reçoit déjà les coups de Bob, mais pas encore la case qu'il a ouverte.

10 En production

  • Caddy envoie /live/* au conteneur du serveur temps réel, avant la règle de l'application. Il n'y a qu'un conteneur temps réel, pas de bascule bleu-vert comme pour l'application : un déploiement coupe toutes les WebSockets, et les pages se reconnectent avec une attente exponentielle, de 1 à 30 secondes, à ±20 % près pour que tous les onglets ne reviennent pas au même instant.
  • L'image Docker est construite en deux étapes : la compilation dans une image Rust, puis le seul binaire copié dans une Debian minimale, lancé par un utilisateur sans privilèges. Elle n'a pas curl : le binaire sait sonder sa propre route /live/health (stationdoku-live --healthcheck), qui répond après un PING à Redis.
  • L'arrêt est propre : sur SIGTERM, le serveur cesse d'accepter des connexions, demande à chacune de se fermer et leur laisse jusqu'à 5 secondes pour retirer leur présence de Redis, pour que les ami⁠·⁠es voient le départ tout de suite.
  • Le secret est celui de Django, passé au conteneur : changer la SECRET_KEY change tout d'un coup. Les tickets en cours deviennent invalides, et les pages en reçoivent de nouveaux au chargement suivant.
  • Les journaux ne contiennent jamais rien d'identifiant : ni identifiant de joueur, ni clé, ni code ami, ni ticket, ni contenu de notice. Une ligne par minute résume l'activité : connexions ouvertes, notices, scores, fins, réactions et cases livrés, messages jetés. Une signature refusée y apparaît en avertissement : le signe que le secret du serveur temps réel n'est plus celui de Django.

11 Quand quelque chose casse

Ce qui tombe Ce que tu vois Pourquoi ce n'est pas grave
Le serveur temps réel la rangée d'ami⁠·⁠es disparaît, la page réessaie toute la partie passe par l'API
Redis pareil rien de durable n'y vit ; un coup ne dépend jamais de Redis
Un message pub/sub une annonce manque ; présence en retard de 20 s au plus le recalcul toutes les 20 s et le prochain rechargement rattrapent
Un client lent il rate quelques messages les autres n'en souffrent pas ; il rattrape au rechargement
Un processus Rust plante ses joueurs paraissent présents 60 s de trop les baux expirent, le balayage annonce les départs
Deux coups sur la même case le second reçoit « case déjà prise », sans pénalité le verrou de l'équipe met les coups à la file

12 Tester les deux côtés

Python signe, Rust vérifie : si l'un change le format, l'ordre des champs ou la dérivation des clés sans l'autre, tout s'arrête en silence. Des vecteurs de test partagés (un ticket, un score, une fin de partie, une notice, en JSON) sont donc vérifiés par les tests des deux langages. Le serveur Rust a aussi ses tests unitaires dans chaque module, et des tests de bout en bout qui ouvrent de vraies WebSockets contre un vrai Redis (ignorés par défaut, lancés par la CI). Avant chaque fusion, la CI vérifie le formatage, passe clippy avec les avertissements en erreurs, et lance tous ces tests.

13 Pourquoi Rust

Le serveur temps réel passe sa vie à attendre : des messages du navigateur, des messages de Redis, des minuteries. Avec tokio, chaque connexion est une tâche légère qui attend tout cela à la fois dans une seule boucle select!, sans bloquer de thread. Le compilateur garantit qu'aucune donnée partagée n'est modifiée par deux tâches en même temps : le registre des connexions de chaque processus est une table derrière un RwLock, dont aucun verrou ne survit à un .await, et les compteurs sont atomiques. Le tout tient dans un seul binaire, avec une poignée de dépendances : axum pour le HTTP et les WebSockets, tokio, le client redis, serde pour le JSON, hmac, sha2 et base64 pour les tickets, tracing pour les journaux.

Le code est d'ailleurs commenté pour qui apprend Rust : possession et emprunt, Arc, select! et l'annulation, canaux bornés, Notify, erreurs avec thiserror et anyhow, durées de vie… chaque notion du langage est expliquée là où elle sert.