If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/roadrunner-server/roadrunner shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 76% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live roadrunner-server/roadrunner repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/roadrunner-server/roadrunner.

What it runs against: a local clone of roadrunner-server/roadrunner — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in roadrunner-server/roadrunner | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of roadrunner-server/roadrunner. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/roadrunner-server/roadrunner.git
#   cd roadrunner
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of roadrunner-server/roadrunner and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "roadrunner-server/roadrunner(\\.git)?\\b" \\
  && ok "origin remote is roadrunner-server/roadrunner" \\
  || miss "origin remote is not roadrunner-server/roadrunner (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/rr/main.go" \\
  && ok "cmd/rr/main.go" \\
  || miss "missing critical file: cmd/rr/main.go"
test -f "container/container_test.go" \\
  && ok "container/container_test.go" \\
  || miss "missing critical file: container/container_test.go"
test -f "internal/cli/serve/command.go" \\
  && ok "internal/cli/serve/command.go" \\
  || miss "missing critical file: internal/cli/serve/command.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f ".rr.yaml" \\
  && ok ".rr.yaml" \\
  || miss "missing critical file: .rr.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/roadrunner-server/roadrunner"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

RoadRunner is a high-performance PHP application server and process manager written in Go that replaces traditional Nginx+FPM stacks. It provides HTTP/2/3, fCGI, and gRPC servers with automatic TLS management, plus a plugin ecosystem for queues (RabbitMQ, Kafka, SQS, NATS), KV stores (Redis, Memcached, BoltDB), OpenTelemetry observability, and Temporal workflow orchestration—all managed through a single YAML configuration file. Modular monorepo structure: cmd/rr/ contains the CLI entry point, container/ implements the plugin dependency injection system (Endure framework), and the repo relies on external roadrunner-server/* plugin packages (http, grpc, jobs, kv, otel, etc.) loaded at runtime. Configuration flows through .rr.yaml into container/config.go which bootstraps plugins based on declared interfaces.

PHP developers and DevOps engineers seeking to replace traditional web server stacks; teams running high-throughput PHP applications that need better performance than FPM, real-time capabilities, and integrated observability without managing separate infrastructure (Nginx, FPM, Redis, RabbitMQ separately).

Production-ready and actively developed. The project uses semantic versioning (v2025 in go.mod), has comprehensive CI/CD via GitHub Actions (e2e.yml, tests.yml, release.yml), extensive plugin ecosystem with 20+ official plugins, and structured test files throughout the codebase (e.g., container/container_test.go, cmd/rr/command_test.go). The MIT license and active community indicate maturity, though the monolithic plugin-based architecture means stability depends on coordinated plugin updates.

Moderate risk from dependency sprawl: 20+ official roadrunner-server/* plugins plus core Go dependencies creates a large attack surface and requires coordinated updates across plugins. The Go-centric architecture (97% of codebase) means PHP developers may struggle with debugging server-level issues. Breaking changes are managed through versioning, but the PHP-to-Go FFI boundary (via goridge/v3) is a potential failure point for edge cases.

Active development toward v2025 release with Go 1.26.2 support. GitHub Actions workflows show ongoing e2e testing, dependency review, CodeQL security scanning, and automated dependency updates via Dependabot. The release_grpc.yml and release_dep_aarch64.yml workflows indicate focus on multi-architecture support and gRPC plugin maturity.

Clone, install Go 1.26.2+, and build: git clone https://github.com/roadrunner-server/roadrunner.git && cd roadrunner && make build (see Makefile for targets). For a dev server: copy .rr.yaml template, adjust port/plugins, then run ./rr serve. PHP app integration requires the spiral/roadrunner Composer package (see composer.json).

Daily commands: make build compiles the rr binary to bin/rr; then ./rr serve -c .rr.yaml starts the server. For local testing: Docker available (Dockerfile present), example config in .rr.yaml for HTTP on :8080 with PHP app server backend.

• cmd/rr/main.go — Entry point for the RoadRunner CLI; initializes the application and plugin system—every contributor must understand how the server bootstraps.
• container/container_test.go — Core dependency injection and plugin lifecycle management; demonstrates how RoadRunner loads and orchestrates plugins via Endure.
• internal/cli/serve/command.go — Main server startup logic; handles configuration loading, plugin initialization, and graceful shutdown—critical for understanding request handling flow.
• go.mod — Defines all plugin and dependency versions (AMQP, gRPC, HTTP, queue drivers, etc.); changes here cascade across the entire plugin ecosystem.
• .rr.yaml — Default configuration template showing all available plugins and their options; essential reference for understanding system capabilities and defaults.
• internal/rpc/client.go — RPC communication layer for inter-process control (worker management, job queues, metrics); bridges CLI commands to running server instances.
• CONTRIBUTING.md — Documents contribution guidelines, plugin architecture expectations, and development workflows specific to RoadRunner's plugin-based design.

Add a new CLI command

1. Create a new command struct in internal/cli/mycommand/ directory with command.go (implement cobra.Command and Endure interface) (internal/cli/serve/command.go)
2. Add the new command to the root command's subcommands in the init/run logic (internal/cli/root.go)
3. If your command needs RPC communication, use internal/rpc/client.go to invoke methods on the running server (internal/rpc/client.go)
4. Write tests in command_test.go following the patterns in internal/cli/serve/command_test.go (internal/cli/serve/command_test.go)

Integrate a new plugin into RoadRunner

1. Add the plugin package to go.mod (e.g., github.com/roadrunner-server/myfeature/v5) (go.mod)
2. Add the plugin's configuration section to .rr.yaml with all available options and defaults (.rr.yaml)
3. In cmd/rr/main.go or container initialization, register the plugin with the Endure container (cmd/rr/main.go)
4. If the plugin exposes RPC methods for CLI control, implement them following internal/rpc/client.go patterns (internal/rpc/client.go)

Add a new RPC method for server control

1. Define the RPC service interface in the plugin (e.g., Jobs.List, Workers.Status) following roadrunner-server/api patterns (internal/rpc/client.go)
2. Add the RPC client call in internal/rpc/client.go (Call method with struct marshaling) (internal/rpc/client.go)
3. Create or extend a CLI command in internal/cli/mycommand/command.go to invoke the new RPC method (internal/cli/jobs/command.go)
4. Write tests in the CLI command test file to validate RPC integration (internal/cli/jobs/command_test.go)

• Go 1.26.2 — High-performance server runtime with built-in concurrency primitives (goroutines, channels); enables efficient process management and multi-protocol serving.
• Endure framework (container/plugin system) — Plugin-based architecture allows modular, loosely-coupled features (HTTP, gRPC, AMQP, Centrifuge, etc.) to coexist without core bloat; each plugin defines dependencies and lifecycle hooks.
• cobra (CLI framework) — Standard Go CLI library; provides command hierarchies, flag parsing, and help generation matching Unix conventions expected by RoadRunner users.
• YAML configuration with environment variable interpolation — Human-readable server config; environment variable support enables 12-factor app compliance and containerized deployments (Docker, K8s).
• RPC over Unix socket / TCP — Allows CLI commands to control a running server instance without restarting; enables zero-downtime job inspection, worker management, and metrics collection.
• Process manager + worker pools — Manages long-lived PHP worker processes; amortizes startup overhead, reuses connections, and enables graceful shutdown without losing in-flight requests.

• Single binary written in Go, with PHP workers managed as subprocess pool

  • Why: Go provides fast server startup, high concurrency, and small binary size; PHP remains the business logic runtime for backward compatibility with existing packages.
  • Consequence: Requires careful process lifecycle management (signal handling, graceful shutdown) and inter-process communication overhead; not suitable for single-threaded PHP code expecting global state persistence.

• Plugin architecture (Endure) vs. monolithic server

  • Why: Allows optional features (AMQP, Centrifuge, gRPC) to be loaded only when needed; reduces memory footprint for simple HTTP-only deployments.
  • Consequence: Increases codebase complexity; plugin interdependencies can create subtle initialization ordering bugs; testing requires understanding container lifecycle.

• YAML + environment variables for configuration, no CLI flags for server options

  • Why: Configuration as code (YAML) is more maintainable for complex setups than hundreds of CLI flags; environment variable interpolation enables CI/CD workflows.
  • Consequence: Requires file system access and config file validation at startup; less suitable for immutable, flag-driven deployments (though environment variables work).

• RPC control plane separate from data plane (workers)

  • Why: CLI commands (jobs, workers, reset) can introspect/manage running server without modifying request handling; enables monitoring without performance impact.
  • Consequence: Adds complexity: RPC client protocol, separate socket listener, marshaling/unmarshaling overhead; control plane failures could make server appear unmanageable even if workers are healthy.

• Not a PHP framework or application; does not provide routing, ORM, templating, or business logic—it only serves PHP applications.
• Not a package manager; does not manage PHP dependencies (Composer handles that).
• Not a containerization runtime; does not replace Docker or systemd for process supervision (though designed to run well inside containers).
• Not cross-platform in all aspects; Windows support for 'serve' command differs from Unix (see internal/cli/serve/command_windows.go).
• Not a real-time database or event streaming platform; queue plugins (AMQP, BeanStalk, Centrifuge) are integrations, not built-in services.

PHP process communication: RoadRunner uses Goridge (named pipes / Unix sockets) to talk to PHP workers—network issues or buffer overflows in goridge can manifest as hung requests with poor error messages. Configuration reloading: .rr.yaml changes require a full server restart (no hot-reload); plugins must explicitly implement graceful shutdown or you'll lose in-flight requests. Plugin version mismatch: roadrunner-server plugins are versioned separately (v5.x, v4.x) and must match the core version or you get silent initialization failures—check go.mod carefully. PHP worker lifecycle: Workers are pooled and reused; application state persists across requests unless explicitly reset (see resetter/v5 plugin dependency). gRPC definitions: Using the gRPC server requires .proto files outside this repo; the grpc plugin only provides the server runtime. OTEL export: OpenTelemetry observability requires an OTEL collector running separately or export fails silently.

• Plugin Architecture with Interface-Based Discovery — RoadRunner's entire extensibility model depends on Go interfaces (defined in roadrunner-server/api); understanding how plugins register themselves via the Endure framework is essential to adding new plugins or modifying core behavior
• Graceful Shutdown and Worker Pool Lifecycle — RoadRunner manages long-lived PHP worker processes in a pool; incorrect shutdown semantics cause hung requests, zombie processes, or data loss—critical for production reliability
• Named Pipes and Unix Socket IPC (Goridge Protocol) — RoadRunner communicates with PHP workers via Goridge, a binary RPC protocol over named pipes/Unix sockets, not TCP; understanding this transport is essential for debugging low-level communication failures
• Configuration-Driven Plugin Wiring — The entire server topology (which plugins run, how they interact, what ports they bind to) is determined by YAML config parsed into Go structs in container/config.go; config is effectively a DSL for the server
• Process Pooling and Worker Reuse — PHP workers are kept alive and reused across requests to avoid fork/startup overhead; application state persists unless explicitly reset (resetter plugin), so your code must be pool-aware
• OpenTelemetry Instrumentation Points — RoadRunner exports traces, metrics, and logs via OTEL (roadrunner-server/otel v5.5.0); observability is built-in at the server level, not just in PHP code, enabling end-to-end tracing
• Protocol Buffers and gRPC Service Definition — The gRPC plugin requires .proto files defining RPC services; RoadRunner generates Go code from protobuf but does not auto-generate PHP stubs—PHP dev must manually sync .proto definitions

• spiral/roadrunner — Official PHP SDK package (Composer package) that PHP applications require to communicate with RoadRunner server; bundled with PSR-7 adapters and request/response objects
• roadrunner-server/api — Shared Go API interfaces and protobuf definitions (v4.24.0 in deps) that all plugins implement; defines the plugin contract
• roadrunner-server/http — HTTP/2/3 server plugin; one of the most commonly used plugins, implements the PSR-7 HTTP server
• roadrunner-server/endure — Dependency injection and plugin lifecycle framework (v2.6.2 dependency) that powers RoadRunner's entire plugin architecture
• roadrunner-server/goridge — PHP-to-Go IPC transport layer (v3.8.3); the low-level communication protocol between PHP workers and the Go server, critical for performance

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for internal/cli/jobs command suite

The jobs CLI command module (internal/cli/jobs/) has command.go and command_test.go, but the test coverage appears minimal. Given that this is a process manager with job queue support (AMQP, Kafka, Beanstalk, SQS plugins visible in go.mod), the jobs CLI deserves thorough integration tests covering list, pause, resume, and forget operations. This is critical for a server that manages background jobs.

• [ ] Review internal/cli/jobs/command_test.go and internal/cli/jobs/subcommands.go to identify untested code paths
• [ ] Add integration tests that spin up a local RoadRunner server with jobs plugin and verify CLI commands against real job queues
• [ ] Test error scenarios: invalid job IDs, disconnected queues, permission errors
• [ ] Add tests for render.go output formatting with various job states and queue backends

Implement end-to-end test workflow for gRPC plugin with HTTP/2 edge cases

The repo has .github/workflows/e2e.yml and grpc/v5 is a core plugin, but specific gRPC edge cases (HTTP/2 stream prioritization, connection pooling, deadline propagation) should be tested in CI. The E2E workflow likely exists but may not comprehensively cover gRPC-specific scenarios that differ from HTTP/1.1 handling.

• [ ] Examine existing .github/workflows/e2e.yml to understand current gRPC test coverage
• [ ] Create specific gRPC E2E tests in internal/cli/ or a new tests/ directory covering: bidirectional streaming, connection pooling, timeout propagation, and concurrent requests
• [ ] Add performance benchmarks using benchmarks/simple.js pattern but for gRPC endpoints
• [ ] Verify tests run against roadrunner-server/grpc/v5 plugin integration

Add missing OTEL instrumentation tests for plugin initialization chain

The repo includes roadrunner-server/otel/v5 and uses endure/v2 for plugin dependency injection (visible in container/plugins.go), but there are no visible tests verifying that OTEL tracing correctly instruments plugin startup, shutdown, and inter-plugin communication. This is critical for observability in production.

• [ ] Review container/plugins.go and container/plugins_test.go to understand plugin lifecycle hooks
• [ ] Create container/otel_instrumentation_test.go with tests that verify traces are emitted for: plugin Init(), Serve(), Stop() lifecycle phases
• [ ] Test that traces correctly capture inter-plugin dependencies (e.g., HTTP plugin depending on logger plugin)
• [ ] Validate trace context propagation across the endure container initialization in container/container_test.go scenarios

• Add unit test coverage for container/config.go validation edge cases (e.g., missing required fields, invalid plugin names, malformed YAML paths) following the table-driven pattern in container/container_test.go—currently config validation lacks explicit test cases.
• Document the Goridge protocol and PHP worker lifecycle in CONTRIBUTING.md with a concrete example of how HTTP requests flow from Go to PHP and back, including diagrams of the pool/worker/request lifecycle visible in the codebase but undocumented.
• Add a Makefile target and GitHub Actions workflow to validate .rr.yaml schemas against the Go struct definitions in container/config.go (similar to protoc validation for gRPC)—currently there's no tooling to catch config format drift early.

• High · Outdated Go Version in Docker Build — Dockerfile (line: FROM golang:1.26-alpine AS builder). The Dockerfile uses Go 1.26-alpine which appears to be a future/non-existent version. This suggests either a version management issue or use of an unreleased Go version that may not have security patches. Go 1.26 does not exist as of the latest stable releases (current stable is 1.22.x). This could indicate build reproducibility issues and potential use of untested/unsupported Go versions. Fix: Use a stable, well-tested Go version such as golang:1.22-alpine or the latest LTS version. Verify the actual Go version being used in production builds and align with Go's official release schedule.
• High · Inconsistent Supported Versions Security Policy — SECURITY.md and go.mod. The SECURITY.md file indicates that versions 2.x and 2023.x.x receive no support, while only 2024.x.x and 2025.x.x are supported. However, the go.mod module path shows 'github.com/roadrunner-server/roadrunner/v2025', indicating a single major version track. This creates ambiguity about which versions receive security updates and could lead to users running unsupported, vulnerable versions without clear upgrade paths. Fix: Clarify the version support matrix in SECURITY.md. Define clear end-of-life dates for each version branch. Implement automated dependency scanning and security advisories for unsupported versions. Consider maintaining security patches for at least the last 2 major versions.
• Medium · Minimal Alpine Base Image with No Security Scanning — Dockerfile (FROM alpine:3 in final stage). The final Docker stage uses 'alpine:3' as the base image. While Alpine is lightweight, the tag is too generic (missing patch version) and the Dockerfile lacks container image scanning, vulnerability scanning, or security baseline enforcement. No health checks, security contexts, or non-root user configuration is visible. Fix: Use specific Alpine version tags (e.g., alpine:3.20.0). Add RUN apk upgrade --no-cache to update base packages. Consider using distroless or minimal images. Implement container scanning with tools like Trivy or Grype in CI/CD. Define explicit non-root USER in Dockerfile.
• Medium · Excessive Permission Build Arguments — Dockerfile (ARG APP_VERSION and ARG BUILD_TIME). The Dockerfile accepts APP_VERSION and BUILD_TIME as build arguments that are embedded in the binary via LDFLAGS. While not directly sensitive, build arguments can be logged and exposed in image history. No validation or sanitization of these inputs is visible, potentially allowing injection through build argument manipulation. Fix: Validate build arguments against expected patterns (e.g., semantic versioning regex for APP_VERSION). Document build argument security requirements. Consider using build secrets instead of build args for sensitive metadata. Use --progress=plain only when necessary to avoid argument exposure in logs.
• Medium · Missing Dependency Version Pinning Specificity — go.mod (dependency declarations). The go.mod file uses v5.x.x version constraints for most roadrunner-server dependencies, but some packages use minor version constraints (e.g., pool v1.1.3) while others use patch versions. This inconsistency could lead to subtle version mismatches during dependency resolution and makes supply chain security harder to track. Fix: Ensure all dependencies use consistent version pinning strategy. Consider using exact versions (without ^ or ~) for critical security-sensitive packages. Regularly audit go.mod and go.sum files. Implement dependency scanning in CI/CD using tools like 'go mod verify' and GitHub Dependabot (already present in workflow).
• Medium · No Visible Security Headers or Configuration Validation — .rr.yaml (not provided for analysis). The .rr.yaml file is referenced but not shown. Without visibility into the configuration, it's unclear if security headers, TLS configuration, CORS policies, and authentication mechanisms are properly configured. The presence of multiple protocol plugins (gRPC, HTTP, etc.) without visible security defaults is a concern. Fix: Review and document all security-relevant configuration in .rr.yaml. Implement security headers (CSP, X-Frame-Options, X-Content-Type-Options, HSTS, etc.). Enforce TLS/mTLS for inter-service communication. Validate all configuration with a schema. Provide secure configuration templates/examples.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.