docs: measure FRANKENPHP_RESET_KERNEL instead of guessing at it

Changes

- Record the three-way measurement on `/admin` in the Caddyfile, README and
  changelog
- Say what cloning the kernel actually does, and stop implying the reset erases
  worker mode's benefit

Why

The comment claimed the reset costs "a boot per request", which is true —
`AbstractKernel::__clone()` nulls the container and clears `booted`, so the next
`handle()` runs `initializeBundles()` and instantiates the compiled container
again. But it was asserted rather than measured, and the conclusion drawn from it
was wrong.

Measured in prod, 40 seconds at 20 concurrent on `/admin`: 1319 requests per
second and a 9.0 ms median with no worker, 1494 and 4.3 ms with one, 1395 and
6.1 ms with one plus the reset. The reset keeps roughly half the gain and still
beats no worker on both numbers, because the PHP runtime, OPcache and autoloader
stay warm across requests even when the kernel does not.

That makes it a reasonable first worker-mode configuration to deploy rather than
only something to compare against. Also notes that a boot is not a recompile,
which the old wording invited readers to assume.

Author: turegjorup

.docker/Caddyfile

@@ -102,13 +102,17 @@
 		# Uncommenting the worker line is all worker mode needs: FrankenPHP sets
 		# FRANKENPHP_WORKER=1, and symfony/runtime has picked its own
 		# FrankenPhpWorkerRunner off that since 7.4 — no PHP package, no
-		# APP_RUNTIME override. Symfony 8.1 adds FRANKENPHP_RESET_KERNEL=1, which
-		# clones the kernel between requests to mitigate state leaks at the cost
-		# of a boot per request.
+		# APP_RUNTIME override.
 		#
-		# Off until the stateful services are dealt with: LeantimeService caches
-		# the Leantime user directory per instance, and the package/module
-		# factories clear their dedup buffers outside a finally.
+		# Symfony 8.1 adds FRANKENPHP_RESET_KERNEL=1, which clones the kernel
+		# after each request. That does mean a kernel boot per request —
+		# AbstractKernel::__clone() nulls the container and clears `booted`, so
+		# the next handle() runs initializeBundles() and instantiates the
+		# compiled container again — but it keeps the PHP runtime, OPcache and
+		# autoloader warm, so it is not the same as no worker at all. Measured on
+		# /admin in prod: 1319 rps and a 9.0 ms median without a worker, 1494 and
+		# 4.3 ms with one, 1395 and 6.1 ms with one plus the reset. Roughly half
+		# the gain, and immune to state leaking between requests.
 		php_server {
 			#worker /app/public/index.php
 		}

CHANGELOG.md

@@ -63,10 +63,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     `igor-baseline.json` records the 33 existing findings with a reason each, so
     the job fails only on new ones; vendor code is out of scope
   - Document worker mode and the statelessness it requires in `README.md` and
-    `claude.md`. It stays off: measured here it gives roughly 20% more requests
-    per second on `/admin` and half the median latency, but around 40% fewer on
-    `/health/live`, and the numbers come from a laptop sharing CPU with other
-    containers
+    `claude.md`. It stays off. Measured on `/admin` in prod: 1319 requests per
+    second without a worker, 1494 with one, 1395 with one plus
+    `FRANKENPHP_RESET_KERNEL=1` — so the reset keeps about half the gain rather
+    than erasing it. `/health/live` inverts the ranking, and the numbers come
+    from a laptop sharing CPU with other containers
 - [#96](https://github.com/itk-dev/devops_itksites/pull/96)
   Show the Service Agreements monthly price as Danish kroner,
   `12.500,50 kr.`, on index and detail

README.md

@@ -219,14 +219,25 @@ Add a count – `worker /app/public/index.php 8` – to override the default, wh
 is twice the number of CPU cores. Keep `num_threads` × `memory_limit` below the
 memory available to the container.
 
-What it bought here, measured on this project in `prod` with a warm OPcache:
-about 20% more requests per second on `/admin` and half the median latency,
-against about 40% *fewer* on `/health/live`. The trivial endpoint is worker
-mode's worst case – there is no per-request work for the saved kernel boot to be
-weighed against, and the runner's `gc_collect_cycles()` on every request is not
-free. The numbers come from a laptop sharing CPU with other containers and
-running the application over a bind mount, so treat them as a shape rather than
-a figure, and measure again on a server before adopting.
+What it bought here, measured in `prod` with a warm OPcache, 40 seconds at 20
+concurrent on `/admin`:
+
+| | requests/sec | median |
+| --- | --- | --- |
+| no worker | 1319 | 9.0 ms |
+| worker | 1494 | 4.3 ms |
+| worker + `FRANKENPHP_RESET_KERNEL=1` | 1395 | 6.1 ms |
+
+On `/health/live` the ranking inverts – roughly 40% *fewer* requests per second
+with a worker. That endpoint returns a constant, which is worker mode's worst
+case: there is no per-request work for the saved kernel boot to be weighed
+against, and the runner's `gc_collect_cycles()` on every request is not free.
+Worth knowing, since the health endpoints are the polled ones.
+
+The numbers come from a laptop sharing CPU with other containers and running the
+application over a bind mount, so treat them as a shape rather than a figure.
+Short runs on that machine varied by more than tenfold; only 40-second runs were
+reproducible. Measure again on a server before adopting.
 
 **Services must not carry request state.** Under php-fpm a service instance died
 with the request; in a worker it does not, so anything a service remembers leaks
@@ -257,10 +268,18 @@ The audit needs the service map that `IgorPhpBundle` writes during
 scope (`ignore_vendors` in `igor.json`): it reported 341 findings there, none of
 them ours to fix.
 
-`FRANKENPHP_RESET_KERNEL=1`, on Symfony 8.1 and later, clones the kernel between
-requests instead. It hides this class of bug at the cost of a boot per request,
-which is most of what worker mode is for – useful to compare against, not to
-depend on.
+`FRANKENPHP_RESET_KERNEL=1`, on Symfony 8.1 and later, clones the kernel after
+each request instead, which makes this class of bug harmless.
+`AbstractKernel::__clone()` nulls the container and clears `booted`, so the next
+request runs `initializeBundles()` and instantiates the compiled container again
+– a kernel boot, though not a recompile. It is not as expensive as it sounds:
+the PHP runtime, OPcache and autoloader stay warm, and it kept about half the
+worker-mode gain in the table above while still beating no worker on both
+throughput and latency.
+
+That makes it a reasonable first configuration to deploy rather than only a
+diagnostic – most of the latency win, immune to the leaks the audit below
+guards against – with the reset turned off later once there is confidence.
 
 #### Metrics
 

claude.md

@@ -134,9 +134,11 @@ the job fails only on new ones — fix a genuine finding rather than baselining
 it, and regenerate with `composer worker-state-baseline` only after a deliberate
 change.
 
-`FRANKENPHP_RESET_KERNEL=1` (Symfony 8.1+) clones the kernel between requests
-and papers over all of this, at the cost of a boot per request. Treat it as a
-measurement baseline, not a fix.
+`FRANKENPHP_RESET_KERNEL=1` (Symfony 8.1+) clones the kernel after each request,
+which makes all of this harmless. It costs a kernel boot per request but keeps
+the PHP runtime warm, and measured on `/admin` it held about half the worker-mode
+gain while still beating no worker — so it is a usable configuration, not just a
+baseline. It is not a licence to write stateful services: the audit still runs.
 
 ## Quality Checks