feat(backgroundjob): Schedule job after <timestamp>

lib/private/BackgroundJob/JobList.php

@@ -41,6 +41,10 @@
 use OCP\IConfig;
 use OCP\IDBConnection;
 use Psr\Log\LoggerInterface;
+use function get_class;
+use function json_encode;
+use function md5;
+use function strlen;
 
 class JobList implements IJobList {
 	protected IDBConnection $connection;
@@ -55,11 +59,10 @@ public function __construct(IDBConnection $connection, IConfig $config, ITimeFac
 		$this->logger = $logger;
 	}
 
-	/**
-	 * @param IJob|class-string<IJob> $job
-	 * @param mixed $argument
-	 */
-	public function add($job, $argument = null): void {
+	public function add($job, $argument = null, int $firstCheck = null): void {
+		if ($firstCheck === null) {
+			$firstCheck = $this->timeFactory->getTime();
+		}
 		if ($job instanceof IJob) {
 			$class = get_class($job);
 		} else {
@@ -79,18 +82,22 @@ public function add($job, $argument = null): void {
 					'argument' => $query->createNamedParameter($argumentJson),
 					'argument_hash' => $query->createNamedParameter(md5($argumentJson)),
 					'last_run' => $query->createNamedParameter(0, IQueryBuilder::PARAM_INT),
-					'last_checked' => $query->createNamedParameter($this->timeFactory->getTime(), IQueryBuilder::PARAM_INT),
+					'last_checked' => $query->createNamedParameter($firstCheck, IQueryBuilder::PARAM_INT),
 				]);
 		} else {
 			$query->update('jobs')
 				->set('reserved_at', $query->expr()->literal(0, IQueryBuilder::PARAM_INT))
-				->set('last_checked', $query->createNamedParameter($this->timeFactory->getTime(), IQueryBuilder::PARAM_INT))
+				->set('last_checked', $query->createNamedParameter($firstCheck, IQueryBuilder::PARAM_INT))
 				->where($query->expr()->eq('class', $query->createNamedParameter($class)))
 				->andWhere($query->expr()->eq('argument_hash', $query->createNamedParameter(md5($argumentJson))));
 		}
 		$query->executeStatement();
 	}
 
+	public function scheduleAfter(string $job, int $runAfter, $argument = null): void {
+		$this->add($job, $argument, $runAfter);
+	}
+
 	/**
 	 * @param IJob|string $job
 	 * @param mixed $argument

lib/public/BackgroundJob/IJobList.php

@@ -57,6 +57,19 @@ interface IJobList {
 	 */
 	public function add($job, $argument = null): void;
 
+	/**
+	 * Add a job to the list but only run it after the given timestamp
+	 *
+	 * For cron background jobs this means the job will likely run shortly after the timestamp
+	 * has been reached. For ajax background jobs the job might only run when users are active
+	 * on the instance again.
+	 *
+	 * @param class-string<IJob> $job
+	 * @param mixed $argument The serializable argument to be passed to $job->run() when the job is executed
+	 * @since 28.0.0
+	 */
+	public function scheduleAfter(string $job, int $runAfter, $argument = null): void;
+
 	/**
 	 * Remove a job from the list
 	 *

tests/lib/BackgroundJob/DummyJobList.php

@@ -35,7 +35,7 @@ public function __construct() {
 	 * @param IJob|class-string<IJob> $job
 	 * @param mixed $argument
 	 */
-	public function add($job, $argument = null): void {
+	public function add($job, $argument = null, int $firstCheck = null): void {
 		if (is_string($job)) {
 			/** @var IJob $job */
 			$job = \OCP\Server::get($job);
@@ -46,6 +46,10 @@ public function add($job, $argument = null): void {
 		}
 	}
 
+	public function scheduleAfter(string $job, int $runAfter, $argument = null): void {
+		$this->add($job, $argument, $runAfter);
+	}
+
 	/**
 	 * @param IJob|string $job
 	 * @param mixed $argument