12 KiB
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
- 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>) : Linuxruntime-setup-linux-x86_64, Windowsruntime-setup.exe(macOS : bientôt). Les binaires seuls :runtime-linux-x86_64,runtime-windows-x86_64.exe. - Installer : Linux
chmod +x runtime-setup-linux-x86_64 && ./runtime-setup-linux-x86_64; Windows : double-clic surruntime-setup.exe. - Le lancer : une icône apparaît dans la zone de notification ; il démarre ensuite avec votre session.
- 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
-
Rien à installer : le client est dans le moteur (depuis la 0.5.27) ; mettez à jour JumPHP (
bin/jumphp update). -
Rien ne change dans vos connexions :
$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); -
Dans le formulaire, le badge à côté des champs de connexion :
- {class: JumPHP\Runtime\RuntimeBadge, id: runtime} -
Le réglage (project.yaml) :
project: net_mode: auto # auto | server | local -
Pour réagir en code :
$this->engine->runtime()->state(),->check(),->pair($id, $title),->on('change', fn (string $state) => ...),->bridgeUrl(). -
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
RuntimeBadgedans 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 dansgrants.json, ne pas ouvrir de WebSocket vers127.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) ; forcernet_mode: localpar 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 avecbin/jumphp shotet 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.