DE

Dépannage : le navigateur, le réseau et les applications qui restent ouvertes

Ce qui surprend quand un jeu ou une application JumPHP tourne longtemps dans un navigateur et parle à un serveur (un chat, un jeu en ligne, un outil connecté) : des déconnexions « sans raison », des messages perdus, une heure fausse, des notifications qui ne viennent pas. Chaque point ci-dessous a été rencontré pour de vrai (le chat CaraChat, novembre 2026) ; la cause, puis ce qu'il faut faire.

1. Un onglet caché ne dessine plus : le PHP s'arrêtait

Symptôme : l'utilisateur passe sur un autre onglet (ou réduit la fenêtre) ; quelques minutes plus tard, le serveur le déconnecte pour inactivité, alors que sa connexion était bonne.

Cause : le moteur fait tourner le PHP une image par requestAnimationFrame (la boucle d'Emscripten). Un onglet caché ne reçoit aucun requestAnimationFrame : plus une ligne de PHP ne tourne. La WebSocket reste ouverte (le navigateur la garde), mais personne ne lit ce qui arrive ni ne répond aux pings de l'application : le serveur croit le client mort.

Ce que fait le moteur (0.5.63 et plus) : tant que l'onglet est caché, la page fait tourner une image par seconde elle-même (keepRunningWhenHidden() dans engine/web/jumphp.js). Elle n'a pas besoin de recompiler le moteur : le JavaScript appelle jumphp_frame() entre deux images, comme il appelle déjà jumphp_events() quand l'onglet se cache. Il fait le même travail qu'une image normale autour de l'appel (événements de la page, pont, modules). L'horloge est celle d'un Web Worker : les minuteurs de la page sont ralentis à une fois par minute après 5 minutes en arrière-plan, ceux d'un worker non. La boucle principale étant arrêtée, rien ne tourne deux fois ; au retour, les images normales reprennent. project.yaml hidden_frames: false l'éteint (un jeu qui n'a rien à faire caché).

  • Le pas de temps est borné à 0,1 s par image : une seconde d'absence ne « téléporte » rien.
  • Le son est coupé quand l'onglet est caché (mute_when_hidden) ; pause_scene met le jeu en pause s'il en a une.

Ce qui reste impossible : un téléphone gèle l'onglet entier (Chrome Android après quelques minutes, Safari iOS presque tout de suite), comme le mode « Économiseur de mémoire » de Chrome sur ordinateur. Plus aucun JavaScript ne tourne : ni la page, ni le worker. Pour joindre quelqu'un dans ce cas, il faut une notification push envoyée par le serveur (§5) et un serveur qui garde sa place (§3).

2. Le serveur doit compter les signes de vie de la couche réseau

Symptôme : drop … : timeout dans les journaux du serveur.

Cause : le serveur ne comptait comme signe de vie que les messages de l'application (le 667 du chat). Or la couche réseau du navigateur (php-wasm-network) envoie d'elle-même {"t":"ping"} toutes les 15 secondes, depuis JavaScript, même quand le PHP ne tourne pas.

À faire côté serveur :

  • compter ce ping de transport comme une présence (le serveur CaraChat : ChatServer::touch() appelé par WsSession sur ping) ;
  • envoyer lui-même un ping WebSocket (opcode 0x9) toutes les 30 s : Cloudflare coupe une WebSocket muette au bout de 100 s, d'autres proxys plus tôt ;
  • choisir un délai d'inactivité long (minutes), et ne pas confondre « ne répond plus » avec « est parti » (§3).

3. Un socket peut être mort sans le savoir : reprendre la ligne

Symptôme : retour sur l'onglet d'un téléphone après quelques minutes : l'application semble connectée, mais plus rien n'arrive ; ou l'utilisateur est reconnecté et a perdu les messages arrivés entre-temps.

Causes : un téléphone qui dort, un changement de réseau (Wi-Fi → 4G), un proxy qui redémarre. La WebSocket peut rester « ouverte » des deux côtés alors qu'elle ne transporte plus rien ; ou se fermer avec le code 1006 (fermeture anormale, sans raison donnée).

Le modèle qui marche (celui de CaraChat, caramail-server Relay) :

  1. à la connexion, le serveur donne un jeton de reprise (non numéroté) ;
  2. chaque message envoyé au client est numéroté et le serveur garde les derniers ;
  3. quand le socket tombe, le membre reste (affiché « absent » aux autres) pendant une durée de grâce (CaraChat : 12 h) ;
  4. le client se reconnecte de lui-même (0,3 s, 1, 2, 4, 8, 15, puis 30 s) avec jeton + numéro du dernier message reçu : le serveur renvoie ce qui manque ; jeton inconnu (trop tard, serveur redémarré) → nouvelle connexion normale, et on remet l'utilisateur où il était (le même salon) ;
  5. ce que l'utilisateur fait pendant la coupure attend dans une file et part au retour ;
  6. un onglet qui revient après plus de ~20 s caché reprend la ligne tout de suite (ferme et rouvre) : son socket a pu mourir sans prévenir ; la reprise est gratuite grâce aux numéros ;
  7. on ne se reconnecte pas après une éjection ou un « Quitter » ; « Quitter » et la fermeture de la page (close de lifecycle(), l'événement pagehide) disent au serveur « je pars » (sinon le membre reste un fantôme jusqu'à la fin de la grâce).

