Product Decisions This Supports

Build vs. buy on the serving layer — still a buy, but now a versioned, security-patched buy. RoadRunner remains MIT-licensed, single-binary, and maintained by Spiral Scout, and it still turns "replace Nginx + PHP-FPM" into a procurement decision rather than a platform project. What changed at v3 is that the serving layer now has a major-version lifecycle you must plan around, and with v3.0.1 it also has a patch-level security cadence you must staff: the runtime is a Go binary, and Go CVEs land in it whether or not we ship features. The PM decision is no longer just "buy" — it's "buy, and fund both a major-upgrade slot and a standing patch-owner." Budget an upgrade line item the same way you budget framework upgrades, and a monthly "runtime patch review" the same way you budget dependency scanning.
v3.0.1 is a security patch, not a feature release — treat it as mandatory hygiene. It rebuilds on Go 1.27.3 to fix CVE-2026-111943 / GO-2026-6809 in crypto/x509: certificate verification now rejects known untrusted intermediate certificates. Two PM-relevant consequences: (1) if we adopt v3, we should pin >= 3.0.1, not 3.0.0 — shipping a known-vulnerable binary to production is not a defensible default; (2) the fix changes TLS verification behavior, so anything in the worker that terminates or validates TLS against an unusual certificate chain (internal CAs, self-signed intermediates, legacy brokers, mTLS to a payment or identity provider) should be re-verified in staging, not assumed. Ask the vendor/upstream explicitly whether a v2025.x equivalent patch exists — if we stay on the old line, we need the security answer for that line too, not just a stability answer.
A runtime/plugin API contract, not just a runtime. v3 moves plugin contracts to separate versioned modules (api, api-go/v6, api-plugins/v6, pool/v2, goridge/v4, log/slog). That is good hygiene for upstream, but it reclassifies "we'll write a custom plugin" from a small extension task to a maintained dependency on a moving API. Decide explicitly: consume stock plugins only (recommended), or accept ongoing porting cost. This is a build-vs-buy decision inside the buy.
Roadmap unlocks that would otherwise need separate vendors — expanded in v3. The plugin surface now includes HTTP/1.1–3 (with H2C prior-knowledge), gRPC (plus reflection and rich error details), queue consumers (RabbitMQ, Kafka, SQS, NATS, NSQ — new — Beanstalk, in-memory), KV stores, WebSockets/Centrifugo, distributed locks, metrics, and Temporal. Product framing: each roadmap item scopes as "configure a plugin" rather than "integrate a new service."
Edge concerns now ship in the box. v3 promotes rate limiting (global/IP/header keyed, 429 + Retry-After), Zstd response compression, PROXY protocol v1/v2 with explicit trusted proxies, configurable trusted forwarding headers, and static-file serving controls (prefixes, metadata/missing-file cache TTLs, cache limits, rr reset static) into the default container. This is a real PM lever: abuse mitigation, bandwidth cost, correct client-IP attribution behind a load balancer, and offloading static traffic without writing middleware.
Queue QoS becomes a product decision, not an infrastructure one. v3 adds named worker pools for jobs (pipelines routed to separate PHP pools with their own commands and capacity, selected by a pool header) plus outcome metrics (success/failed/requeued via rr_jobs_jobs_requeue) and trace continuity for jobs submitted over RPC. That means you can offer a "priority/beta pipeline" without new infrastructure, define queue SLOs, and get end-to-end traces through async work — a concrete observability win for any feature with background processing.
Broker and protocol flexibility reduces lock-in. NSQ is added; AMQP gains named connections (pipelines to different brokers) and independent queue/exchange declaration controls (use pre-provisioned broker resources where the service account lacks declare rights); NATS gains ack_wait and changes stream retention semantics. Translation for roadmap: "we can use the platform team's existing broker and least-privilege credentials" is now a supported answer.
gRPC gets production-grade ergonomics. Server reflection plus the bundled Protoreg plugin (PHP service descriptors) and google.rpc.Status error details in failed unary-call logs materially reduce the cost of internal gRPC services — reflection alone unlocks grpcurl/tooling workflows and cuts a class of "how do I even call this locally" support tickets.
Latency/cost scaling story is unchanged and still the core ROI. Long-lived workers pay framework bootstrap once per worker; capacity levers are pool size and auto-scaling (dynamic_allocator.max_workers now counted above the base pool, with retry-after-scale-up) rather than more FPM children.
Observability standardization holds. OpenTelemetry (gRPC, HTTP, Jaeger) plus Prometheus-compatible metrics remain platform defaults; v3 extends tracing into the job pipeline and adds queue outcome counters.
Framework-adjacent adoption unchanged. spiral/roadrunner is the low-level worker SDK; practical entry points are Laravel Octane, the Symfony Runtime, and spiral/roadrunner-cli. Don't read "0 dependents" on the bare SDK as an adoption signal.

