README

A high-performance, low-memory process manager and queue runner for Laravel, powered by a lightweight Rust daemon.

Replace heavy, persistent, long-running PHP worker processes (which consume ~50MB – 200MB+ RAM each 24/7) with a single Rust worker daemon that consumes under 5MB of RAM when idle.

⚡ How it Works

Instead of running standard PHP queue workers that stay booted in memory waiting for jobs, this package runs a pre-compiled Rust daemon:

1. Lightweight Idle State: The Rust daemon connects to your Redis queue and uses blocking pops (BLPOP) to wait for jobs. Idle memory footprint is under 5MB.
2. On-Demand PHP Execution: When a job arrives, Rust pops it and spawns php artisan rust-worker:execute as a short-lived process.
3. Secure stdin Piping: Rust writes the job payload directly to the PHP process via stdin. This avoids shell escaping vulnerabilities and command length limitations.
4. Immediate Memory Release: Once the job finishes, the PHP process terminates immediately, releasing 100% of its memory back to the OS.
5. Robust Retries & Failure Logging:
   • Failed jobs are automatically retried by Rust after a 5-second backoff (placed in the Redis delayed set).
   • Once a job exceeds its maximum retries, the final run sets a final flag, triggering Laravel's native event listeners to write it to the failed_jobs table.

📦 Installation

Step 1: Install via Composer

You can install this package in any Laravel project via Composer:

composer require malak4web/laravel-rust-queue

Step 2: Publish Configuration

Publish the package configuration file:

php artisan vendor:publish --provider="Malak\LaravelRustQueue\RustQueueServiceProvider"

This creates config/rust-queue.php in your application.

🚀 Running the Worker

To start the Rust worker daemon:

php artisan rust-worker:start

This Artisan command will automatically detect your operating system and CPU architecture, find the correct pre-compiled binary inside the package's bin/ directory, and launch it.

Production Setup (Supervisor)

In production, run the pre-compiled binary directly or supervise the Artisan command. Here is an example Supervisor configuration:

[program:laravel-rust-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/forge/app.com/artisan rust-worker:start
autostart=true
autorestart=true
user=forge
numprocs=1
redirect_stderr=true
stdout_logfile=/home/forge/app.com/storage/logs/rust-worker.log
stopwaitsecs=3600

⚙️ Configuration (config/rust-queue.php)

return [
    // The connection name from config/queue.php to listen to
    'connection' => env('RUST_QUEUE_CONNECTION', 'redis'),

    // The queue name to monitor
    'queue' => env('RUST_QUEUE_NAME', 'default'),

    // Path to the directory containing pre-compiled binaries
    'bin_path' => env('RUST_QUEUE_BIN_PATH', base_path('vendor/malak/laravel-rust-queue/bin')),

    // PHP binary used to run the artisan command
    'php_path' => env('RUST_QUEUE_PHP_PATH', PHP_BINARY),

    // Path to the Laravel artisan script
    'artisan_path' => env('RUST_QUEUE_ARTISAN_PATH', base_path('artisan')),
];

🛠️ Compiling Binaries Manually

The package comes pre-compiled with optimized binaries for Windows, macOS, and Linux in the bin/ directory. If you make modifications to the Rust daemon, you can compile it yourself:

1. Navigate to the rust/ folder:

   cd packages/laravel-rust-queue/rust

2. Build the release binary:

   cargo build --release

3. Locate the compiled executable under target/release/rust-worker and copy it to the package's bin/ folder.