Add a Talk API for OCP

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

6 files changed, 263 insertions, 0 deletions

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;
+}