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.
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é :
{
"v": 2,
"grid": 42,
"player": "<ta clé de présence>",
"friends": [["<clé>", "ABCD2345EFGH"]],
"team": {"key": "<clé d'équipe>", "members": [["<clé>", "K7MP3QRS9TUV"]]},
"exp": 1762297200
}
playern'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.friendsliste 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 dans23456789ABCDEFGHJKMNPQRSTUVWXYZ, sans0,O,1,IniL).teamn'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.
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 :
// 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 :
- le serveur attend au plus 10 secondes un message
{"type":"hello","ticket":…}d'au plus 16 Kio ; signature fausse :bad_ticketet fermeture ; ticket expiré :expiredet fermeture ; - il enregistre la connexion dans le registre du processus ;
- ensuite seulement, il annonce sa présence dans Redis ;
- il envoie la liste des ami·es présent·es, et celle des coéquipier·ères si le ticket a une équipe ;
- 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! :
// 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.
| 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 :
// 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 :
# 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.
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.
- 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 :
-- 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]}, ounullquand 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 :
// 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 unPINGà 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_KEYchange 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.