Decision this release creates: what is our patch floor? v3.0.1 is the first maintenance release on the v3 line and it exists purely to close a Go stdlib CVE. That establishes the operating model: pin a minimum patch (currently 3.0.1), not just a major, and re-verify the binary checksum on every bump. The earlier scheduling recommendation stands — stay on v2025.x for the current quarter unless a v3 capability unblocks a committed roadmap item — but with one addition: confirm the v2025.x line's security posture before treating "stay put" as the safe option. A stability argument for staying is not a security argument for staying.

When to Consider This Package

Adopt (or continue adopting) when most of these hold:

You control the runtime and process lifecycle (containers, VMs, Kubernetes) — not shared hosting or a managed PHP platform.
You have a measurable serving-layer problem: p95 latency dominated by bootstrap, FPM saturation, per-request overhead, or instance cost per 1k requests you want to cut.
Your stack is Laravel or Symfony and can adopt Octane/Runtime, so the worker loop isn't hand-rolled.
You have (or can hire) someone comfortable owning a Go binary in the build pipeline, .rr.yaml config, worker restart/memory policies, a major-version upgrade treadmill, and a security-patch cadence.
You want more than one plugin capability — HTTP plus queues plus gRPC plus metrics. HTTP alone under-sells it and often isn't worth the operational delta.
You need WebSockets, gRPC, or queue consumption and would otherwise add a second runtime or service.

Specifically consider v3 when you need:

Edge controls without extra infrastructure: rate limiting, Zstd compression, PROXY protocol/trusted headers, static-file cache tuning.
Queue isolation by criticality (named worker pools) or per-pipeline trace propagation and requeue metrics.
gRPC server reflection for developer tooling and fewer hand-written descriptors.
NSQ, multiple RabbitMQ brokers in one process, or least-privilege broker accounts that cannot declare exchanges/queues.
Correct client IPs and forwarded-header priority behind an ALB/ingress (previously awkward).

Look elsewhere when:

Traffic is modest and FPM is not a bottleneck. Complexity isn't free; ROI is negative.
The application depends on per-request process isolation — superglobals as state store, static caches assuming a cold process, $_SESSION semantics, or libraries that leak memory across requests. Long-lived workers turn these into incidents, not code smells.
You're on serverless/FaaS or a managed platform where you don't own the process manager.
Org policy is "PHP only, no non-PHP binaries in the deploy artifact" and won't move.
You need commercial support with SLAs; MIT community support (Discord, GitHub Discussions) is the model.
You need a one-line change. Benchmark alternatives in the same evaluation: stay on Nginx + FPM, FrankenPHP, Swoole/OpenSwoole. Add "stay on RoadRunner v2025.x — but only with a confirmed patch path for that line" to that list — it's a legitimate outcome, not a failure to decide, provided security is answered.

Non-negotiable pre-adoption checklist (unchanged): load test against your FPM baseline, state-leakage audit, worker memory/restart policy, rollback path to FPM.

Non-negotiable v3 upgrade checklist:

Read the migration guide end to end — v3 is explicitly a breaking change; assume config keys and some PHP-side APIs move.
Pin >= 3.0.1, not 3.0.0. v3.0.0 carries a known Go crypto/x509 CVE; do not let an early pin calcify at the vulnerable patch.
Middleware order is now left-to-right. Reverse any existing http.middleware list to preserve behavior. Treat this as a silent behavioral change: diff the effective order and add a test for auth-before-routing and similar ordering assumptions.
Goridge v4 drops MessagePack. Inventory anything using MessagePack RPC payloads; JSON/protobuf/Gob/raw remain. If an internal tool or sidecar speaks MessagePack, it breaks.
Environment file is now required at startup (no experimental flag). Deploy manifests, local dev, and CI must ship one, or the server won't boot. This is the most likely "works locally, dies in staging" item.
AMQP config restructure: config.version removed; static pipelines require config.connection with nested exchange and queue. Rewrite queue configs before cutover and verify declaration rights under least-privilege accounts.
Cleartext HTTP/2: Upgrade: h2c is gone; use prior-knowledge H2C. Verify every internal client (service mesh, older SDKs, health checkers) that relied on upgrade.
Audit NATS retention semantics — streams are preserved on pipeline stop unless deletion is enabled; re-check redelivery assumptions before upgrading, or you may change at-least-once behavior silently.
Re-verify TLS chains under the 3.0.1 crypto/x509 behavior. The patch rejects known untrusted intermediate certificates. Test every outbound/inbound TLS dependency the workers touch — internal CA, broker mTLS, third-party APIs, SSO — in staging before the bump, and have a rollback patch ready.
Pin, checksum, and re-verify the binary and Go module path (github.com/roadrunner-server/roadrunner/v3); if you embed or custom-build, confirm the plugin API ports (api-go/v6, api-plugins/v6, pool/v2, log/slog) and rebase onto Go 1.27.3+ so the CVE fix is retained. Note TCP now requires a custom build.
Re-run the load test. v3 is not a drop-in perf-neutral swap; re-baseline p95 and cost per 1k requests rather than assuming parity. Patch releases should be perf-neutral — verify, don't assume.

