Async Task Architecture

_instanceof:
  App\AsyncTask\Service\TaskHandler\AsyncTaskHandlerInterface:
    tags: [ 'app.async-task.handler' ]
  App\AsyncTask\Service\Runner\AsyncTaskRunnerInterface:
    tags: [ 'app.async-task.runner' ]
  App\AsyncTask\Service\TaskCompletedHandler\AsyncTaskCompletedHandlerInterface:
    tags: [ 'app.async-task.completed.handler' ]
  App\AsyncTask\Service\TaskProgressedHandler\AsyncTaskProgressedHandlerInterface:
    tags: [ 'app.async-task.progressed.handler' ]
  App\AsyncTask\Service\TaskFailureHandler\AsyncTaskFailureHandlerInterface:
    tags: [ 'app.async-task.failure.handler' ]

$taskId      // UUID of the task record
$taskType    // Runner type (e.g. 'manual-migration-tasks', 'processes')
$module      // Module name (for routing and record lookup)
$handlerKey  // Unique handler identifier (e.g. 'migrate-notes-files')
$data        // Custom task data from the Process options
$progress    // Phase/progress state (see section 5)

class AsyncManualMigrationRunner extends AsyncTaskRunner
{
    const TYPE = 'manual-migration-tasks';

    public function getType(): string
    {
        return self::TYPE;
    }

    protected function getMaxItemsToQueuePerRunConfigKey(): string
    {
        return 'max_migration_items_to_queue_per_run';
    }

    protected function getMaxItemsToProcessPerRunConfigKey(): string
    {
        return 'max_migration_items_to_process_per_run';
    }
}

return (new Feedback())
    ->setSuccess(true)
    ->setMessages(['Migrated successfully'])
    ->setData(['media_object_id' => $id]);

interface AsyncTaskHandlerInterface
{
    public function getHandlerKey(): string;
    public function getType(): string;

    /** @return AsyncTaskBatchItemInterface[] */
    public function getNextBatchToQueue(
        Record $task, array $progress, int $batchSize
    ): array;

    public function processItem(Record $task, array $item): Feedback;

    public function finalize(Record $task): Feedback;
    public function hasFinalization(): bool;

    public function getMaxItemRetries(): int;
    public function allowsFailureRetry(): bool;
    public function allowsFailureRerun(): bool;
}