128 lines
8.9 KiB
Markdown
128 lines
8.9 KiB
Markdown
# Troubleshooting: the browser, the network and applications that stay open
|
|
|
|
What surprises when a JumPHP game or application runs **for a long time in a browser** and talks to a server (a chat, an
|
|
online game, a connected tool): disconnections "for no reason", lost messages, a wrong time, notifications that never come.
|
|
Each point below was met for real (the CaraChat chat, November 2026): the cause, then what to do.
|
|
|
|
## 1. A hidden tab draws nothing: PHP used to stop
|
|
|
|
**Symptom**: the user switches to another tab (or minimizes the window); a few minutes later the server drops them for
|
|
inactivity, although their connection was fine.
|
|
|
|
**Cause**: the engine runs PHP one frame per `requestAnimationFrame` (Emscripten's main loop). A hidden tab gets **no**
|
|
`requestAnimationFrame` at all: not one line of PHP runs. The WebSocket stays open (the browser keeps it), but nobody reads
|
|
what arrives nor answers the application's pings: the server believes the client is dead.
|
|
|
|
**What the engine does (0.5.63 and later)**: while the tab is hidden, the page runs **one frame a second** itself
|
|
(`keepRunningWhenHidden()` in `engine/web/jumphp.js`). No new WebAssembly build is needed: the JavaScript calls
|
|
`jumphp_frame()` between two frames, as it already calls `jumphp_events()` when the tab is being hidden. It does what a
|
|
normal frame does around the call (page events, bridge, modules). The clock is a **Web Worker**'s: the page's own timers
|
|
are slowed to once a minute after 5 minutes in the background, a worker's are not. The main loop being stopped, nothing
|
|
runs twice; back in sight, the normal frames go on. `project.yaml` `hidden_frames: false` turns it off (a game with nothing
|
|
to do while hidden).
|
|
|
|
- The time step stays capped at 0.1 s a frame: a second away teleports nothing.
|
|
- The sound is muted while hidden (`mute_when_hidden`); `pause_scene` pauses the game if it has one.
|
|
|
|
**What stays impossible**: a **phone freezes the whole tab** (Android Chrome after a few minutes, iOS Safari almost at once),
|
|
as Chrome's "Memory Saver" does on a computer. No JavaScript runs any more: neither the page nor the worker. To reach someone
|
|
then, the server sends a **push notification** (§5) and keeps their place (§3).
|
|
|
|
## 2. The server must count the network layer's signs of life
|
|
|
|
**Symptom**: `drop …: timeout` in the server's logs.
|
|
|
|
**Cause**: the server counted only the application's own messages (the chat's `667`). But the browser's network layer
|
|
(`php-wasm-network`) sends `{"t":"ping"}` by itself **every 15 seconds**, from JavaScript, even while PHP does not run.
|
|
|
|
**On the server**:
|
|
- count **that transport ping** as presence (the CaraChat server: `ChatServer::touch()` called by `WsSession` on `ping`);
|
|
- send a WebSocket ping (opcode `0x9`) itself every **30 s**: **Cloudflare cuts a silent WebSocket after 100 s**, other
|
|
proxies sooner;
|
|
- pick a long inactivity delay (minutes), and do **not** take "no longer answers" for "left" (§3).
|
|
|
|
## 3. A socket can be dead without knowing it: take the line again
|
|
|
|
**Symptom**: back on a phone's tab after a few minutes: the application looks connected but nothing arrives any more; or the
|
|
user is connected again and lost the messages that came meanwhile.
|
|
|
|
**Causes**: a sleeping phone, a network change (Wi-Fi → 4G), a proxy restarting. The WebSocket may stay "open" on both sides
|
|
while carrying nothing; or close with code **1006** (abnormal closure, no reason given).
|
|
|
|
**The model that works** (CaraChat's, `caramail-server` `Relay`):
|
|
1. at login the server gives a **resume token** (not numbered);
|
|
2. every message sent to the client is **numbered**, and the server keeps the last ones;
|
|
3. when the socket goes, the member **stays** (shown "away" to the others) for a grace period (CaraChat: 12 h);
|
|
4. the client reconnects by itself (0.3 s, 1, 2, 4, 8, 15, then 30 s) with `token + number of the last message received`: the
|
|
server sends what is missing; an unknown token (too late, server restarted) → a normal new login, and the user is put
|
|
back where they were (the same room);
|
|
5. what the user does during the cut **waits** in a queue and goes once back;
|
|
6. a tab coming back after more than ~20 s hidden **takes its line again at once** (closes and reopens): its socket may have
|
|
died silently; the resume is free thanks to the numbers;
|
|
7. **no** reconnection after an ejection or a "Quit"; "Quit" and the page going away (`lifecycle()`'s `close`, the
|
|
`pagehide` event) tell the server "I am leaving" (else the member stays a ghost until the grace ends).
|
|
|
|
Measure the time away with `Time::now()` (the real clock), **not** `$engine->time()`: game time stops with the tab.
|
|
|
|
## 4. The PHP server itself (a `stream_select` loop)
|
|
|
|
- **Never give a closed stream to `stream_select()`**: PHP 8 throws a `TypeError` ("supplied resource is not a valid stream
|
|
resource"), the server dies and **everybody is disconnected** at once. It happens when a client is dropped outside the read
|
|
loop (the `tick()` that drops silent ones): remove closed sessions **before** building the `select` lists, and skip what is
|
|
no longer a resource (`is_resource()`).
|
|
- Block nothing: an outgoing HTTP call (sending a notification) goes through `curl_multi`, advanced at each pass.
|
|
- Log **why** each connection ends: closed by the client (WebSocket code: 1000 normal, 1001 page left, 1006 cut), end of
|
|
stream, write failure, inactivity, ejection. And have the client tell, once back, what it saw (the browser's reason, how
|
|
long the tab was hidden): without that, "there are cuts" stays a mystery.
|
|
- The disk: a machine that deploys often with Docker piles up images and build cache. A full disk breaks the server's saves
|
|
(`No space left on device`). `docker image prune -f`, `docker builder prune -f`, and watch `df -h`.
|
|
- Restarting the server cuts everybody: do it when `status` shows few people, with clients that reconnect (§3).
|
|
|
|
## 5. Notifications
|
|
|
|
Two paths that complete each other:
|
|
|
|
| | Browser notification | Push notification (JumPHP runtime) |
|
|
|---|---|---|
|
|
| When | the page is open, even hidden (§1) | even with the page closed, the phone asleep |
|
|
| Where | computers; not Android Chrome (it requires a service worker) | Android phones with the JumPHP runtime |
|
|
| Code | `JumPHP\Native\Notification::show($title, $text)` | the extension `jumphp/notification` (docs/notifications.md), sent by the **server** |
|
|
| Consent | `Notification::requestPermission()` **from a click**; `Notification::permission()` | the runtime's window on the phone |
|
|
|
|
- A permission is asked from a user **gesture** (click, key): browsers refuse it otherwise.
|
|
- A page **in a frame of another origin** (the playground's games) may not ask for the permission: the engine then goes
|
|
through the parent page (`postMessage` `jumphp:notify`, `jumphp:notify-permission`, and `jumphp:notify-state` at the start), which shows the notification itself.
|
|
- Push: the application's server knows the id the page subscribed (`subscribe($id)`) and sends with the owner's `jnt_…` token
|
|
(in **its** configuration, never in a repository). Three doors: the `notify` right approved by the administrator, the token,
|
|
the person's consent.
|
|
- Notify only when useful: the person is **away** (tab hidden or line cut), a message **for them** (private, their nickname),
|
|
a session about to end; one notification of a kind every few minutes at most.
|
|
|
|
## 6. Time, numbers, clocks
|
|
|
|
- PHP in the browser runs in **UTC**: `date('H:i')` shows Greenwich time. Set the time zone
|
|
(`date_default_timezone_set('Europe/Paris')`, or the one the page gives).
|
|
- `Time::now()` counts from its first call (it starts at 0): it is **not** a date. A date: `time()` / `microtime(true)` (float).
|
|
- **32-bit** integers in the browser (`PHP_INT_SIZE === 4`): no milliseconds since 1970 as an int, no `pack('J')` (AGENTS.md
|
|
golden rules §2).
|
|
|
|
## 7. The page's life
|
|
|
|
- `lifecycle()`: `hide` and `close` are delivered **at once**, between two frames (PHP can still save or warn the server);
|
|
`show` when it comes back.
|
|
- `close` comes from `pagehide`: the page is going (closed, reloaded, navigated away). A page may **come back** from the cache
|
|
(bfcache): the application must be able to reconnect after a `close`.
|
|
- On phones the on-screen keyboard shrinks or covers the page; do not focus a field by yourself (it opens the keyboard).
|
|
|
|
## 8. Checklist of a connected application
|
|
|
|
- [ ] The server counts transport pings and sends its own (≤ 30 s).
|
|
- [ ] Long inactivity delay; a lost socket is not a departure (grace, member "away").
|
|
- [ ] Automatic reconnection with resume (token + numbers), queue of what is sent, back-off, none after an ejection.
|
|
- [ ] Immediate resume when the tab comes back after a long absence.
|
|
- [ ] "Quit" and `close` tell the server.
|
|
- [ ] The server never gives a closed stream to `stream_select()`, never blocks, logs why connections end.
|
|
- [ ] The client tells the server about its cuts once back.
|
|
- [ ] Time zone set; no 64-bit integers.
|
|
- [ ] Notifications: browser (permission from a click) + push through the runtime for phones.
|
|
- [ ] Server disk watched; restarts at quiet hours.
|