# NGauge Queues Module

`portalpeople/ngauge-queues` is a Yii2 extension that adds queue monitoring controls for NGauge projects.

It is designed for environments where users cannot access `supervisorctl` directly (for example typical Plesk users), while still needing visibility into queue health.

## Features

- Auto-discovers queue components registered in app config (`queue`, `mailqueue`, `netsuitequeue`, etc.)
- Reads queue health from DB (`pending`, `running`, stale jobs, oldest pending age)
- Checks whether supervisor config appears to exist (`console/config/supervisor.conf` or per-queue conf files)
- Optional heartbeat-file monitoring for worker liveness
- Dashboard page + JSON status endpoint
- Integrates with existing backend `QueueController` routes for queue drill-down

## Installation

Add to your project `composer.json`:

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://dev.azure.com/portalpeople/ngauge/_git/ngauge-queues"
    }
  ],
  "require": {
    "portalpeople/ngauge-queues": "^1.0"
  }
}
```

Then install:

```bash
composer update portalpeople/ngauge-queues
```

## Module Registration

```php
'modules' => [
    'ngauge-queues' => [
        'class' => PortalPeople\queues\Module::class,
        'supervisorQueues' => ['queue', 'mailqueue', 'dfqueue', 'netsuitequeue'],
        'pendingWarning' => 25,
        'pendingCritical' => 100,
        'staleReserveSeconds' => 1200,
        'heartbeatFreshFor' => 300,
        'heartbeatDirectory' => '@runtime/queue-heartbeats',
    ],
],
```

## Routes

- `/ngauge-queues` — queue monitoring dashboard
- `/ngauge-queues/status` — JSON status payload

## Recurring Background Jobs

The module supports auto-bootstrapping recurring jobs that continuously run in the background.

### Configure Recurring Jobs

Add to your `common/config/params-local.php`:

```php
return [
    'settings' => [
        'queues' => [
            'recurring' => [
                [
                    'class' => 'frontend\jobs\CartReminders',
                    'name' => 'Cart Reminders - Every 4 Hours',
                    'queue' => 'queue',          // Queue component to use
                    'interval' => 14400,         // Seconds between runs (4 hours)
                    'ttr' => 3600,               // Max execution time (1 hour)
                    'enabled' => true,           // Enable/disable
                    'checkDuplicates' => true,   // Prevent duplicates on restart
                    'maxRetries' => 3,           // Retry attempts on failure
                    'params' => [                // Job constructor parameters
                        'customParam' => 'value',
                    ],
                ],
                // Add more recurring jobs...
            ],
        ],
    ],
];
```

### How It Works

1. When the console application starts, the module bootstrap checks for recurring job configurations
2. For each enabled job, it queues a `RecurringJobWrapper` that:
   - Executes your job class
   - Automatically re-queues itself after the specified interval
   - Continues indefinitely until disabled or stopped
3. Duplicate checking prevents multiple instances on application restart

### Dynamic Recurring Jobs

Implement `RecurringJobInterface` for jobs that need dynamic control:

```php
namespace console\jobs;

use PortalPeople\queues\RecurringJobInterface;

class SmartJob extends BaseObject implements RecurringJobInterface
{
    public function execute($queue)
    {
        // Your job logic
    }
    
    public function getRecurringInterval()
    {
        // Dynamically adjust interval based on conditions
        return $this->isHeavyLoad() ? 300 : 3600;
    }
    
    public function shouldContinue()
    {
        // Control whether to keep recurring
        return Yii::$app->params['features']['enabled'] ?? true;
    }
}
```

See `examples/recurring_jobs_example.php` and `examples/custom_recurring_job_example.php` for detailed examples.

## Optional Queue Settings (`params`)

If present, the module reads `Yii::$app->params['settings']['queues']` and merges it with discovered queue components.

Supported keys per queue:

- `supervisor` (`bool`)
- `processes` or `procs` (`int`)
- `pending_warning` (`int`)
- `pending_critical` (`int`)
- `stale_seconds` (`int`)
- `heartbeat_fresh_for` (`int`)
- `heartbeat_file` (`string`)

See `SETTINGS.md` for examples.

## Heartbeat Integration (Optional)

If your queue listeners can write heartbeat files periodically, this module will include that in health checks.

Example heartbeat file path:

- `@runtime/queue-heartbeats/queue.heartbeat`

## License

MIT
