malak4web/laravel-rust-queue

A high-performance, low-memory Laravel queue worker runner powered by a Rust daemon.

dev-main 2026-06-25 12:01 UTC

Requires

• php: ^8.2
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/queue: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

MIT

• Malak

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

The queue worker daemon must run persistently in the background to process incoming jobs. It is not a one-time installation or setup script.

For local testing, you can start it by running:

php artisan rust-worker:start

This Artisan command will automatically:

1. Detect your operating system and CPU architecture.
2. Find the correct pre-compiled binary (e.g. rust-worker-linux-x64, rust-worker-linux-arm64, rust-worker-macos, or rust-worker-windows.exe) inside the package's bin/ directory.
3. Apply execute permissions (chmod +x) automatically on Unix-like systems.
4. Launch the persistent background listener in the foreground.

🖥️ Production Deployment

In a production environment, you should use a process manager (such as Supervisor or systemd) to keep the worker running 24/7, restart it if it crashes, and launch it automatically upon server reboots.

Option A: Supervisor Setup (Recommended)

Create a configuration file (e.g., /etc/supervisor/conf.d/laravel-rust-worker.conf):

[program:laravel-rust-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan rust-worker:start
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/html/storage/logs/rust-worker.log
stopwaitsecs=3600
stopasgroup=true
killasgroup=true

(Be sure to replace /var/www/html with the absolute path to your Laravel installation and www-data with your system's web user).

After creating the file, reload and start it:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-rust-worker:*

Option B: systemd Service Setup

If you prefer using systemd instead of Supervisor, create a service file at /etc/systemd/system/laravel-rust-worker.service:

[Unit]
Description=Laravel Rust Queue Worker Daemon
After=network.target mysql.service redis-server.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/html
ExecStart=/usr/bin/php /var/www/html/artisan rust-worker:start
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

(Update /var/www/html to your application path and /usr/bin/php to the path of your PHP CLI binary).

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable laravel-rust-worker.service
sudo systemctl start laravel-rust-worker.service

⚙️ 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/malak4web/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.