Merge branch 'master' into refactor/OC-Server-getThemingDefaults

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>

7 files changed, 179 insertions, 11 deletions

diff --git a/lib/public/TextProcessing/Exception/TaskFailureException.php b/lib/public/TextProcessing/Exception/TaskFailureException.php
new file mode 100644
index 00000000000..300864711e7
--- /dev/null
+++ b/lib/public/TextProcessing/Exception/TaskFailureException.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace OCP\TextProcessing\Exception;
+
+/**
+ * Exception thrown when a task failed
+ * @since 28.0.0
+ */
+class TaskFailureException extends \RuntimeException {
+}
diff --git a/lib/public/TextProcessing/IManager.php b/lib/public/TextProcessing/IManager.php
index dec0baba4bb..2f517a4ebe2 100644
--- a/lib/public/TextProcessing/IManager.php
+++ b/lib/public/TextProcessing/IManager.php
@@ -27,7 +27,9 @@ declare(strict_types=1);
 namespace OCP\TextProcessing;
 
 use OCP\Common\Exception\NotFoundException;
+use OCP\DB\Exception;
 use OCP\PreConditionNotMetException;
+use OCP\TextProcessing\Exception\TaskFailureException;
 use RuntimeException;
 
 /**
@@ -48,7 +50,7 @@ interface IManager {
 	public function getProviders(): array;
 
 	/**
-	 * @return class-string<ITaskType>[]
+	 * @return string[]
 	 * @since 27.1.0
 	 */
 	public function getAvailableTaskTypes(): array;