Mesurer le temps d'absence avec Time::now() (horloge réelle), pas $engine->time() : le temps du jeu s'arrête avec l'onglet.

4. Le serveur PHP lui-même (une boucle stream_select)

  • Ne jamais passer un flux fermé à stream_select() : PHP 8 lève une TypeError (« supplied resource is not a valid stream resource »), le serveur meurt et tout le monde est déconnecté d'un coup. Arrive quand un client est coupé hors de la boucle de lecture (le tick() qui coupe les silencieux) : retirer les sessions fermées avant de construire les listes du select, et ignorer ce qui n'est plus une ressource (is_resource()).
  • Ne rien bloquer : un appel HTTP sortant (envoyer une notification) passe par curl_multi, avancé à chaque tour.
  • Journaliser pourquoi chaque connexion se termine : fermée par le client (code WebSocket : 1000 normal, 1001 page quittée, 1006 coupure), fin de flux, échec d'écriture, inactivité, éjection. Et faire raconter au client, une fois reconnecté, ce qu'il a vu (la raison du navigateur, depuis combien de temps l'onglet était caché) : sans ça, « il y a des coupures » reste un mystère.
  • Le disque : une machine qui déploie souvent avec Docker accumule images et cache de build. Un disque plein casse l'écriture des sauvegardes du serveur (No space left on device). docker image prune -f, docker builder prune -f, et surveiller df -h.
  • Redémarrer le serveur coupe tout le monde : le faire quand status montre peu de monde, et que les clients sachent se reconnecter (§3).

5. Les notifications

Deux chemins, qui se complètent :

Notification du navigateur Notification push (runtime JumPHP)
Quand la page est ouverte, même cachée (§1) même page fermée, téléphone en veille
Où ordinateur ; pas Android Chrome (il exige un service worker) téléphone Android avec le runtime JumPHP
Code JumPHP\Native\Notification::show($titre, $texte) l'extension jumphp/notification (docs/notifications.md), envoi par le serveur
Accord Notification::requestPermission() depuis un clic ; Notification::permission() la fenêtre du runtime sur le téléphone
  • Une permission se demande depuis un geste de l'utilisateur (clic, touche) : un navigateur refuse sinon.
  • Une page dans une iframe d'une autre origine (les jeux du playground) n'a pas le droit de demander la permission : le moteur passe alors par la page parente (postMessage jumphp:notify, jumphp:notify-permission, et jumphp:notify-state au démarrage), qui affiche la notification à sa place.
  • Le push : le serveur de l'application connaît l'identifiant que la page a abonné (subscribe($id)), et l'envoie avec le jeton jnt_… du propriétaire (dans sa configuration, jamais dans le dépôt). Trois portes : le droit notify approuvé par l'administrateur, le jeton, l'accord de la personne.
  • Notifier seulement quand c'est utile : la personne est absente (onglet caché ou ligne coupée), un message pour elle (privé, son pseudo), une fin de session proche ; une notification par sorte toutes les quelques minutes au plus.

6. L'heure, les nombres, le temps

  • Le PHP du navigateur est en UTC : date('H:i') affiche l'heure de Greenwich. Fixer le fuseau (date_default_timezone_set('Europe/Paris'), ou celui que la page donne).
  • Time::now() compte depuis son premier appel (il commence à 0) : ce n'est pas une date. Une date : time() / microtime(true) (en flottant).
  • Entiers sur 32 bits dans le navigateur (PHP_INT_SIZE === 4) : pas de millisecondes depuis 1970 en entier, pas de pack('J') (§2 des règles d'or d'AGENTS.md).

7. La vie de la page

  • lifecycle() : hide et close sont livrés tout de suite, entre deux images (le PHP peut encore sauvegarder ou prévenir le serveur) ; show à la reprise.
  • close vient de pagehide : la page s'en va (fermée, rechargée, navigation). Une page peut revenir du cache (bfcache) : l'application doit savoir se reconnecter après un close.
  • Sur téléphone, le clavier à l'écran réduit la page ou la recouvre ; ne pas donner le focus à un champ tout seul (ça ouvre le clavier).

8. Liste de contrôle d'une application connectée

  • Le serveur compte les pings de transport et envoie les siens (≤ 30 s).
  • Délai d'inactivité long ; une coupure de socket n'est pas un départ (grâce, membre « absent »).
  • Reconnexion automatique avec reprise (jeton + numéros), file des envois, back-off, pas après une éjection.
  • Reprise immédiate quand l'onglet revient après une longue absence.
  • « Quitter » et close préviennent le serveur.
  • Le serveur ne passe jamais de flux fermé à stream_select(), ne bloque jamais, journalise les causes de coupure.
  • Le client raconte ses coupures au serveur une fois revenu.
  • Fuseau horaire fixé ; pas d'entiers 64 bits.
  • Notifications : navigateur (permission depuis un clic) + push via le runtime pour les téléphones.
  • Disque du serveur surveillé ; redémarrages aux heures creuses.