# NGauge Queues Settings

## 1. Component Discovery

The monitor discovers queue components from `Yii::$app->components` where:

- component id is `queue` or ends with `queue`
- OR class contains `common\\components\\Queue`

This matches your existing config pattern:

```php
'queue' => [
    'class' => \common\components\Queue\drivers\db\Queue::class,
    'channel' => 'default',
],
```

## 2. Optional Queue Overrides

You can define per-queue monitor settings under `params`:

```php
'settings' => [
    'queues' => [
        'queue' => [
            'supervisor' => true,
            'processes' => 1,
            'pending_warning' => 25,
            'pending_critical' => 100,
            'stale_seconds' => 1200,
            'heartbeat_fresh_for' => 300,
            'heartbeat_file' => '@runtime/queue-heartbeats/queue.heartbeat',
        ],
        'mailqueue' => [
            'supervisor' => true,
            'processes' => 1,
        ],
    ],
],
```

Also supported list format:

```php
'settings' => [
    'queues' => [
        ['name' => 'queue', 'supervisor' => true],
        ['name' => 'mailqueue', 'supervisor' => true],
    ],
],
```

## 3. Health Rules

The monitor evaluates:

- pending count thresholds
- pending with no running workers
- stale running jobs (`reserved_at` older than threshold)
- supervisor config presence (`console/config/supervisor.conf` or `console/config/supervisor/<name>.conf`)
- optional heartbeat freshness

## 4. Supervisor-safe Monitoring

This module does **not** require `supervisorctl` access. It uses:

- queue DB state (`queue` table)
- filesystem checks for config and heartbeat files
- computed health statuses (`healthy`, `warning`, `critical`)

## 5. Recurring Jobs Configuration

Configure background jobs that automatically re-queue themselves:

```php
'settings' => [
    'queues' => [
        'recurring' => [
            [
                'class' => 'frontend\jobs\CartReminders',  // Required: Job class name
                'name' => 'Cart Reminders',                // Optional: Human-readable name
                'queue' => 'queue',                        // Optional: Queue component (default: 'queue')
                'interval' => 14400,                       // Optional: Seconds between runs (default: 3600)
                'ttr' => 3600,                            // Optional: Max execution time (default: 300)
                'enabled' => true,                         // Optional: Enable/disable (default: true)
                'checkDuplicates' => true,                 // Optional: Check for existing jobs (default: true)
                'maxRetries' => 3,                         // Optional: Retry attempts (default: 3)
                'params' => [                              // Optional: Job constructor params
                    'customParam' => 'value',
                ],
            ],
        ],
    ],
]
```

### Recurring Job Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `class` | string | *required* | Fully qualified job class name |
| `name` | string | `"Recurring: {class}"` | Human-readable job name for tracking |
| `queue` | string | `'queue'` | Queue component name to use |
| `interval` | int | `3600` | Seconds to wait before re-queuing |
| `ttr` | int | `300` | Time-to-reserve in seconds (max runtime) |
| `enabled` | bool | `true` | Whether to start this job |
| `checkDuplicates` | bool | `true` | Check for existing queued jobs before starting |
| `maxRetries` | int | `3` | Maximum retry attempts on failure |
| `params` | array | `[]` | Parameters passed to job constructor |

### Disabling Auto-Start

To disable automatic recurring job bootstrap:

```php
'modules' => [
    'queues' => [
        'class' => PortalPeople\queues\Module::class,
        'autoStartRecurringJobs' => false,  // Disable auto-start
    ],
],
```

## Example Configuration

See `examples/config_example.php`, `examples/recurring_jobs_example.php`, and `examples/custom_recurring_job_example.php` for complete configuration examples.
