Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\Automation\Queue\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Automation\Queue\Domain\Model\QueueJob;
12use DateTimeImmutable;
13
14/**
15 * Queue Repository Contract Interface.
16 *
17 * Defines persistence operations for background queue tasks and locks.
18 *
19 * @package App\Modules\Automation\Queue\Domain\Repository
20 */
21interface QueueRepositoryInterface
22{
23    /**
24     * Enqueues a new background job.
25     *
26     * @param string $jobType Machine name of the job type.
27     * @param string $label Human-readable title.
28     * @param array<string, mixed> $payload Serialized execution parameters.
29     * @param int $createdBy User ID.
30     * @param int $owner Owner User ID.
31     * @return int Enqueued job ID.
32     */
33    public function enqueue(
34        string $jobType,
35        string $label,
36        array $payload,
37        int $createdBy = 1,
38        int $owner = 1
39    ): int;
40
41    /**
42     * Fetches the next due pending job and locks it for execution.
43     *
44     * @param DateTimeImmutable $now Current timestamp.
45     * @return QueueJob|null Next queue job or null if queue is empty.
46     */
47    public function fetchNextPending(DateTimeImmutable $now): ?QueueJob;
48
49    /**
50     * Finds and recovers stale or crashed running jobs (zombie jobs) where heartbeat timed out.
51     *
52     * @param int $staleSeconds Threshold in seconds since last heartbeat to consider job dead.
53     * @param DateTimeImmutable $now Current timestamp.
54     * @return int Count of recovered/failed zombie jobs.
55     */
56    public function recoverStaleJobs(int $staleSeconds, DateTimeImmutable $now): int;
57
58    /**
59     * Updates job progress and heartbeat timestamp.
60     *
61     * @param int $jobId Job identifier.
62     * @param int $processedItems Processed work items count.
63     * @param int $totalItems Total items count.
64     * @param DateTimeImmutable $now Current timestamp.
65     * @return void
66     */
67    public function updateProgress(int $jobId, int $processedItems, int $totalItems, DateTimeImmutable $now): void;
68
69    /**
70     * Marks job as successfully completed.
71     *
72     * @param int $jobId Job identifier.
73     * @param DateTimeImmutable $now Completion timestamp.
74     * @param string|null $outputLog Optional execution output diagnostics log.
75     * @return void
76     */
77    public function markCompleted(int $jobId, DateTimeImmutable $now, ?string $outputLog = null): void;
78
79    /**
80     * Marks job as failed with error details.
81     *
82     * @param int $jobId Job identifier.
83     * @param string $errorMessage Error description.
84     * @param DateTimeImmutable $now Failure timestamp.
85     * @return void
86     */
87    public function markFailed(int $jobId, string $errorMessage, DateTimeImmutable $now): void;
88
89    /**
90     * Finds a queue job by ID.
91     *
92     * @param int $jobId Job identifier.
93     * @return QueueJob|null Found job or null.
94     */
95    public function findById(int $jobId): ?QueueJob;
96}