Temps réel (WebSocket / Socket.IO)
Temps réel : WebSocket et Socket.IO
Dodock envoie des événements en temps réel aux navigateurs connectés avec Socket.IO.
En production, un bench Dokos lance toujours le serveur Node.js socketio.js (processus node apps/frappe/socketio.js du Procfile et de la configuration supervisor). La version next contient aussi un serveur Socket.IO écrit en Python (asyncio et uvicorn). Il démarre avec python -m frappe.realtime.server, dans un processus séparé du serveur web, ou dans le même processus que l'application web avec uvicorn frappe.asgi:application. Ce serveur Python n'est pas encore celui utilisé en production.
Cette page décrit comment publier un événement depuis le serveur et comment écrire vos propres handlers.
Architecture
- Le code serveur publie un message avec
frappe.publish_realtime(). - Le message passe par Redis (
redis_queue). - Le serveur Socket.IO reçoit le message et l'envoie aux navigateurs de la « room » visée.
Configuration
Le serveur lit sa configuration dans common_site_config.json :
| Clé | Défaut | Rôle |
|---|---|---|
socketio_port | 9000 | Port d'écoute du serveur Socket.IO |
socketio_uds | Aucun | Socket Unix à utiliser au lieu d'un port |
socketio_worker_threads | 4 | Nombre de threads pour les tâches bloquantes : authentification, contrôles d'autorisation, handlers synchrones |
redis_queue | redis://127.0.0.1:11311 | Instance Redis qui transporte les messages |
Publier un événement depuis le serveur
frappe.publish_realtime()
Appelez cette fonction depuis n'importe quel code Python : contrôleur, tâche planifiée, tâche de fond.
frappe.publish_realtime(
event="import_termine",
message={"statut": "terminé", "avancement": 100},
user="jean@example.com",
)
| Paramètre | Rôle |
|---|---|
event | Nom de l'événement reçu par le navigateur |
message | Données envoyées (dictionnaire) |
room | Room visée. Par défaut, tout le site |
user | Envoie à toutes les sessions de cet utilisateur |
doctype, docname | Envoie aux navigateurs abonnés à ce document |
task_id | Envoie la progression d'une tâche de fond |
after_commit | Avec True, publie seulement après le commit de la transaction en cours |
Fonctions nommées
Le module frappe.realtime donne une fonction par cible. Chacune appelle publish_realtime. Toutes acceptent l'argument nommé after_commit=False.
| Fonction | Room | Destinataires |
|---|---|---|
publish_to_user(user, event, message=None) | user:{user} | Toutes les sessions de l'utilisateur sur ce site |
publish_to_doc(doctype, docname, event, message=None) | doc:{doctype}/{docname} | Navigateurs abonnés au document |
publish_to_doctype(doctype, event, message=None) | doctype:{doctype} | Navigateurs abonnés au type de document |
publish_task_progress(task_id, message=None) | task_progress:{task_id} | Navigateurs qui suivent la tâche (événement task_progress) |
publish_to_website(event, message=None) | website | Toutes les connexions du site |
publish_to_all(event, message=None) | all | Utilisateurs système du site (pas les invités) |
publish_to_room(room, event, message=None) | {room} | La room indiquée |
from frappe.realtime import publish_to_all, publish_to_doc, publish_to_user
publish_to_user("jean@example.com", "alerte", {"texte": "Nouveau message"})
publish_to_doc("Project", "PROJ-0001", "mise_a_jour", {"avancement": 75})
publish_to_all("maintenance", {"message": "Redémarrage dans 5 minutes"})
Écrire des handlers
Un handler réagit à un événement envoyé par le navigateur.
Emplacement
Placez vos handlers dans le module <app>.realtime.handlers, soit le fichier mon_app/mon_app/realtime/handlers.py. Au démarrage, le serveur importe ce module pour chaque application installée. Si le module n'existe pas, l'application n'a pas de handler. Si le module lève une erreur à l'import, le serveur ne démarre pas.
Un handler ne s'exécute que pour les connexions d'un site où son application est installée.
Handler asynchrone
# mon_app/mon_app/realtime/handlers.py
from frappe.realtime import Socket, realtime
@realtime.on("project_subscribe")
async def project_subscribe(socket: Socket, project: str) -> dict:
allowed = await socket.has_permission("Project", project)
if allowed:
await socket.join(f"project:{project}")
return {"subscribed": allowed}
- Le premier argument est toujours l'objet
Socket. Les arguments suivants sont les données envoyées par le navigateur. - Si le navigateur envoie l'événement avec une fonction de rappel, la valeur renvoyée par le handler lui répond.
- N'utilisez pas d'appel bloquant dans un handler
async def: il bloque toutes les autres connexions.
Handler synchrone
Une fonction def simple fonctionne aussi. Elle s'exécute dans un thread et reçoit un SyncSocket, avec les mêmes méthodes sans await. Utilisez-la quand le code doit bloquer.
Options du décorateur
| Option | Défaut | Rôle |
|---|---|---|
frappe_context | False | Ouvre un contexte Dodock (base de données et session) pour le handler |
allow_guest | False | Avec False, l'événement est ignoré pour un utilisateur Guest |
Avec frappe_context=True, le handler doit être une fonction synchrone. Un handler async def avec cette option lève une erreur à l'import.
import frappe
from frappe.realtime import Socket, realtime
@realtime.on("project_subscribe_db", frappe_context=True)
def project_subscribe_db(socket: Socket, project: str) -> None:
if frappe.has_permission("Project", doc=project, ptype="read"):
socket.join(f"project:{project}")
frappe_context=True initialise Dodock, ouvre une connexion à la base, puis la ferme. Préférez socket.has_permission(), qui interroge le processus web sans connexion à la base.L'objet Socket
| Membre | Rôle |
|---|---|
socket.site | Site de la connexion |
socket.user | Utilisateur, Guest pour un visiteur anonyme |
socket.user_type | Type d'utilisateur, par exemple System User |
socket.installed_apps | Applications installées sur le site |
await socket.join(room) / await socket.leave(room) | Ajoute ou retire la connexion d'une room |
await socket.emit(event, data=None, room=None) | Envoie un événement à une room, ou à ce navigateur si room est vide |
await socket.has_permission(doctype, name=None) | Demande au processus web si l'utilisateur peut lire le document |
await socket.set(key, value) / socket.get(key, default=None) | État propre à la connexion, effacé à la déconnexion |
Exemple complet : suivre l'avancement d'un projet
Les navigateurs s'abonnent à un projet. Ils reçoivent un événement quand le projet change.
Handler, dans mon_app/mon_app/realtime/handlers.py :
from frappe.realtime import Socket, realtime
@realtime.on("project_subscribe")
async def project_subscribe(socket: Socket, project: str) -> None:
if await socket.has_permission("Project", project):
await socket.join(f"project:{project}")
@realtime.on("project_unsubscribe")
async def project_unsubscribe(socket: Socket, project: str) -> None:
await socket.leave(f"project:{project}")
Publication, dans un doc_events du hooks.py de l'application :
# mon_app/hooks.py
doc_events = {
"Project": {"on_update": "mon_app.projets.notifier_avancement"},
}
# mon_app/projets.py
from frappe.realtime import publish_to_room
def notifier_avancement(doc, method=None):
publish_to_room(
f"project:{doc.name}",
"project_updated",
{"name": doc.name, "status": doc.status, "percent_complete": doc.percent_complete},
after_commit=True,
)
Navigateur :
frappe.realtime.emit("project_subscribe", "PROJ-0001");
frappe.realtime.on("project_updated", (data) => {
console.log("Avancement :", data.percent_complete);
});
La room publiée doit être celle que le handler a rejointe.
Dépannage
| Symptôme | Cause probable | Solution |
|---|---|---|
| Le handler n'est jamais appelé | Module <app>.realtime.handlers absent ou application non installée sur le site | Vérifiez le chemin du fichier et l'installation de l'application |
| Le serveur ne démarre pas | Erreur à l'import du module de handlers | Lisez la trace au démarrage du serveur |
frappe.get_doc() échoue dans un handler | Pas de contexte Dodock | Utilisez frappe_context=True sur un handler synchrone |
| Les événements n'arrivent pas | Room publiée différente de la room rejointe | Utilisez exactement la même chaîne |