Workers Documentation

Background workers process long-running operations asynchronously, allowing the web interface to remain responsive.

Overview

Workers are long-running PHP CLI scripts that:

Poll the database for queued jobs
Process jobs of a specific type
Handle errors gracefully
Log progress and results
Run continuously until stopped

Worker Architecture

All workers follow a similar pattern:

Initialization: Connect to database, verify connection
Main Loop: Continuously poll for jobs
Job Processing: Fetch, process, and complete jobs
Error Handling: Log errors and mark failed jobs

Running Workers

Workers are designed to run as systemd services:

# Enable and start a worker
sudo systemctl enable hotspot_worker.service
sudo systemctl start hotspot_worker.service

# Check status
sudo systemctl status hotspot_worker.service

# View logs
sudo journalctl -u hotspot_worker.service -f

Available Workers

Worker Configuration

Workers are configured via systemd service files in the systemd/ directory. Each service file specifies:

Working directory
PHP executable path
User/group to run as
Restart behavior
Resource limits

Job Processing

Workers use the background_jobs table to manage jobs:

Enqueue: Jobs are created with status ‘queued’
Fetch: Workers fetch jobs using FOR UPDATE SKIP LOCKED
Process: Workers update status to ‘running’ and process
Complete: Workers update status to ‘completed’ with results
Error: On failure, status set to ‘failed’ with error message

Monitoring

Monitor workers via:

Systemd logs: journalctl -u {worker_name}.service
Application logs: logs/worker_{name}.log
Database: Query background_jobs table for job status