Add a Talk API for OCP

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>

11 files changed, 470 insertions, 0 deletions

diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
index 637a6de8ac8..58c6fe9665b 100644
--- a/lib/composer/composer/autoload_classmap.php
+++ b/lib/composer/composer/autoload_classmap.php
@@ -536,6 +536,11 @@ return array(
     'OCP\\SystemTag\\SystemTagsEntityEvent' => $baseDir . '/lib/public/SystemTag/SystemTagsEntityEvent.php',
     'OCP\\SystemTag\\TagAlreadyExistsException' => $baseDir . '/lib/public/SystemTag/TagAlreadyExistsException.php',
     'OCP\\SystemTag\\TagNotFoundException' => $baseDir . '/lib/public/SystemTag/TagNotFoundException.php',
+    'OCP\\Talk\\Exceptions\\NoBackendException' => $baseDir . '/lib/public/Talk/Exceptions/NoBackendException.php',
+    'OCP\\Talk\\IBroker' => $baseDir . '/lib/public/Talk/IBroker.php',
+    'OCP\\Talk\\IConversation' => $baseDir . '/lib/public/Talk/IConversation.php',
+    'OCP\\Talk\\IConversationOptions' => $baseDir . '/lib/public/Talk/IConversationOptions.php',
+    'OCP\\Talk\\ITalkBackend' => $baseDir . '/lib/public/Talk/ITalkBackend.php',
     'OCP\\Template' => $baseDir . '/lib/public/Template.php',
     'OCP\\UserInterface' => $baseDir . '/lib/public/UserInterface.php',
     'OCP\\UserStatus\\IManager' => $baseDir . '/lib/public/UserStatus/IManager.php',
@@ -1458,6 +1463,8 @@ return array(
     'OC\\Tagging\\Tag' => $baseDir . '/lib/private/Tagging/Tag.php',
     'OC\\Tagging\\TagMapper' => $baseDir . '/lib/private/Tagging/TagMapper.php',
     'OC\\Tags' => $baseDir . '/lib/private/Tags.php',
+    'OC\\Talk\\Broker' => $baseDir . '/lib/private/Talk/Broker.php',
+    'OC\\Talk\\ConversationOptions' => $baseDir . '/lib/private/Talk/ConversationOptions.php',
     'OC\\TempManager' => $baseDir . '/lib/private/TempManager.php',
     'OC\\TemplateLayout' => $baseDir . '/lib/private/TemplateLayout.php',
     'OC\\Template\\Base' => $baseDir . '/lib/private/Template/Base.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
index 9c37cd83978..d80bead5592 100644
--- a/lib/composer/composer/autoload_static.php
+++ b/lib/composer/composer/autoload_static.php
@@ -565,6 +565,11 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
         'OCP\\SystemTag\\SystemTagsEntityEvent' => __DIR__ . '/../../..' . '/lib/public/SystemTag/SystemTagsEntityEvent.php',
         'OCP\\SystemTag\\TagAlreadyExistsException' => __DIR__ . '/../../..' . '/lib/public/SystemTag/TagAlreadyExistsException.php',
         'OCP\\SystemTag\\TagNotFoundException' => __DIR__ . '/../../..' . '/lib/public/SystemTag/TagNotFoundException.php',
+        'OCP\\Talk\\Exceptions\\NoBackendException' => __DIR__ . '/../../..' . '/lib/public/Talk/Exceptions/NoBackendException.php',
+        'OCP\\Talk\\IBroker' => __DIR__ . '/../../..' . '/lib/public/Talk/IBroker.php',
+        'OCP\\Talk\\IConversation' => __DIR__ . '/../../..' . '/lib/public/Talk/IConversation.php',
+        'OCP\\Talk\\IConversationOptions' => __DIR__ . '/../../..' . '/lib/public/Talk/IConversationOptions.php',
+        'OCP\\Talk\\ITalkBackend' => __DIR__ . '/../../..' . '/lib/public/Talk/ITalkBackend.php',
         'OCP\\Template' => __DIR__ . '/../../..' . '/lib/public/Template.php',
         'OCP\\UserInterface' => __DIR__ . '/../../..' . '/lib/public/UserInterface.php',
         'OCP\\UserStatus\\IManager' => __DIR__ . '/../../..' . '/lib/public/UserStatus/IManager.php',
@@ -1487,6 +1492,8 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
         'OC\\Tagging\\Tag' => __DIR__ . '/../../..' . '/lib/private/Tagging/Tag.php',
         'OC\\Tagging\\TagMapper' => __DIR__ . '/../../..' . '/lib/private/Tagging/TagMapper.php',
         'OC\\Tags' => __DIR__ . '/../../..' . '/lib/private/Tags.php',
+        'OC\\Talk\\Broker' => __DIR__ . '/../../..' . '/lib/private/Talk/Broker.php',
+        'OC\\Talk\\ConversationOptions' => __DIR__ . '/../../..' . '/lib/private/Talk/ConversationOptions.php',
         'OC\\TempManager' => __DIR__ . '/../../..' . '/lib/private/TempManager.php',
         'OC\\TemplateLayout' => __DIR__ . '/../../..' . '/lib/private/TemplateLayout.php',
         'OC\\Template\\Base' => __DIR__ . '/../../..' . '/lib/private/Template/Base.php',
diff --git a/lib/private/AppFramework/Bootstrap/RegistrationContext.php b/lib/private/AppFramework/Bootstrap/RegistrationContext.php
index 6a9073b576b..401a967c988 100644
--- a/lib/private/AppFramework/Bootstrap/RegistrationContext.php
+++ b/lib/private/AppFramework/Bootstrap/RegistrationContext.php
@@ -30,6 +30,8 @@ declare(strict_types=1);
 namespace OC\AppFramework\Bootstrap;
 
 use Closure;
+use OCP\Talk\ITalkBackend;
+use RuntimeException;
 use function array_shift;
 use OC\Support\CrashReport\Registry;
 use OCP\AppFramework\App;
@@ -65,6 +67,9 @@ class RegistrationContext {
 	/** @var ServiceRegistration<ILinkAction>[] */
 	private $profileLinkActions = [];
 
+	/** @var null|ServiceRegistration<ITalkBackend> */
+	private $talkBackendRegistration = null;
+
 	/** @var ServiceFactoryRegistration[] */
 	private $services = [];
 
@@ -259,6 +264,13 @@ class RegistrationContext {
 					$actionClass
 				);
 			}
+
+			public function registerTalkBackend(string $backend): void {
+				$this->context->registerTalkBackend(
+					$this->appId,
+					$backend
+				);
+			}
 		};
 	}
 
