list reserved date and allow filtering by reservered for background job list command

core/Command/Background/ListCommand.php

@@ -26,6 +26,7 @@
 namespace OC\Core\Command\Background;
 
 use OC\Core\Command\Base;
+use OCP\BackgroundJob\IJob;
 use OCP\BackgroundJob\IJobList;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
@@ -61,24 +62,34 @@ protected function configure(): void {
 				InputOption::VALUE_OPTIONAL,
 				'Offset for retrieving jobs',
 				'0'
+			)->addOption(
+				'reserved',
+				null,
+				InputOption::VALUE_NONE,
+				'Only show reserved jobs'
 			)
 		;
 		parent::configure();
 	}
 
 	protected function execute(InputInterface $input, OutputInterface $output): int {
-		$jobs = $this->jobList->getJobsIterator($input->getOption('class'), (int)$input->getOption('limit'), (int)$input->getOption('offset'));
+		$jobs = $this->jobList->getJobsIterator($input->getOption('class'), (int)$input->getOption('limit'), (int)$input->getOption('offset'), (bool)$input->getOption('reserved'));
 		$this->writeTableInOutputFormat($input, $output, $this->formatJobs($jobs));
 		return 0;
 	}
 
+	/**
+	 * @param iterable<IJob> $jobs
+	 * @return array
+	 */
 	protected function formatJobs(iterable $jobs): array {
 		$jobsInfo = [];
 		foreach ($jobs as $job) {
 			$jobsInfo[] = [
 				'id' => $job->getId(),
 				'class' => get_class($job),
 				'last_run' => date(DATE_ATOM, $job->getLastRun()),
+				'reserved_at' => $job->getReservedAt() > 0 ? date(DATE_ATOM, $job->getReservedAt()) : 'not reserved',
 				'argument' => json_encode($job->getArgument()),
 			];
 		}

lib/private/BackgroundJob/Job.php

@@ -33,11 +33,9 @@
  * @deprecated internal class, use \OCP\BackgroundJob\Job
  */
 abstract class Job implements IJob {
-	/** @var int */
-	protected $id;
-
-	/** @var int */
-	protected $lastRun;
+	protected int $id;
+	protected int $lastRun;
+	protected int $reservedAt;
 
 	/** @var mixed */
 	protected $argument;
@@ -80,6 +78,10 @@ public function setLastRun(int $lastRun) {
 		$this->lastRun = $lastRun;
 	}
 
+	public function setReservedAt(int $reservedAt): void {
+		$this->reservedAt = $reservedAt;
+	}
+
 	public function setArgument($argument) {
 		$this->argument = $argument;
 	}
@@ -95,4 +97,8 @@ public function getLastRun() {
 	public function getArgument() {
 		return $this->argument;
 	}
+
+	public function getReservedAt(): int {
+		return $this->reservedAt;
+	}
 }

lib/private/BackgroundJob/JobList.php

@@ -174,7 +174,7 @@ public function getJobs($job, ?int $limit, int $offset): array {
 	 * @param IJob|class-string<IJob>|null $job
 	 * @return iterable<IJob> Avoid to store these objects as they may share a Singleton instance. You should instead use these IJobs instances while looping on the iterable.
 	 */
-	public function getJobsIterator($job, ?int $limit, int $offset): iterable {
+	public function getJobsIterator($job, ?int $limit, int $offset, bool $reservedOnly = false): iterable {
 		$query = $this->connection->getQueryBuilder();
 		$query->select('*')
 			->from('jobs')
@@ -190,6 +190,10 @@ public function getJobsIterator($job, ?int $limit, int $offset): iterable {
 			$query->where($query->expr()->eq('class', $query->createNamedParameter($class)));
 		}
 
+		if ($reservedOnly) {
+			$query->where($query->expr()->gt('reserved_at', $query->createNamedParameter($this->timeFactory->getTime() - 12 * 3600, IQueryBuilder::PARAM_INT)));
+		}
+
 		$result = $query->executeQuery();
 
 		while ($row = $result->fetch()) {
@@ -293,7 +297,7 @@ public function getDetailsById(int $id): ?array {
 	/**
 	 * get the job object from a row in the db
 	 *
-	 * @param array{class:class-string<IJob>, id:mixed, last_run:mixed, argument:string} $row
+	 * @param array{class:class-string<IJob>, id:mixed, last_run:mixed, argument:string, reserved_at:int} $row
 	 * @return ?IJob the next job to run. Beware that this object may be a singleton and may be modified by the next call to buildJob.
 	 */
 	private function buildJob(array $row): ?IJob {
@@ -320,6 +324,7 @@ private function buildJob(array $row): ?IJob {
 			$job->setId((int) $row['id']);
 			$job->setLastRun((int) $row['last_run']);
 			$job->setArgument(json_decode($row['argument'], true));
+			$job->setReservedAt((int) $row['reserved_at']);
 			return $job;
 		} catch (AutoloadNotAllowedException $e) {
 			// job is from a disabled app, ignore

lib/public/BackgroundJob/IJob.php

@@ -87,6 +87,12 @@ public function setLastRun(int $lastRun);
 	 */
 	public function setArgument($argument);
 
+	/**
+	 * @param int $reservedAt
+	 * @since 28.0.0
+	 */
+	public function setReservedAt(int $reservedAt): void;
+
 	/**
 	 * Get the id of the background job
 	 * This id is determined by the job list when a job is added to the list
@@ -112,4 +118,11 @@ public function getLastRun();
 	 * @since 7.0.0
 	 */
 	public function getArgument();
+
+	/**
+	 * Get the timestamp when the job was reserved, or 0 if the job is not currently reserved
+	 *
+	 * @return int
+	 */
+	public function getReservedAt(): int;
 }

lib/public/BackgroundJob/IJobList.php

@@ -92,7 +92,7 @@ public function getJobs($job, ?int $limit, int $offset): array;
 	 * @return iterable<IJob>
 	 * @since 26.0.0
 	 */
-	public function getJobsIterator($job, ?int $limit, int $offset): iterable;
+	public function getJobsIterator($job, ?int $limit, int $offset, bool $reservedOnly = false): iterable;
 
 	/**
 	 * get the next job in the list

lib/public/BackgroundJob/Job.php

@@ -41,6 +41,7 @@
 abstract class Job implements IJob, IParallelAwareJob {
 	protected int $id = 0;
 	protected int $lastRun = 0;
+	protected int $reservedAt;
 	protected $argument;
 	protected ITimeFactory $time;
 	protected bool $allowParallelRuns = true;
@@ -119,6 +120,10 @@ public function setArgument($argument) {
 		$this->argument = $argument;
 	}
 
+	public function setReservedAt(int $reservedAt): void {
+		$this->reservedAt = $reservedAt;
+	}
+
 	/**
 	 * @since 15.0.0
 	 */
@@ -140,6 +145,10 @@ public function getArgument() {
 		return $this->argument;
 	}
 
+	public function getReservedAt(): int {
+		return $this->reservedAt;
+	}
+
 	/**
 	 * Set this to false to prevent two Jobs from this class from running in parallel
 	 *

tests/lib/BackgroundJob/DummyJobList.php

@@ -77,7 +77,7 @@ public function getAll(): array {
 		return $this->jobs;
 	}
 
-	public function getJobsIterator($job, ?int $limit, int $offset): array {
+	public function getJobsIterator($job, ?int $limit, int $offset, bool $reservedOnly = false): array {
 		if ($job instanceof IJob) {
 			$jobClass = get_class($job);
 		} else {