enh(TextProcessing): Add IProvider2

- allow providers to obtain current task's userId
- allow providers to expose average task runtime

Signed-off-by: Marcel Klehr <mklehr@gmx.net>

3 files changed, 80 insertions, 3 deletions

diff --git a/lib/public/TextProcessing/IManager.php b/lib/public/TextProcessing/IManager.php
index dec0baba4bb..aae686e318c 100644
--- a/lib/public/TextProcessing/IManager.php
+++ b/lib/public/TextProcessing/IManager.php
@@ -27,6 +27,7 @@ declare(strict_types=1);
 namespace OCP\TextProcessing;
 
 use OCP\Common\Exception\NotFoundException;
+use OCP\DB\Exception;
 use OCP\PreConditionNotMetException;
 use RuntimeException;
 
@@ -68,11 +69,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 RuntimeException 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/IProvider2.php b/lib/public/TextProcessing/IProvider2.php
new file mode 100644
index 00000000000..74e6a47fed5
--- /dev/null
+++ b/lib/public/TextProcessing/IProvider2.php
@@ -0,0 +1,48 @@
+<?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 supersedes IProvider. It allows the system to learn
+ * the provider's expected runtime and lets the provider know which user is running a task
+ * @since 28.0.0
+ * @template T of ITaskType
+ * @template-extends IProvider<T>
+ */
+interface IProvider2 extends IProvider {
+	/**
+	 * @param ?string $userId the current user's id
+	 * @since 28.0.0
+	 */
+	public function setUserId(?string $userId): string;
+
+	/**
+	 * @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/Task.php b/lib/public/TextProcessing/Task.php
index 446e414cb04..16850348358 100644
--- a/lib/public/TextProcessing/Task.php
+++ b/lib/public/TextProcessing/Task.php
@@ -35,6 +35,7 @@ namespace OCP\TextProcessing;
 final class Task implements \JsonSerializable {
 	protected ?int $id = null;
 	protected ?string $output = null;
+	private ?\DateTime $completionExpectedAt = null;
 
 	/**
 	 * @since 27.1.0
@@ -92,12 +93,15 @@ final class Task implements \JsonSerializable {
 
 	/**
 	 * @psalm-param P $provider
-	 * @param IProvider $provider
+	 * @param IProvider|IProvider2 $provider
 	 * @return string
 	 * @since 27.1.0
 	 */
-	public function visitProvider(IProvider $provider): string {
+	public function visitProvider(IProvider|IProvider2 $provider): string {
 		if ($this->canUseProvider($provider)) {
+			if ($provider instanceof IProvider2) {
+				$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());
@@ -203,7 +207,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: S, 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 +220,15 @@ final class Task implements \JsonSerializable {
 			'input' => $this->getInput(),
 			'output' => $this->getOutput(),
 			'identifier' => $this->getIdentifier(),
+			'completionExpectedAt' => $this->getCompletionExpectedAt()?->getTimestamp(),
 		];
 	}
+
+final public function setCompletionExpectedAt(\DateTime $completionExpectedAt): void {
+	$this->completionExpectedAt = $completionExpectedAt;
+}
+
+final public function getCompletionExpectedAt(): ?\DateTime {
+	return $this->completionExpectedAt;
+}
 }