RoadRunner 概要とアーキテクチャ

RoadRunner は、Go 言語で構築された高性能な PHP アプリケーションサーバーおよびプロセスマネージャーです。従来の PHP-FPM とは異なり、アプリケーションをワーカープロセスとして常驻メモリ上で実行することで、フレームワークのブートストラップ時間を排除し、処理速度を劇的に向上させます。

このサーバーは、HTTP リクエストだけでなく、キュー、gRPC、または AWS Lambda など、さまざまなトリガーからデータを受け取ることが可能です。Go 側のランタイムが Goroutine を利用して負荷分散を行い、PHP ワーカー間で効率的にジョブを処理します。

主要な特徴

• 永続メモリ: ワーカーはリクエスト間で生存するため、データベース接続やキャッシュなどのリソースを再利用できます。
• プロトコル対応: HTTP/1.1、HTTP/2、HTTPS、FastCGI をネイティブでサポートしています。
• 拡張性: Prometheus によるメトリクス収集、健康チェック、自動リロード機能を備えています。
• ワークフローエンジン: Temporal.io と統合し、耐久性のあるワークフロー実行を可能にします。
• フレームワーク統合: Laravel、Symfony、Spiral などの主要 PHP フレームワークと互換性があります。

インストール方法

RoadRunner はクロスプラットフォーム対応であり、Linux、macOS、Windows および FreeBSD で動作します。導入には主に以下の 3 つの方法があります。

1. Composer によるインストール

PHP プロジェクトに組み込む場合、Composer パッケージを利用するのが最も簡単です。以下のコマンドで依存関係を追加し、バイナリを取得します。

$ composer require spiral/roadrunner
$ ./vendor/bin/rr get-binary

これにより、プロジェクトルートに実行可能ファイルが配置されます。なお、自動ダウンロードには php-curl および php-zip 拡張機能が必要です。

2. 事前構築バイナリの利用

GitHub のリリースページから、OS に適したコンパイル済みバイナリを直接ダウンロードすることもできます。環境変数 PATH に通すことで、グローバルコマンドとして利用可能になります。

3. ソースからのビルド

Go 1.13 以上の環境があれば、ソースコードから独自にビルドできます。カスタム機能が必要な場合に有効です。

$ go mod download
$ make build
$ make test

設定ファイルの構成

RoadRunner の動作は、プロジェクトルートに配置される設定ファイル（.rr.yaml または .rr.json）によって制御されます。各プラグインごとにセクションが分かれており、必要な機能だけを有効化することができます。

最小構成例

HTTP サーバーとして動作させるための最小限の設定は以下の通りです。ポート番号やワーカー数は環境に合わせて調整してください。

rpc:
  listen: tcp://127.0.0.1:6005

server:
  command: "php bin/bootstrap.php"
  relay: pipes

http:
  address: 0.0.0.0:9000
  pool:
    num_workers: 8
    max_jobs: 100
    allocate_timeout: 60s
    destroy_timeout: 60s

主要設定項目の詳細

本番環境では、ログ出力、SSL 設定、スーパーバイザー機能などを詳細に定義する必要があります。

サーバープロセス管理

server セクションでは、ワーカーの起動コマンドや実行ユーザーを指定します。メモリリークを防ぐために、ワーカーの生存時間やメモリ使用量の制限を設定することが推奨されます。

server:
  command: "php bin/worker.php"
  user: "www-data"
  group: "www-data"
  env:
    APP_ENV: "production"
  relay: tcp://127.0.0.1:6005
  relay_timeout: 30s

HTTP プラグインとミドルウェア

HTTP リクエストの処理設定です。静的ファイルの提供や、Gzip 圧縮、ヘッダー操作などのミドルウェアをチェーンで定義できます。

http:
  address: ":8080"
  max_request_size: 128
  middleware: ["gzip", "static", "headers"]
  uploads:
    dir: "/var/cache/uploads"
    forbid: [".php", ".sh", ".exe"]
  static:
    dir: "./public"
    forbid: [".htaccess"]
  pool:
    num_workers: 4
    supervisor:
      max_worker_memory: 256
      exec_ttl: 120s

ログ設定

ログレベルや出力形式をプラグインごとに細かく制御できます。本番環境では JSON 形式での出力が推奨されます。

logs:
  mode: production
  level: info
  encoding: json
  output: stderr
  channels:
    http:
      level: warn
      encoding: json

運用と拡張機能

環境変数の利用

設定ファイル内で環境変数を参照することで、コンテナ環境などでの柔軟な設定変更が可能になります。

http:
  pool:
    num_workers: ${RR_WORKERS_COUNT}

CLI オプションによるオーバーライド

起動時に -o フラグを使用すると、設定ファイルの値を一時的に上書きできます。これは CI/CD パイプラインやテスト環境で有用です。

$ rr serve -o http.address=:9090 -o http.pool.num_workers=2

自動リロード機能

開発モードでは、PHP ファイルの変更を検知してワーカーを自動的に再起動する機能を利用できます。これにより、サーバーの再起動なしでコード変更を反映できます。

reload:
  interval: 1s
  patterns: [".php", ".yaml"]
  services:
    http:
      dirs: ["./src"]
      ignore: ["vendor", "cache"]

メトリクスと健康チェック

Prometheus 形式のメトリクスを公開するエンドポイントや、ロードバランサー向けの健康チェックエンドポイントを用意できます。

metrics:
  address: "127.0.0.1:2112"
  collect:
    app_requests:
      type: counter
      help: "Total requests processed"

status:
  address: "127.0.0.1:2114"
  unavailable_status_code: 503

Temporal ワークフロー

分散システム向けのワークフローエンジンである Temporal と連携する場合、以下の設定でアクティビティプールを定義します。

temporal:
  address: "127.0.0.1:7233"
  activities:
    num_workers: 4
    max_jobs: 32
    supervisor:
      max_worker_memory: 512
      exec_ttl: 300s