RoadRunner 3 is available

We are glad to announce the release of RoadRunner 3.

RoadRunner 3 is the last major version for the foreseeable future, and its API is very stable. For this release, we closed the backlog of earlier RoadRunner versions. We also went back to a clear versioning scheme: we stopped using calendar versions and returned to SemVer. RoadRunner 3 will continue to get bug fixes and security updates. But the team now puts most of its effort into Rapira.

This post describes the changes in the server and in the PHP packages. It also tells you how to upgrade.

Main changes

The release notes contain the full list. These are the main changes:

• Plugins in the default build. The default build now includes the NSQ jobs driver, HTTP rate limiting, Zstd compression, and the protobuf registry (Protoreg). We removed the TCP plugin.
• HTTP. RoadRunner supports PROXY protocol v1 and v2 with an explicit list of trusted proxies. The rate_limiter middleware returns 429 with a Retry-After header. static has new cache settings and the new rr reset static command.
• gRPC. RoadRunner supports server reflection through Protoreg. Error logs include google.rpc.Status details.
• Jobs. You can bind a pipeline to a named pool of PHP workers. AMQP supports named connections to different brokers. Kafka can consume selected partitions.
• Lock. A new Redis backend shares locks between multiple RoadRunner instances.
• Logger. The logger now uses Go log/slog. Writes to the output do not block.
• Unix sockets. You can set the permissions, owner, and group of sockets for listeners and worker relays.
• Status. /livez and /readyz work as aliases of /health and /ready.

Breaking changes

The upgrade guide from v2025 to v3 gives the full step-by-step list. These are the most important changes:

Area	Change
HTTP middleware	A request goes through http.middleware from left to right. To keep the old order, reverse the list.
HTTP/2	Cleartext HTTP/2 works only with prior knowledge. RoadRunner no longer supports Upgrade: h2c.
AMQP	Broker settings move to named connections. The config.version option no longer exists.
Logger	file_logger_options and the built-in rotation no longer exist. Use output and an external rotation tool. When the queue is full, the logger drops new entries.
Tracing	The native Zipkin exporter no longer exists. Use OTLP.
RPC	Goridge v4 does not support MessagePack. You can use JSON, protobuf, Gob, and raw.
Jobs	RoadRunner reserves the pool header to route jobs to a named pool. The default pipeline_size is now 100000.
NATS	When a pipeline stops, RoadRunner keeps the stream by default.
Centrifuge	The centrifuge.RateLimit method no longer exists.
envfile	RoadRunner loads the root envfile without experimental mode. The specified file must exist.
server.on_init.env	The values override inherited environment variables.
TCP plugin	RoadRunner 3 does not support it.

The root of .rr.yaml still sets version: "3". To build from source, you need Go 1.27 or later.

Go plugin authors must move to api-go/v6, api-plugins/v6, pool/v2, goridge/v4, and *slog.Logger. The Velox builder uses a new module configuration. Velox no longer has the remote build server or the Windows targets. The release still includes prebuilt Windows binaries.

PHP packages

We also updated the PHP packages. These are the main changes:

• The minimum PHP version is 8.2.
• All packages use the new roadrunner/* vendor name instead of spiral/* and roadrunner-php/*.
• Class namespaces stay the same for backward compatibility.
• Each new package declares replace for its old name with self.version. The metapackage is an exception, as described below.
• The spiral/roadrunner metapackage is now roadrunner/roadrunner. The roadrunner/* packages require roadrunner/roadrunner ^3.0. The new name solves these problems:
  • The calendar versions 2023.x–2025.x do not follow SemVer, but they often appeared as the latest stable versions. CalVer stays in spiral/roadrunner.
  • The advisory CVE-2025-22871 marks spiral/roadrunner < 2025.1.0 as vulnerable. This advisory blocked the installation of RoadRunner 3 through Composer. The new name does not have this problem.
• All packages require RoadRunner 3. We do not guarantee that older RoadRunner versions work with the new packages.
• RoadRunner 3 does not include the TCP plugin. If your application uses the TCP plugin, we recommend that you stay on RoadRunner v2025. This change does not affect the tcp:// transport for RPC and worker relays. That transport works as before.

Other improvements:

• We rewrote the tests with Testo.
• We improved the code coverage, mutation testing, and static analysis scores.
• RoadRunner CLI 3.0.0 uses DLoad to download binaries.

Old name	New name	Status
spiral/roadrunner	roadrunner/roadrunner
spiral/roadrunner-worker	roadrunner/worker
spiral/roadrunner-http	roadrunner/http
spiral/roadrunner-grpc	roadrunner/grpc
spiral/roadrunner-jobs	roadrunner/jobs
spiral/roadrunner-kv	roadrunner/kv
spiral/roadrunner-metrics	roadrunner/metrics
spiral/roadrunner-services	roadrunner/services
spiral/goridge	roadrunner/goridge
spiral/roadrunner-cli	roadrunner/cli
roadrunner-php/app-logger	roadrunner/app-logger
roadrunner-php/centrifugo	roadrunner/centrifugo
roadrunner-php/lock	roadrunner/lock
roadrunner-php/symfony-lock-driver	roadrunner/symfony-lock-driver
roadrunner-php/version-checker	roadrunner/version-checker
roadrunner-php/roadrunner-api-dto	roadrunner/api-dto

To migrate, replace the package names and versions in composer.json.

Even more stable

RoadRunner already had the most reliable integration with PHP. What can be more stable than STDIN and STDOUT? Even so, we found things to improve in version 3. Memory use is now steadier, and performance is slightly higher.

However, if you need the highest performance for HTTP or gRPC endpoints, it may be time to try Rapira.