9 KiB
Cryo dans JumPHP
ext-cryo est liée en statique dans le moteur WebAssembly de JumPHP
(docker/ext/cryo, copiée depuis PhpCryo par tools/sync-jumphp.sh). Elle sert à quatre choses dans un jeu ou une
application : des snapshots du tas PHP (fuites de mémoire), leur lecture (CryoReader), la réécriture à
chaud du code (Cryo\Engine), des métriques, et des sandboxes : du code PHP isolé dans une autre instance
de PHP, qui ne peut ni planter ni geler le jeu.
Pour commencer, avec des exemples courts (une touche pour photographier la mémoire, trouver une fuite, le code d'un
joueur dans une sandbox, attendre plusieurs résultats, un drapeau lu à chaque image, changer une règle à chaud) :
https://jumphp.net/docs/cryo. Le guide complet de l'extension (congeler et reprendre un script, fork, métriques,
sécurité…) : php-cryo, docs/guide/,
et 13 exemples en ligne de commande : examples/.
Cette page-ci décrit le fonctionnement en détail. English: cryo.md.
Snapshots et CryoReader
cryo_snapshot(sys_get_temp_dir() . '/a.cryo', ['redact' => ['password']]); // le graphe d'objets, racines, orphelins
$r = CryoReader::open(sys_get_temp_dir() . '/a.cryo');
$r->top('class', 10); // qui prend la mémoire
$r->dominators(10); // qui RETIENT la mémoire
$r->path($id); // racine -> ... -> l'objet
cryo_roots_of($obj); // en direct, sans fichier : qui garde cet objet en vie ?
Dans le navigateur, le fichier est écrit dans le système de fichiers d'emscripten (/tmp), ou dans var/
(IndexedDB) pour le garder. Cryo Studio ouvre les .cryo.
Cryo\Engine
$e = Cryo\Engine::current();
$e->redefineFunction('score_bonus', fn (int $n) => $n * 3); // le corps de la fonction change en place
$e->journal(); $e->revert($id); $e->exportJournal();
Métriques
cryo_metrics() (mémoire, objets vivants, appels), cryo_metrics_sample() / cryo_metrics_mark() (séries
.cryom). Dans le navigateur il n'y a pas de serveur HTTP : le texte Prometheus et les événements arrivent sur la
page en événements cryo :
addEventListener('cryo', (e) => console.log(e.detail.kind, e.detail.text)); // kind 1 = JSON des métriques
La sandbox dans le navigateur (asynchrone)
Un Cryo\Sandbox\Sandbox est, dans le navigateur, un Web Worker qui démarre sa propre instance de PHP (le même
moteur et les mêmes fichiers que le jeu, engine/web/jumphp-cryo-worker.js) : sa mémoire est séparée, un exit(),
une erreur fatale, un dépassement de memory_limit ou un trap WebAssembly n'y touchent jamais le jeu. Sur le
bureau, c'est un processus PHP fils ; le même code marche des deux côtés.
Le navigateur appelle PHP image par image (pas de JSPI, pas d'Asyncify, pas de SharedArrayBuffer) : rien ne peut
attendre. Seule l'API asynchrone existe donc dans le navigateur ; call(), eval(), get(), set(),
include(), metrics(), proxy(), Future::await() d'un futur pas encore prêt, awaitAll/awaitAny,
Pool::call/map, recv() lèvent une SandboxException :
« synchronous calls are not possible in the browser: use callAsync()->then() or Sandbox::wait() ».
Envoyer (renvoie un Cryo\Sandbox\Future) |
|
|---|---|
callAsync('fn', [args]), callAsync(['Class', 'method'], [args]) |
appel |
evalAsync('return 1 + 1;'), includeAsync('src/x.php') |
code |
getAsync('nom'), setAsync('nom', $valeur) |
variables globales de la sandbox |
metricsAsync() |
mémoire, appels, objets vivants de la sandbox |
send($message) / messages() |
messages (Cryo\Sandbox\Channel::parent()->send() côté sandbox) |
Lire un Future (jamais bloquant) |
|
|---|---|
status() |
'pending', 'ready', 'failed', 'cancelled' |
isReady(), isFailed(), isCancelled() |
les mêmes drapeaux en booléens |
value() |
la valeur une fois prête, sinon null |
error() |
l'exception une fois en échec : RemoteException (exception dans la sandbox, getRemoteClass()), SandboxMemoryException, SandboxTimeoutException, SandboxCrashedException (getExitCode(), getStderr()), SandboxException |
then(fn ($v) => ..., fn (\Throwable $e) => ...) |
un nouveau futur ; les rappels tournent entre deux images |
cancel() |
une requête pas encore commencée n'est jamais exécutée |
Sandbox::wait($futur ou [$futurs], ?$timeout) |
un futur réglé quand tous le sont (valeurs, mêmes clés) |
Sandbox::pump(), Sandbox::pending() |
lit ce qui est arrivé et exécute les rappels ; nombre en attente |
La boucle : JumPHP\Cryo\SandboxLoop
SandboxLoop::spawn($options) crée la sandbox et ajoute à la boucle ReactPHP du jeu (GameLoop, celle qui tourne
une fois par image dans le navigateur) un timer périodique qui appelle Sandbox::pump() : les réponses arrivent,
les rappels then() s'exécutent, entre deux images, sans jamais attendre. SandboxLoop::wait() renvoie une
JumPHP\Async\Task (même API que les tâches : then(), isDone(), result()).
use JumPHP\Cryo\SandboxLoop;
final class PuzzleScene extends AbstractScene
{
private ?\Cryo\Sandbox\Sandbox $sb = null;
private string $text = '';
public function enter(array $params = []): void
{
// dans enter() : le PHP de la sandbox démarre dans son Worker (~0,5-1 s), les requêtes l'attendent là-bas
$this->sb = SandboxLoop::spawn([
'timeout' => 2, // par requête : au-delà, le Worker est terminé -> SandboxTimeoutException
'memory_limit' => '64M', // dépassé -> SandboxMemoryException
'disable_functions' => ['exec'],
'bootstrap' => 'src/Puzzle/rules.php',
'restart' => 'on_crash', // une nouvelle instance après un plantage
]);
$this->sb->callAsync('solve', [$this->grid])
->then(fn ($moves) => $this->text = count($moves) . ' moves',
fn (\Throwable $e) => $this->text = $e->getMessage());
SandboxLoop::wait([$this->sb->evalAsync('return 6 * 7;'), $this->sb->getAsync('version')], 5.0)
->then(fn (array $v) => ..., fn (\Throwable $e) => ...);
}
public function exit(): void
{
$this->sb?->kill();
}
public function render(Renderer $r): void
{
// les drapeaux, lus à chaque image sans attendre : $future->status() === 'pending' ...
}
}
- Une sandbox exécute ses requêtes une par une : une requête lente (ou une boucle infinie, jusqu'à son
timeout) retarde les suivantes de la même sandbox. Deux sandboxes travaillent en parallèle. timeout(secondes, par requête) : la page termine le Worker (worker.terminate()) et le futur échoue avecSandboxTimeoutException; les requêtes suivantes de cette sandbox échouent (SandboxCrashedException, code 124) et, avecrestart => 'on_crash', la requête suivante démarre une nouvelle instance.- Erreur fatale,
memory_limit,exit(): la sandbox répond d'abord (SandboxMemoryException,SandboxException), puis son instance se termine. - Un trap (débordement de pile du moteur...) ou une erreur du Worker :
SandboxCrashedException(code 134,getStderr(): le message du Worker). start => 'fork'n'existe pas dans le navigateur (pas de copie d'instance) :spawn(par défaut) ousnapshot.- Les valeurs passent sérialisées (
serialize) : nombres, chaînes, tableaux, objets simples ; pas de closures ni de ressources. Entiers 32 bits dans le navigateur (§2 de AGENTS.md).
Démo : games/cryo-sandbox-demo (bin/jumphp build cryo-sandbox-demo, bin/jumphp webshot cryo-sandbox-demo 8).
Côté JavaScript
engine/web/jumphp.js installe Module.cryoHost (fonctions EM_JS de ext-cryo/cryo_host.c) avec l'hôte de
engine/web/jumphp-cryo.js :
Module.cryoHost. |
|
|---|---|
spawn(json) → id |
démarre un Worker jumphp-cryo-worker.js ({"timeout": s, "memory_limit": octets}) |
send(id, bytes) |
octets vers la sandbox ; chaque trame complète (en-tête 12 octets + charge) part en un postMessage |
recv(id, cap) |
au plus cap octets déjà arrivés ; null : rien encore ; -2 : la sandbox est terminée |
kill(id), status(id), error(id) |
status : -1 tant qu'elle tourne, sinon son code de sortie (124 timeout, 134 trap, 137 tuée) |
Dans le Worker, chaque trame reçue est mise dans le cryoHost.recv de son PHP, puis
Module._cryo_sandbox_step() (exporté par le moteur) exécute une requête et renvoie ses réponses par
cryoHost.send(0, ...). Au début d'une requête, cryoHost.arm(ms, trame) donne à la page la réponse « timeout »
préparée : c'est elle que PHP reçoit si la page doit terminer le Worker. window.JumPHP.cryoSandboxes liste les
instances (débogage).