How to Pitch It (Stakeholders)

To executives — the one-liner: RoadRunner is a drop-in application server that replaces our Nginx + PHP-FPM layer with a single MIT-licensed binary, and v3 adds the edge and queue features we'd otherwise buy separately — rate limiting, compression, proxy-aware client IPs, queue prioritization and metrics, and gRPC tooling. The trade-off is a planned major-version migration plus an ongoing runtime patch cadence — not an unplanned one, and the first patch (v3.0.1) is a security fix we should take.

The business case:

Cost: fewer instances for equivalent throughput (bootstrap paid per worker, not per request). v3 additionally cuts bandwidth via Zstd and reduces app-tier load via static-file controls. Validate with a load test; don't quote a number before it.
Speed to market: capabilities we'd otherwise buy or build — WebSockets, gRPC, queue consumers, Temporal workflows, abuse rate limiting, NSQ/Multi-broker AMQP — become configuration. That compresses roadmap estimates for real-time, async, and internal-API work.
Operational simplicity: one binary and one versioned YAML config instead of Nginx config sprawl plus FPM pools; simpler container images; queue priority handled by worker pools rather than parallel infrastructure.
Predictable dependency management: the project has moved to a clear major-version model with an active patch line. We can stay on v2025.x while we plan, then upgrade deliberately — and we now know patches ship within days of a relevant CVE (v3.0.0 → v3.0.1 for a crypto/x509 Go advisory). Exit cost stays low — MIT, PSR-7/PSR-17 interfaces, first-class Laravel/Symfony integration.
Observability as a default: OpenTelemetry and Prometheus out of the box, now extended to async job traces and queue outcome counters — lowers the cost of the tracing initiative and gives us queue SLOs for free.

To engineering — the honest framing:

This is a breaking major, not a patch — and v3.0.1 is the patch you should actually deploy. v3 uses v6 Go plugins with separate versioned API modules; config and some APIs change. Budget a scoped migration (estimate 1–3 engineer-weeks for a single service, more if you have custom plugins or MessagePack RPC consumers), not an afternoon. If we custom-build, rebase onto Go 1.27.3+ so we inherit the crypto/x509 fix rather than reintroducing it.
The five highest-probability breakages: middleware order is now left-to-right (reverse old lists); MessagePack removed from Goridge v4; envfile is required at startup; AMQP config restructured (config.version removed, nested connection/exchange/queue); and, as of 3.0.1, stricter intermediate-certificate validation — chains that previously "worked" may now be rejected. Add Upgrade: h2c removal and changed NATS retention semantics to the same shortlist.
The underlying adoption work is unchanged and still the real risk: worker lifecycle means eliminating cross-request state, memory growth in long-lived workers, partial superglobal emulation, and a new debugging model. Mitigate with per-worker memory limits, restart policy, staging soak tests.
Custom plugins are now a maintenance commitment. If we write one, it targets api-go/v6/api-plugins/v6 and must be ported on each major — and rebuilt against patched Go. Default to stock plugins.
The Go binary is a pinned, security-relevant CI/supply-chain artifact. Assign an owner, checksum it, subscribe to upstream releases and Go vulnerability advisories, and set a policy for patch uptake (e.g., critical/high CVEs within one sprint). The release channel has shifted shape twice (year-versioned → semver major), so track it deliberately rather than incidentally.
Recommendation: pin v2025.x for stability only after confirming that line's patch status for GO-2026-6809; if it is unpatched and unpatchable, that materially raises the priority of the v3 move. In parallel, run a timeboxed v3 spike on one non-critical service (pinned to >= 3.0.1) that exercises HTTP + one queue driver + metrics + a TLS dependency. Go/no-go criteria defined up front: documented migration diff, p95 improvement vs. the FPM baseline, cost per 1k requests, zero state-leakage defects in soak, zero middleware-order regressions in the test suite, clean TLS verification against all dependencies, and a working rollback to both v2025.x and FPM.

The ask: (1) a scoped v3 evaluation (2–4 engineer-weeks) on a single service, pinned to 3.0.1; (2) an answer from upstream on the v2025.x security patch path; (3) standing ownership — a named owner for runtime version and security-patch uptake. Decide on data, not on the release notes.

Roadrunner Laravel Package

Product Decisions This Supports

When to Consider This Package

How to Pitch It (Stakeholders)