cryo / bridge
Warm boot with ext-cryo: freeze an application after its boot, resume it in each new process, with ready-made resource handlers and adapters for Laravel, Symfony and JumPHP.
Requires
- php: >=8.3
Requires (Dev)
- phpunit/phpunit: ^11.5
Suggests
- ext-cryo: required for the warm boot itself; without it WarmBoot::run() boots and runs normally
- ext-sodium: encryption of the CryoPdo password kept in the snapshot (otherwise openssl)
Provides
None
Conflicts
None
Replaces
None
README
Le boot d'une application (conteneur, configuration, routes, providers…) est fait une fois, congelé juste
après, et chaque processus suivant reprend depuis le snapshot au lieu de rebooter. Ce paquet fournit le
mode d'emploi complet autour de cryo_freeze(..., ['mode' => 'continue']) et -d cryo.thaw= :
WarmBoot::run(): boot → gel →$main($app), et la reprise à chaud au bon endroit ;Context: ce qui appartient à une exécution et pas au snapshot (fuseau, environnement, graines aléatoires, signaux, répertoire courant) ;ResourceBridge,CryoPdo,CryoCurl,Reconnectable: les connexions qui se rouvrent seules ;- des adaptateurs Laravel, Symfony et JumPHP (applications CLI) qui réinitialisent au thaw ce qui ne survit pas à un processus neuf.
PHP ≥ 8.3, licence MIT. ext-cryo est suggérée, pas requise : sans elle, WarmBoot::run() fait simplement
$main($boot()).
composer require cryo/bridge
Démarrage rapide
Le point d'entrée doit être le script principal (pas un fichier inclus) et appeler WarmBoot::run() au
niveau supérieur (ext-cryo refuse de geler à travers un include, une closure ou une fonction interne).
<?php // public/index.php, artisan, bin/console, app.php…
require __DIR__ . '/../vendor/autoload.php';
use Cryo\Bridge\WarmBoot;
use Cryo\Bridge\Adapter\LaravelAdapter;
exit(WarmBoot::run(__DIR__ . '/../storage/app.cryo',
function () { // le boot : joué au premier lancement seulement
$app = require __DIR__ . '/../bootstrap/app.php';
LaravelAdapter::register($app);
return $app;
},
function ($app) { // le travail : joué à chaque lancement
$kernel = $app->make(Illuminate\Contracts\Console\Kernel::class);
return $kernel->handle(new Symfony\Component\Console\Input\ArgvInput(), new Symfony\Component\Console\Output\ConsoleOutput());
},
['watch' => ['composer.lock', '.env', 'config', 'routes']],
));
export CRYO_KEY=$(openssl rand -hex 32) # ou -d cryo.key=…
php -d extension=cryo -d cryo.thaw=storage/app.cryo artisan about # 1er lancement : boot + gel
php -d extension=cryo -d cryo.thaw=storage/app.cryo artisan about # reprise à chaud, boot non rejoué
Déroulement :
- À froid (fichier absent, périmé ou invalide → démarrage normal, c'est le comportement de
cryo.thaw) :$app = $boot(), puiscryo_freeze($cacheFile, ['mode' => 'continue', 'watch' => …])écrit le snapshot et l'exécution continue avec$main($app). - À chaud : ext-cryo restaure l'état et reprend dans
WarmBoot::run(), juste après le gel. Les hookscryo_on_thaws'exécutent avant :Context(priorité 1000), les adaptateurs (0), les hooks de l'application (0, enregistrés après), puis la résolution des valeurs en attente (−1000). Ensuite$main($app)s'exécute ;WarmBoot::isWarm()vauttrue.
Options de WarmBoot::run()
| Option | Défaut | Rôle |
|---|---|---|
watch | ['composer.lock', '.env', 'config'] | fichiers / dossiers (relatifs à base_path) dont le changement invalide le snapshot. Les dossiers sont développés en fichiers (chacun hashé par l'extension) ; un fichier ajouté ou supprimé dans un dossier surveillé est détecté au thaw : le snapshot est supprimé et $boot est rejoué dans ce processus |
base_path | getcwd() | base des chemins relatifs de watch |
key | cryo.key, puis CRYO_KEY | clé HMAC passée à cryo_freeze(). Elle n'est écrite ni dans le snapshot ni dans les variables gelées. Le thaw au démarrage ne lit que cryo.key / CRYO_KEY : donnez-y la même clé |
pending | 'null' | valeurs qu'aucun handler n'a pu rouvrir : 'null', 'fail' (le thaw échoue avec la liste) ou callable(string $path, string $type, mixed $desc): mixed |
context | [] | options de Context::install() |
resources | [] | options de ResourceBridge::register(), p. ex. ['pdo' => fn (array $d) => new PDO(...)] |
compress, encrypt, exclude | — | passées telles quelles à cryo_freeze() |
strict | false | un gel raté lève l'exception (sinon : signalé via on_error, l'exécution continue à froid) |
on_error | error_log() | callable(string $message) ; jamais un warning PHP (les frameworks les transforment en exceptions) |
enabled | true | false : ne jamais geler (comme sans l'extension) |
Sans clé (cryo.key, CRYO_KEY ou l'option key) et sans cryo.allow_unsigned=1, WarmBoot ne gèle pas : le
snapshot non signé serait refusé au thaw. Le message passe par on_error.
Déjà vérifié par l'extension au thaw : même version de PHP, sources incluses inchangées, composer.lock et .env
à côté du script et dans le répertoire courant, signature HMAC, fichier 0600.
Context : ce qui est « par exécution »
ext-cryo laisse déjà les superglobales hors du snapshot : après un thaw, $_SERVER, $_ENV, $argv, $argc,
REQUEST_TIME(_FLOAT) sont ceux du nouveau processus. Context (installé par WarmBoot) remet le reste :
| Quoi | Au thaw | Option |
|---|---|---|
| fuseau horaire | date_default_timezone_set() du boot (un processus neuf repart de date.timezone) | timezone (true) |
| environnement | les variables posées pendant le boot (putenv(), Dotenv…) et absentes du nouveau processus sont remises (putenv, $_ENV, $_SERVER) ; les valeurs du nouveau processus gagnent toujours. Jamais CRYO_*, PWD, TERM… | env ('merge' | 'fresh') |
| argv | $GLOBALS['argv'] / ['argc'] alignés sur $_SERVER['argv'] | — |
| aléatoire | chaque Random\Randomizer et moteur à graine (Mt19937, PcgOneseq128XslRr64, Xoshiro256StarStar) du snapshot est remplacé par un neuf, graine aléatoire — sinon chaque démarrage tirerait les mêmes nombres. mt_rand(), random_int() n'ont pas d'état dans le snapshot | random (true) |
| signaux | les handlers pcntl_signal() du boot (SIGINT, SIGTERM, SIGHUP, SIGUSR1/2, SIGQUIT, SIGCHLD, SIGWINCH, SIGALRM) et pcntl_async_signals() sont réinstallés | signals (true) |
| répertoire | ext-cryo revient au répertoire du gel ; 'invocation' va dans $PWD du nouveau processus | cwd ('frozen') |
Accesseurs pour le code qui a gardé une copie : Context::argv(), startTime(), pid(), bootPid(),
bootTime(), isThawed(), boot(), restored().
Ressources
| Ressource | Comportement |
|---|---|
flux (fichiers, php://stdin/stdout/stderr, sockets) | gérés par l'extension, rien à faire |
CryoPdo | PDO qui retient DSN, utilisateur et options ; chaque thaw ouvre une connexion neuve |
CryoCurl | enveloppe de CurlHandle qui mémorise les options ; le thaw recrée le handle avec les mêmes options |
CurlHandle nu | handler cryo_register_resource : nouveau handle sur la même URL (les autres options sont perdues) |
Random\Engine\Secure | handler : un moteur neuf (il n'a pas d'état) |
PDO nu | uniquement avec ResourceBridge::register(['pdo' => fn (array $desc) => …]) (PDO ne donne pas son DSN) ; sinon valeur en attente, résolue par la politique pending (null par défaut) |
| client maison | implements Reconnectable + use ReconnectableTrait |
CryoPdo et le mot de passe
Le mot de passe n'est jamais écrit en clair :
// relu dans l'environnement à chaque thaw (rien dans le snapshot)
$pdo = new CryoPdo($dsn, 'app', getenv('DB_PASSWORD'), passwordSource: 'env:DB_PASSWORD');
// ou chiffré dans le snapshot (libsodium, sinon AES-256-GCM), avec une clé relue au thaw
$pdo = new CryoPdo($dsn, 'app', $password, encryptionKey: 'file:/run/secrets/cryo-pdo-key');
Les sources sont 'env:NOM', 'file:CHEMIN' ou une Closure (gardée comme code, rejouée au thaw) ; jamais la
valeur elle-même. Un mot de passe sans passwordSource ni encryptionKey fait échouer le gel (LogicException
dans __cryoFreeze) : WarmBoot le signale et continue à froid. Les transactions en cours, requêtes préparées
et réglages de session (SET …) ne survivent pas : WarmBoot gèle entre le boot et le travail, quand il n'y
en a pas.
Reconnectable
final class Mailer implements Cryo\Bridge\Reconnectable
{
use Cryo\Bridge\ReconnectableTrait;
private $socket;
public function __construct(private string $host, private int $port) { $this->reconnect(); }
public function cryoConnectionProperties(): array { return ['socket']; } // non sauvegardé
public function reconnect(): void { $this->socket = stream_socket_client("tcp://$this->host:$this->port"); }
}
Adaptateurs
XxxAdapter::register($cible, $options) ajoute l'adaptateur à WarmBoot ; son reset() s'exécute à chaque
thaw (et WarmBoot::resetAdapters() le déclenche à la main pour les tests). Aucun framework n'est requis à
l'installation : les adaptateurs appellent les méthodes seulement si elles existent (method_exists,
class_exists). Option commune : on_thaw (callables (cible, CryoThawContext|null) exécutés après le reset).
Ce qui a été fait au dernier thaw : WarmBoot::lastThaw() (adapters, errors, pending).
Laravel — LaravelAdapter::register($app, ['forget' => [...]])
Uniquement les services déjà résolus (rien n'est construit pour rien), dans cet ordre :
db:DatabaseManager::purge($nom)pour chaque connexion ouverte (getConnections()) ; la requête suivante ouvre un PDO neuf ;redis:RedisManager::purge($nom)pour chaque connexion (connections()) ;cache:CacheManager::forgetDriver([stores])(ouforgetDrivers()), puisforgetInstance('cache.store');queue:forgetConnections()/forgetDrivers()s'ils existent, sinon la propriétéconnectionsvidée ;session:SessionManager::forgetDrivers(), puisforgetInstance('session.store');auth:AuthManager::forgetGuards(), puisforgetInstance('auth.driver');cookie:CookieJar::flushQueuedCookies();forgetInstance('request')(le kernel HTTP lie la nouvelle requête) ;forgetScopedInstances(), puisforgetInstance()de chaque service de l'optionforget;Illuminate\Support\Facades\Facade::clearResolvedInstances().
Non touchés : config, routes, vues, événements, canaux de log (leurs fichiers sont des flux rouverts par l'extension), générateur d'URL.
Symfony — SymfonyAdapter::register($kernel) (kernel démarré, ou son conteneur)
services_resetter→reset()(tous les services taggéskernel.reset) ;doctrine:close()de chaque connexion (getConnections()), puisresetManager($nom)de chaque gestionnaire (getManagerNames()) ;request_stackvidée (pop()jusqu'ànull) ;logger:reset()(Monolog : handlers et processors), sinonreset()de chaque handler.
Seuls les services déjà initialisés sont touchés (initialized() quand le conteneur l'a).
JumPHP — JumphpAdapter::register($app)
Pour les applications CLI (kind: cli, Symfony Console + symfony/tui) et les programmes en arrière-plan
(services, serveurs). Au thaw :
- répertoire de l'utilisateur :
chdir($PWD)(l'extension revient au répertoire du gel, or une application CLI prend les chemins relatifs depuis là où l'utilisateur se trouve) ; la constanteJUMPHP_CWD(définie par le stub de l'exécutable exporté, gelée avec l'ancienne valeur) est redéfinie viaCryo\Enginesicryo.engine=1; optioncwd => 'frozen'pour ne pas bouger ; Symfony\Component\Console\Terminal: taille, stty et mode de couleur en cache oubliés ;- option
reset_loop => true:React\EventLoop\Loop::set(new StreamSelectLoop)pour un serveur gelé avec une boucle qui tenait déjà des sockets ou des signaux (les timers ajoutés au boot sont perdus) ; on_thaw: p. ex. rechoisir la commande par défaut selonstream_isatty(STDOUT), comme le squelette CLI le fait au boot (sinon c'est la valeur du processus qui a gelé).
exit(WarmBoot::run(__DIR__ . '/var/app.cryo',
function () { $main = App\Main::boot(__DIR__); JumphpAdapter::register($main); return $main; },
fn (App\Main $main) => $main->run()));
Les jeux et applications graphiques ne sont pas pris en charge : register() refuse
JumPHP\Kernel\Application et JumPHP\Kernel\Engine (LogicException). Engine::boot() ouvre SDL (fenêtre,
renderer, surface headless), charge les textures (SDL_Texture), ouvre l'audio (chunks et musiques SDL_mixer,
OpenAL pour Audio3d), les manettes et les sessions réseau (NetSession, Tcp, Ssh, RuntimeLink). Aucun de
ces handles ne survit à un processus : il faudrait tout recréer dans l'ordre, et Sdl ne retient que le fichier
de chaque texture (pour le hot reload), pas l'état du renderer ni les cibles de rendu. La partie du boot qui
resterait à gagner (configuration + conteneur compilé JumPHPCachedContainer) est déjà mise en cache par JumPHP.
Un jeu dégelé tiendrait des pointeurs morts : refusé plutôt que planter plus tard.
Tests
cd bridge
composer install
vendor/bin/phpunit # unitaires (sans ext-cryo) + intégration (avec)
tests/Unit: repli sans extension,Context, ressources (CryoPdo,CryoCurl,Reconnectable,Secret), adaptateurs contre de petites classes factices qui imitent les API utilisées (tests/Fake).tests/Integration: vrais allers-retours warm boot dans des processus enfants. ext-cryo est compilée depuis../ext-cryodans un dossier temporaire (phpize && ./configure --enable-cryo && make, une fois par version des sources), avecCRYO_BRIDGE_PHP(défaut/usr/bin/php, un PHP partagé avecphpizeà côté). Le 1er lancement gèle (mode continue), le 2e (-d cryo.thaw=) reprend : boot non rejoué, resets des adaptateurs faits, PDO SQLite reconnecté et fonctionnel, argv / fuseau / environnement / graines / signaux remis, clé absente du snapshot ; invalidation par fichier modifié et par fichier ajouté. PDO SQLite doit exister pour ce PHP (dans sonextension_dir, ouCRYO_BRIDGE_PDO_SQLITE=/chemin/pdo_sqlite.socompilé depuisext/pdo_sqlitedes sources de la même version de PHP) ; sinon ces tests sont sautés avec la raison.
Limites
- Le point d'entrée doit être le script principal, et
WarmBoot::run()appelé à son niveau supérieur ou depuis des fonctions/méthodes utilisateur (pas depuis une closure, uninclude, un callback interne commearray_map). - Un snapshot qui passe les contrôles (signature, sources) mais dont la restauration échoue fait échouer le
démarrage (erreur fatale avant tout code PHP) : supprimez le fichier. Même chose si une valeur reste en attente
avec
pending => 'fail'. - Les objets qui ont copié une valeur « par exécution » au boot la gardent (un
ArgvInputconstruit au boot, une date calculée au boot,stream_isatty()évalué au boot) : construisez-les dans$main, ou corrigez-les danson_thaw. PDOnu,mysqli, clients Redis/AMQP natifs… : sans handler, ils deviennentnullau thaw (politiquepending) ; c'est sans conséquence pour Laravel/Symfony dont les adaptateurs purgent les connexions, mais le code qui les garde ailleurs doit utiliserCryoPdo,Reconnectableou un handler.- Fichiers ajoutés hors des dossiers de
watch: non détectés (seuls les fichiers inclus,composer.lock,.envet la listewatchle sont). - Les adaptateurs Laravel et Symfony sont testés contre des imitations des API, pas contre les frameworks réels.