README

PAM Octane

Laravel Octane lifecycle, powered by Rust and Tokio.

Connect PAM's native HTTP transport to Octane while Octane keeps ownership of Laravel isolation and worker lifecycle.

Documentation · Why this exists · What you can build · Quick start · Issues

Why this exists

Connect PAM's native HTTP transport to Octane while Octane keeps ownership of Laravel isolation and worker lifecycle.


Role	Octane server adapter
Execution path	PAM Runtime · Laravel Octane
This repository owns	Transport bridge and PAM server integration
Boundary	Octane remains the lifecycle authority; this is not a Laravel fork

What you can build

Existing Octane applications on PAM transport
High-throughput Laravel services
Rust-served opt-in public response caching with safe bypass rules

Quick start

pam composer require laravel/octane pushinbr/pam-octane
pam octane:start

The PAM documentation covers prerequisites, production setup, and the complete workflow. PAM projects keep normal manifests and lockfiles; product features stay in the package that owns them.

PAM Octane connects PAM's native HTTP transport directly to Laravel Octane's worker. Octane continues to own application isolation, lifecycle events and request cleanup; PAM owns PHP Embed, networking, streaming, supervision and Tokio-powered infrastructure.

HTTP → PAM / Tokio → PamClient → Octane Worker → Laravel
HTTP ← PAM / Tokio ← PamClient ← Octane Worker ← Laravel

Why this bridge exists

PAM already embeds PHP and provides a persistent native HTTP runtime. This package deliberately does not duplicate Octane's Laravel lifecycle. It adapts PAM's request and response objects to Octane's public Client contract and then uses the real Laravel\Octane\Worker.

That gives an application:

one warm Laravel application per worker;
Octane's request sandbox and lifecycle events;
PAM's bounded streaming and client backpressure;
correct cookies, uploads, HEAD, streamed and binary responses;
one safe Laravel execution slot per worker;
normal Laravel package discovery and configuration.

Configure

The defaults are production-safe and require no configuration. To customize limits, publish the small configuration file:

pam artisan vendor:publish --tag=pam-octane-config

Environment variables include:

PAM_HOST=127.0.0.1
PAM_PORT=8000
PAM_REQUEST_TIMEOUT_MS=30000
PAM_MAX_BODY_BYTES=2097152
PAM_MAX_RESPONSE_BYTES=268435456

maxConcurrentRequests is intentionally fixed to 1 for Laravel. Framework managers and facades contain process-global mutable state. Scale safely with multiple supervised PAM workers instead of overriding that boundary.

Production

The package owns the Octane bridge; the PAM binary owns process supervision. For a supervised production cluster, run Artisan as the worker entrypoint:

pam start artisan \
  --workers 8 \
  --max-requests 100000 \
  --admin-address 127.0.0.1:3010 \
  -- pam:octane --host=0.0.0.0 --port=8000

PAM then provides crash recovery, health checks, worker recycling and generational SIGHUP reloads. Queue workers, Horizon and the scheduler remain separate supervised processes.

For systemd, copy the hardened pam-octane.service unit and place deployment-specific values in /etc/pam/pam-octane.env. The unit binds application HTTP to loopback and keeps the control plane on 127.0.0.1:3010 by default.

Workloads with different latency or memory profiles can run in isolated pools:

pam octane:start \
  --ingress-address=0.0.0.0:8000 \
  --pool=api=8@/api,/graphql \
  --pool=web=4@* \
  -- --host=0.0.0.0 --port=8000

The Rust ingress streams HTTP and WebSocket traffic, uses segment-aware longest prefix routing, and keeps each pool's Laravel container, PHP heap, OPcache and restart boundary independent. Exactly one * fallback is required. Terminate TLS/HTTP3 at the edge when pools are enabled; internal traffic is loopback-only.

Compatibility

The maintained matrix is:

PHP	Laravel	Octane
8.5 (default)	12.x	2.19+
8.5 (default)	13.x	2.19+
8.4 (supported)	12.x	2.19+
8.4 (supported)	13.x	2.19+

PAM Octane requires the PAM runtime. Running php artisan pam:octane reports a clear error because ordinary PHP CLI does not contain PAM's native server.

Troubleshooting

Run these commands from the Laravel project root before opening a report:

pam --version
pam doctor .
pam artisan about
pam octane:status

If the package reports that the PAM runtime is missing, replace php artisan with pam artisan or use pam octane:start.
If a worker grows after repeated requests, reproduce with one worker, inspect request-scoped singletons and run the soak contract before lowering --max-requests.
If requests stall, identify blocking PDO, filesystem, HTTP or extension calls; use PAM's cooperative clients, an isolated process pool or additional workers.
If a reverse proxy cannot connect, keep the PAM listener private but bind it to the interface reachable by that proxy. Never expose the admin listener publicly.

Sanitize diagnostics: remove credentials, cookies, authorization headers, private URLs and application data.

Quality

composer verify

The suite checks request marshalling, output buffers, repeated headers, cookies, streaming, HEAD, package discovery and invalid context handling. Integration tests in the PAM repository cover the native transport and Laravel runtime.

Runtime capabilities

generational reload, status, stop and control-plane health;
route-aware worker pools with crash and memory isolation;
cooperative Fiber scheduling and HTTP/Redis clients;
isolated bounded PDO and process pools for blocking work;
production response cache with tags, authenticated invalidation, collapse and stale-while-revalidate;
bounded route metrics plus Pulse, Telescope and OpenTelemetry integration.

PAM Octane is Apache-2.0 licensed.

Usage questions belong in PAM GitHub Discussions. Reproducible defects use the main PAM issue tracker, and vulnerabilities must use private GitHub Security Advisories as described in SECURITY.md.

Repository model

PAM Octane is developed in packages/octane alongside the runtime so transport and lifecycle changes can be tested atomically. It remains an independent, optional Composer package: applications that do not use Laravel or Octane do not install it.

pushinbr / pam-octane

Maintainers

Package info

Statistics

Security