01 Une partie, plusieurs mains
Quand tu joues une grille en équipe en direct, il n'y a qu'une seule partie en base : celle de l'équipe, que le modèle Team désigne par son champ holder. Chaque coéquipier·ère y écrit depuis son téléphone, et chaque réponse (Guess) garde dans author qui l'a jouée. Les parties des autres membres ne sont que des renvois vers celle-là, sans réponses à elles. Quand le serveur charge l'état d'un membre, il suit ce renvoi :
@classmethod
def load(cls, player, grid):
game = player_games().filter(player=player, grid=grid).first()
if game is not None and game.is_live_member:
game = player_games().filter(pk=game.team.holder_id).first() or game
return cls.for_grid(grid, game, player)
C'est ce qui rend le jeu à plusieurs simple à suivre : un seul score, un seul compteur d'erreurs, une seule grille. Mais c'est aussi ce qui crée le problème. Alice et Bob voient tous les deux la case « Ligne 4 × Rive gauche » vide. Alice tape Saint-Michel, Bob tape Odéon, à quelques millisecondes d'écart. Les deux réponses sont justes. Laquelle remplit la case ?
Un coup, côté serveur, c'est trois étapes : lire l'état de la partie, décider (la case est-elle libre, la station convient-elle), écrire la réponse. Si les deux requêtes s'exécutent en parallèle, chacune lit la grille avant que l'autre ait écrit, voit la case vide et enregistre sa réponse. C'est la course classique du « lire, décider, écrire », et elle donne deux stations dans une case, deux fois les points, ou une erreur de base de données au milieu de la partie.
02 Un verrou par équipe
La parade est de rendre les trois étapes indivisibles pour une équipe donnée : chaque coup d'une équipe passe par un verrou. Toute l'opération tient dans une transaction, et la première chose qu'elle fait est de verrouiller la ligne de l'équipe :
def locked_state(player, grid):
current = Game.objects.filter(player=player, grid=grid).order_by("-started_at", "-pk").first()
if current is not None and current.team_id is not None:
Team.objects.select_for_update().get(pk=current.team_id)
return GameState.load(player, grid)
def _play_team(grid, player, answers, cell, station):
with transaction.atomic():
state = locked_state(player, grid)
move = play(state, answers, cell, station)
if move.is_stored:
guess_of(grid, state, move, state.game_id).save(force_insert=True)
settle_team(state)
return GuessPlay(state, move, ...)
select_for_update() se traduit en SQL par un SELECT … FOR UPDATE :
BEGIN;
SELECT "game_team"."id", … FROM "game_team" WHERE "game_team"."id" = 42 FOR UPDATE;
-- l'état de la partie, relu
-- INSERT INTO "game_guess" …
-- UPDATE "game_game" SET "score" = … WHERE "game_game"."id" = …
COMMIT;
Le verrou est posé sur la ligne de l'équipe et tenu jusqu'au COMMIT. Si la transaction de Bob arrive au même SELECT … FOR UPDATE pendant que celle d'Alice le tient, PostgreSQL la met en attente. Elle ne repart qu'une fois la transaction d'Alice validée. Les deux coups ne sont pas joués en même temps : ils sont joués l'un après l'autre, dans l'ordre où ils ont obtenu le verrou.
Pourquoi relire l'état après le verrou
L'ordre des lignes compte. Le verrou est pris avant de charger l'état de la partie, pas après. PostgreSQL tourne ici à son niveau d'isolation par défaut, READ COMMITTED : chaque requête voit ce qui était validé au moment où elle démarre, pas au début de la transaction. Quand Bob obtient enfin le verrou, les requêtes suivantes de sa transaction, celles de GameState.load, voient donc la réponse qu'Alice vient de valider.
Si j'avais chargé l'état d'abord et verrouillé ensuite, Bob aurait attendu le verrou avec en main une grille déjà périmée, et il aurait écrit sa réponse par-dessus celle d'Alice. Un verrou ne protège que ce qui est lu après l'avoir pris.
Pourquoi l'équipe, et pas la partie
Je pourrais verrouiller la ligne de la partie commune. Mais chaque membre arrive par sa propre partie, celle qui renvoie vers la partie commune, et il faudrait d'abord suivre ce renvoi sans verrou pour savoir quoi verrouiller. La ligne de l'équipe, elle, est atteinte directement depuis la partie du membre (team_id) et ne change jamais d'identité : tous les membres verrouillent la même ligne, toujours. Les indices (_hint_team) et l'abandon (_give_up_team) prennent le même verrou, si bien qu'un indice et un coup ne se croisent pas non plus, et qu'une partie ne peut pas être abandonnée deux fois.
Le verrou porte sur une seule équipe. Les autres équipes et les parties jouées seul·e ne l'attendent jamais. La transaction est courte : une lecture de l'état, une insertion, une mise à jour du score.
Du code synchrone dans une application asynchrone
Toute l'application est asynchrone : les routes FastAPI appellent l'ORM de Django avec ses méthodes a* (aget, acreate…). Mais les transactions de Django ne fonctionnent qu'en code synchrone, car transaction.atomic() est lié à la connexion du thread courant. Le coup d'une équipe est donc écrit en code synchrone et appelé à travers sync_to_async, qui l'exécute dans un thread avec sa propre connexion :
async def play_guess(grid, player, answers, cell, station):
state = await GameState.aload(player, grid)
if state.team_id is not None and not state.is_over:
return await sync_to_async(_play_team)(grid, player, answers, cell, station)
...
Le premier aload, sans verrou, ne sert qu'à choisir le chemin : équipe ou seul·e. L'état qui compte est celui que _play_team relit sous le verrou.
03 Le premier gagne, le second ne perd rien
Une fois sous le verrou, le coup de Bob passe par la fonction play, la même que pour n'importe quel coup. Les vérifications s'y font dans cet ordre :
if state.is_over:
return move(GuessResult.GAME_OVER)
if cell in state.cells:
return move(GuessResult.CELL_TAKEN)
if station.pk in state.cells.values():
return move(GuessResult.ALREADY_USED)
if station.pk in answers[cell].counts:
... # la case est remplie, les points comptent
return move(GuessResult.CORRECT, ...)
state.errors += 1
return move(GuessResult.WRONG, -ERROR_PENALTY)
| Situation | Résultat | Effet |
|---|---|---|
| La partie est déjà finie | game_over |
rien n'est enregistré |
| La case est déjà remplie | cell_taken |
rien n'est enregistré |
| La station est déjà placée ailleurs | already_used |
rien n'est enregistré |
| La station convient | correct |
la case est remplie, les points comptent |
| La station ne convient pas | wrong |
une erreur, −20 points |
L'ordre a son importance : la case prise est testée avant la validité de la station. Bob tombe sur la deuxième ligne, que sa réponse soit juste ou fausse. Son coup n'est pas enregistré (move.is_stored est faux), la case garde la réponse d'Alice, et surtout il ne perd ni point ni essai. Il n'a pas fait d'erreur : il a été devancé. Si Alice et Bob placent la même station dans deux cases différentes, le second reçoit already_used, sans pénalité non plus.
Pour l'API, ce n'est pas une erreur. POST /api/grids/{grid_id}/guesses répond normalement (200), et la réponse dit simplement que rien n'a changé :
{
"result": "cell_taken",
"points": null,
"score": 245,
"errors": 1,
"hints": 0,
"found_count": 4,
"restarts_count": 0,
"cell": null,
"board": null,
"open_counts": [[3, 0, 5], [2, 4, 1], [6, 2, 3]],
...
}
Les compteurs (found_count, errors, hints, restarts_count) sont ceux de la partie commune après le coup, donc ceux qui incluent la réponse d'Alice. Tu verras plus bas pourquoi c'est utile.
04 Ce que voit Bob
Publier après le COMMIT
Une fois le coup d'Alice joué, la route publie une notice dans Redis, que le serveur temps réel transmet aux pages des coéquipier·ères. Cette publication a lieu après la transaction, quand _play_team est revenue :
played = await services.play_guess(grid, player, answers, cell, station)
...
# What the live server must tell the others, published once the move is committed (it is).
await live_bus.publish(*messages)
C'est voulu. Si la notice partait avant le COMMIT, la page de Bob pourrait recharger la grille et ne pas encore y trouver la réponse d'Alice. Publiée après, une notice décrit toujours un état qu'une lecture de la base peut confirmer. Un coup refusé (cell_taken, already_used) ne publie rien : il n'a rien changé.
Un delta, et des compteurs qui doivent se suivre
La notice d'un coup en équipe transporte un delta : la case trouvée et son auteur, le score, les compteurs, le nombre de réponses encore ouvertes de chaque case. La page de Bob l'applique sans rien redemander à l'API. Mais elle vérifie d'abord que ce delta suit exactement ce qu'elle affiche :
export const deltaVerdict = (board: Board, delta: BoardDelta): DeltaVerdict => {
if (delta.restarts_count !== board.restarts_count) return "gap";
const found = delta.found_count - boardCellsFound(board);
const errors = delta.errors - board.errors;
const hints = delta.hints - board.hints;
if (found <= 0 && errors <= 0 && hints <= 0) return "stale";
const steps = [found, errors, hints];
if (steps.every((step) => step === 0 || step === 1) && steps.filter((step) => step === 1).length === 1) return "apply";
return "gap";
};
apply: un seul compteur avance, d'exactement un. C'est le coup suivant, la page l'applique et anime la case.stale: la page a déjà tout ça. C'est un doublon, ou un coup qu'elle a déjà reçu par un autre chemin. Elle l'ignore.gap: il manque quelque chose entre les deux. Un message s'est perdu, ou l'équipe a repris la grille. La page recharge la grille depuis l'API.
Quand la réponse de Bob arrive avant la notice
Rien ne garantit l'ordre d'arrivée entre la réponse HTTP de Bob et la notice WebSocket du coup d'Alice. La notice peut même se perdre : Redis ne garde rien, et la publication ne lève jamais d'erreur. La réponse de Bob suffit alors à s'en rendre compte, grâce à ses compteurs :
export const ownMoveSkipped = (before, counters, move): boolean => {
if (counters.restarts_count !== before.restarts_count) return true;
const found = boardCellsFound(before) + Number(move === "found");
const errors = before.errors + Number(move === "missed");
const hints = before.hints + Number(move === "hint");
return counters.found_count !== found || counters.errors !== errors || counters.hints !== hints;
};
Pour un coup refusé, move vaut "none" : la page s'attend à des compteurs inchangés. Or la réponse dit found_count: 4 alors que la grille affichée n'a que 3 cases remplies. Un coup est passé entre-temps, que la page n'a pas vu : elle recharge la grille, et la station d'Alice apparaît.
Enfin, la page affiche une ligne dans le fil de l'équipe : « Alice l'a trouvée juste avant toi ». Elle retrouve l'auteur dans la grille, par le champ found_by de la case (le code ami de qui l'a trouvée). Si elle ne le connaît pas encore, la ligne devient « Un·e coéquipier·ère l'a trouvée juste avant toi ». Et si c'est Bob lui-même qui avait placé cette station ailleurs, elle ne dit rien : ce n'est pas une course, juste une station déjà utilisée. Pas de message d'erreur, pas de case qui clignote en rouge.
Le mieux reste encore d'éviter la course. Quand un·e coéquipier·ère ouvre une case, les autres la voient s'allumer sur leur grille. Ce signal ne passe que par le serveur temps réel, sans toucher la base, et c'est souvent le signe qu'il vaut mieux chercher ailleurs.
05 Et seul·e, sur deux onglets ?
Une partie jouée seul·e ne prend pas de verrou. Une seule personne joue, et ses coups restent asynchrones, sans thread ni transaction. Mais rien ne t'empêche d'ouvrir la grille sur ton téléphone et sur ton ordinateur, et de jouer la même case sur les deux.
Là, c'est la base de données qui tranche, avec deux contraintes d'unicité partielles sur les réponses :
class Meta:
constraints = (
# A cell is found once per game, and a station fills one cell per game.
models.UniqueConstraint(
fields=("game", "row", "col"),
condition=models.Q(correct=True),
name="unique_found_cell",
),
models.UniqueConstraint(
fields=("game", "station"),
condition=models.Q(correct=True),
name="unique_found_station",
),
)
Dans PostgreSQL, chacune devient un index unique avec une clause WHERE :
CREATE UNIQUE INDEX "unique_found_cell" ON "game_guess" ("game_id", "row", "col") WHERE "correct";
Partielles, parce qu'une case peut recevoir plusieurs mauvaises réponses, mais une seule bonne. Si deux bonnes réponses arrivent en même temps, PostgreSQL refuse la seconde insertion avec une IntegrityError. Le serveur ne la laisse pas remonter en erreur 500 : il relit l'état et rejoue le coup.
move = play(state, answers, cell, station)
try:
guess = await save_guess(grid, state, move)
except IntegrityError:
state = await GameState.aload(player, grid)
move = play(state, answers, cell, station)
guess = None
Rejoué sur l'état à jour, le coup tombe sur cell_taken ou already_used, exactement comme en équipe. C'est la version optimiste de la même idée : au lieu d'empêcher la course, je la laisse se produire et je laisse la base refuser le perdant. Ça suffit quand les courses sont rares, ce qui est le cas pour une personne seule.
Une limite connue
Ces contraintes ne couvrent que les bonnes réponses. Deux mauvaises réponses envoyées exactement en même temps depuis deux onglets sont enregistrées toutes les deux, et comptent pour deux erreurs. C'est le cas normal : deux mauvaises réponses restent deux mauvaises réponses. Mais elles ne passent pas l'une après l'autre, si bien que chacune peut lire « 2 erreurs » avant que l'autre ait écrit. La partie peut alors finir avec 4 erreurs, alors qu'elle aurait dû s'arrêter à la troisième. Il faut jouer sur deux écrans à la même milliseconde pour y arriver, et ça ne coûte qu'à toi.
06 Comment je le teste
Deux tests couvrent ces cas. Le premier joue en équipe : le propriétaire trouve une case, puis son coéquipier y place une autre station, avec une page qui ne sait encore rien.
taken = await _play(friend, today, {"row": 0, "col": 1, "station": other.pk})
assert taken["result"] == "cell_taken"
assert taken["points"] is None
assert taken["errors"] == before["errors"]
assert bus.messages == [] # nothing happened: nothing to tell
Le second reproduit la course d'une partie seul·e sans avoir besoin de deux requêtes simultanées. Il remplace save_guess par une version qui enregistre la réponse, comme si l'autre requête était passée la première, puis lève l'IntegrityError que PostgreSQL aurait levée :
async def racing(grid, state, move):
await real(grid, state, move) # the other request wrote it first
raise IntegrityError("unique_found_cell")
monkeypatch.setattr(services, "save_guess", racing)
out = await _play(client, today, solutions[0][0])
assert out["result"] == "cell_taken"
Les deux tests vérifient la logique de chaque chemin. Aucun ne lance deux transactions réellement concurrentes contre le verrou : là, c'est PostgreSQL qui fait le travail, et SELECT … FOR UPDATE fait ce qu'il promet depuis longtemps.