winzik/docs/runtime.md

147 lines
12 KiB
Markdown

# Le JumPHP runtime : utiliser son propre réseau depuis le navigateur
## Ce que c'est
Une application JumPHP qui tourne **dans le navigateur** (jumphp.net, `play.jumphp.net`) n'a pas de socket : ses connexions TCP, SSH, UDP et
pings passent par le **pont du serveur** jumphp.net, qui ne voit que ce que le serveur voit. Le **JumPHP runtime** est un petit programme
installé sur *votre* ordinateur (une icône dans la zone de notification). Une fois installé, l'application connecte **depuis votre adresse IP
et votre réseau** : réseau local, VPN, serveur qui n'ouvre son port qu'à votre adresse.
## Pourquoi
- joindre une base de données de votre réseau local (`192.168.x.x`) que le serveur ne verra jamais ;
- passer par votre VPN d'entreprise ;
- vous connecter à un serveur dont le pare-feu n'accepte que votre IP ;
- pas de liste de ports du pont du serveur (tout port est permis côté serveur sauf 25 / 465 / 587 ; ici, c'est vous qui décidez) (avec votre accord, cible par cible).
## Est-ce sûr ?
Oui, et c'est fait pour : le runtime n'accepte pas n'importe qui.
- il n'écoute que sur `127.0.0.1` (votre machine), jamais sur le réseau ;
- il n'accepte que les pages des sites JumPHP connus (`jumphp.net`, `play.jumphp.net`) ; un autre site ou un programme local sans origine est refusé et journalisé ;
- **deux portes** : l'administrateur de jumphp.net a approuvé l'application *pour cette version exacte du code* (le ticket), **et** vous avez autorisé l'application sur votre ordinateur (fenêtre du système, jamais dans la page) ;
- une confirmation de plus la première fois que l'application vise une adresse privée ou un port inhabituel (hors bases de données, DNS...) : c'est une question posée à vous, pas un refus, et elle ne limite pas les ports permis ;
- vos autorisations sont révocables une par une ou toutes d'un coup ; un refus est gardé 10 minutes ;
- aucune commande locale, aucun accès à vos fichiers, rien n'écoute pour les pages ; le trafic n'est jamais enregistré (seuls l'origine, l'appli, la cible, l'heure et le volume le sont) ;
- les mises à jour sont signées.
Détails : `docs/runtime-protocol.md`.
## Installer
1. **Télécharger** pour votre système sur https://jumphp.net/runtime ou dans les releases de https://git.jumphp.net/jumphp/jumPhp (tag `runtime-v<version>`) :
Linux `runtime-setup-linux-x86_64`, Windows `runtime-setup.exe` (macOS : bientôt). Les binaires seuls : `runtime-linux-x86_64`, `runtime-windows-x86_64.exe`.
2. **Installer** : Linux `chmod +x runtime-setup-linux-x86_64 && ./runtime-setup-linux-x86_64` ; Windows : double-clic sur `runtime-setup.exe`.
3. **Le lancer** : une icône apparaît dans la zone de notification ; il démarre ensuite avec votre session.
4. **Autoriser l'application** : la première fois, une fenêtre du runtime demande « le site play.jumphp.net veut utiliser votre réseau pour l'application X. Autoriser ? ».
Chrome peut aussi demander « Accéder aux appareils du réseau local » : acceptez. Safari bloque ce contenu : l'appli reste sur le pont du serveur.
L'application vous guide elle-même (le badge, plus bas) et la fenêtre d'aide se met au vert toute seule.
## Langue
Le runtime parle la langue de l'ordinateur (14 langues : fr en es de it pt nl pl ru uk tr ja zh ko ; sinon l'anglais). Ordre : le choix fait dans la fenêtre
(liste « Langue »), la variable d'environnement `JUMPHP_LANG`, le fichier `install.json` du dossier de données (`{"lang": "fr"}` : un installateur peut l'écrire ;
sinon le runtime l'écrit lui-même la première fois qu'une page JumPHP lui parle, avec la langue de la page : `ws://127.0.0.1:47820/v1?lang=fr`), puis la langue du
système (`LC_ALL` / `LC_MESSAGES` / `LANGUAGE` / `LANG` sous Linux, la langue d'affichage de Windows, `AppleLanguages` sous macOS). Les textes : `apps/runtime/config/lang.yaml`
(menu de la zone de notification, boîtes de dialogue, question d'autorisation) et `apps/runtime/ui/lang.js` (les pages) ; `tests/LangTest.php` vérifie qu'ils sont complets.
## L'utiliser dans une appli, pas à pas
1. Rien à installer : le client est dans le moteur (depuis la 0.5.27) ; mettez à jour JumPHP (`bin/jumphp update`).
2. Rien ne change dans vos connexions :
```php
$c = $this->engine->tcp()->connect('192.168.1.10', 3306); // ou ssh(), udp(), icmp()
$c->on('open', fn () => ...);
$c->on('error', fn (string $why) => $this->status->text = $why);
```
3. Dans le formulaire, le badge à côté des champs de connexion :
```yaml
- {class: JumPHP\Runtime\RuntimeBadge, id: runtime}
```
4. Le réglage (project.yaml) :
```yaml
project:
net_mode: auto # auto | server | local
```
5. Pour réagir en code : `$this->engine->runtime()->state()`, `->check()`, `->pair($id, $title)`, `->on('change', fn (string $state) => ...)`, `->bridgeUrl()`.
6. Tests : `$engine->setRuntime(new JumPHP\Runtime\ManualRuntime(RuntimeLink::READY))` donne l'état que vous voulez, sans navigateur.
## Le badge
| Couleur | État | Texte | Au clic |
|---|---|---|---|
| vert | `ready` : installé et autorisé | Local network active | rien |
| orange | `running` (installé, pas autorisé) ou `refused` | Allow this app on your network | demande l'autorisation (`pair`) |
| rouge | `missing` : pas installé ou pas lancé | Local network off - install the runtime | ouvre le guide d'installation (`RuntimeGuide`) |
| orange | `unsupported` **parce que le navigateur bloque** `ws://127.0.0.1` (question « réseau local » refusée ou fermée) | Local network blocked by your browser - click for help | ouvre le guide, qui dit où l'autoriser (icône à gauche de la barre d'adresse > Paramètres du site > Accès au réseau local > Autoriser) |
| gris | `unsupported`, `net_mode: server`, ou recherche en cours | Server network | rien : le pont du serveur suffit |
`RuntimeGuide` est la boîte de dialogue : pourquoi, les 4 étapes (télécharger pour votre système, installer, lancer, autoriser), les liens vers
jumphp.net/runtime et les releases. Elle revérifie toutes les 2 s. On l'ouvre aussi à la main : `$this->engine->scenes->push(RuntimeGuide::class)`.
Le système est lu dans le navigateur (module `jumphp-runtime.js`) ou donné par le runtime ; inconnu, tous les systèmes sont montrés.
La version proposée se règle : `jumphp_runtime: {version: 0.1.0}` dans project.yaml.
## Les modes
| `net_mode` | Comportement |
|---|---|
| `auto` (défaut) | le runtime quand son état est `ready`, sinon le pont du serveur |
| `server` | toujours le pont du serveur |
| `local` | le runtime (`running` ou `ready`) ; sinon erreur `the JumPHP runtime is not available (state: missing)` |
Aussi `JUMPHP_NET_MODE` (adresse de la page `?net_mode=local`, ou variable d'environnement), qui l'emporte sur project.yaml. Le ticket est toujours
demandé au serveur ; seule l'adresse ouverte ensuite change. Sur le bureau, rien de tout cela : l'appli a déjà son réseau.
## En cas de problème
| Symptôme | À faire |
|---|---|
| Badge rouge alors qu'il est installé | est-il lancé (icône) ? Un pare-feu qui bloque `127.0.0.1:47820-47829` ? Chrome : acceptez « appareils du réseau local » |
| Détecté seulement après avoir fermé Chrome | corrigé : la page attend la réponse à la question « réseau local » de Chrome sans fermer la connexion (fermer la question la laissait en suspens), et cherche à nouveau dès le retour sur la page (onglet, installation terminée, réseau) : tout de suite, puis à 0,5 s, 1,5 s, 4 s |
| Badge gris sous Safari | Safari bloque `ws://127.0.0.1` depuis une page https : le pont du serveur est utilisé |
| Orange qui reste orange | cliquez le badge et répondez « Autoriser » dans la fenêtre du runtime (30 s sans réponse = refus ; un refus dure 10 min) |
| `the JumPHP runtime is not available (state: …)` | mode `local` sans runtime : installez-le, ou passez en `auto` |
| `origin` refusé (403) dans le journal du runtime | le site n'est pas dans sa liste blanche (fenêtre du runtime) |
| Connexion refusée côté ticket | l'administrateur n'a pas approuvé cette version de l'appli (`docs/tcp.md`) : les deux portes doivent être ouvertes |
## Tests de bout en bout
`tools/e2e/run.sh [chrome|firefox|all]` démarre le vrai démon (Docker, Xvfb, `HOME` temporaire) et pilote Chrome et Firefox sans interface : une page **https**
ouvre `ws://127.0.0.1:<port>/v1` et reçoit `hello` ; une origine hors liste blanche est refusée (403) et un mauvais `Host` aussi (421) ; le vrai module
`jumphp-runtime.js` retrouve le runtime sur 47820..47829 et donne le système et la version ; un ticket falsifié reçoit `error ticket` ; une origine ajoutée dans `config.json` est acceptée.
Ne couvre **pas** un ticket valide + la boîte de consentement (il faut une personne ; c'est le `ServerTest` de PHPUnit, avec une fausse boîte), ni Safari
(contenu mixte bloqué, repli sur le pont du serveur), ni l'invite « Local Network Access » de Chrome. Détails : `apps/runtime/tests/e2e/README.md`.
## Pour les agents IA
- **Quand l'utiliser** : une application JumPHP *pour le navigateur* qui doit joindre une machine du réseau de l'utilisateur (base locale, VPN, serveur filtré par IP) en TCP / SSH / UDP / ping. Pas pour un jeu, pas pour une appli de bureau (elle a déjà son réseau).
- **Comment** : mettre à jour le moteur (0.5.27 ou plus), un `RuntimeBadge` dans le formulaire de connexion, `net_mode: auto` (défaut). Garder le code de connexion identique (`$engine->tcp()` etc.) : pas de code spécial « local ».
- **Ne jamais** : contourner le consentement (ne pas appeler le runtime autrement que par `pair()` / les connexions, ne pas écrire dans `grants.json`, ne pas ouvrir de WebSocket vers `127.0.0.1:47820` à la main) ; demander à l'utilisateur de désactiver une sécurité (pare-feu, Local Network Access, Mixed Content, liste blanche d'origines) ; forcer `net_mode: local` par défaut dans une appli publiée (un utilisateur sans runtime n'aurait que des erreurs) ; mettre un secret ou une adresse privée dans le dépôt.
- Tests : `ManualRuntime` ; ne jamais supposer un runtime réel. Vérifier le badge avec `bin/jumphp shot` et regarder l'image.
## Android
Un téléphone Android peut lancer le runtime : `apps/runtime-android` (une petite appli Kotlin, `jumphp-runtime-android.apk` de la release
`runtime-android-v<version>`, que le guide du moteur propose sur un téléphone). Même protocole et même adresse que sur ordinateur ; les
questions de consentement sont des notifications avec leurs boutons ; il redémarre avec le téléphone. Sur iPhone ce n'est pas possible : l'application
continue de passer par le pont du serveur jumphp.net.
## Surveillance et interrupteur
Le client du moteur (`RuntimeClient`) regarde en permanence si le runtime est là : toutes les 8 s tant qu'il manque (ou que le navigateur le bloque), toutes les
20 s sinon (il peut s'arrêter ou démarrer plus tard), tout de suite quand une connexion échoue, quand l'onglet revient au premier plan ou que le réseau revient.
Quand le runtime est prêt, le voyant (`RuntimeBadge`) montre un demi-bouton **Local | Server** : la personne peut repasser par le proxy du serveur jumphp.net
pour les nouvelles connexions même si son réseau local est disponible (réglage gardé : option `net_use_server`).
## Réveil du runtime Android par Firebase
Si l'appli Android est arrêtée (redémarrage, gestion de batterie), la page de l'application demande au serveur jumphp.net (`POST /api/runtime/wake`, même origine que le
ticket) de la réveiller : le serveur envoie par Firebase Cloud Messaging un message `{t: wake}` à priorité haute (projet Firebase `jumphp-runtime`, clé de compte de service
dans l'environnement du site `FCM_SERVICE_ACCOUNT_B64`), l'appli rallume son relais. La page garde le jeton anonyme de l'appli (donné dans son `hello`, `RuntimeClient::pushToken()`) ;
rien d'autre n'est envoyé. Il faut les services Google Play sur le téléphone ; sans eux, le démarrage avec le téléphone et le bouton de la page restent.