<?php

declare(strict_types=1);

namespace App\Framework\Queue\Contracts;

use App\Framework\Queue\Entities\DeadLetterJob;
use App\Framework\Queue\ValueObjects\DeadLetterQueueName;
use App\Framework\Queue\ValueObjects\QueueName;

/**
 * Interface for Dead Letter Queue operations
 */
interface DeadLetterQueueInterface
{
    /**
     * Add a failed job to the dead letter queue
     */
    public function addFailedJob(DeadLetterJob $deadLetterJob): void;

    /**
     * Get all jobs from a dead letter queue
     *
     * @return DeadLetterJob[]
     */
    public function getJobs(DeadLetterQueueName $deadLetterQueueName, int $limit = 100): array;

    /**
     * Get jobs from dead letter queue by original queue
     *
     * @return DeadLetterJob[]
     */
    public function getJobsByOriginalQueue(QueueName $originalQueue, int $limit = 100): array;

    /**
     * Retry a job from the dead letter queue
     * Moves it back to the original queue and increments retry count
     */
    public function retryJob(string $deadLetterJobId): bool;

    /**
     * Permanently delete a job from the dead letter queue
     */
    public function deleteJob(string $deadLetterJobId): bool;

    /**
     * Retry all jobs in a dead letter queue
     * Returns the number of jobs successfully retried
     */
    public function retryAllJobs(DeadLetterQueueName $deadLetterQueueName): int;

    /**
     * Clear all jobs from a dead letter queue
     * Returns the number of jobs deleted
     */
    public function clearQueue(DeadLetterQueueName $deadLetterQueueName): int;

    /**
     * Get statistics for a dead letter queue
     */
    public function getQueueStats(DeadLetterQueueName $deadLetterQueueName): array;

    /**
     * Get all dead letter queue names
     *
     * @return DeadLetterQueueName[]
     */
    public function getAvailableQueues(): array;
}