@@ -56,7 +58,7 @@ interface IManager {
 	/**
 	 * @param Task $task The task to run
 	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
-	 * @throws RuntimeException If something else failed
+	 * @throws TaskFailureException If running the task failed
 	 * @since 27.1.0
 	 */
 	public function runTask(Task $task): string;
@@ -68,11 +70,26 @@ interface IManager {
 	 *
 	 * @param Task $task The task to schedule
 	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
+	 * @throws Exception storing the task in the database failed
 	 * @since 27.1.0
 	 */
 	public function scheduleTask(Task $task) : void;
 
 	/**
+	 * If the designated provider for the passed task provides an expected average runtime, we check if the runtime fits into the
+	 * max execution time of this php process and run it synchronously if it does, if it doesn't fit (or the provider doesn't provide that information)
+	 * execution is deferred to a background job
+	 *
+	 * @param Task $task The task to schedule
+	 * @returns bool A boolean indicating whether the task was run synchronously (`true`) or offloaded to a background job (`false`)
+	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
+	 * @throws TaskFailureException If running the task failed
+	 * @throws Exception storing the task in the database failed
+	 * @since 28.0.0
+	 */
+	public function runOrScheduleTask(Task $task): bool;
+
+	/**
 	 * Delete a task that has been scheduled before
 	 *
 	 * @param Task $task The task to delete
diff --git a/lib/public/TextProcessing/IProvider.php b/lib/public/TextProcessing/IProvider.php
index 6132e60b493..fc57add1835 100644
--- a/lib/public/TextProcessing/IProvider.php
+++ b/lib/public/TextProcessing/IProvider.php
@@ -31,7 +31,7 @@ use RuntimeException;
 /**
  * This is the interface that is implemented by apps that
  * implement a text processing provider
- * @template T of ITaskType
+ * @psalm-template-covariant  T of ITaskType
  * @since 27.1.0
  */
 interface IProvider {
diff --git a/lib/public/TextProcessing/IProviderWithExpectedRuntime.php b/lib/public/TextProcessing/IProviderWithExpectedRuntime.php
new file mode 100644
index 00000000000..17767fc02d4
--- /dev/null
+++ b/lib/public/TextProcessing/IProviderWithExpectedRuntime.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Marcel Klehr <mklehr@gmx.net>
+ *
+ * @author Marcel Klehr <mklehr@gmx.net>
+ *
+ * @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 OCP\TextProcessing;
+
+/**
+ * This interface  allows the system to learn the provider's expected runtime
+ * @since 28.0.0
+ * @template T of ITaskType
+ * @template-extends IProvider<T>
+ */
+interface IProviderWithExpectedRuntime extends IProvider {
+	/**
+	 * @return int The expected average runtime of a task in seconds
+	 * @since 28.0.0
+	 */
+	public function getExpectedRuntime(): int;
+}
diff --git a/lib/public/TextProcessing/IProviderWithId.php b/lib/public/TextProcessing/IProviderWithId.php
new file mode 100644
index 00000000000..1bd02278d1c
--- /dev/null
+++ b/lib/public/TextProcessing/IProviderWithId.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Marcel Klehr <mklehr@gmx.net>
+ *
+ * @author Marcel Klehr <mklehr@gmx.net>
+ *
+ * @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 OCP\TextProcessing;
+
+/**
+ * @since 28.0.0
+ * @extends IProvider<T>
+ * @template T of ITaskType
+ */
+interface IProviderWithId extends IProvider {
+	/**
+	 * The id of this provider
+	 * @since 28.0.0
+	 */
+	public function getId(): string;
+}
diff --git a/lib/public/TextProcessing/IProviderWithUserId.php b/lib/public/TextProcessing/IProviderWithUserId.php
new file mode 100644
index 00000000000..0a01a4c56c4
--- /dev/null
+++ b/lib/public/TextProcessing/IProviderWithUserId.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Marcel Klehr <mklehr@gmx.net>
+ *
+ * @author Marcel Klehr <mklehr@gmx.net>
+ *
+ * @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 OCP\TextProcessing;
+
+/**
+ * This interface allows providers to access the user that initiated the task being run.
+ * @since 28.0.0
+ * @template T of ITaskType
+ * @template-extends IProvider<T>
+ */
+interface IProviderWithUserId extends IProvider {
+	/**
+	 * @param ?string $userId the current user's id
+	 * @since 28.0.0
+	 */
+	public function setUserId(?string $userId): void;
+}
diff --git a/lib/public/TextProcessing/Task.php b/lib/public/TextProcessing/Task.php
index 446e414cb04..c62b7b2fff8 100644
--- a/lib/public/TextProcessing/Task.php
+++ b/lib/public/TextProcessing/Task.php
@@ -28,13 +28,12 @@ namespace OCP\TextProcessing;
 /**
  * This is a text processing task
  * @since 27.1.0
- * @psalm-template T of ITaskType
- * @psalm-template S as class-string<T>
- * @psalm-template P as IProvider<T>
+ * @psalm-template-covariant T of ITaskType
  */
 final class Task implements \JsonSerializable {
 	protected ?int $id = null;
 	protected ?string $output = null;
+	private ?\DateTime $completionExpectedAt = null;
 
 	/**
 	 * @since 27.1.0
@@ -73,7 +72,7 @@ final class Task implements \JsonSerializable {
 	protected int $status = self::STATUS_UNKNOWN;
 
 	/**
-	 * @psalm-param S $type
+	 * @psalm-param class-string<T> $type
 	 * @param string $type
 	 * @param string $input
 	 * @param string $appId
@@ -91,13 +90,16 @@ final class Task implements \JsonSerializable {
 	}
 
 	/**
-	 * @psalm-param P $provider
+	 * @psalm-param IProvider<T> $provider
 	 * @param IProvider $provider
 	 * @return string
 	 * @since 27.1.0
 	 */
 	public function visitProvider(IProvider $provider): string {
 		if ($this->canUseProvider($provider)) {
+			if ($provider instanceof IProviderWithUserId) {
+				$provider->setUserId($this->getUserId());
+			}
 			return $provider->process($this->getInput());
 		} else {
 			throw new \RuntimeException('Task of type ' . $this->getType() . ' cannot visit provider with task type ' . $provider->getTaskType());
@@ -105,7 +107,7 @@ final class Task implements \JsonSerializable {
 	}
 
 	/**
-	 * @psalm-param P $provider
+	 * @psalm-param IProvider<T> $provider
 	 * @param IProvider $provider
 	 * @return bool
 	 * @since 27.1.0
@@ -115,7 +117,7 @@ final class Task implements \JsonSerializable {
 	}
 
 	/**
-	 * @psalm-return S
+	 * @psalm-return class-string<T>
 	 * @since 27.1.0
 	 */
 	final public function getType(): string {
@@ -203,7 +205,7 @@ final class Task implements \JsonSerializable {
 	}
 
 	/**
-	 * @psalm-return array{id: ?int, type: S, status: 0|1|2|3|4, userId: ?string, appId: string, input: string, output: ?string, identifier: string}
+	 * @psalm-return array{id: ?int, type: class-string<T>, status: 0|1|2|3|4, userId: ?string, appId: string, input: string, output: ?string, identifier: string, completionExpectedAt: ?int}
 	 * @since 27.1.0
 	 */
 	public function jsonSerialize(): array {
@@ -216,6 +218,24 @@ final class Task implements \JsonSerializable {
 			'input' => $this->getInput(),
 			'output' => $this->getOutput(),
 			'identifier' => $this->getIdentifier(),
+			'completionExpectedAt' => $this->getCompletionExpectedAt()?->getTimestamp(),
 		];
 	}
+
+	/**
+	 * @param null|\DateTime $completionExpectedAt
+	 * @return void
+	 * @since 28.0.0
+	 */
+	final public function setCompletionExpectedAt(?\DateTime $completionExpectedAt): void {
+		$this->completionExpectedAt = $completionExpectedAt;
+	}
+
+	/**
+	 * @return \DateTime|null
+	 * @since 28.0.0
+	 */
+	final public function getCompletionExpectedAt(): ?\DateTime {
+		return $this->completionExpectedAt;
+	}
 }