<?php
/**
 * Background job storage port.
 *
 * @package Akantio\Cache
 */

declare(strict_types=1);

namespace Akantio\Cache\Application\Queue;

/**
 * Durable queue with de-duplication by type + payload.
 */
interface JobQueue {

	/**
	 * Adds a job, or lowers the priority of an identical pending job.
	 *
	 * @param string               $type     Type.
	 * @param array<string, mixed> $payload  Payload.
	 * @param int                  $priority Lower runs first.
	 */
	public function push( string $type, array $payload, int $priority = 10 ): void;

	/**
	 * Locks and returns the next runnable job, or null.
	 */
	public function claim(): ?Job;

	/**
	 * Removes a finished job.
	 *
	 * @param Job $job Job.
	 */
	public function complete( Job $job ): void;

	/**
	 * Releases a job for another attempt after a delay.
	 *
	 * @param Job    $job           Job.
	 * @param string $error         Sanitised error.
	 * @param int    $delay_seconds Delay.
	 */
	public function retry( Job $job, string $error, int $delay_seconds ): void;

	/**
	 * Marks a job as permanently failed.
	 *
	 * @param Job    $job   Job.
	 * @param string $error Sanitised error.
	 */
	public function fail( Job $job, string $error ): void;

	/**
	 * Number of pending jobs.
	 */
	public function countPending(): int;

	/**
	 * Puts a claimed job back to wait, without counting the attempt.
	 *
	 * @param Job $job           Claimed job.
	 * @param int $delay_seconds Delay before it may be claimed again.
	 */
	public function postpone( Job $job, int $delay_seconds ): void;

	/**
	 * Removes jobs of one type, or all jobs.
	 *
	 * @param string|null $type Type or null for all.
	 */
	public function clear( ?string $type = null ): void;
}