22 KiB
ext-cryo 0.1.0-dev
Guide (français) : ../docs/guide/README.md ; exemples : ../examples/.
Snapshot, restore, leak analysis and sandboxing for PHP (CLI and WebAssembly).
What works — every milestone of the roadmap
| Milestone | Feature | Status |
|---|---|---|
| 1 | cryo_snapshot() (object graph, roots, orphans, function statics), allocation sites (cryo.track_alloc=site|stack), CryoReader |
done |
| 2 | path(), dominators() (retained size), orphans(), dupes(), query() (array or class=App\* and retained>1M), node(), heuristics(), write sites (« hooked by »), allocation stacks, CryoDelta (bySite/byClass/byStack/timeline/explain), cryo_roots_of(), cryo_orphans(), cryo_diff(), redact |
done |
| 2 | metrics: cryo_metrics*(), live counts per class (cryo.metrics=1), .cryom series (cryo_metrics_sample/mark/read), HTTP exporter (cryo_metrics_serve: Prometheus, JSON, series, remote snapshot, CORS, token), StatsD (cryo_metrics_push), OTLP (cryo.otlp_endpoint), cryo.auto_snapshot_every |
done |
| 3 | Cryo Studio (JumPHP app, cryo-studio/ library + https://jumphp.net/cryo-studio) |
done |
| 4 | cryo_restart() (also from a cryo_memory_watch() callback), cryo_memory_watch(), cryo_fork_pool() (max_jobs, max_memory, pull mode), cryo_fork() child/parent/template, cryo_thaw_fork(), cryo_fork_send/recv(), hooks cryo_on_freeze/on_thaw, cryo_register_resource() |
done |
| 5 | cryo_freeze() / cryo_thaw() with the whole stack (nested frames, $this, extra args, foreach over arrays, temporaries), closures (bound references), streams, CryoAware, #[CryoTransient], exclude, error/exception/shutdown handlers |
done |
| 6 | Cryo\Engine (redefine/add/remove/rename functions and methods, constants, superglobals, journal, revert, export/replay) and Cryo\Sandbox (spawn/fork/snapshot, futures, channel, proxies, Pool, rlimits, seccomp) |
done |
| 7 | warm boot (-d cryo.thaw=file, or CRYO_THAW=file; a missing or stale file = a normal start), signed files (HMAC-SHA256, cryo.key, required unless cryo.allow_unsigned=1), zlib compression, XChaCha20-Poly1305 encryption (libsodium, optional), 0600 files, cryo_info(), cryo_verify(), cryo_is_thawed(), cryo_thaw_count(), cryo_origin() |
done |
| WASM | linked statically in the JumPHP engine (--enable-cryo --enable-cryo-wasm); host functions are EM_JS calls to Module.cryoHost (wasm-host/) |
built |
Tested: PHP 8.4.27 and 8.5.12 NTS, Linux x86_64 — 68 .phpt (make test); WebAssembly: the JumPHP engine builds with it.
Torture test
bin/cryo-torture script.php runs the script with -d cryo.torture=K for K = 1, 2, 3...: it freezes at its K-th
safe point (loop header, function entry), a fresh process thaws it, and the output of both together must be the
output of a normal run (the « freeze at every instruction » test of the plan; tests/016_torture.phpt, CI).
Freeze, restart, warm boot
cryo_on_thaw(function (CryoThawContext $ctx) use (&$pdo, $dsn) { $pdo = new PDO($dsn); });
cryo_memory_watch(512 << 20, fn() => cryo_restart('/var/run/import.cryo')); // freezes at the next safe point
foreach ($rows as $row) { importRow($row); } // resumes here, same $offset
$app = require 'bootstrap/app.php';
if (cryo_freeze('/var/cache/app.cryo', ['mode' => 'continue']) === CRYO_THAWED) { /* warm start */ }
// php -d cryo.thaw=/var/cache/app.cryo -d cryo.key=... script.php
cryo_thaw()runs in a fresh process (php -d cryo.key=... -r 'cryo_thaw("f.cryo");'): it includes again the files the frozen process had, recompiles the script (refused if any source, composer.lock or .env changed), restores the values, runs thecryo_on_thawhooks, rebuilds the frames on the VM stack and resumes.- Refused with a readable reason: an internal frame between {main} and the call (array_map callback, error handler...), a running generator or fiber, a closure frame, an include frame, a pending call (freeze inside the arguments of a call), a foreach over an object or by reference, JIT on.
- Values go through the PHP serializer, except objects of classes with
__sleep/__wakeup/__serialize/__unserialize: their properties are carried raw and they come back without constructor nor magic method (as the spec asks); closures, resources, generators,CryoAwareobjects and transient values go through markers (cryo_walk.c). - Files: zstd (default;
lz4= zstd's fastest level; zlib when asked or without libzstd, e.g. in WebAssembly), XChaCha20-Poly1305 with libsodium or the built-in implementation (cryo_crypto.c, same bytes: a file encrypted in the browser decrypts on a server and back).
Build (Linux)
phpize && ./configure --enable-cryo && make && make test
php -d extension=$PWD/modules/cryo.so -d cryo.track_alloc=site tests/demo_leak.php
Build (WebAssembly, JumPHP-style static link)
make -f Makefile.wasm PHP_SRC=/path/to/php-src
Align PHP_CONFIGURE_FLAGS and EMCC_LDFLAGS with the JumPHP php-wasm-sdl build.
Find a leak in 3 commands
php -d extension=cryo -d cryo.track_alloc=site your_script.php # calls cryo_snapshot() every N batches
bin/cryo-inspect delta /tmp/snap-*.cryo
bin/cryo-inspect top /tmp/snap-3.cryo --by=site
Then, on one snapshot:
bin/cryo-inspect top /tmp/snap-3.cryo --by=write # the line that stored the leaking objects
bin/cryo-inspect query /tmp/snap-3.cryo --class=App\\Query --limit=1
bin/cryo-inspect path /tmp/snap-3.cryo 1234 # root -> ... -> node 1234
bin/cryo-inspect dominators /tmp/snap-3.cryo # who retains the most memory
bin/cryo-inspect orphans /tmp/snap-3.cryo # uncollected cycles
bin/cryo-inspect dupes /tmp/snap-3.cryo # duplicated strings / arrays
bin/cryo-inspect query /tmp/snap-3.cryo 'class=App\* and retained>1M'
bin/cryo-inspect heuristics /tmp/snap-3.cryo /tmp/snap-1.cryo /tmp/snap-2.cryo
bin/cryo-inspect delta /tmp/snap-*.cryo --explain=0 # code + typical paths of the first site
bin/cryo-inspect serve --port=9600 /tmp/snap-*.cryo # GET /info /top /delta /path /node /query ...
Live, without a file: cryo_roots_of($obj) (who keeps this object alive?), cryo_orphans().
cryo_snapshot($f, ['redact' => ['password', 'token', '*Secret*']]) keeps only the length of the
matching strings (keys below them become [redacted N], flat arrays holding them get no hash).
cryo.track_alloc=site records the allocation site and the write site of each object;
cryo.track_alloc=stack also records the allocation call stack (slower). The tracking installs
user opcode handlers on ZEND_NEW and the ZEND_ASSIGN* opcodes (chained with any previous handler).
Live: metrics and snapshots of a running script
cryo_metrics_serve(9600, '127.0.0.1', [
'cors' => 'https://jumphp.net', // or '*'; default: no CORS header
'token' => getenv('CRYO_TOKEN'), // ?token=... or Authorization: Bearer ...; else 401
'snapshot' => ['redact' => ['password']], // cryo_snapshot() options; false disables /snapshot
'snapshot_timeout' => 10, // seconds (default 10)
]);
cryo_metrics_sample(1000, '/tmp/app.cryom'); // optional: feeds /series.json
| Endpoint | Answer |
|---|---|
GET /metrics |
Prometheus text |
GET /metrics.json |
cryo_metrics() + time + pid (+ class_counts, top 50, with cryo.metrics=1); refreshed every second |
GET /series.json?since=SEQ |
samples of the active cryo_metrics_sample() series with seq >= SEQ (last 1024), its marks, active, session, interval_ms, file, next (the since of the next call) |
POST /snapshot (also GET when a token is set) |
the script takes a cryo_snapshot() at its next safe point; the child returns the .cryo (application/octet-stream, Content-Disposition, X-Cryo-Snapshot: N). 504 after snapshot_timeout, 409 while one is pending, 403 with snapshot => false |
OPTIONS * |
preflight: 204, Access-Control-Allow-Methods/Headers, and Access-Control-Allow-Private-Network: true when asked (a public page calling 127.0.0.1); never needs the token |
- The exporter is a plain child process (no PHP in it). The parent sends it the Prometheus text, the
JSON and the samples over a socketpair, written with
MSG_DONTWAIT(what does not fit waits for the next tick, whole frames only): the script never blocks on the exporter. - A snapshot request is read by the sampling thread of the script, which raises
EG(vm_interrupt); the snapshot is written at the next safe point into a 0600 file ofsys_get_temp_dir(), streamed by the child, then deleted. A script stuck in a long internal call (sleep(), blocking I/O) cannot take it: 504 after the timeout, and the request is cancelled. - Cryo Studio (the JumPHP app) connects to it from the browser:
corsmust allow its origin. - WebAssembly: there is no exporter process; the Prometheus text goes to
cryo_host_emit(), and the options throw aCryoException.
Layout
| File | Role |
|---|---|
cryo.c |
module, INI, functions, metrics, stubs of later milestones |
cryo_graph.c |
allocation tracking + snapshot writer (iterative walk, no C recursion) |
cryo_reader.c |
CryoReader (records stay in C memory), CryoDelta, graph analyses, live functions |
cryo_analysis.h |
declarations and arginfo of cryo_roots_of(), cryo_orphans(), cryo_diff() |
cryo_engine.c |
Cryo\Engine: in-place body swap, ZEND_INIT_FCALL frame fix, journal, export/replay |
cryo_sandbox.c |
Cryo\Sandbox\*: framed channel, child loop, process control, futures, pool |
cryo_metrics.c |
metrics, .cryom series, exporters (cryo_metrics_serve child: Prometheus, JSON, series, remote snapshot; StatsD; OTLP) |
cryo_format.h |
.cryo v1 format |
cryo_host.h |
WebAssembly host imports (restart, clone, spawn, channel, timers) |
cryo_platform.c |
backend selection (posix / wasm) |
cryo.stub.php |
target public API |
bin/cryo-inspect |
CLI |
Makefile.wasm |
static WASM build recipe |
Cryo\Engine (milestone 6)
$e = Cryo\Engine::current();
$id = $e->redefineFunction('price', fn(int $qty) => $qty * 2); // call sites already cached keep working
$e->redefineMethod('Cart', 'total', function () { return $this->items * 10; }); // $this, private access
$e->redefineConstant('Cart::VAT', 0.2);
$e->journal(); // [id, kind, target, time, file, line, replayable]
$e->revert($id); // or revert() for everything; everything is reverted at the end of the request
- User functions keep their address: the op_array receives the closure's body in place (name, scope,
prototype, access flags and attributes are kept), with its own run-time cache and static variables.
No opcode handler: when a body is swapped, the frame size precomputed in the
ZEND_INIT_FCALLcall sites already compiled is grown (cryo_patch_call_sites()), so the Engine costs nothing until it is used. - Refused: OPcache-cached (immutable) code, JIT on, inside a Fiber, a function that is running, being called or suspended in a generator/fiber, inherited methods (redefine the declaring class).
- Internal functions (
cryo.engine_internal_override=1): trampoline handler; inside the closure the function is the original one. Calls compiled before the change to VM builtins (strlen,count,is_*, ...) or frameless functions (in_array,str_replace, ...) do not see it; code compiled after does (ZEND_COMPILE_NO_BUILTINS). - Constants: values are changed in place (call sites cache the slot). The compiler inlines constants
already known when a file is compiled (
self::Xin the class body, constants defined before aninclude): those references keep the old value. Code compiled after a change fetches at run time. exportJournal()/replayJournal()(C:cryo_engine_journal_export()/_replay()): closures are exported as file + first/last line + scope + bound variables and recompiled from the source.
Cryo\Sandbox (milestone 6)
use Cryo\Sandbox\{Sandbox, Pool};
$sb = new Sandbox(['memory_limit' => '64M', 'timeout' => 2, 'network' => false, 'restart' => 'on_crash']);
$sb->call('strtoupper', ['abc']); // "ABC"
$f = $sb->evalAsync('return heavy();'); // Future: await(), isReady(), cancel(), then()
Sandbox::awaitAll([$f]);
$pool = new Pool(4, ['max_jobs' => 100]);
$pool->map('render', $listOfArgs);
- Frames
length | type | id | payload(PHP serializer) over a socketpair; several requests in flight. start:spawn(default, exec ofPHP_BINARYwith the same ini file and the shared extensions loaded here),fork,snapshot(spawn +cryo_thaw()),thread(refused on NTS).- Exceptions:
RemoteException(class, message, file, line, trace of the child),SandboxCrashedException(signal, exit code, last 2 KiB of stderr),SandboxTimeoutException(timeout,cpu_time),SandboxMemoryException. After a fatal error the child exits (the interpreter is not trusted any more);restartdecides what happens next. network => false: seccomp-bpf filter (Linux x86_64/aarch64/i386/arm) that makessocket()fail with EPERM for every family but AF_UNIX; elsewhere the PHP network functions are disabled.status()['network']tells which (seccomporfunctions). On i386 libcs that go throughsocketcall()the filter does not apply.disable_functions: realdisable_functionsin a spawned child; in a fork the handlers are replaced (frameless calls compiled in the parent before the fork are not covered).- WebAssembly (
--enable-cryo-wasm): same protocol overcryo_host_spawn/clone/send/recv/kill/status; the host calls the exportedcryo_sandbox_main(channel)in the new instance. Timeouts are enforced by the parent (no signals). Built into the JumPHP engine; without a host that implements spawn/recv (the JumPHP page installs onlyemit), a sandbox reports « no host ».
Cryo\Sandbox in the browser (WebAssembly): asynchronous only
The browser runs PHP frame by frame (no JSPI, no Asyncify, no SharedArrayBuffer): nothing can wait. A sandbox
is a Web Worker running its own PHP instance (the JS host spawns it: Module.cryoHost.spawn), and only the
non-blocking API works there; the synchronous one (call, eval, get, set, include, metrics, proxy,
recv, await() of a pending future, awaitAll/awaitAny, Pool::call/map) throws a SandboxException
("synchronous calls are not possible in the browser: use callAsync()->then() or Sandbox::wait()"). The same
non-blocking API works on POSIX too (tests/028_sandbox_nonblocking.phpt).
$sb = new Cryo\Sandbox\Sandbox(['timeout' => 2, 'memory_limit' => '64M']); // returns at once (HELLO read later)
$f = $sb->callAsync('str_repeat', ['ab', 3]); // also evalAsync, includeAsync, getAsync, setAsync, metricsAsync
$f->then(fn ($v) => print($v), fn (Throwable $e) => print($e->getMessage()));
$all = Cryo\Sandbox\Sandbox::wait([$f, $sb->evalAsync('return 1;')], 5.0); // a Future of [values], never blocks
// at each frame (JumPHP: JumPHP\Cryo\SandboxLoop does it from the game loop):
Cryo\Sandbox\Sandbox::pump(); // reads what arrived, runs then() callbacks, settles wait()
$f->status(); // 'pending' | 'ready' | 'failed' | 'cancelled'
$f->value(); $f->error(); $f->isReady(); $f->isFailed(); $f->isCancelled();
$sb->messages(); // what Channel::parent()->send() sent, never waits
Cryo\Sandbox\Sandbox::pending(); // requests + then()/wait() futures not settled yet
- Child side: the worker queues each frame for its
cryoHost.recv, then calls the exportedcryo_sandbox_step()(EXPORTED_FUNCTIONS_cryo_sandbox_step): it reads the frames already there and runs ONE request (returns 1; 0 when nothing to run; -1 before INIT). INIT applies memory_limit, ini, disable_functions, bootstrap and answers HELLO. Answers go throughcryoHost.send(0, ...); a request start/end callscryoHost.arm(ms, frame): the parent's host ends the worker aftertimeoutand hands PHP that prebuilt timeout answer (SIGALRM's role on POSIX). exit(), a fatal error or a failed bootstrap end the instance with_exit()after answering (emscripten's ExitStatus in the worker); a trap is reported as a crash (134). - Host contract (
cryo_host.h):recv(id, cap)returns at mostcapbytes already there,null(nothing yet) or-2(ended);status(id)-1 while running, else the exit code;error(id)its last error text. start => forkis refused in WebAssembly. Reference host:wasm-host/src/index.js; complete one in JumPHP (engine/web/jumphp-cryo.js,jumphp-cryo-worker.js).
Security: hostile files, fuzzing
The readers take files that may come from anywhere (a snapshot attached to a bug report, a .cryom
uploaded to Cryo Studio, a freeze file on a shared disk). What they guarantee on a corrupted or hostile file:
CryoReader/CryoReader::delta()/cryo_diff()(.cryo),cryo_metrics_read()(.cryom),cryo_info()/cryo_verify()(freeze files) andcryo_thaw_vars(): aCryoException, or a result; never a crash, a fatal error, a warning or an endless loop. Every counter is checked against the bytes really present, a section that appears twice is read once (the first one wins), ids out of range are ignored, sums of sizes follow PHP arithmetic (int, then float), sorts are n log n.CryoDelta::explain()shows the code of a site only from a plain local regular file: no stream wrapper (phar://,http://,php://,data:), no device or FIFO named by the snapshot.cryo_info()reads the meta before any signature check: no class is instantiated from it (objects become__PHP_Incomplete_Class).cryo_thaw_vars()is a plainunserialize()of the file, objects included: only thaw files you trust (signed freeze files are the way to carry state between machines).- The pure-PHP readers of
cryo-studio/(PhpCryoReader,PhpCryoDelta,MetricSeries) throwRuntimeExceptionwhere ext-cryo throws, and return exactly the same result otherwise.
tools/fuzz-readers.php fuzzes all of them: valid seeds (snapshots with sites / stacks / HASH / WRIT /
STKS, a metric series, freeze files plain / compressed / signed / encrypted, cryo_freeze_vars() files)
are generated, then mutated (bits, bytes, section lengths and tags, counters, record fields set to
0 / n / n+1 / 0x7FFFFFFF / 0xFFFFFFFF, u64 extremes, truncations, splices, site strings, serialize()
payloads re-wrapped with zlib / libsodium / HMAC so that mutations reach the unserializer). Each case runs
in a child process (/usr/bin/php -d extension=cryo.so) with a timeout; a signal, a sanitizer report, a
timeout, a fatal error, a PHP warning, an unexpected exception or a difference between ext-cryo and the
PHP readers is kept, minimized, in fuzz/crashes/ (the case and a .txt report with the output).
# AddressSanitizer + UndefinedBehaviorSanitizer build, outside the repository
cp -r ext-cryo /tmp/cryo-asan && (cd /tmp/cryo-asan && phpize &&
CFLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g -O1" LDFLAGS="-fsanitize=address,undefined" \
./configure --enable-cryo && make -j)
/usr/bin/php tools/fuzz-readers.php --ext=/tmp/cryo-asan/modules/cryo.so --asan --jobs=12 --execs=200000
# without sanitizers (quicker), or for a given time; replay kept cases
/usr/bin/php tools/fuzz-readers.php --ext=ext-cryo/modules/cryo.so --time=600
/usr/bin/php tools/fuzz-readers.php --ext=/tmp/cryo-asan/modules/cryo.so --asan --replay fuzz/crashes/*.cryo
--asan preloads libasan / libubsan (found with gcc -print-file-name) into the non-instrumented
PHP and sets USE_ZEND_ALLOC=0, so that every emalloc() is checked. Other options: --php=BIN
(default /usr/bin/php; it must load extensions, a static PHP cannot), --seed=N (repeatable
mutations), --batch=N (cases per child), --timeout=S (per case), --out=DIR, --no-minimize.
clang's libFuzzer is not used: the readers need a PHP runtime (zend_string, arrays, exceptions) and the
distribution ships no embeddable libphp, so the fuzzer works at the process level.
Regression tests of the bugs it found: tests/318 to 323 (small corrupted files built in the test).
Known limits
-
In the JumPHP browser engine the game runs from
jumphp_frame(), called by C every frame: freezing the stack from there is refused (internal frame); snapshots, readers, Engine, metrics,cryo_freeze_vars()and values-only freezes work. Restart, fork and sandboxes need a full JS host (@cryo/wasm-host). -
Generators: suspended ones are frozen and rebuilt (key, value, send(), $this, not started yet); a generator inside a
yield from, a closure generator, or aforeachover a generator/iterator object being iterated by a frame are refused (a warning and null for a value; the next safe point for the torture test). -
After a thaw, equal strings may share one
zend_string: a snapshot of the thawed process can count one string node fewer than the original (identity of strings is not visible from PHP). -
NTS only (tracking, engine and sandbox state are in statics).
-
Object sizes are approximate (struct + declared properties); array and string sizes from their allocation.
-
Site prediction relies on the handle the next
newwill take; the class is re-checked at snapshot time, and objects created by internal code withoutnewhave no site. -
Write sites: a plain
$x = $objinside a function is ignored (local variable) unless$xis bound by reference (static,global,&); writes done by internal functions (array_push(), …) are not seen. -
dupes()relies on a 32-bit hash plus length: collisions are possible, in theory. -
redactapplies to values reached through a matching name; a string already reached first through another, non-matching path (shared zend_string) keeps its hash. -
path()returns the shortest paths only (all of minimal length); longer alternative paths are not listed. -
cryo_metrics_serve(): plain HTTP/1.1, one client at a time (a large snapshot being streamed delays the other requests), no TLS (bind it to 127.0.0.1 or put it behind a proxy); without a token anyone who can reach the port can read the metrics and ask for snapshots. -
PhpCryoReaderkeeps the graph in PHP arrays (~15 times the file size): a very large snapshot can exceedmemory_limitwith it where ext-cryo reads it.