docs: document worker mode and the statelessness it requires

Worker mode needs no package and no code change — symfony/runtime has shipped FrankenPhpWorkerRunner since 7.4 and the Caddyfile already reads {$FRANKENPHP_CONFIG} — so it is documented as an environment variable, with what it measured here and the caveats on those numbers.

The statelessness rules go in claude.md as a section rather than a bullet, because messenger:consume is already long-running in production and the rules apply whether or not worker mode is on. Each rule points at the service in this codebase that follows it.

Author: turegjorup

CHANGELOG.md

@@ -47,6 +47,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     consumer, which in a worker outlives the request
   - Cover all of it with tests: the factories had none, and neither the
     dashboard nor the Security Contract CRUD was in the admin smoke test
+  - 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
 - [#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

@@ -154,6 +154,45 @@ does not carry: this build has `console`, `json`, `append`, `filter` and
 `journald`. JSON also matches supercronic, which the fpm image already runs with
 `-json`.
 
+#### Worker mode
+
+Worker mode is off. Turning it on needs no PHP package and no code change:
+`symfony/runtime` has shipped `FrankenPhpWorkerRunner` since 7.4, FrankenPHP
+sets `FRANKENPHP_WORKER=1` for a worker script, and `SymfonyRuntime::getRunner()`
+switches on that. `.docker/Caddyfile` reads `{$FRANKENPHP_CONFIG}`, so the switch
+is an environment variable on the `frankenphp` service:
+
+```yaml
+environment:
+    FRANKENPHP_CONFIG: worker /app/public/index.php
+```
+
+Add a count – `worker /app/public/index.php 8` – to override the default, which
+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.
+
+**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
+into the next request. Prefer keeping services stateless. Where state is
+deliberate, implement `Symfony\Contracts\Service\ResetInterface` –
+`autoconfigure` tags it `kernel.reset` and Symfony calls it between requests.
+For an object you do not own, clear it at the call site, the way every
+`AdminUrlGenerator` chain here opens with `unsetAll()`.
+
+`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.
+
 #### Metrics
 
 `/metrics` serves Prometheus metrics from Caddy, behind the `ITKMetricsAuth@file`

claude.md

@@ -85,6 +85,44 @@ docker compose exec frankenphp composer queues
 docker compose run --rm node yarn install && docker compose run --rm node yarn build
 ```
 
+## Long-running processes
+
+The site is served by a single FrankenPHP container in place of phpfpm and
+nginx. Worker mode is off but available — `symfony/runtime` has shipped
+`FrankenPhpWorkerRunner` since 7.4, and `.docker/Caddyfile` reads
+`{$FRANKENPHP_CONFIG}`, so it is an environment variable, not a code change:
+
+```yaml
+FRANKENPHP_CONFIG: worker /app/public/index.php
+```
+
+`messenger:consume` is already long-running in production regardless, so the
+rules below apply whether or not worker mode is on.
+
+**Writing a service that has to remember something:**
+
+1. Prefer statelessness. If the state only needs to live for one method call,
+   make it a local and thread it through the private helpers — see
+   `PackageVersionFactory`, whose deduplication buffers work this way. The
+   `ResetInterface` docblock advises this over the interface where possible.
+2. Where the state is deliberate, implement
+   `Symfony\Contracts\Service\ResetInterface` and clear everything in
+   `reset()`. `autoconfigure` tags it `kernel.reset` with no manual tagging —
+   see `LeantimeService`, which caches the Leantime user directory because
+   `resolveUserName()` runs in a loop.
+3. For an object you do not own, clear it where you use it. Every
+   `AdminUrlGenerator` chain in this codebase opens with `unsetAll()` for this
+   reason: EasyAdmin registers it `shared: no`, but the services holding it are
+   shared, so the instance outlives the request.
+
+Things that break a worker and have no place here: `exit()`/`die()`, writes to
+superglobals, `__destruct()` on a shared service, and mutable `static`
+properties.
+
+`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.
+
 ## Quality Checks
 
 All commands run inside Docker containers:
@@ -146,3 +184,6 @@ Pull requests run these checks:
 - Async processing uses Symfony Messenger with AMQP transport
 - Environment-specific config goes in `.env.local` (not committed)
 - API specs (`public/api-spec-v1.yaml` and `.json`) must be regenerated and committed when API changes
+- Services must not carry request state. The web container and the messenger
+  consumer are both long-running, so anything a service remembers outlives the
+  request that put it there