<?php

declare(strict_types=1);

namespace Apexl\Io\Jobs\Interfaces;

use Apexl\Io\Jobs\Entities\QueueJob;

/**
 * Opt-in extension of {@see QueueTaskHandlerInterface} for handlers that
 * want their failed jobs retried with a backoff schedule rather than being
 * marked failed after the default attempt budget.
 *
 * When a handler implements this interface, {@see QueueJob::handleFailure()}
 * will, on each failed attempt below {@see maxAttempts()}, defer the job
 * (set its `run_after` to now + {@see retryDelaySeconds()}) instead of
 * marking it failed. Handlers that do NOT implement this keep the legacy
 * behaviour untouched.
 */
interface RetryableTaskHandlerInterface extends QueueTaskHandlerInterface
{
    /** Total attempts (including the first) before the job is marked failed. */
    public function maxAttempts(): int;

    /**
     * Backoff delay in seconds before the given retry.
     *
     * @param int $attempt the attempt number that just failed (1-based)
     */
    public function retryDelaySeconds(int $attempt): int;
}
