Allow apps to specify if their background job can be delayed

Signed-off-by: Joas Schilling <coding@schilljs.com>

core/Migrations/Version24000Date20220131153041.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright Copyright (c) 2022 Joas Schilling <coding@nextcloud.com>
+ *
+ * @author Joas Schilling <coding@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OC\Core\Migrations;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+class Version24000Date20220131153041 extends SimpleMigrationStep {
+	/**
+	 * @param IOutput $output
+	 * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+
+		$table = $schema->getTable('jobs');
+		if (!$table->hasColumn('time_sensitive')) {
+			$table->addColumn('time_sensitive', Types::SMALLINT, [
+				'default' => 1,
+			]);
+			$table->addIndex(['time_sensitive'], 'jobs_time_sensitive');
+			return $schema;
+		}
+		return null;
+	}
+}

lib/composer/composer/autoload_classmap.php

@@ -1001,6 +1001,7 @@
     'OC\\Core\\Migrations\\Version24000Date20211213081604' => $baseDir . '/core/Migrations/Version24000Date20211213081604.php',
     'OC\\Core\\Migrations\\Version24000Date20211222112246' => $baseDir . '/core/Migrations/Version24000Date20211222112246.php',
     'OC\\Core\\Migrations\\Version24000Date20211230140012' => $baseDir . '/core/Migrations/Version24000Date20211230140012.php',
+    'OC\\Core\\Migrations\\Version24000Date20220131153041' => $baseDir . '/core/Migrations/Version24000Date20220131153041.php',
     'OC\\Core\\Notification\\CoreNotifier' => $baseDir . '/core/Notification/CoreNotifier.php',
     'OC\\Core\\Service\\LoginFlowV2Service' => $baseDir . '/core/Service/LoginFlowV2Service.php',
     'OC\\DB\\Adapter' => $baseDir . '/lib/private/DB/Adapter.php',

lib/composer/composer/autoload_static.php

@@ -1030,6 +1030,7 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
         'OC\\Core\\Migrations\\Version24000Date20211213081604' => __DIR__ . '/../../..' . '/core/Migrations/Version24000Date20211213081604.php',
         'OC\\Core\\Migrations\\Version24000Date20211222112246' => __DIR__ . '/../../..' . '/core/Migrations/Version24000Date20211222112246.php',
         'OC\\Core\\Migrations\\Version24000Date20211230140012' => __DIR__ . '/../../..' . '/core/Migrations/Version24000Date20211230140012.php',
+        'OC\\Core\\Migrations\\Version24000Date20220131153041' => __DIR__ . '/../../..' . '/core/Migrations/Version24000Date20220131153041.php',
         'OC\\Core\\Notification\\CoreNotifier' => __DIR__ . '/../../..' . '/core/Notification/CoreNotifier.php',
         'OC\\Core\\Service\\LoginFlowV2Service' => __DIR__ . '/../../..' . '/core/Service/LoginFlowV2Service.php',
         'OC\\DB\\Adapter' => __DIR__ . '/../../..' . '/lib/private/DB/Adapter.php',

lib/private/BackgroundJob/JobList.php

@@ -184,9 +184,10 @@ public function getAll() {
 	/**
 	 * get the next job in the list
 	 *
+	 * @param bool $onlyTimeSensitive
 	 * @return IJob|null
 	 */
-	public function getNext() {
+	public function getNext(bool $onlyTimeSensitive = true): ?IJob {
 		$query = $this->connection->getQueryBuilder();
 		$query->select('*')
 			->from('jobs')
@@ -195,6 +196,10 @@ public function getNext() {
 			->orderBy('last_checked', 'ASC')
 			->setMaxResults(1);
 
+		if ($onlyTimeSensitive) {
+			$query->andWhere($query->expr()->eq('time_sensitive', $query->createNamedParameter(IJob::TIME_SENSITIVE, IQueryBuilder::PARAM_INT)));
+		}
+
 		$update = $this->connection->getQueryBuilder();
 		$update->update('jobs')
 			->set('reserved_at', $update->createNamedParameter($this->timeFactory->getTime()))
@@ -215,7 +220,7 @@ public function getNext() {
 
 			if ($count === 0) {
 				// Background job already executed elsewhere, try again.
-				return $this->getNext();
+				return $this->getNext($onlyTimeSensitive);
 			}
 			$job = $this->buildJob($row);
 
@@ -229,7 +234,7 @@ public function getNext() {
 				$reset->execute();
 
 				// Background job from disabled app, try again.
-				return $this->getNext();
+				return $this->getNext($onlyTimeSensitive);
 			}
 
 			return $job;
@@ -333,6 +338,12 @@ public function setLastRun(IJob $job) {
 		$query->update('jobs')
 			->set('last_run', $query->createNamedParameter(time(), IQueryBuilder::PARAM_INT))
 			->where($query->expr()->eq('id', $query->createNamedParameter($job->getId(), IQueryBuilder::PARAM_INT)));
+
+		if ($job instanceof \OCP\BackgroundJob\TimedJob
+			&& !$job->isTimeSensitive()) {
+			$query->set('time_sensitive', $query->createNamedParameter(IJob::TIME_INSENSITIVE));
+		}
+
 		$query->execute();
 	}
 

lib/public/BackgroundJob/IJob.php

@@ -34,6 +34,15 @@
  * @since 7.0.0
  */
 interface IJob {
+	/**
+	 * @since 24.0.0
+	 */
+	public const TIME_INSENSITIVE = 0;
+	/**
+	 * @since 24.0.0
+	 */
+	public const TIME_SENSITIVE = 1;
+
 	/**
 	 * Run the background job with the registered argument
 	 *

lib/public/BackgroundJob/IJobList.php

@@ -85,10 +85,11 @@ public function getAll();
 	/**
 	 * get the next job in the list
 	 *
+	 * @param bool $onlyTimeSensitive
 	 * @return \OCP\BackgroundJob\IJob|null
-	 * @since 7.0.0
+	 * @since 7.0.0 - In 24.0.0 parameter $onlyTimeSensitive got added
 	 */
-	public function getNext();
+	public function getNext(bool $onlyTimeSensitive = false): ?IJob;
 
 	/**
 	 * @param int $id

lib/public/BackgroundJob/TimedJob.php

@@ -38,6 +38,8 @@
 abstract class TimedJob extends Job {
 	/** @var int */
 	protected $interval = 0;
+	/** @var int */
+	protected $timeSensitivity = IJob::TIME_SENSITIVE;
 
 	/**
 	 * set the interval for the job
@@ -50,6 +52,36 @@ public function setInterval(int $seconds) {
 		$this->interval = $seconds;
 	}
 
+	/**
+	 * Whether the background job is time sensitive and needs to run soon after
+	 * the scheduled interval, of if it is okay to be delayed until a later time.
+	 *
+	 * @return bool
+	 * @since 24.0.0
+	 */
+	public function isTimeSensitive(): bool {
+		return $this->timeSensitivity === IJob::TIME_SENSITIVE;
+	}
+
+	/**
+	 * If your background job is not time sensitive (sending instant email
+	 * notifications, etc.) it would be nice to set it to IJob::TIME_INSENSITIVE
+	 * This way the execution can be delayed during high usage times.
+	 *
+	 * @param int $sensitivity
+	 * @psalm-param IJob::TIME_* $sensitivity
+	 * @return void
+	 * @since 24.0.0
+	 */
+	public function setTimeSensitivity(int $sensitivity): void {
+		if ($sensitivity !== IJob::TIME_SENSITIVE &&
+			$sensitivity !== IJob::TIME_INSENSITIVE) {
+			throw new \InvalidArgumentException('Invalid sensitivity');
+		}
+
+		$this->timeSensitivity = $sensitivity;
+	}
+
 	/**
 	 * run the job if the last run is is more than the interval ago
 	 *

tests/lib/BackgroundJob/DummyJobList.php

@@ -75,9 +75,10 @@ public function getAll() {
 	/**
 	 * get the next job in the list
 	 *
+	 * @param bool $onlyTimeSensitive
 	 * @return IJob|null
 	 */
-	public function getNext() {
+	public function getNext(bool $onlyTimeSensitive = true): ?IJob {
 		if (count($this->jobs) > 0) {
 			if ($this->last < (count($this->jobs) - 1)) {
 				$i = $this->last + 1;