roadrunner-server/roadrunner v3.0.0

on GitHub

3.0.0 (2026-10-08)

RoadRunner v3 uses v6 Go plugins. See Upgrade from v2025 to v3 for the required configuration and API changes.

🎯 Core

• ✨ Go module: Import RoadRunner through github.com/roadrunner-server/roadrunner/v3. See Embedding a server.
• ✨ 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, PR.
• ✨ Unix sockets: Configure socket mode, owner, and group for supported listeners and worker relays. See Configuration, FR.
• ✨ Environment files: Load the root envfile without experimental mode. A configured file is required when the server starts. See Environment.
• ✨ RPC codecs: Goridge v4 removes MessagePack support. JSON, protobuf, Gob, and raw payloads remain available through the existing Goridge RPC transport. See RPC, PR.
• ✨ 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, FR.
• ✨ Initialization environment: Values in server.on_init.env override inherited values. See Server, PR.
• ✨ Default plugins: Add NSQ, HTTP rate limiting, Zstd compression, and the protobuf registry to the default container. TCP requires a custom build. See NSQ and TCP, rate limiting, and Zstd and Protoreg.

📦 http plugin

• ✨ Middleware order: Requests enter http.middleware from left to right. Reverse a v5 list to keep its previous order. See Middleware order, PR.
• ✨ Cleartext HTTP/2: Use HTTP/2 prior knowledge for H2C connections. HTTP/1.1 Upgrade: h2c is no longer supported. See HTTP/2.
• ✨ PROXY protocol: Accept v1 and v2 headers on HTTP and HTTPS listeners with explicit trusted proxy addresses. See HTTP, FR.

📦 proxy_ip_parser middleware

• ✨ Trusted headers: Select forwarding headers and their priority through http.trusted_headers. See Proxy IP parser, FR.

📦 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, PR.

📦 rate_limiter middleware

• ✨ Request limits: Limit requests by global, IP, or header key. Rejected requests return 429 with Retry-After. See Rate limiter, FR.

📦 zstd middleware

• ✨ Response compression: Compress HTTP responses with Zstandard when the client accepts zstd. See Zstd, FR.

📦 grpc plugin

• ✨ Server reflection: Discover services through reflection and retrieve PHP service descriptors through the bundled Protoreg plugin. See Protoreg, FR.
• ✨ Error details: Include supported google.rpc.Status details in failed unary-call logs. See gRPC, FR.

📦 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, FR.
• ✨ Declaration controls: Configure queue and exchange declarations independently. Use existing broker resources with accounts that cannot declare them. See RabbitMQ, FR.

📦 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, PR.
• ✨ Trace continuity: Preserve valid producer trace context when jobs are submitted through RPC. See Jobs, FR.
• ✨ Outcome metrics: Count successful, failed, and requeued attempts separately with rr_jobs_jobs_requeue. Outcome and push totals use counters. See Metrics, FR.

📦 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, FR.

📦 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, PR.
• ✨ Acknowledgment wait: Configure ack_wait for JetStream redelivery timing. See NATS, PR.

📦 kafka driver

• ✨ Direct partition consumption: Apply consume_partitions to select topic partitions and starting offsets. See Kafka, PR.
• 🐛 Requeue isolation: A requeued job, or a job nacked with redelivery, goes back to the RoadRunner priority queue. The driver no longer produces a copy to the source topic, so other consumer groups do not receive the retry. The driver honors the requested delay. A burst of retries no longer drops jobs. A retry waits in memory: it is lost after a stop, restart, or crash once a later offset of its partition is committed. See Kafka, BUG.
• 🐛 Consumer recovery: When the consumer gets a non-retriable Kafka error, for example when the broker denies access to the topic or removes the consumer from the group, the jobs plugin restarts the pipeline. The old consumer closes, and a pipeline in jobs.consume continues with a new consumer. If the restart of a configured pipeline fails, RoadRunner stops with an error. See Kafka, BUG.

📦 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, PR.

📦 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.

📦 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, FR.
• ✨ Custom formats: Set format placeholders and time_format to control log records and timestamps. See Logger, FR.
• ✨ Non-blocking output: Queue log records before writing them. A full output queue drops new records to keep application calls responsive. See Logger, FR.

📦 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, FR.

📦 redis driver

• ✨ Sentinel authentication: Configure sentinel_username and sentinel_password independently from Redis master credentials. Password-only Sentinel authentication remains supported. See Redis, FR.

📦 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, FR.

📦 status plugin

• ✨ Kubernetes probes: Use /livez as an alias for /health and /readyz as an alias for /ready. See HealthChecks, PR.

📦 otel plugin

• ✨ Span timing: End named middleware spans before the next handler starts. Use the outer HTTP server span for request latency. See OpenTelemetry and HTTP tracing, FR.
• ✨ Exporters: Remove the native Zipkin exporter. Send traces through OTLP to a compatible receiver. See OpenTelemetry.

📦 centrifuge plugin

• ✨ Protocol update: Add NotifyCacheEmpty event support and remove centrifuge.RateLimit. The new event needs matching PHP DTO and handler support. See Centrifuge.

📦 temporal plugin

• ✨ Worker heartbeats: Configure the worker heartbeat interval and report PHP SDK identity with host CPU and memory metrics. See Temporal, PR.
• ✨ Dynamic workflows: Register a catch-all workflow for workflow types without a named registration. See Worker, PR.
• 🐛 Activity-worker recovery: Replace a failed activity worker without restarting healthy workers in the same activity pool. See Worker, BUG.

📦 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, PR.