Docs · Internals
Comment le chat arrive jusqu'à ton écran
Le tableau de bord parle à une session de chat par un WebSocket. Cette page suit une connexion de la première requête jusqu'aux messages en direct, y compris ce qui se passe quand tu te reconnectes.
Ce que ça fait
La session est créée en REST ; le WebSocket sur /ws/chat/{session_id} ne fait que s'y attacher. L'authentification se fait avant l'upgrade, avec un cookie ou un ticket à usage unique.
À la connexion, le serveur rejoue tous les événements persistés après le dernier vu par le client, puis envoie le texte en cours de flux, puis passe en direct.
Le format du fil est un contrat versionné : plus de trente événements serveur, 9 messages client et 5 trames de contrôle, avec des fixtures vérifiées par des tests et copiées par le frontend avec une somme de contrôle.
Le schéma
Fais glisser pour te déplacer. Pince, Ctrl + molette ou les touches + et - pour zoomer ; flèches pour bouger ; 0 ou double-clic pour ajuster. Choisis un nœud pour allumer ses liens.
Description textuelle du schéma
Diagramme de séquence à cinq participants : le tableau de bord, le gestionnaire du chat, ws_authenticate, le magasin d'événements dans Neo4j et le ChatManager. Le tableau de bord demande le WebSocket avec le numéro du dernier événement. Le gestionnaire authentifie par cookie ou ticket à usage unique avant l'upgrade, puis répond auth_ok. En phase de rejeu, il lit les événements persistés depuis ce numéro, s'abonne à la diffusion locale, récupère l'instantané du flux et envoie partial_text et replay_complete. En phase directe, le ChatManager diffuse des événements que le gestionnaire transmet avec un numéro de séquence, et les trames client comme user_message, interrupt et permission_response sont routées vers le ChatManager. Une note finale explique events_lagged et session_dormant.
Lecture guidée
Étape 1. Créer, puis s'attacher
La session est créée en REST (ou par un outil MCP), jamais par le WebSocket. Le client se connecte à /ws/chat/{id} et passe last_event, le numéro de séquence du dernier événement qu'il possède.
Étape 2. S'authentifier avant l'upgrade
Le gestionnaire essaie d'abord le cookie, puis un ticket à usage unique (un repli pour les vues web de bureau). Sans l'un ni l'autre, la requête est rejetée en 401 avant l'upgrade. Si le serveur tourne sans authentification configurée, la connexion est anonyme.
Étape 3. Rejeu
Après auth_ok, le gestionnaire lit dans le graphe les événements persistés depuis last_event et les envoie.
Étape 4. S'abonner, instantané, prêt
Il s'abonne à la diffusion de la session (ou à NATS quand la session vit sur une autre instance), récupère l'instantané du flux, envoie partial_text puis replay_complete.
Étape 5. La boucle en direct
Une boucle select fusionne la diffusion, les événements distants, les pings et les trames client. Chaque événement de chat porte un numéro de séquence.
Étape 6. Trames client
user_message, interrupt, cancel_tools, permission_response, set_permission_mode, set_model et set_auto_continue sont routées vers le ChatManager. Une réponse de permission est dédoublonnée par connexion.
Étape 7. Retard et veille
Un client lent reçoit events_lagged et se reconnecte pour rejouer l'écart. Si la diffusion se ferme parce que le processus de la session a été nettoyé, le client reçoit session_dormant, et le serveur se réabonne quand la session reprend.
Pourquoi c'est conçu ainsi
Tout se rattrape par le rejeu
Une coupure réseau, un client en retard et une session en veille mènent au même chemin : se reconnecter et rejouer depuis un numéro de séquence. Un seul mécanisme de reprise garde le serveur simple.
Pas de socket pour qui n'est pas authentifié
L'authentification passe avant l'upgrade et le ticket est à usage unique : il n'y a pas d'état « connecté mais inconnu » à gérer.
Un contrat avec sommes de contrôle
Le contrat du chat, dans la doc du backend, contient des fixtures JSON et un fichier de sommes de contrôle. Un test régénère le contrat depuis le code et échoue si les fixtures versionnées diffèrent.
Fermer, ce n'est pas se déconnecter
Fermer une session supprime son canal : les clients voient session_dormant et restent connectés. Un événement session_closed existe dans le contrat, mais le gestionnaire ne l'émet pas et le frontend le traite comme réservé.
Ce qui n'est pas établi
- Le chemin NATS (une session qui tourne sur une autre instance) n'a pas été testé contre un vrai NATS. Les trames de contrôle sont des copies statiques qu'aucun test ne relie au gestionnaire.
Sources publiques
Où vérifier chaque affirmation, dans les dépôts publics.