-
-
Notifications
You must be signed in to change notification settings - Fork 421
release: v2025.1.4 #2240
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+208
−85
Merged
release: v2025.1.4 #2240
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,143 @@ | ||
| # CLAUDE.md | ||
|
|
||
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | ||
|
|
||
| ## Project Overview | ||
|
|
||
| RoadRunner is a high-performance PHP application server and process manager written in Go. It supports running as a service with extensive plugin functionality for HTTP/2/3, gRPC, queues (RabbitMQ, Kafka, SQS, NATS), KV stores, WebSockets, Temporal workflows, and more. | ||
|
|
||
| ## Development Commands | ||
|
|
||
| ### Build | ||
| ```bash | ||
| make build | ||
| # Or manually: | ||
| CGO_ENABLED=0 go build -trimpath -ldflags "-s" -o rr cmd/rr/main.go | ||
| ``` | ||
|
|
||
| ### Test | ||
| ```bash | ||
| make test | ||
| # Or manually: | ||
| go test -v -race ./... | ||
| ``` | ||
|
|
||
| ### Debug | ||
| ```bash | ||
| make debug | ||
| # Uses delve to debug with sample config | ||
| ``` | ||
|
|
||
| ### Run RoadRunner | ||
| ```bash | ||
| ./rr serve -c .rr.yaml | ||
| ``` | ||
|
|
||
| ### Other Commands | ||
| ```bash | ||
| ./rr workers # Show worker status | ||
| ./rr workers -i # Interactive worker information | ||
| ./rr reset # Reset workers | ||
| ./rr jobs # Jobs management commands | ||
| ./rr stop # Stop RoadRunner server | ||
| ``` | ||
|
|
||
| ### Run Single Test | ||
| ```bash | ||
| go test -v -race -run TestName ./path/to/package | ||
| ``` | ||
|
|
||
| ## Architecture | ||
|
|
||
| ### Plugin System | ||
|
|
||
| RoadRunner uses the **Endure** dependency injection container. All plugins are registered in `container/plugins.go:Plugins()`. The plugin architecture follows these principles: | ||
|
|
||
| 1. **Plugin Registration**: Plugins are listed in `container/plugins.go` and automatically wired by Endure | ||
| 2. **Plugin Dependencies**: Plugins declare dependencies via struct fields with interface types | ||
| 3. **Initialization Order**: Endure resolves the dependency graph and initializes plugins in correct order | ||
|
|
||
| ### Key Components | ||
|
|
||
| - **`cmd/rr/main.go`**: Entry point that delegates to CLI commands | ||
| - **`internal/cli/`**: CLI command implementations (serve, workers, reset, jobs, stop) | ||
| - **`container/`**: Plugin registration and Endure container configuration | ||
| - **Plugin packages**: External packages under `github.com/roadrunner-server/*` (imported in go.mod) | ||
|
|
||
| ### Configuration | ||
|
|
||
| - Primary config: `.rr.yaml` (extensive sample provided) | ||
| - Version 3 config format required (`version: '3'`) | ||
| - Environment variable substitution supported: `${ENVIRONMENT_VARIABLE_NAME}` | ||
| - Sample configs: `.rr-sample-*.yaml` for different use cases (HTTP, gRPC, Temporal, Kafka, etc.) | ||
|
|
||
| ### Core Plugins | ||
|
|
||
| **Server Management:** | ||
| - `server`: Worker pool management (NewWorker, NewWorkerPool) | ||
| - `rpc`: RPC server for PHP-to-Go communication (default: tcp://127.0.0.1:6001) | ||
| - `logger`: Logging infrastructure | ||
| - `informer`: Worker status reporting | ||
| - `resetter`: Worker reset functionality | ||
|
|
||
| **Protocol Servers:** | ||
| - `http`: HTTP/1/2/3 and FastCGI server with middleware support | ||
| - `grpc`: gRPC server | ||
| - `tcp`: Raw TCP connection handling | ||
|
|
||
| **Jobs/Queue Drivers:** | ||
| - `jobs`: Core jobs plugin | ||
| - `amqp`, `sqs`, `nats`, `kafka`, `beanstalk`: Queue backends | ||
| - `gps`: Google Pub/Sub | ||
|
|
||
| **KV Stores:** | ||
| - `kv`: Core KV plugin | ||
| - `memory`, `boltdb`, `redis`, `memcached`: Storage backends | ||
|
|
||
| **HTTP Middleware:** | ||
| - `static`, `headers`, `gzip`, `prometheus`, `send`, `proxy_ip_parser`, `otel`, `fileserver` | ||
|
|
||
| **Other:** | ||
| - `temporal`: Temporal.io workflow engine integration | ||
| - `centrifuge`: WebSocket/Broadcast via Centrifugo | ||
| - `lock`: Distributed locks | ||
| - `metrics`: Prometheus metrics | ||
| - `service`: Systemd-like service manager | ||
|
|
||
| ### Worker Communication | ||
|
|
||
| RoadRunner communicates with PHP workers via: | ||
| - **Goridge protocol**: Binary protocol over pipes, TCP, or Unix sockets | ||
| - **RPC**: For management operations (reset, stats, etc.) | ||
| - Workers are PHP processes that implement the RoadRunner worker protocol | ||
|
|
||
| ### Testing | ||
|
|
||
| - Tests use standard Go testing with `-race` flag | ||
| - Test files follow `*_test.go` convention | ||
| - Sample configs in `.rr-sample-*.yaml` are used for integration tests | ||
| - Test directories: `container/test`, `internal/rpc/test` | ||
|
|
||
| ## Important Notes | ||
|
|
||
| - Go version: 1.25+ required (see go.mod) | ||
| - Module path: `github.com/roadrunner-server/roadrunner/v2025` | ||
| - Some versions are explicitly excluded in go.mod (e.g., go-redis v9.15.0, viper v1.18.x) | ||
| - Debug mode available via `--debug` flag (starts debug server on :6061) | ||
| - Config overrides supported via `-o dot.notation=value` flag | ||
| - Working directory can be set with `-w` flag | ||
| - `.env` file support via `--dotenv` flag or `DOTENV_PATH` environment variable | ||
|
|
||
| ## Adding New Plugins | ||
|
|
||
| 1. Import the plugin package in `container/plugins.go` | ||
| 2. Add plugin instance to the `Plugins()` slice | ||
| 3. Plugin must implement appropriate RoadRunner plugin interfaces | ||
| 4. Endure will handle dependency injection and lifecycle management | ||
|
|
||
| ## Configuration Patterns | ||
|
|
||
| - Each plugin has its own configuration section (named after plugin) | ||
| - Pools configuration is consistent across plugins (num_workers, max_jobs, timeouts, supervisor) | ||
| - TLS configuration follows similar pattern across plugins | ||
| - Most plugins support graceful shutdown via timeouts |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.