> For the complete documentation index, see [llms.txt](https://docs.roadrunner.dev/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadrunner.dev/docs/releases/v3-0-0.md).

# v3.0.0

RoadRunner v3 uses v6 Go plugins. See [Upgrade from v2025 to v3](/docs/general/v3-migration.md) for the required configuration and API changes.

## Changelog

### 🎯 Core

* ✨ **Go module**: Import RoadRunner through `github.com/roadrunner-server/roadrunner/v3`. See [Embedding a server](/docs/customization/embedding.md).
* ✨ **Plugin API**: Protobuf schemas, generated Go messages, and Go plugin contracts now have separate repositories: `api`, `api-go/v6`, and `api-plugins/v6`. Custom plugins use `log/slog`, `pool/v2`, and `goridge/v4`. See [Writing a Plugin](/docs/customization/plugin.md), [PR](https://github.com/roadrunner-server/roadrunner/pull/2383).
* ✨ **Unix sockets**: Configure socket mode, owner, and group for supported listeners and worker relays. See [Configuration](/docs/general/config.md#unix-socket-attributes), [FR](https://github.com/roadrunner-server/roadrunner/issues/1789).
* ✨ **Environment files**: Load the root `envfile` without experimental mode. A configured file is required when the server starts. See [Environment](/docs/php-worker/environment.md).
* ✨ **RPC codecs**: Goridge v4 removes MessagePack support. JSON, protobuf, Gob, and raw payloads remain available through the existing Goridge RPC transport. See [RPC](/docs/php-worker/rpc.md), [PR](https://github.com/roadrunner-server/goridge/pull/194).
* ✨ **Worker scaling**: Retry worker acquisition after automatic scale-up and revise idle-worker removal. `dynamic_allocator.max_workers` counts workers added above the base pool size. See [Auto workers scaling](/docs/php-worker/auto-scaling.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2086).
* ✨ **Initialization environment**: Values in `server.on_init.env` override inherited values. See [Server](/docs/plugins/server.md), [PR](https://github.com/roadrunner-server/server/pull/137).
* ✨ **Default plugins**: Add NSQ, HTTP rate limiting, Zstd compression, and the protobuf registry to the default container. RoadRunner v3 does not support the [TCP plugin](/docs/plugins/tcp.md). See [NSQ](https://github.com/roadrunner-server/roadrunner/pull/2383), [rate limiting](https://github.com/roadrunner-server/roadrunner/pull/2389), and [Zstd and Protoreg](https://github.com/roadrunner-server/roadrunner/pull/2410).

### 📦 `http` plugin

* ✨ **Middleware order**: Requests enter `http.middleware` from left to right. Reverse a v5 list to keep its previous order. See [Middleware order](/docs/http/http.md#middleware-order), [PR](https://github.com/roadrunner-server/http/pull/226).
* ✨ **Cleartext HTTP/2**: Use HTTP/2 prior knowledge for H2C connections. HTTP/1.1 `Upgrade: h2c` is no longer supported. See [HTTP/2](/docs/http/http.md#http2).
* ✨ **PROXY protocol**: Accept v1 and v2 headers on HTTP and HTTPS listeners with explicit trusted proxy addresses. See [HTTP](/docs/http/http.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/937).

### 📦 `proxy_ip_parser` middleware

* ✨ **Trusted headers**: Select forwarding headers and their priority through `http.trusted_headers`. See [Proxy IP parser](/docs/http/proxy.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/1515).

### 📦 `static` middleware

* ✨ **File serving controls**: Configure URL prefixes, metadata cache TTL, missing-file cache TTL, and cache limits. Reset both caches with `rr reset static`. Weak ETags now use file size and modification time. See [Static files](/docs/http/static.md), [PR](https://github.com/roadrunner-server/static/pull/147).

### 📦 `rate_limiter` middleware

* ✨ **Request limits**: Limit requests by global, IP, or header key. Rejected requests return `429` with `Retry-After`. See [Rate limiter](/docs/http/rate-limiter.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/934).

### 📦 `zstd` middleware

* ✨ **Response compression**: Compress HTTP responses with Zstandard when the client accepts `zstd`. See [Zstd](/docs/http/zstd.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2080).

### 📦 `grpc` plugin

* ✨ **Server reflection**: Discover services through reflection and retrieve PHP service descriptors through the bundled Protoreg plugin. See [Protoreg](/docs/grpc/protoreg.md#server-reflection), [FR](https://github.com/roadrunner-server/roadrunner/issues/1208).
* ✨ **Error details**: Include supported `google.rpc.Status` details in failed unary-call logs. See [gRPC](/docs/grpc/grpc.md#error-details-in-logs), [FR](https://github.com/roadrunner-server/roadrunner/issues/1897).

### 📦 `amqp` driver

* ✨ **Named connections**: Connect pipelines to different brokers. Static pipelines require `config.connection` and nested `exchange` and `queue` settings; AMQP `config.version` is removed. See [RabbitMQ](/docs/queues-and-jobs/amqp.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/1962).
* ✨ **Declaration controls**: Configure queue and exchange declarations independently. Use existing broker resources with accounts that cannot declare them. See [RabbitMQ](/docs/queues-and-jobs/amqp.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2275).

### 📦 `jobs` plugin

* ✨ **Named worker pools**: Assign pipelines to separate PHP worker pools with their own commands and capacity. The `pool` header selects the destination pool. See [Jobs](/docs/queues-and-jobs/overview-queues.md#named-worker-pools), [PR](https://github.com/roadrunner-server/jobs/pull/139).
* ✨ **Trace continuity**: Preserve valid producer trace context when jobs are submitted through RPC. See [Jobs](/docs/queues-and-jobs/overview-queues.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2211).
* ✨ **Outcome metrics**: Count successful, failed, and requeued attempts separately with `rr_jobs_jobs_requeue`. Outcome and push totals use counters. See [Metrics](/docs/logging-and-observability/metrics.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/1566).
* ✨ **Queue size**: The default `pipeline_size` is `100000`. See [Jobs](/docs/queues-and-jobs/overview-queues.md), [PR](https://github.com/roadrunner-server/jobs/pull/157).
* 🐛 **Full queue**: A driver waits for a free slot in a full priority queue without CPU use. Jobs with the same priority leave the queue in arrival order. See [Jobs](/docs/queues-and-jobs/overview-queues.md), [BUG](https://github.com/roadrunner-server/roadrunner/issues/2411).
* 🐛 **Pollers**: A `jobs.pool` without `num_workers` uses `num_workers + 2` pollers with the default worker count of the pool. See [Jobs](/docs/queues-and-jobs/overview-queues.md), [PR](https://github.com/roadrunner-server/jobs/pull/157).

### 📦 `nsq` driver

* ✨ **NSQ jobs**: Publish and consume jobs through NSQ topics and channels. Support broker discovery, delayed delivery, acknowledgements, and configurable reconnection intervals. See [NSQ](/docs/queues-and-jobs/nsq.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/1948).

### 📦 `nats` driver

* ✨ **Stream retention**: Preserve stream contents when a pipeline stops unless stream deletion is enabled. Review retention and repeated-delivery handling when upgrading. See [NATS](/docs/queues-and-jobs/nats.md), [PR](https://github.com/roadrunner-server/nats/pull/226).
* ✨ **Acknowledgment wait**: Configure `ack_wait` for JetStream redelivery timing. See [NATS](/docs/queues-and-jobs/nats.md), [PR](https://github.com/roadrunner-server/nats/pull/190).

### 📦 `kafka` driver

* ✨ **Direct partition consumption**: Apply `consume_partitions` to select topic partitions and starting offsets. See [Kafka](/docs/queues-and-jobs/kafka.md), [PR](https://github.com/roadrunner-server/kafka/pull/580).

### 📦 `sqs` driver

* 🐛 **FIFO retry delivery**: Use a fresh broker deduplication ID for each republished retry while retaining the application job ID. This prevents SQS from discarding the retry as a duplicate of the deleted original. See [SQS](/docs/queues-and-jobs/sqs.md), [PR](https://github.com/roadrunner-server/sqs/pull/864).

### 📦 `beanstalk` driver

* ✨ **Job headers**: Preserve headers through storage and retries, including trace context and named-pool routing. Existing messages cannot recover headers that were not stored. See [Beanstalk](/docs/queues-and-jobs/beanstalk.md).

### 📦 `logger` plugin

* ✨ **Logging configuration**: Use Go `log/slog` with JSON, text, and raw formats. Configure file destinations through `output`; built-in rotation and `file_logger_options` are removed. See [Logger](/docs/logging-and-observability/logger.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/1750).
* ✨ **Custom formats**: Set `format` placeholders and `time_format` to control log records and timestamps. See [Logger](/docs/logging-and-observability/logger.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/1376).
* ✨ **Non-blocking output**: Queue log records before writing them. A full output queue drops new records to keep application calls responsive. See [Logger](/docs/logging-and-observability/logger.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2195).

### 📦 `lock` plugin

* ✨ **Redis backend**: Share locks between RoadRunner instances through Redis with the existing lock RPC API. The in-memory backend remains the default. See [Locks](/docs/plugins/locks.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2070).

### 📦 `redis` driver

* ✨ **Sentinel authentication**: Configure `sentinel_username` and `sentinel_password` independently from Redis master credentials. Password-only Sentinel authentication remains supported. See [Redis](/docs/key-value/redis.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2407).

### 📦 `service` plugin

* ✨ **Deferred updates**: Change stored service configuration through `service.Update`. Existing processes keep their current settings; new processes use the updated values. PHP applications need client and DTO support for this method. See [Service](/docs/plugins/service.md), [FR](https://github.com/roadrunner-server/roadrunner/issues/2119).

### 📦 `status` plugin

* ✨ **Kubernetes probes**: Use `/livez` as an alias for `/health` and `/readyz` as an alias for `/ready`. See [HealthChecks](/docs/logging-and-observability/health.md), [PR](https://github.com/roadrunner-server/status/pull/154).

### 📦 `otel` plugin

* ✨ **Span timing**: End named middleware spans before the next handler starts. Use the outer HTTP server span for request latency. See [OpenTelemetry](/docs/logging-and-observability/otel.md) and [HTTP tracing](/docs/http/http.md#tracing), [FR](https://github.com/roadrunner-server/roadrunner/issues/2276).
* ✨ **Exporters**: Remove the native Zipkin exporter. Send traces through OTLP to a compatible receiver. See [OpenTelemetry](/docs/logging-and-observability/otel.md).

### 📦 `centrifuge` plugin

* ✨ **Protocol update**: Add `NotifyCacheEmpty` event support and remove `centrifuge.RateLimit`. The new event needs matching PHP DTO and handler support. See [Centrifuge](/docs/plugins/centrifuge.md).

### 📦 `temporal` plugin

* ✨ **Worker heartbeats**: Configure the worker heartbeat interval and report PHP SDK identity with host CPU and memory metrics. See [Temporal](/docs/workflow-engine/temporal.md), [PR](https://github.com/temporalio/roadrunner-temporal/pull/790).
* ✨ **Dynamic workflows**: Register a catch-all workflow for workflow types without a named registration. See [Worker](/docs/workflow-engine/worker.md), [PR](https://github.com/temporalio/roadrunner-temporal/pull/784).
* 🐛 **Activity-worker recovery**: Replace a failed activity worker without restarting healthy workers in the same activity pool. See [Worker](/docs/workflow-engine/worker.md), [BUG](https://github.com/roadrunner-server/roadrunner/issues/2335).

### 📦 `velox` builder

* ✨ **Module configuration**: Select plugins through `[plugins.<name>]`, with `module_name` and `tag`. Support module replacements, exclusions, and repeatable build timestamps. The remote build server and Windows targets are removed. See [Building a Server](/docs/customization/build.md), [PR](https://github.com/roadrunner-server/velox/pull/350).