README

Overview

Runiva integrates alternative server runtimes with the Glueful Framework — RoadRunner (default), (Open)Swoole, and FrankenPHP. It provides a unified command, environment‑driven configuration, and a PSR‑7 bridge to route HTTP requests through Glueful’s Application and Router.

Features

• ✅ RoadRunner worker and config (rr.yaml)
• ✅ PSR‑7 bridge auto‑detection (Nyholm + Symfony bridge)
• ✅ Single console entrypoint: runiva:serve
• ✅ Config‑driven via .env + merged config
• ✅ Composer discovery via extra.glueful.provider
• ⚙️ Stubs for Swoole and FrankenPHP server scripts

Requirements

• PHP 8.2+
• Glueful Framework ^1.6.2
• Optional (RoadRunner mode):
  • spiral/roadrunner (binary management + base worker)
  • spiral/roadrunner-http (PSR‑7 HTTP worker)
  • nyholm/psr7, symfony/psr-http-message-bridge (PSR‑7 <-> HttpFoundation)

Optional (Swoole/OpenSwoole mode):

• PHP extensions: ext-swoole or ext-openswoole (installed via PECL/package manager)

Installation

composer require glueful/runiva

RoadRunner (recommended for HTTP)

composer require spiral/roadrunner spiral/roadrunner-http nyholm/psr7 symfony/psr-http-message-bridge

Verify Installation

php glueful extensions:list
php glueful extensions:info Runiva
php glueful extensions:why Glueful\\Extensions\\Runiva\\RunivaServiceProvider

Getting Started

Configuration via .env (all optional; defaults provided):

• RUNIVA_RUNTIME=roadrunner|swoole|frankenphp
• RUNIVA_BINARY=rr (RoadRunner binary or absolute path)
• RUNIVA_CONFIG=vendor/glueful/runiva/rr.yaml
• RUNIVA_WORKERS=2
• RUNIVA_ADDRESS=:8080

Runiva merges defaults from config/runiva.php within the package. App‑level .env values override these. You can also create config/runiva.php in your app to hard‑set values.

Usage

Start the configured runtime:

php glueful runiva:serve

Validate configuration and environment without starting:

php glueful runiva:serve --check

Force a specific runtime:

php glueful runiva:serve --runtime=roadrunner
php glueful runiva:serve --runtime=swoole

RoadRunner uses the included rr.yaml by default:

server:
  command: "php vendor/glueful/runiva/bin/worker.php"
http:
  address: ":8080"
  pool:
    num_workers: 2

RoadRunner + PSR‑7 Bridge

With spiral/roadrunner-http, nyholm/psr7, and symfony/psr-http-message-bridge installed, the worker will:

• Receive PSR‑7 requests from RoadRunner
• Convert to Symfony HttpFoundation requests
• Dispatch through Glueful Application/Router
• Convert Symfony responses back to PSR‑7 and respond

RR worker lifecycle (simplified):

• Bootstrap Glueful once (Framework::create()->boot()).
• Loop: waitRequest() → convert PSR‑7 → handle → convert response → respond.
• On SIGTERM/SIGINT/SIGQUIT: exit loop and allow RR to stop workers gracefully.

watch plugin (dev hot‑reload) in rr.yaml:

plugins:
  watch:
    patterns: ["**.php", "rr.yaml"]
    ignore: ["vendor/**", "storage/**"]
    jobs: ["http"]

Swoole / FrankenPHP

Swoole/OpenSwoole:

• Install the extension: ext-swoole or ext-openswoole must be enabled in PHP.
• Start the server:

php glueful runiva:serve --runtime=swoole

FrankenPHP:

• Ensure the frankenphp binary is installed and on PATH, or set FRANKENPHP_BINARY to its full path.
• Start the server:

php glueful runiva:serve --runtime=frankenphp

Notes:

• The launcher generates a minimal Caddyfile and runs frankenphp run --config <tempfile>.
• It sets APP_ENV based on your environment; adjust RUNIVA_ADDRESS to change the listen address (default :8080).
• For production, prefer a full Caddy configuration with TLS, timeouts, and headers tuned for your deployment.

Production Caddyfile (example)

{
  # Global server options
  servers {
    timeouts {
      read_header 10s
      read_body   30s
      write       30s
      idle        2m
    }
    trusted_proxies private_ranges
  }
}

example.com {
  # ACME/Let’s Encrypt or email for zero‑config certificates
  tls you@example.com

  # Serve static assets efficiently
  encode zstd gzip

  # Path to your app’s public directory
  root * /var/www/public

  # Security headers (adjust CSP for your frontend needs)
  header {
    Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    X-Frame-Options "SAMEORIGIN"
    X-Content-Type-Options "nosniff"
    Referrer-Policy "no-referrer"
    X-XSS-Protection "0"
    Content-Security-Policy "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'"
  }

  # Long‑cache immutable assets
  @static {
    file
    path *.css *.js *.png *.jpg *.jpeg *.svg *.ico *.woff *.woff2 *.ttf *.map
  }
  handle @static {
    header Cache-Control "public, max-age=31536000, immutable"
    file_server
  }

  # PHP application served by FrankenPHP
  handle {
    php_server {
      # Optional tuning
      # worker 4
      env APP_ENV=production
      env APP_DEBUG=0
    }
  }

  # Structured access logs
  log {
    output stdout
    format json
  }
}

Adjust example.com, root, and header policies to your needs. For multi‑app setups, define multiple site blocks or use handle_path to mount sub‑apps.

Hot‑Reload

• RoadRunner: enable the watch plugin in rr.yaml or run with rr --watch during development to auto‑reload workers on file changes.
• Swoole/OpenSwoole: send SIGUSR1 to the master PID to reload workers gracefully (kill -USR1 <master_pid>), or use a file‑watcher script to trigger reloads.
• FrankenPHP: restart the frankenphp run process (or reload Caddy) after code changes.

Graceful Shutdown

• RoadRunner: Runiva’s worker handles SIGTERM/SIGINT and exits loops cleanly.
• Swoole/OpenSwoole: hooks registered for shutdown and workerStop events for orderly teardown.
• FrankenPHP: process termination is handled by the launcher/Caddy; no extra hooks required.

Troubleshooting

• Changes to .env and configs require a RoadRunner restart (hot workers persist state).
• If the worker logs that PSR‑7 bridge is unavailable, install:
  • spiral/roadrunner spiral/roadrunner-http nyholm/psr7 symfony/psr-http-message-bridge
• Ensure rr is installed and on PATH, or set RUNIVA_BINARY to an absolute path.

Health & Readiness

Glueful exposes server‑agnostic health endpoints you can rely on in any runtime:

• GET /healthz — liveness check (200 OK when the process is up)
• GET /ready — readiness check (dependencies ready; secured via IP allowlist middleware by default)
• GET /health — full health suite root with sub‑routes (database, cache, middleware, response‑api, queue)

Examples (enable/adjust per your env/security):

• GET /health/database — DB connectivity and migrations status
• GET /health/cache — cache connectivity and basic operations
• GET /health/detailed — extended metrics (auth required)
• GET /health/middleware — middleware pipeline health (auth required)
• GET /health/response-api — response API health (auth required)
• GET /health/queue — queue stats and worker activity

Runiva is designed to be minimal and composable. Start with RoadRunner and PSR‑7 for full HTTP performance, then layer in Swoole or FrankenPHP as needed.