apps/cryo-studio
/ README.md · commit 76aa68d
# Cryo StudioAnalyse des snapshots mémoire `.cryo` et des séries `.cryom` écrits par l'extension PHP **ext-cryo** (`cryo_snapshot()`,`cryo_metrics_sample()`), pour trouver la ligne PHP qui fuit et celle qui garde ses objets. Application JumPHP(`JumPHP\Gui`, sans HTML) : https://jumphp.net/cryo-studioÉcrans (radios en haut de la fenêtre ; la liste des snapshots à gauche) :- **Vue d'ensemble** : alertes des heuristiques (`heuristics()` : score, type, message, chemin), top des classes (taille retenue), des sites, racines (clic → inspecteur).- **Fuites** : delta par site d'allocation, classe ou pile (`CryoDelta::bySite/byClass/byStack`), `[LEAK]`, colonne « accroché par » (`hooked_by`, site d'écriture) ; le détail montre le code de la ligne de création et de la ligne d'écriture, et le chemin type (`explain()`).- **Classes** : objets par classe triés par taille retenue ; clic → instances (`query(['class' => …])`) ; clic → inspecteur.- **Inspecteur** : `node($id)` (type, classe, taille, retenu, site, écriture, pile, racines), références sortantes / entrantes cliquables, « Chemin vers une racine » (`path()`), Retour.- **Dominateurs** (`dominators()`), **Orphelins** (`orphans()` par classe), **Doublons** (`dupes()`) : clic → inspecteur.- **Requête** : langage de `query()` (`class=Query and retained>1K`), résultats cliquables, erreurs de syntaxe affichées.- **Série** : courbe mémoire d'un `.cryom` et ses repères (`cryo_metrics_mark()`), widget maison `App\Gui\MemoryChart`.- **Pile** : un fichier de freeze `.cryf` (`cryo_freeze()`) : en-tête (PHP, date, hôte, signé / zlib, reprises), frames de la plus interne à `{main}` (fonction, fichier:ligne), au clic leurs variables (type + aperçu court) et le code de la ligne. Lu par `App\Cryo\FreezeFile` sans exécuter de code (`unserialize` avec `allowed_classes => false`), signature non vérifiée (un visualiseur n'a pas la clé), fichier chiffré refusé ; avec ext-cryo, l'en-tête vient de `cryo_info()`.- **Live** : connexion à un script qui tourne et qui a lancé l'exportateur d'ext-cryo (`cryo_metrics_serve(9600, '127.0.0.1', ['cors' => '*', 'token' => '...'])`). Adresse + jeton, « Connect » : l'écran interroge `/metrics.json` toutes les 2 s par `$this->engine->http()` (`fetch()` dans le navigateur, jamais bloquant, une seule requête à la fois), dessine la courbe mémoire en direct (`App\Gui\MemoryChart`, 10 min gardées) et les compteurs (mémoire, RSS, objets vivants, GC, objets par classe avec `cryo.metrics=1`). « Snapshot » appelle `POST /snapshot` : le script écrit un `cryo_snapshot()` à son prochain point sûr, le fichier reçu est enregistré dans `sys_get_temp_dir()/cryo-studio-live/` et rejoint la liste des snapshots (il remplace la démo, comme un fichier ouvert) ; il sert dans tous les écrans, et deux snapshots Live successifs donnent un delta (Fuites). Les snapshots sont marqués sur la courbe. Seule l'adresse est retenue (options), jamais le jeton. Erreurs dites en clair : pas de réponse (script arrêté, CORS absent), 401 (jeton), 403 (`snapshot => false`), 409, 504 (script bloqué dans `sleep()` ou une E/S). Dans le navigateur, le Live marche grâce aux en-têtes CORS de `cryo_metrics_serve()` (option `cors`, préflight et `Access-Control-Allow-Private-Network` gérés) ; `http://127.0.0.1` est accepté depuis une page https par Chrome et Firefox.Vérifié dans le navigateur avec un moteur WASM de test qui inclut ext-cryo (`bin/jumphp build` + `webshot`) : « Reader:ext-cryo », les écrans Vue d'ensemble, Fuites, Série et Pile sans erreur ; avec le moteur publié (sans ext-cryo), le replipur PHP (32 bits) donne les mêmes écrans (« Reader: PHP reader »).Le Live est testé contre un faux exportateur (`tests/FakeExporter.php`, réponses immédiates ou différées comme `fetch()`) ;`App\Cryo\LiveClient` a aussi été vérifié de bout en bout avec le vrai `JumPHP\Http` (desktop) contre un script qui faittourner `cryo_metrics_serve()` (jeton, courbe, deux snapshots, delta).| Fichier | Rôle || --- | --- || `src/Form/MainForm.php` + `forms/MainForm.form.yaml` | la fenêtre (une page par écran) || `src/Gui/MemoryChart.php` | le widget de la courbe mémoire || `src/Cryo/LiveClient.php` | le lien Live : sondage de `/metrics.json`, `POST /snapshot`, messages d'erreur, points de la courbe ; transport injectable (`$engine->http()`, ou un faux serveur dans les tests) || `src/Cryo/FreezeFile.php` | lecteur pur PHP des fichiers de freeze `.cryf` v2 (en-tête, frames, variables) || `src/Cryo/Studio.php` | ensemble de snapshots, lignes des écrans, extraits de source || `src/Cryo/PhpCryoReader.php`, `PhpCryoDelta.php`, `MetricSeries.php` | lecteurs pur PHP des formats `.cryo` v1 et `.cryom` v1, copiés tels quels du dépôt PhpCryo (`cryo-studio/src/`, seul le namespace change) : mêmes résultats que `CryoReader` / `CryoDelta` / `cryo_metrics_read()` d'ext-cryo, compatibles PHP 32 bits (jamais `pack`/`unpack` `P`/`q`/`J`). Quand ext-cryo est chargée (natif, ou un moteur qui l'inclut), l'extension est utilisée. || `stubs/cryo.stub` | `CryoReader`, `CryoDelta`, `cryo_metrics_read()` pour PHPStan || `assets/demo/` | `shop_worker.php` (un worker qui fuit), ses 5 snapshots (`cryo.track_alloc=stack`) et `shop.cryom` ; `freeze_worker.php` et `worker.cryf` (gelé au milieu de sa boucle, signé avec la clé `demo-key`, zlib) || `tools/demo/make_demo.sh`, `rewrite_paths.php` | régénèrent la démo avec ext-cryo compilée ; dans les snapshots les chemins absolus deviennent `demo/` (section STRS) ; le freeze, signé HMAC, n'est pas réécrit (la signature serait cassée) : il est produit dans un espace de noms privé (`unshare`) où le dossier est `/mnt/demo` et l'hôte `cryo-demo` || `tools/logo.py`, `tools/site/images.py` | logo, vignette et images du site (depuis les captures des tests) |```bashbin/jumphp test cryo-studio # PHPStan + 37 tests (GameTestCase) + smoke testbin/jumphp run cryo-studiopython3 apps/cryo-studio/tools/site/images.py && bin/jumphp build:site cryo-studio && bin/jumphp siteshot cryo-studio# démo : compiler ext-cryo dans une copie (phpize && ./configure --enable-cryo && make), puisapps/cryo-studio/tools/demo/make_demo.sh <copie>/modules/cryo.so /usr/bin/php # snapshots, série et freeze```