{"id":34611201,"url":"https://github.com/roadrunner-plugins/velox-middleware","last_synced_at":"2026-05-27T11:39:04.868Z","repository":{"id":324011868,"uuid":"1095522612","full_name":"roadrunner-plugins/velox-middleware","owner":"roadrunner-plugins","description":"HTTP middleware plugin that intercepts Velox binary build requests from PHP workers, manages intelligent caching with LRU eviction, and streams binaries directly to clients without blocking expensive PHP worker processes.","archived":false,"fork":false,"pushed_at":"2025-11-13T09:50:44.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-13T11:22:13.575Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roadrunner-plugins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T06:55:18.000Z","updated_at":"2025-11-13T09:50:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/roadrunner-plugins/velox-middleware","commit_stats":null,"previous_names":["roadrunner-plugins/velox-middleware"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/roadrunner-plugins/velox-middleware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-plugins%2Fvelox-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-plugins%2Fvelox-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-plugins%2Fvelox-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-plugins%2Fvelox-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roadrunner-plugins","download_url":"https://codeload.github.com/roadrunner-plugins/velox-middleware/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-plugins%2Fvelox-middleware/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28003726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T14:13:33.660Z","updated_at":"2025-12-24T14:14:51.775Z","avatar_url":"https://github.com/roadrunner-plugins.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Velox Middleware Plugin\n\nA RoadRunner middleware plugin that offloads Velox binary builds from PHP workers to Go, enabling non-blocking builds\nwith direct file streaming to clients.\n\n## Overview\n\nThe Velox middleware plugin intercepts HTTP responses from PHP workers that contain build requests, immediately releases\nthe worker, delegates the build to a Velox server, and streams the resulting binary directly to the HTTP client.\n\n## Features\n\n- **Non-blocking PHP Workers**: Workers are freed immediately after sending build parameters (\u003c 100ms vs ~60s)\n- **Binary Caching**: SHA-256 content-based caching with configurable size, count, and age limits\n- **Smart Eviction**: Multiple eviction policies (LRU, LFU, FIFO) for optimal cache management\n- **Direct File Streaming**: Binaries stream directly from filesystem to client using efficient 10MB chunking\n- **Retry Logic**: Configurable exponential backoff for Velox server communication\n- **Context Propagation**: Client disconnects properly cancel ongoing builds\n- **Security**: Path traversal protection for file streaming\n- **Efficient Buffering**: Smart buffer allocation based on file size\n\n## Configuration\n\nAdd to your `.rr.yaml`:\n\n```yaml\nhttp:\n  address: '0.0.0.0:8080'\n  middleware:\n    - velox // Register middleware\n\nvelox:\n  # Velox build server endpoint (required)\n  server_url: \"http://127.0.0.1:9000\"\n\n  # Build timeout - maximum time to wait for build completion (default: 5m)\n  build_timeout: \"5m\"\n\n  # Request timeout - HTTP timeout for Velox communication (default: 180s)\n  request_timeout: \"180s\"\n\n  # Retry configuration\n  retry:\n    # Maximum retry attempts (default: 3)\n    max_attempts: 3\n\n    # Initial delay before first retry (default: 1s)\n    initial_delay: \"1s\"\n\n    # Maximum delay between retries (default: 10s)\n    max_delay: \"10s\"\n\n    # Backoff multiplier for exponential backoff (default: 2.0)\n    backoff_multiplier: 2.0\n\n  # Binary cache configuration (optional)\n  cache:\n    # Enable caching (default: false)\n    enabled: true\n\n    # Cache directory (default: ./cache/velox)\n    directory: \"/var/cache/velox\"\n\n    # Maximum total cache size in GB, 0 = unlimited (default: 0)\n    max_size_gb: 50\n\n    # Maximum number of cached binaries, 0 = unlimited (default: 0)\n    max_entries: 1000\n\n    # Maximum age for cache entries in days, 0 = never expire (default: 0)\n    max_age_days: 30\n\n    # Cleanup interval, 0 = disabled (default: 1h)\n    cleanup_interval: \"1h\"\n\n    # Eviction policy: lru, lfu, or fifo (default: lru)\n    eviction_policy: \"lru\"\n\n    # Access metadata update interval, 0 = immediate (default: 5m)\n    access_update_interval: \"5m\"\n```\n\n### Configuration Options\n\n#### Server Configuration\n\n- **`server_url`** (required): Velox build server endpoint URL\n- **`build_timeout`**: Maximum time to wait for build completion (default: 5m)\n- **`request_timeout`**: HTTP timeout for Velox communication (default: 180s)\n\n#### Retry Configuration\n\n- **`max_attempts`**: Maximum number of retry attempts (default: 3)\n- **`initial_delay`**: Initial delay before first retry (default: 1s)\n- **`max_delay`**: Maximum delay between retries (default: 10s)\n- **`backoff_multiplier`**: Exponential backoff multiplier (default: 2.0)\n\n#### Cache Configuration\n\n- **`enabled`**: Enable or disable binary caching (default: false)\n- **`directory`**: Directory for cached binaries (default: ./cache/velox)\n- **`max_size_gb`**: Maximum total cache size in gigabytes, 0 = unlimited (default: 0)\n- **`max_entries`**: Maximum number of cached binaries, 0 = unlimited (default: 0)\n- **`max_age_days`**: Maximum age for cache entries in days, 0 = never expire (default: 0)\n- **`cleanup_interval`**: How often to run cache cleanup, 0 = disabled (default: 1h)\n- **`eviction_policy`**: Strategy for cache eviction (default: lru)\n    - `lru`: Least Recently Used - removes entries that haven't been accessed in the longest time\n    - `lfu`: Least Frequently Used - removes entries with the lowest access count\n    - `fifo`: First In First Out - removes the oldest created entries first\n- **`access_update_interval`**: How often to update access statistics, 0 = immediate (default: 5m)\n    - Higher values reduce disk I/O but access tracking is less accurate\n\n## PHP Integration\n\n### Triggering a Velox Build\n\nFrom your PHP worker, return a response with the `X-Velox-Build` header and a JSON payload:\n\n```php\n\u003c?php\n\nuse Spiral\\RoadRunner\\Http\\Request;\nuse Spiral\\RoadRunner\\Http\\Response;\n\n// Build request parameters\n$buildRequest = [\n    'request_id' =\u003e 'b66d5617-64dd-419b-a68b-b002938320ab',\n    'target_platform' =\u003e [\n        'os' =\u003e 'windows',\n        'arch' =\u003e 'amd64',\n    ],\n    'rr_version' =\u003e 'v2025.1.2',\n    'plugins' =\u003e [\n        [\n            'module_name' =\u003e 'github.com/roadrunner-server/http/v5',\n            'tag' =\u003e 'v5.2.7',\n        ],\n        [\n            'module_name' =\u003e 'github.com/roadrunner-server/grpc/v5',\n            'tag' =\u003e 'v5.1.0',\n        ],\n    ],\n];\n\n// Return response with Velox header\nreturn new Response(\n    status: 200,\n    headers: [\n        'X-Velox-Build' =\u003e 'true',\n        'Content-Type' =\u003e 'application/json',\n    ],\n    body: json_encode($buildRequest)\n);\n```\n\n### Response Flow\n\n1. PHP worker sends response with `X-Velox-Build` header\n2. Velox middleware intercepts the response\n3. Worker is immediately released back to the pool\n4. **Middleware checks cache for matching build**\n5. **If cache hit**: Binary streams immediately from cache (~10ms)\n6. **If cache miss**: Middleware sends build request to Velox server\n7. Velox server builds the binary and returns file path\n8. Binary is stored in cache (async, non-blocking)\n9. Middleware streams binary directly to HTTP client\n\n## Binary Caching\n\n### How It Works\n\nThe cache system uses **content-based hashing** to identify identical builds:\n\n1. **Hash Calculation**: A SHA-256 hash is computed from:\n    - RoadRunner version\n    - Target platform (OS + architecture)\n    - All plugins (sorted by module name and tag)\n\n2. **Cache Lookup**: On build request, the hash is calculated and checked against cached entries\n\n3. **Cache Storage**: Successful builds are stored with paired files:\n    - `{hash}.bin` - The binary file\n    - `{hash}.json` - Metadata (creation time, access stats, build info)\n\n4. **Cache Management**: Periodic cleanup enforces size, count, and age limits using the configured eviction policy\n\n### Cache Storage Structure\n\n```\n/var/cache/velox/\n├── a3f5b8c9d2e1...f9a0.bin     # Cached binary\n├── a3f5b8c9d2e1...f9a0.json    # Metadata\n├── b4c6d9e1f2a3...a1b2.bin\n└── b4c6d9e1f2a3...a1b2.json\n```\n\n### Metadata Example\n\n```json\n{\n  \"version\": \"1.0\",\n  \"hash\": \"a3f5b8c9d2e1f4a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0\",\n  \"binary_file\": \"a3f5b8c9d2e1...f9a0.bin\",\n  \"file_size\": 45678912,\n  \"rr_version\": \"2024.1.0\",\n  \"platform\": {\n    \"os\": \"linux\",\n    \"arch\": \"amd64\"\n  },\n  \"plugins\": [\n    {\n      \"module_name\": \"github.com/roadrunner-server/http/v5\",\n      \"tag\": \"v5.2.7\"\n    }\n  ],\n  \"created_at\": 1699889234,\n  \"last_accessed\": 1699989234,\n  \"access_count\": 15,\n  \"build_duration_ms\": 45000\n}\n```\n\n### Cache Performance\n\n- **Cache Hit**: ~10ms (file stat + metadata load)\n- **Cache Miss**: ~60s (Velox build time)\n- **Cache Speedup**: ~6000x faster for cached builds\n- **Memory Overhead**: ~2KB per cached entry (metadata)\n- **Disk Usage**: Depends on binary sizes (typically 40-80MB per binary)\n\n### Cache Eviction Strategies\n\n**LRU (Least Recently Used)** - Default, recommended for most use cases\n\n- Keeps frequently accessed builds in cache\n- Good for environments with recurring build patterns\n\n**LFU (Least Frequently Used)**\n\n- Prioritizes builds that are accessed many times\n- Best for identifying truly popular builds vs one-time requests\n\n**FIFO (First In First Out)**\n\n- Simplest strategy, removes oldest entries\n- Predictable behavior but may evict frequently-used entries\n\n### Cache Safety\n\n- **Atomic Operations**: All writes use temp file + atomic rename\n- **Graceful Degradation**: Cache failures never block build requests\n- **No Lock Contention**: Each binary has independent metadata file\n- **Orphan Cleanup**: Automatic removal of binaries without metadata\n- **Corruption Handling**: Corrupted metadata files are automatically removed\n\n## Protocol\n\n### Build Request Format\n\n```json\n{\n  \"request_id\": \"b66d5617-64dd-419b-a68b-b002938320ab\",\n  \"target_platform\": {\n    \"os\": \"windows\",\n    \"arch\": \"amd64\"\n  },\n  \"rr_version\": \"v2025.1.2\",\n  \"plugins\": [\n    {\n      \"module_name\": \"github.com/roadrunner-server/http/v5\",\n      \"tag\": \"v5.2.7\"\n    }\n  ]\n}\n```\n\n### Velox Server Response Format\n\n**Success:**\n\n```json\n{\n  \"success\": true,\n  \"path\": \"/tmp/velox/builds/roadrunner-windows-amd64-abc123.exe\",\n  \"build_id\": \"abc123def456\",\n  \"duration_ms\": 58234\n}\n```\n\n**Failure:**\n\n```json\n{\n  \"success\": false,\n  \"error\": \"failed to compile plugin: github.com/invalid/plugin\",\n  \"code\": \"BUILD_ERROR\"\n}\n```\n\n## Architecture\n\n### Request Flow\n\n```\n┌──────────┐     ┌──────────┐     ┌────────┐     ┌───────┐\n│  Client  │────▶│ RR HTTP  │────▶│  PHP   │────▶│ Velox │\n│          │     │          │     │ Worker │     │Plugin │\n└──────────┘     └──────────┘     └────────┘     └───────┘\n                                       │              │\n                                       │Released      │Cache Check\n                                       │immediately   │     │\n                                       ▼              ▼     ▼\n                                  ┌──────────────────────────┐\n                                  │  Cache Hit?              │\n                                  └──────────────────────────┘\n                                       │              │\n                                  Yes  │              │ No\n                                       ▼              ▼\n                                  ┌────────┐   ┌──────────┐\n                                  │ Stream │   │  Build   │\n                                  │ Cached │   │  with    │\n                                  │ Binary │   │  Velox   │\n                                  └────────┘   └──────────┘\n                                                     │\n                                                     ▼\n                                                ┌────────┐\n                                                │ Store  │\n                                                │  in    │\n                                                │ Cache  │\n                                                └────────┘\n                                                     │\n                                                     ▼\n                                                ┌────────┐\n                                                │ Stream │\n                                                │ Binary │\n                                                └────────┘\n```\n\n### Key Design Decisions\n\n**Binary Caching**: SHA-256 content-based hashing ensures identical builds are never rebuilt unnecessarily.\n**Per-Binary Metadata**: Independent JSON files eliminate lock contention and enable concurrent cache operations.\n**Writer Pooling**: Response writers are pooled to reduce garbage collection pressure during high traffic.\n**Chunked Streaming**: Files are streamed in 10MB chunks with automatic flushing for progressive downloads.\n**Smart Buffer Allocation**: Small files use exact-size buffers, large files use fixed 10MB buffers to prevent memory\nspikes.\n**Context Propagation**: Client disconnects trigger context cancellation, aborting ongoing Velox requests and cache\noperations.\n**Retry with Backoff**: Failed Velox requests retry with exponential backoff up to configured maximum.\n**Batched Access Updates**: Access statistics are batched to minimize disk I/O on cache hits.\n\n## License\n\nMIT License - see LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froadrunner-plugins%2Fvelox-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froadrunner-plugins%2Fvelox-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froadrunner-plugins%2Fvelox-middleware/lists"}