README

RoadRunner worker adapter for the PilotPHP Agent-First framework.

pilotphp/runtime-roadrunner connects long-lived RoadRunner HTTP and gRPC worker processes to PilotPHP transport applications (HttpApplication, GrpcApplication). It owns the receive/respond loop, process boot/shutdown gate, transport ports, and worker error/recycle policy. It does not compile artifacts, assemble the application container, or dispatch operations directly.

Requirements

PHP 8.5+
pilotphp/contracts ^0.1.2
pilotphp/runtime ^0.1.2
pilotphp/http ^0.1.4
pilotphp/grpc ^0.1.4
Spiral RoadRunner worker packages (spiral/roadrunner-http, spiral/roadrunner-grpc, spiral/roadrunner-worker)

Install

composer require pilotphp/runtime-roadrunner

Discovery uses the fixed path pilot/package.json inside the Composer package root. This package does not publish extra.pilotphp.manifest.

Note: pilotphp/http and pilotphp/grpc may not yet be on Packagist. See docs/blockers.md for local development workarounds.

Modes

Mode	Worker loop	Transport application	Reset owner
HTTP	`RoadRunnerHttpWorkerLoop`	`HttpApplication`	`HttpApplication`
gRPC	`RoadRunnerGrpcWorkerLoop`	`GrpcApplication`	`HostRequestCycle` + `InvokeTrackingKernel`

Each mode uses a separate RoadRunner worker entry script and .rr.yaml plugin section. See examples/ and docs/rr-configuration.md.

Bootstrap sketch

Build and artifact loading happen outside this package. The application owns composition; the worker only loads finalized bytes and runs the loop.

# Build time (CI / deploy, NOT in worker)
php bin/pilot build
  → finalized artifacts (http/route-map.json, grpc/method-map.json, container, …)

# Worker boot (application bootstrap)
require vendor/autoload.php
  → App\RuntimeAssembler loads artifact bytes
  → constructs ContainerInterface, KernelInterface, transport apps
  → wraps kernel with InvokeTrackingKernel (gRPC only)
  → RoadRunnerHttpWorkerLoop or RoadRunnerGrpcWorkerLoop::run()

Who does what:

Concern	Owner
Build (`php bin/pilot build`)	Application / `pilotphp/build`
Load artifact bytes	Application bootstrap
Assemble `RuntimeKernel`, container, dispatch graph	Application / `RuntimeAssembler`
Boot / shutdown	`WorkerLifecycle` via `WorkerProcessGate`
Per-request reset (HTTP)	`HttpApplication`
Per-request reset (gRPC)	`HostRequestCycle` + `InvokeTrackingKernel`
Receive/respond loop	This package

Non-goals

Running pilotphp/build or any build stage inside a worker
Depending on pilotphp/operation, pilotphp/container, or pilotphp/app
Registering compile-time metadata (register() is intentionally empty)
Publishing a BuildStage or finalized artifact schema
Replacing HttpApplication / GrpcApplication routing or mapping logic
Using Spiral\RoadRunner\GRPC\Server reflection-based service registration

Public API (summary)

Type	Role
`RoadRunnerRuntimePackage`	Package identity; empty `register()`
`RoadRunnerHttpWorkerLoop`	HTTP wait → handle → respond loop
`RoadRunnerGrpcWorkerLoop`	gRPC wait → decode → handle → respond loop
`RoadRunnerHttpWorkerPort`	Production HTTP transport port
`RoadRunnerGrpcWorkerPort`	Production gRPC payload port (no `Server::registerService`)
`WorkerProcessGate`	Boot once, job counting, recycle, shutdown
`HostRequestCycle`	gRPC per-job scope + reset (HTTP must not use this)
`InvokeTrackingKernel`	Required gRPC kernel decorator
`RoadRunnerWorkerOptions`	Adapter recycle and error policy
`WorkerExitCode`	Process exit outcome enum

Documentation

Examples

Illustrative worker entry scripts and minimal RoadRunner configs:

Examples are not executable application skeletons — they show bootstrap shape with placeholder App\RuntimeAssembler comments.

License

MIT

pilotphp / runtime-roadrunner

Maintainers

Package info

Statistics

Security