@@ -350,6 +362,21 @@ class RegistrationContext {
 	}
 
 	/**
+	 * @psalm-param class-string<ITalkBackend> $backend
+	 */
+	public function registerTalkBackend(string $appId, string $backend) {
+		// Some safeguards for invalid registrations
+		if ($appId !== 'spreed') {
+			throw new RuntimeException("Only the Talk app is allowed to register a Talk backend");
+		}
+		if ($this->talkBackendRegistration !== null) {
+			throw new RuntimeException("There can only be one Talk backend");
+		}
+
+		$this->talkBackendRegistration = new ServiceRegistration($appId, $backend);
+	}
+
+	/**
 	 * @param App[] $apps
 	 */
 	public function delegateCapabilityRegistrations(array $apps): void {
@@ -600,4 +627,12 @@ class RegistrationContext {
 	public function getProfileLinkActions(): array {
 		return $this->profileLinkActions;
 	}
+
+	/**
+	 * @return ServiceRegistration|null
+	 * @psalm-return ServiceRegistration<ITalkBackend>|null
+	 */
+	public function getTalkBackendRegistration(): ?ServiceRegistration {
+		return $this->talkBackendRegistration;
+	}
 }
diff --git a/lib/private/Talk/Broker.php b/lib/private/Talk/Broker.php
new file mode 100644
index 00000000000..a686adeed04
--- /dev/null
+++ b/lib/private/Talk/Broker.php
@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2022 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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\Talk;
+
+use OC\AppFramework\Bootstrap\Coordinator;
+use OCP\IServerContainer;
+use OCP\Talk\Exceptions\NoBackendException;
+use OCP\Talk\IBroker;
+use OCP\Talk\IConversation;
+use OCP\Talk\IConversationOptions;
+use OCP\Talk\ITalkBackend;
+use Psr\Log\LoggerInterface;
+use RuntimeException;
+use Throwable;
+
+class Broker implements IBroker {
+	private Coordinator $coordinator;
+
+	private IServerContainer $container;
+
+	private LoggerInterface $logger;
+
+	private ?bool $hasBackend = null;
+
+	private ?ITalkBackend $backend = null;
+
+	public function __construct(Coordinator $coordinator,
+								IServerContainer $container,
+								LoggerInterface $logger) {
+		$this->coordinator = $coordinator;
+		$this->container = $container;
+		$this->logger = $logger;
+	}
+
+	public function hasBackend(): bool {
+		if ($this->hasBackend !== null) {
+			return $this->hasBackend;
+		}
+
+		$context = $this->coordinator->getRegistrationContext();
+		if ($context === null) {
+			// Backend requested too soon, e.g. from the bootstrap `register` method of an app
+			throw new RuntimeException("Not all apps have been registered yet");
+		}
+		$backendRegistration = $context->getTalkBackendRegistration();
+		if ($backendRegistration === null) {
+			// Nothing to do. Remember and exit.
+			return $this->hasBackend = false;
+		}
+
+		try {
+			$this->backend = $this->container->get(
+				$backendRegistration->getService()
+			);
+
+			// Remember and return
+			return $this->hasBackend = true;
+		} catch (Throwable $e) {
+			$this->logger->error("Talk backend {class} could not be loaded: " . $e->getMessage(), [
+				'class' => $backendRegistration->getService(),
+				'exception' => $e,
+			]);
+
+			// Temporary result. Maybe the next time the backend is requested it can be loaded.
+			return false;
+		}
+	}
+
+	public function newConversationOptions(): IConversationOptions {
+		return ConversationOptions::default();
+	}
+
+	public function createConversation(string $name,
+									   array $moderators,
+									   IConversationOptions $options = null): IConversation {
+		if (!$this->hasBackend()) {
+			throw new NoBackendException("The Talk broker has no registered backend");
+		}
+
+		return $this->backend->createConversation(
+			$name,
+			$moderators,
+			$options ?? ConversationOptions::default()
+		);
+	}
+}
diff --git a/lib/private/Talk/ConversationOptions.php b/lib/private/Talk/ConversationOptions.php
new file mode 100644
index 00000000000..f86c8d037d3
--- /dev/null
+++ b/lib/private/Talk/ConversationOptions.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2022 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2022 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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\Talk;
+
+use OCP\Talk\IConversationOptions;
+
+class ConversationOptions implements IConversationOptions {
+	private bool $isPublic;
+
+	private function __construct(bool $isPublic) {
+		$this->isPublic = $isPublic;
+	}
+
+	public static function default(): self {
+		return new self(false);
+	}
+
+	public function setPublic(bool $isPublic = true): IConversationOptions {
+		$this->isPublic = $isPublic;
+		return $this;
+	}
+
+	public function isPublic(): bool {
+		return $this->isPublic;
+	}
+}
diff --git a/lib/public/AppFramework/Bootstrap/IRegistrationContext.php b/lib/public/AppFramework/Bootstrap/IRegistrationContext.php
index be936540aee..19b5665f547 100644
--- a/lib/public/AppFramework/Bootstrap/IRegistrationContext.php
+++ b/lib/public/AppFramework/Bootstrap/IRegistrationContext.php
@@ -264,4 +264,15 @@ interface IRegistrationContext {
 	 * @since 23.0.0
 	 */
 	public function registerProfileLinkAction(string $actionClass): void;
+
+	/**
+	 * Register the backend of the Talk app
+	 *
+	 * This service must only be used by the Talk app
+	 *
+	 * @param string $backend
+	 * @return void
+	 * @since 24.0.0
+	 */
+	public function registerTalkBackend(string $backend): void;
 }
diff --git a/lib/public/Talk/Exceptions/NoBackendException.php b/lib/public/Talk/Exceptions/NoBackendException.php
new file mode 100644
index 00000000000..9e3187a27ca
--- /dev/null
+++ b/lib/public/Talk/Exceptions/NoBackendException.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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\Talk\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown when the Talk API is accessed but there is no registered backend
+ *
+ * @since 24.0.0
+ */
+final class NoBackendException extends RuntimeException {
+}
diff --git a/lib/public/Talk/IBroker.php b/lib/public/Talk/IBroker.php
new file mode 100644
index 00000000000..d28771544c8
--- /dev/null
+++ b/lib/public/Talk/IBroker.php
@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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\Talk;
+
+use OCP\IUser;
+use OCP\Talk\Exceptions\NoBackendException;
+
+/**
+ * Abstraction over the optional Talk backend
+ *
+ * http://software-pattern.org/Broker
+ *
+ * @since 24.0.0
+ */
+interface IBroker {
+
+	/**
+	 * Check if the Talk backend is available
+	 *
+	 * @return bool
+	 * @since 24.0.0
+	 */
+	public function hasBackend(): bool;
+
+	/**
+	 * Create a new instance of the objects object for specifics of a new conversation
+	 *
+	 * @return IConversationOptions
+	 * @throws NoBackendException when Talk is not available
+	 * @since 24.0.0
+	 */
+	public function newConversationOptions(): IConversationOptions;
+
+	/**
+	 * Create a new conversation
+	 *
+	 * The conversation is private by default. Use the options parameter to make
+	 * it public.
+	 *
+	 * @param string $name
+	 * @param IUser[] $moderators
+	 * @param IConversationOptions|null $options optional configuration for the conversation
+	 *
+	 * @return IConversation
+	 * @throws NoBackendException when Talk is not available
+	 * @since 24.0.0
+	 */
+	public function createConversation(string $name,
+									   array $moderators,
+									   IConversationOptions $options = null): IConversation;
+}
diff --git a/lib/public/Talk/IConversation.php b/lib/public/Talk/IConversation.php
new file mode 100644
index 00000000000..43698b9069f
--- /dev/null
+++ b/lib/public/Talk/IConversation.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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\Talk;
+
+/**
+ * @since 24.0.0
+ */
+interface IConversation {
+
+	/**
+	 * Get the absolute URL to this conversation
+	 *
+	 * @return string
+	 * @since 24.0.0
+	 */
+	public function getAbsoluteUrl(): string;
+}
diff --git a/lib/public/Talk/IConversationOptions.php b/lib/public/Talk/IConversationOptions.php
new file mode 100644
index 00000000000..020a98cc405
--- /dev/null
+++ b/lib/public/Talk/IConversationOptions.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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\Talk;
+
+/**
+ * @since 24.0.0
+ */
+interface IConversationOptions {
+
+	/**
+	 * Will the conversation be public?
+	 *
+	 * @return bool
+	 * @since 24.0.0
+	 */
+	public function isPublic(): bool;
+
+	/**
+	 * Make the new conversation public
+	 *
+	 * @param bool $isPublic
+	 *
+	 * @return $this
+	 * @since 24.0.0
+	 */
+	public function setPublic(bool $isPublic = true): self;
+}
diff --git a/lib/public/Talk/ITalkBackend.php b/lib/public/Talk/ITalkBackend.php
new file mode 100644
index 00000000000..700d5d8c4d3
--- /dev/null
+++ b/lib/public/Talk/ITalkBackend.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2021 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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\Talk;
+
+use OCP\IUser;
+
+/**
+ * Interface for the Talk app to implement
+ *
+ * Other apps must not implement nor use this interface in any way. Use the
+ * broker instead
+ *
+ * @see IBroker
+ * @since 24.0.0
+ */
+interface ITalkBackend {
+
+	/**
+	 * @param string $name
+	 * @param IUser[] $moderators
+	 * @param IConversationOptions $options configuration for the conversation
+	 *
+	 * @return IConversation
+	 * @since 24.0.0
+	 */
+	public function createConversation(string $name,
+									   array $moderators,
+									   IConversationOptions $options): IConversation;
+}