Skip to content

Commit bdd1522

Browse files
rustatianrustatian
authored
Merge pull request #248 from roadrunner-server/feature/server
New Velox server for the remote RR builds.
2 parents ce4ac5d + b2a466d commit bdd1522

40 files changed

+2883
-77
lines changed

‎.claude/CLAUDE.md

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# Velox - RoadRunner Build System
2+
3+
## Project Overview
4+
5+
Velox is an automated build system for RoadRunner server and its plugins. It's part of the Spiral/RoadRunner ecosystem and provides tools for building, testing, and managing RoadRunner plugin builds.
6+
7+
**Key Technologies:**
8+
9+
- Go 1.24+
10+
- Protocol Buffers (protobuf) with buf
11+
- GitHub/GitLab API integration
12+
- gRPC and Connect
13+
- Cobra CLI framework
14+
15+
## Repository Structure
16+
17+
```
18+
├── api/ # Protocol buffer definitions
19+
├── builder/ # Core build logic
20+
├── cmd/vx/ # Main CLI entry point
21+
├── gen/ # Generated protobuf code
22+
├── github/ # GitHub API integration
23+
├── gitlab/ # GitLab API integration
24+
├── internal/cli/ # CLI command implementations
25+
├── v2/ # Version 2 refactored components
26+
└── velox.toml # Configuration file
27+
```
28+
29+
## Common Commands
30+
31+
### Building and Testing
32+
33+
```bash
34+
# Run tests
35+
go test -v -race ./...
36+
make test
37+
38+
# Regenerate protobuf code
39+
make regenerate
40+
# Or manually:
41+
rm -rf ./gen && buf generate && buf format -w
42+
43+
# Build the velox binary
44+
go build -o vx ./cmd/vx
45+
46+
# Run velox (requires config)
47+
./vx -c velox.toml build
48+
./vx -c velox.toml server -a 127.0.0.1:8080
49+
```
50+
51+
### Development Tools
52+
53+
```bash
54+
# Format Go code
55+
go fmt ./...
56+
57+
# Run linter (if available)
58+
golangci-lint run
59+
60+
# Check dependencies
61+
go mod tidy
62+
go mod verify
63+
```
64+
65+
## Core Files and Components
66+
67+
### Main Entry Points
68+
69+
- `cmd/vx/main.go` - CLI application entry point
70+
- `internal/cli/root.go:18` - Root command setup with configuration
71+
72+
### Build System
73+
74+
- `builder/builder.go` - Core build logic
75+
- `builder/templates/` - Build templates for different versions
76+
- `v2/builder/` - Refactored v2 build system
77+
78+
### Configuration
79+
80+
- `config.go` - Configuration structure and validation
81+
- `velox.toml` - Default configuration file format
82+
83+
### API Integration
84+
85+
- `github/repo.go` - GitHub repository management
86+
- `gitlab/repo.go` - GitLab repository management
87+
- `api/` - Protocol buffer service definitions
88+
89+
## Code Style Guidelines
90+
91+
### Go Conventions
92+
93+
- Follow standard Go formatting (`gofmt`)
94+
- Use meaningful variable names
95+
- Prefer explicit error handling
96+
- Use context.Context for cancellation
97+
- Follow Go module structure with `github.com/roadrunner-server/velox/v2025`
98+
99+
### Protocol Buffers
100+
101+
- Use buf for generation and formatting
102+
- Service definitions in `api/service/v1/`
103+
- Generate code with `buf generate`
104+
105+
### Error Handling
106+
107+
- Use `github.com/pkg/errors` for error wrapping
108+
- Always handle errors explicitly
109+
- Use structured logging with zap
110+
111+
## Testing Instructions
112+
113+
```bash
114+
# Run all tests with race detection
115+
make test
116+
# or
117+
go test -v -race ./...
118+
119+
# Run specific package tests
120+
go test -v ./builder/
121+
go test -v ./github/
122+
123+
# Run with coverage
124+
go test -cover ./...
125+
```
126+
127+
## Repository Etiquette
128+
129+
### Branching
130+
131+
- Main branch: `master`
132+
- Feature branches: `feature/description`
133+
- Use conventional commit messages
134+
135+
### Plugin Compatibility
136+
137+
⚠️ **Important Plugin Guidelines:**
138+
139+
- Do not use plugin's `master` branch
140+
- Use tags with the **same major version**
141+
- Currently supported plugins version: `v5.x.x`
142+
- Currently supported RR version: `>=v2024.x.x`
143+
144+
### Commit Guidelines
145+
146+
- Use descriptive commit messages
147+
- Reference issues when applicable
148+
- Keep commits focused and atomic
149+
150+
## Developer Environment Setup
151+
152+
### Prerequisites
153+
154+
- Go 1.24+ (toolchain: go1.24.0)
155+
- buf CLI for protocol buffer generation
156+
- Git for version control
157+
158+
### Setup Steps
159+
160+
1. Clone repository
161+
2. Install dependencies: `go mod download`
162+
3. Generate protobuf code: `make regenerate`
163+
4. Run tests: `make test`
164+
5. Build: `go build ./cmd/vx`
165+
166+
### Configuration
167+
168+
Create `velox.toml` based on project requirements. The CLI expects:
169+
170+
```bash
171+
./vx -c velox.toml build # Build mode
172+
./vx -c velox.toml server # Server mode
173+
```
174+
175+
## Unexpected Project Behaviors
176+
177+
### Version Management
178+
179+
- Project uses `v2025` module path
180+
- Replace directive: `github.com/roadrunner-server/velox/v2025/gen => ./gen`
181+
- Multiple template versions in `builder/templates/`
182+
183+
### Build System
184+
185+
- Templates are versioned (V2, V2023, V2024, V2025)
186+
- Build process involves GitHub/GitLab API calls
187+
- Server mode provides build-as-a-service functionality
188+
189+
### Protobuf Generation
190+
191+
- Uses buf instead of protoc directly
192+
- Generated code goes into `gen/` directory
193+
- Must regenerate after proto changes
194+
195+
## Useful Development Patterns
196+
197+
### Adding New Build Templates
198+
199+
1. Create new template in `builder/templates/`
200+
2. Update `builder.go` to reference new template
201+
3. Add corresponding tests in `builder_test.go`
202+
203+
### GitHub/GitLab Integration
204+
205+
- Use existing pool patterns in `github/pool.go`
206+
- Implement repository interface consistently
207+
- Handle rate limiting and authentication
208+
209+
### CLI Commands
210+
211+
- Follow cobra patterns in `internal/cli/`
212+
- Use persistent flags for common options
213+
- Implement proper validation in `PersistentPreRunE`
214+
215+
## Links and Documentation
216+
217+
- [RoadRunner Docs](https://docs.roadrunner.dev/customization/build)
218+
- [Project Repository](https://github.com/roadrunner-server/velox)
219+
- [Discord Community](https://discord.gg/TFeEmCs)

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
*.so
66
*.dylib
77
.venv
8+
.DS_Store
89

910
# Test binary, built with `go test -c`
1011
*.test

‎Makefile

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
11
test:
2-
go test -v -race ./...
2+
go test -v -race ./...
3+
4+
regenerate:
5+
rm -rf ./gen
6+
buf generate
7+
buf format -w

‎api/request/v1/request.proto

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
syntax = "proto3";
2+
3+
package api.request.v1;
4+
5+
import "buf/validate/validate.proto";
6+
7+
option go_package = "github.com/roadrunner-server/velox/v2025/gen/go/api/request/v1;requestV1";
8+
9+
message Platform {
10+
// GOOS
11+
string os = 1;
12+
// GOARCH
13+
string arch = 2;
14+
}
15+
16+
message BuildRequest {
17+
// request_id is optional and needed to match requests with their responses on the client side
18+
// must be a valid uuid
19+
string request_id = 1 [
20+
(buf.validate.field).string.uuid = true,
21+
(buf.validate.field).required = false
22+
];
23+
// rr version is required and must be a valid semantic version
24+
string rr_version = 2 [
25+
(buf.validate.field).required = true,
26+
(buf.validate.field).cel = {
27+
id: "rr_version.format"
28+
message: "rr_version must be a semantic version starting with 'v' (e.g., v2025.1.0), 'master', or a git commit SHA (7-40 hex characters)"
29+
expression: "this.matches('^(v\\\\d+\\\\.\\\\d+\\\\.\\\\d+.*|master|[a-f0-9]{7,40})$')"
30+
}
31+
];
32+
bool force_rebuild = 3 [(buf.validate.field).required = false];
33+
// target platform is required and must be a valid platform. Used to specify the platform for the build (host platform used by default)
34+
Platform target_platform = 4 [(buf.validate.field).required = false];
35+
// plugins are required and represent the list of plugins to be used for the build
36+
repeated Plugin plugins = 5 [(buf.validate.field).required = true];
37+
}
38+
39+
message Plugin {
40+
// module name in a Go module format, for example: "github.com/roadrunner-server/velox" or "github.com/roadrunner-server/velox/v2"
41+
string module_name = 1 [(buf.validate.field).required = true];
42+
// plugin github tag
43+
string tag = 2 [(buf.validate.field).required = true];
44+
}

‎api/response/v1/response.proto

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
syntax = "proto3";
2+
3+
package api.response.v1;
4+
5+
option go_package = "github.com/roadrunner-server/velox/v2025/gen/go/api/response/v1;responseV1";
6+
7+
message BuildResponse {
8+
string path = 1;
9+
string logs = 2;
10+
}

‎api/service/v1/service.proto

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
syntax = "proto3";
2+
3+
package api.service.v1;
4+
5+
import "api/request/v1/request.proto";
6+
import "api/response/v1/response.proto";
7+
8+
option go_package = "github.com/roadrunner-server/velox/v2025/gen/go/api/service/v1;serviceV1";
9+
10+
service BuildService {
11+
rpc Build(api.request.v1.BuildRequest) returns (api.response.v1.BuildResponse);
12+
}

‎buf.gen.yaml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: v2
2+
plugins:
3+
- remote: buf.build/protocolbuffers/go:v1.36.7
4+
out: gen/go
5+
opt: paths=source_relative
6+
- remote: buf.build/grpc/go:v1.5.1
7+
out: gen/go
8+
opt:
9+
- paths=source_relative
10+
- require_unimplemented_servers=false
11+
- remote: buf.build/bufbuild/connect-go:v1.10.0
12+
out: gen/go
13+
opt:
14+
- paths=source_relative

‎buf.lock

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Generated by buf. DO NOT EDIT.
2+
version: v2
3+
deps:
4+
- name: buf.build/bufbuild/protovalidate
5+
commit: 6c6e0d3c608e4549802254a2eee81bc8
6+
digest: b5:a7ca081f38656fc0f5aaa685cc111d3342876723851b47ca6b80cbb810cbb2380f8c444115c495ada58fa1f85eff44e68dc54a445761c195acdb5e8d9af675b6

‎buf.yaml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
version: v2
2+
deps:
3+
- buf.build/bufbuild/protovalidate:v0.14.2
4+
5+
name: buf.build/roadrunner-server/velox
6+
lint:
7+
use:
8+
- STANDARD
9+
except:
10+
- FIELD_NOT_REQUIRED
11+
- PACKAGE_NO_IMPORT_CYCLE
12+
breaking:
13+
use:
14+
- FILE
15+
except:
16+
- EXTENSION_NO_DELETE
17+
- FIELD_SAME_DEFAULT

0 commit comments

Comments
 (0)