# QueueManager Decomposition Plan (1.1 Milestone)

Internal planning document. Not shipped with releases.

Last updated: 2026-03-27

## Current State

`QueueManager` (776 lines, 17+ public methods) serves as the primary facade for
queue operations. While functional and fully tested, its scope spans multiple
concerns that would benefit from extraction into focused services for long-term
maintainability.

## Method Groupings

### 1. Queue CRUD / Routing

- `queueForConversion()` — orchestrates dedup, assignment, progress, queue item
- `insertQueueEntry()` (private) — atomic insert with rollback
- `removeFromQueue()` — dedup marker + assignment cleanup

### 2. State Queries

- `isQueued()` — dedup check
- `getQueuedMediaCount()` — count query
- `getQueuedMediaIds()` — ordered list of media IDs
- `getQueuedItemIds()` — ordered list of item IDs
- `getQueuedMediaIdsForQueue()` — queue-filtered media IDs
- `getQueuedItemIdsForQueue()` — queue-filtered item IDs
- `getQueueStats()` — aggregated statistics
- `isLimitReached()` — concurrent limit check
- `getQueueNameForSize()` — size-based routing (delegated)
- `getQueueForFile()` — file-based routing (delegated)
- `getLargeFileThreshold()` — config value (delegated)

### 3. Cleanup / Maintenance

- `cleanupStuckConversions()` — timeout-based stuck detection + recovery
- `cleanupStaleQueueEntries()` — age-based stale marker removal

### 4. Immediate Conversion

- `processImmediately()` — sync conversion bypass with lock management

## Proposed Extracted Services

### `QueueStateService` (implements `QueueStateServiceInterface`)

All read-only query methods from group 2.

Injected: `Connection`, `QueueFactory`, `ProgressTrackerInterface`,
`QueueAssignmentRepositoryInterface`, `QueueAssignmentServiceInterface`,
`ConfigFactoryInterface`.

### `QueueCleanupService` (implements `QueueCleanupServiceInterface`)

`cleanupStuckConversions()`, `cleanupStaleQueueEntries()`.

Injected: `Connection`, `ProgressTrackerInterface`, `LockManagerInterface`,
`LoggerChannelInterface`, `QueueStateServiceInterface`.

### `ImmediateConversionService` (implements `ImmediateConversionServiceInterface`)

`processImmediately()`.

Injected: `LockManagerInterface`, `VideoConverterInterface` (lazy via
service_closure), `QueueManagerInterface` (for `removeFromQueue`),
`LoggerChannelInterface`.

## BC Strategy

`QueueManager` remains as the public facade. All existing public methods are
retained but delegate to the extracted services:

```php
// Before (1.0):
public function getQueueStats(): array { /* 40 lines of logic */ }

// After (1.1):
public function getQueueStats(): array {
    return $this->queueStateService->getQueueStats();
}
```

`QueueManagerInterface` is unchanged. Callers (QueueWorker, DashboardController,
Drush commands, SseProgressController) continue injecting
`QueueManagerInterface`.

New interfaces are `@internal` initially. Promotion to supported extension API
is deferred to 2.0 based on community feedback.

## Timeline

- **1.0.0-stable:** No changes. Current structure is functional and tested.
- **1.1.0:** Extract services, delegate from QueueManager. Full BC preservation.
- **2.0.0:** Evaluate promoting extracted interfaces; deprecate direct
  QueueManager injection where a narrower interface suffices.

## Test Impact

- Existing `QueueManagerTest` remains unchanged (tests the facade).
- New unit tests for each extracted service (mocked dependencies).
- Integration tests verify delegation produces identical results.
