Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
API

Temps réel (WebSocket / Socket.IO)

Comment utiliser et étendre le serveur Socket.IO Python de Dodock pour envoyer des événements en temps réel et définir des handlers personnalisés dans votre application.

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

  1. Le code serveur publie un message avec frappe.publish_realtime().
  2. Le message passe par Redis (redis_queue).
  3. 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éfautRôle
socketio_port9000Port d'écoute du serveur Socket.IO
socketio_udsAucunSocket Unix à utiliser au lieu d'un port
socketio_worker_threads4Nombre de threads pour les tâches bloquantes : authentification, contrôles d'autorisation, handlers synchrones
redis_queueredis://127.0.0.1:11311Instance 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ètreRôle
eventNom de l'événement reçu par le navigateur
messageDonnées envoyées (dictionnaire)
roomRoom visée. Par défaut, tout le site
userEnvoie à toutes les sessions de cet utilisateur
doctype, docnameEnvoie aux navigateurs abonnés à ce document
task_idEnvoie la progression d'une tâche de fond
after_commitAvec 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.

FonctionRoomDestinataires
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)websiteToutes les connexions du site
publish_to_all(event, message=None)allUtilisateurs 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

OptionDéfautRôle
frappe_contextFalseOuvre un contexte Dodock (base de données et session) pour le handler
allow_guestFalseAvec 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}")
Chaque événement d'un handler 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

MembreRôle
socket.siteSite de la connexion
socket.userUtilisateur, Guest pour un visiteur anonyme
socket.user_typeType d'utilisateur, par exemple System User
socket.installed_appsApplications 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ômeCause probableSolution
Le handler n'est jamais appeléModule <app>.realtime.handlers absent ou application non installée sur le siteVérifiez le chemin du fichier et l'installation de l'application
Le serveur ne démarre pasErreur à l'import du module de handlersLisez la trace au démarrage du serveur
frappe.get_doc() échoue dans un handlerPas de contexte DodockUtilisez frappe_context=True sur un handler synchrone
Les événements n'arrivent pasRoom publiée différente de la room rejointeUtilisez exactement la même chaîne