Search by

cryo / bridge

davidnurdin

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.

v0.1.0 2026-11-14 16:48 UTC

This package is auto-updated.

Last update: 2026-11-14 18:45:42 UTC


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 :

  1. À froid (fichier absent, périmé ou invalide → démarrage normal, c'est le comportement de cryo.thaw) : $app = $boot(), puis cryo_freeze($cacheFile, ['mode' => 'continue', 'watch' => …]) écrit le snapshot et l'exécution continue avec $main($app).
  2. À chaud : ext-cryo restaure l'état et reprend dans WarmBoot::run(), juste après le gel. Les hooks cryo_on_thaw s'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() vaut true.

Options de WarmBoot::run()

OptionDéfautRô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_pathgetcwd()base des chemins relatifs de watch
keycryo.key, puis CRYO_KEYclé 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()
strictfalseun gel raté lève l'exception (sinon : signalé via on_error, l'exécution continue à froid)
on_errorerror_log()callable(string $message) ; jamais un warning PHP (les frameworks les transforment en exceptions)
enabledtruefalse : 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 :

QuoiAu thawOption
fuseau horairedate_default_timezone_set() du boot (un processus neuf repart de date.timezone)timezone (true)
environnementles 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éatoirechaque 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 snapshotrandom (true)
signauxles handlers pcntl_signal() du boot (SIGINT, SIGTERM, SIGHUP, SIGUSR1/2, SIGQUIT, SIGCHLD, SIGWINCH, SIGALRM) et pcntl_async_signals() sont réinstalléssignals (true)
répertoireext-cryo revient au répertoire du gel ; 'invocation' va dans $PWD du nouveau processuscwd ('frozen')

Accesseurs pour le code qui a gardé une copie : Context::argv(), startTime(), pid(), bootPid(), bootTime(), isThawed(), boot(), restored().

Ressources

RessourceComportement
flux (fichiers, php://stdin/stdout/stderr, sockets)gérés par l'extension, rien à faire
CryoPdoPDO qui retient DSN, utilisateur et options ; chaque thaw ouvre une connexion neuve
CryoCurlenveloppe de CurlHandle qui mémorise les options ; le thaw recrée le handle avec les mêmes options
CurlHandle nuhandler cryo_register_resource : nouveau handle sur la même URL (les autres options sont perdues)
Random\Engine\Securehandler : un moteur neuf (il n'a pas d'état)
PDO nuuniquement 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 maisonimplements 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 :

  1. db : DatabaseManager::purge($nom) pour chaque connexion ouverte (getConnections()) ; la requête suivante ouvre un PDO neuf ;
  2. redis : RedisManager::purge($nom) pour chaque connexion (connections()) ;
  3. cache : CacheManager::forgetDriver([stores]) (ou forgetDrivers()), puis forgetInstance('cache.store') ;
  4. queue : forgetConnections() / forgetDrivers() s'ils existent, sinon la propriété connections vidée ;
  5. session : SessionManager::forgetDrivers(), puis forgetInstance('session.store') ;
  6. auth : AuthManager::forgetGuards(), puis forgetInstance('auth.driver') ;
  7. cookie : CookieJar::flushQueuedCookies() ;
  8. forgetInstance('request') (le kernel HTTP lie la nouvelle requête) ;
  9. forgetScopedInstances(), puis forgetInstance() de chaque service de l'option forget ;
  10. 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)

  1. services_resetter → reset() (tous les services taggés kernel.reset) ;
  2. doctrine : close() de chaque connexion (getConnections()), puis resetManager($nom) de chaque gestionnaire (getManagerNames()) ;
  3. request_stack vidée (pop() jusqu'à null) ;
  4. logger : reset() (Monolog : handlers et processors), sinon reset() 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 :

  1. 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 constante JUMPHP_CWD (définie par le stub de l'exécutable exporté, gelée avec l'ancienne valeur) est redéfinie via Cryo\Engine si cryo.engine=1 ; option cwd => 'frozen' pour ne pas bouger ;
  2. Symfony\Component\Console\Terminal : taille, stty et mode de couleur en cache oubliés ;
  3. 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) ;
  4. on_thaw : p. ex. rechoisir la commande par défaut selon stream_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-cryo dans un dossier temporaire (phpize && ./configure --enable-cryo && make, une fois par version des sources), avec CRYO_BRIDGE_PHP (défaut /usr/bin/php, un PHP partagé avec phpize à 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 son extension_dir, ou CRYO_BRIDGE_PDO_SQLITE=/chemin/pdo_sqlite.so compilé depuis ext/pdo_sqlite des 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, un include, un callback interne comme array_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 ArgvInput construit au boot, une date calculée au boot, stream_isatty() évalué au boot) : construisez-les dans $main, ou corrigez-les dans on_thaw.
  • PDO nu, mysqli, clients Redis/AMQP natifs… : sans handler, ils deviennent null au thaw (politique pending) ; c'est sans conséquence pour Laravel/Symfony dont les adaptateurs purgent les connexions, mais le code qui les garde ailleurs doit utiliser CryoPdo, Reconnectable ou un handler.
  • Fichiers ajoutés hors des dossiers de watch : non détectés (seuls les fichiers inclus, composer.lock, .env et la liste watch le sont).
  • Les adaptateurs Laravel et Symfony sont testés contre des imitations des API, pas contre les frameworks réels.