141 lines
10 KiB
Markdown
141 lines
10 KiB
Markdown
# 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.
|