311 lines
22 KiB
Markdown
311 lines
22 KiB
Markdown
# 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
|
|
|
|
```php
|
|
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 the `cryo_on_thaw` hooks, 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, `CryoAware` objects 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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```php
|
|
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 of `sys_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: `cors` must allow its origin.
|
|
- WebAssembly: there is no exporter process; the Prometheus text goes to `cryo_host_emit()`, and the
|
|
options throw a `CryoException`.
|
|
|
|
## 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)
|
|
|
|
```php
|
|
$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_FCALL` call 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::X` in the class body, constants defined before an
|
|
`include`): 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)
|
|
|
|
```php
|
|
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 of `PHP_BINARY` with 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); `restart` decides what happens next.
|
|
- `network => false`: seccomp-bpf filter (Linux x86_64/aarch64/i386/arm) that makes `socket()`
|
|
fail with EPERM for every family but AF_UNIX; elsewhere the PHP network functions are disabled.
|
|
`status()['network']` tells which (`seccomp` or `functions`). On i386 libcs that go through
|
|
`socketcall()` the filter does not apply.
|
|
- `disable_functions`: real `disable_functions` in 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 over `cryo_host_spawn/clone/send/recv/kill/status`;
|
|
the host calls the exported `cryo_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 only `emit`), 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`).
|
|
|
|
```php
|
|
$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 exported
|
|
`cryo_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 through `cryoHost.send(0, ...)`; a request start/end calls
|
|
`cryoHost.arm(ms, frame)`: the parent's host ends the worker after `timeout` and 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 most `cap` bytes already there, `null` (nothing yet)
|
|
or `-2` (ended); `status(id)` -1 while running, else the exit code; `error(id)` its last error text.
|
|
- `start => fork` is 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) and `cryo_thaw_vars()`: a `CryoException`, 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 plain `unserialize()` 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`) throw
|
|
`RuntimeException` where 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).
|
|
|
|
```bash
|
|
# 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 a `foreach` over 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 `new` will take; the class is re-checked at snapshot time, and objects created by internal code without `new` have no site.
|
|
- Write sites: a plain `$x = $obj` inside a function is ignored (local variable) unless `$x` is 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.
|
|
- `redact` applies 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.
|
|
- `PhpCryoReader` keeps the graph in PHP arrays (~15 times the file size): a very large snapshot can exceed
|
|
`memory_limit` with it where ext-cryo reads it.
|