Aller au contenu

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

Une connexion WebSocket de chat, de la requête au flux en directDiagramme 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.ChatManagerEvent store (Neo4j)ws_authenticate/ws/chat/{id} handlerDashboard(chatWebSocket.ts)the session was created overREST, never over the WebSocketreplay phaselive phase, one select loopbroadcast lagging givesevents_lagged: reconnect andreplay the gapbroadcast closed givessession_dormant: resubscribeafter resumeGET /ws/chat/{id} withlast_event=N1cookie, else a one-time ticket2claims, or 401 before the upgrade3upgrade, then auth_ok4get_events_since(last_event)5persisted ChatEvents6subscribe (local broadcast)7get_streaming_snapshot8events, then partial_text andreplay_complete9broadcast ChatEvent10ChatEvent with seq11user_message, interrupt,cancel_tools12route_user_message, interrupt, cancel_running_tools13permission_response,set_permission_mode, set_model14route_permission_response, set_session_permission_mode, set_session_model15

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.

DézoomerZoomerPlein écran
Redessiné depuis le diagramme vérifié po-chat-transport (vérifié 878281ca). Les libellés sont les noms utilisés dans le code.
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

  1. É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.

  2. É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.

  3. Étape 3. Rejeu

    Après auth_ok, le gestionnaire lit dans le graphe les événements persistés depuis last_event et les envoie.

  4. É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.

  5. É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.

  6. É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.

  7. É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.