[stable30] feat(polls): Allow moderators to draft polls

appinfo/routes/routesPollController.php

@@ -21,6 +21,8 @@
 	'ocs' => [
 		/** @see \OCA\Talk\Controller\PollController::createPoll() */
 		['name' => 'Poll#createPoll', 'url' => '/api/{apiVersion}/poll/{token}', 'verb' => 'POST', 'requirements' => $requirements],
+		/** @see \OCA\Talk\Controller\PollController::getAllDraftPolls() */
+		['name' => 'Poll#getAllDraftPolls', 'url' => '/api/{apiVersion}/poll/{token}/drafts', 'verb' => 'GET', 'requirements' => $requirements],
 		/** @see \OCA\Talk\Controller\PollController::showPoll() */
 		['name' => 'Poll#showPoll', 'url' => '/api/{apiVersion}/poll/{token}/{pollId}', 'verb' => 'GET', 'requirements' => $requirementsWithPollId],
 		/** @see \OCA\Talk\Controller\PollController::votePoll() */

docs/capabilities.md

@@ -158,5 +158,6 @@
 
 ## 20.1
 * `archived-conversations` (local) - Conversations can be marked as archived which will hide them from the conversation list by default
+* `talk-polls-drafts` - Whether moderators can store and retrieve poll drafts
 * `config => call => start-without-media` (local) - Boolean, whether media should be disabled when starting or joining a conversation
 * `config => call => max-duration` - Integer, maximum call duration in seconds. Please note that this should only be used with system cron and with a reasonable high value, due to the expended duration until the background job ran.

lib/Capabilities.php

@@ -104,6 +104,7 @@ class Capabilities implements IPublicCapability {
 		'mention-permissions',
 		'edit-messages-note-to-self',
 		'archived-conversations',
+		'talk-polls-drafts',
 	];
 
 	public const LOCAL_FEATURES = [

lib/Controller/PollController.php

@@ -11,9 +11,11 @@
 
 use JsonException;
 use OCA\Talk\Chat\ChatManager;
+use OCA\Talk\Exceptions\PollPropertyException;
 use OCA\Talk\Exceptions\WrongPermissionsException;
 use OCA\Talk\Middleware\Attribute\FederationSupported;
 use OCA\Talk\Middleware\Attribute\RequireModeratorOrNoLobby;
+use OCA\Talk\Middleware\Attribute\RequireModeratorParticipant;
 use OCA\Talk\Middleware\Attribute\RequireParticipant;
 use OCA\Talk\Middleware\Attribute\RequirePermission;
 use OCA\Talk\Middleware\Attribute\RequireReadWriteConversation;
@@ -34,6 +36,7 @@
 
 /**
  * @psalm-import-type TalkPoll from ResponseDefinitions
+ * @psalm-import-type TalkPollDraft from ResponseDefinitions
  */
 class PollController extends AEnvironmentAwareController {
 
@@ -58,8 +61,10 @@ public function __construct(
 	 * @param 0|1 $resultMode Mode how the results will be shown
 	 * @psalm-param Poll::MODE_* $resultMode Mode how the results will be shown
 	 * @param int $maxVotes Number of maximum votes per voter
-	 * @return DataResponse<Http::STATUS_CREATED, TalkPoll, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array<empty>, array{}>
+	 * @param bool $draft Whether the poll should be saved as a draft (only allowed for moderators and with `talk-polls-drafts` capability)
+	 * @return DataResponse<Http::STATUS_OK, TalkPollDraft, array{}>|DataResponse<Http::STATUS_CREATED, TalkPoll, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: 'draft'|'options'|'question'|'room'}, array{}>
 	 *
+	 * 200: Draft created successfully
 	 * 201: Poll created successfully
 	 * 400: Creating poll is not possible
 	 */
@@ -69,16 +74,20 @@ public function __construct(
 	#[RequireParticipant]
 	#[RequirePermission(permission: RequirePermission::CHAT)]
 	#[RequireReadWriteConversation]
-	public function createPoll(string $question, array $options, int $resultMode, int $maxVotes): DataResponse {
+	public function createPoll(string $question, array $options, int $resultMode, int $maxVotes, bool $draft = false): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
 			$proxy = \OCP\Server::get(\OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController::class);
-			return $proxy->createPoll($this->room, $this->participant, $question, $options, $resultMode, $maxVotes);
+			return $proxy->createPoll($this->room, $this->participant, $question, $options, $resultMode, $maxVotes, $draft);
 		}
 
 		if ($this->room->getType() !== Room::TYPE_GROUP
 			&& $this->room->getType() !== Room::TYPE_PUBLIC) {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(['error' => PollPropertyException::REASON_ROOM], Http::STATUS_BAD_REQUEST);
+		}
+
+		if ($draft === true && !$this->participant->hasModeratorPermissions()) {
+			return new DataResponse(['error' => PollPropertyException::REASON_DRAFT], Http::STATUS_BAD_REQUEST);
 		}
 
 		$attendee = $this->participant->getAttendee();
@@ -91,11 +100,16 @@ public function createPoll(string $question, array $options, int $resultMode, in
 				$question,
 				$options,
 				$resultMode,
-				$maxVotes
+				$maxVotes,
+				$draft,
 			);
-		} catch (\Exception $e) {
+		} catch (PollPropertyException $e) {
 			$this->logger->error('Error creating poll', ['exception' => $e]);
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(['error' => $e->getReason()], Http::STATUS_BAD_REQUEST);
+		}
+
+		if ($draft) {
+			return new DataResponse($poll->renderAsDraft());
 		}
 
 		$message = json_encode([
@@ -117,7 +131,37 @@ public function createPoll(string $question, array $options, int $resultMode, in
 			$this->logger->error($e->getMessage(), ['exception' => $e]);
 		}
 
-		return new DataResponse($this->renderPoll($poll, []), Http::STATUS_CREATED);
+		return new DataResponse($this->renderPoll($poll), Http::STATUS_CREATED);
+	}
+
+	/**
+	 * Get all drafted polls
+	 *
+	 * Required capability: `talk-polls-drafts`
+	 *
+	 * @return DataResponse<Http::STATUS_OK, list<TalkPollDraft>, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, list<empty>, array{}>
+	 *
+	 * 200: Poll returned
+	 * 403: User is not a moderator
+	 * 404: Poll not found
+	 */
+	#[FederationSupported]
+	#[PublicPage]
+	#[RequireModeratorParticipant]
+	public function getAllDraftPolls(): DataResponse {
+		if ($this->room->isFederatedConversation()) {
+			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
+			$proxy = \OCP\Server::get(\OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController::class);
+			return $proxy->getDraftsForRoom($this->room, $this->participant);
+		}
+
+		$polls = $this->pollService->getDraftsForRoom($this->room->getId());
+		$data = [];
+		foreach ($polls as $poll) {
+			$data[] = $poll->renderAsDraft();
+		}
+
+		return new DataResponse($data);
 	}
 
 	/**
@@ -143,7 +187,11 @@ public function showPoll(int $pollId): DataResponse {
 
 		try {
 			$poll = $this->pollService->getPoll($this->room->getId(), $pollId);
-		} catch (DoesNotExistException $e) {
+		} catch (DoesNotExistException) {
+			return new DataResponse([], Http::STATUS_NOT_FOUND);
+		}
+
+		if ($poll->getStatus() === Poll::STATUS_DRAFT && !$this->participant->hasModeratorPermissions()) {
 			return new DataResponse([], Http::STATUS_NOT_FOUND);
 		}
 
@@ -181,7 +229,11 @@ public function votePoll(int $pollId, array $optionIds = []): DataResponse {
 
 		try {
 			$poll = $this->pollService->getPoll($this->room->getId(), $pollId);
-		} catch (\Exception $e) {
+		} catch (DoesNotExistException) {
+			return new DataResponse([], Http::STATUS_NOT_FOUND);
+		}
+
+		if ($poll->getStatus() === Poll::STATUS_DRAFT) {
 			return new DataResponse([], Http::STATUS_NOT_FOUND);
 		}
 
@@ -222,9 +274,10 @@ public function votePoll(int $pollId, array $optionIds = []): DataResponse {
 	 *
 	 * @param int $pollId ID of the poll
 	 * @psalm-param non-negative-int $pollId
-	 * @return DataResponse<Http::STATUS_OK, TalkPoll, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, TalkPoll, array{}>|DataResponse<Http::STATUS_ACCEPTED|Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
 	 *
 	 * 200: Poll closed successfully
+	 * 202: Poll draft was deleted successfully
 	 * 400: Poll already closed
 	 * 403: Missing permissions to close poll
 	 * 404: Poll not found
@@ -242,10 +295,15 @@ public function closePoll(int $pollId): DataResponse {
 
 		try {
 			$poll = $this->pollService->getPoll($this->room->getId(), $pollId);
-		} catch (\Exception $e) {
+		} catch (DoesNotExistException) {
 			return new DataResponse([], Http::STATUS_NOT_FOUND);
 		}
 
+		if ($poll->getStatus() === Poll::STATUS_DRAFT) {
+			$this->pollService->deleteByPollId($poll->getId());
+			return new DataResponse([], Http::STATUS_ACCEPTED);
+		}
+
 		if ($poll->getStatus() === Poll::STATUS_CLOSED) {
 			return new DataResponse([], Http::STATUS_BAD_REQUEST);
 		}
@@ -293,7 +351,7 @@ public function closePoll(int $pollId): DataResponse {
 	 * @throws JsonException
 	 */
 	protected function renderPoll(Poll $poll, array $votedSelf = [], array $detailedVotes = []): array {
-		$data = $poll->asArray();
+		$data = $poll->renderAsPoll();
 
 		$canSeeSummary = !empty($votedSelf) && $poll->getResultMode() === Poll::MODE_PUBLIC;
 

lib/Exceptions/PollPropertyException.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Talk\Exceptions;
+
+class PollPropertyException extends \InvalidArgumentException {
+	public const REASON_DRAFT = 'draft';
+	public const REASON_QUESTION = 'question';
+	public const REASON_OPTIONS = 'options';
+	public const REASON_ROOM = 'room';
+
+	/**
+	 * @param self::REASON_* $reason
+	 */
+	public function __construct(
+		protected string $reason,
+	) {
+		parent::__construct($reason);
+	}
+
+	/**
+	 * @return self::REASON_*
+	 */
+	public function getReason(): string {
+		return $this->reason;
+	}
+}

lib/Federation/Proxy/TalkV1/Controller/PollController.php

@@ -20,6 +20,7 @@
 
 /**
  * @psalm-import-type TalkPoll from ResponseDefinitions
+ * @psalm-import-type TalkPollDraft from ResponseDefinitions
  */
 class PollController {
 	public function __construct(
@@ -28,6 +29,38 @@ public function __construct(
 	) {
 	}
 
+	/**
+	 * @return DataResponse<Http::STATUS_OK, list<TalkPollDraft>, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, list<empty>, array{}>
+	 * @throws CannotReachRemoteException
+	 *
+	 * 200: Polls returned
+	 * 404: Polls not found
+	 *
+	 * @see \OCA\Talk\Controller\PollController::showPoll()
+	 */
+	public function getDraftsForRoom(Room $room, Participant $participant): DataResponse {
+		$proxy = $this->proxy->get(
+			$participant->getAttendee()->getInvitedCloudId(),
+			$participant->getAttendee()->getAccessToken(),
+			$room->getRemoteServer() . '/ocs/v2.php/apps/spreed/api/v1/poll/' . $room->getRemoteToken() . '/drafts',
+		);
+
+		$status = $proxy->getStatusCode();
+		if ($status === Http::STATUS_NOT_FOUND || $status === Http::STATUS_FORBIDDEN) {
+			return new DataResponse([], $status);
+		}
+
+		/** @var list<TalkPollDraft> $list */
+		$list = $this->proxy->getOCSData($proxy);
+
+		$data = [];
+		foreach ($list as $poll) {
+			$data[] = $this->userConverter->convertPoll($room, $poll);
+		}
+
+		return new DataResponse($data);
+	}
+
 	/**
 	 * @return DataResponse<Http::STATUS_OK, TalkPoll, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 * @throws CannotReachRemoteException
@@ -93,15 +126,16 @@ public function votePoll(Room $room, Participant $participant, int $pollId, arra
 
 
 	/**
-	 * @return DataResponse<Http::STATUS_CREATED, TalkPoll, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, TalkPollDraft, array{}>|DataResponse<Http::STATUS_CREATED, TalkPoll, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: 'draft'|'options'|'question'|'room'}, array{}>
 	 * @throws CannotReachRemoteException
 	 *
+	 * 200: Draft created successfully
 	 * 201: Poll created successfully
 	 * 400: Creating poll is not possible
 	 *
 	 * @see \OCA\Talk\Controller\PollController::createPoll()
 	 */
-	public function createPoll(Room $room, Participant $participant, string $question, array $options, int $resultMode, int $maxVotes): DataResponse {
+	public function createPoll(Room $room, Participant $participant, string $question, array $options, int $resultMode, int $maxVotes, bool $draft): DataResponse {
 		$proxy = $this->proxy->post(
 			$participant->getAttendee()->getInvitedCloudId(),
 			$participant->getAttendee()->getAccessToken(),
@@ -111,17 +145,23 @@ public function createPoll(Room $room, Participant $participant, string $questio
 				'options' => $options,
 				'resultMode' => $resultMode,
 				'maxVotes' => $maxVotes,
+				'draft' => $draft,
 			],
 		);
 
-		if ($proxy->getStatusCode() === Http::STATUS_BAD_REQUEST) {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+		$status = $proxy->getStatusCode();
+		if ($status === Http::STATUS_BAD_REQUEST) {
+			$data = $this->proxy->getOCSData($proxy, [Http::STATUS_BAD_REQUEST]);
+			return new DataResponse($data, Http::STATUS_BAD_REQUEST);
 		}
 
 		/** @var TalkPoll $data */
-		$data = $this->proxy->getOCSData($proxy, [Http::STATUS_CREATED]);
+		$data = $this->proxy->getOCSData($proxy, [Http::STATUS_OK, Http::STATUS_CREATED]);
 		$data = $this->userConverter->convertPoll($room, $data);
 
+		if ($status === Http::STATUS_OK) {
+			return new DataResponse($data);
+		}
 		return new DataResponse($data, Http::STATUS_CREATED);
 	}
 

lib/Federation/Proxy/TalkV1/UserConverter.php

@@ -18,6 +18,7 @@
 /**
  * @psalm-import-type TalkChatMessageWithParent from ResponseDefinitions
  * @psalm-import-type TalkPoll from ResponseDefinitions
+ * @psalm-import-type TalkPollDraft from ResponseDefinitions
  * @psalm-import-type TalkReaction from ResponseDefinitions
  */
 class UserConverter {
@@ -137,9 +138,12 @@ public function convertMessages(Room $room, array $messages): array {
 	}
 
 	/**
+	 * @template T of TalkPoll|TalkPollDraft
 	 * @param Room $room
-	 * @param TalkPoll $poll
-	 * @return TalkPoll
+	 * @param TalkPoll|TalkPollDraft $poll
+	 * @psalm-param T $poll
+	 * @return TalkPoll|TalkPollDraft
+	 * @psalm-return T
 	 */
 	public function convertPoll(Room $room, array $poll): array {
 		$poll = $this->convertAttendee($room, $poll, 'actorType', 'actorId', 'actorDisplayName');