feat(openapi): Add known limitations to some type, int and string fields

Signed-off-by: Joas Schilling <[email protected]>

Author: nickvergessen

lib/Chat/ChatManager.php

@@ -245,7 +245,7 @@ public function addSystemMessage(
 	 * @return IComment
 	 */
 	public function addChangelogMessage(Room $chat, string $message): IComment {
-		$comment = $this->commentsManager->create(Attendee::ACTOR_GUESTS, Attendee::ACTOR_ID_CHANGELOG, 'chat', (string) $chat->getId());
+		$comment = $this->commentsManager->create(Attendee::ACTOR_GUESTS, Attendee::CHANGELOG_ACTOR_ID, 'chat', (string) $chat->getId());
 
 		$comment->setMessage($message, self::MAX_CHAT_LENGTH);
 		$comment->setCreationDateTime($this->timeFactory->getDateTime());
@@ -345,8 +345,8 @@ public function sendMessage(
 
 			// Update last_message
 			if ($comment->getActorType() !== Attendee::ACTOR_BOTS
-				|| $comment->getActorId() === Attendee::ACTOR_ID_CHANGELOG
-				|| str_starts_with($comment->getActorId(), Attendee::ACTOR_BOT_PREFIX)) {
+				|| $comment->getActorId() === Attendee::CHANGELOG_ACTOR_ID
+				|| str_starts_with($comment->getActorId(), Attendee::BOT_ACTOR_PREFIX)) {
 				$this->roomService->setLastMessage($chat, $comment);
 				$this->unreadCountCache->clear($chat->getId() . '-');
 			} else {

lib/Chat/MessageParser.php

@@ -137,7 +137,7 @@ protected function getActorInformation(Message $message, string $actorType, stri
 			$displayName = $actorId;
 			$actorId = MatterbridgeManager::BRIDGE_BOT_USERID;
 		} elseif ($actorType === Attendee::ACTOR_GUESTS
-			&& !in_array($actorId, [Attendee::ACTOR_ID_CLI, Attendee::ACTOR_ID_CHANGELOG], true)) {
+			&& !in_array($actorId, [Attendee::CLI_ACTOR_ID, Attendee::CHANGELOG_ACTOR_ID], true)) {
 			if (isset($guestNames[$actorId])) {
 				$displayName = $this->guestNames[$actorId];
 			} else {
@@ -151,8 +151,8 @@ protected function getActorInformation(Message $message, string $actorType, stri
 		} elseif ($actorType === Attendee::ACTOR_BOTS) {
 			$displayName = $actorId . '-bot';
 			$token = $message->getRoom()->getToken();
-			if (str_starts_with($actorId, Attendee::ACTOR_BOT_PREFIX)) {
-				$urlHash = substr($actorId, strlen(Attendee::ACTOR_BOT_PREFIX));
+			if (str_starts_with($actorId, Attendee::BOT_ACTOR_PREFIX)) {
+				$urlHash = substr($actorId, strlen(Attendee::BOT_ACTOR_PREFIX));
 				$botName = $this->getBotNameByUrlHashForConversation($token, $urlHash);
 				if ($botName) {
 					$displayName = $botName . ' (Bot)';

lib/Chat/Parser/Changelog.php

@@ -29,12 +29,12 @@ public function handle(Event $event): void {
 		}
 
 		if ($chatMessage->getActorType() !== Attendee::ACTOR_GUESTS ||
-			$chatMessage->getActorId() !== Attendee::ACTOR_ID_CHANGELOG) {
+			$chatMessage->getActorId() !== Attendee::CHANGELOG_ACTOR_ID) {
 			return;
 		}
 
 		$l = $chatMessage->getL10n();
-		$chatMessage->setActor(Attendee::ACTOR_BOTS, Attendee::ACTOR_ID_CHANGELOG, $l->t('Talk updates ✅'));
+		$chatMessage->setActor(Attendee::ACTOR_BOTS, Attendee::CHANGELOG_ACTOR_ID, $l->t('Talk updates ✅'));
 		$event->stopPropagation();
 	}
 }

lib/Chat/Parser/SystemMessage.php

@@ -156,11 +156,11 @@ protected function parseMessage(Message $chatMessage): void {
 				$participant->getAttendee()->getActorId() === $parsedParameters['actor']['id'];
 		}
 		$cliIsActor = $parsedParameters['actor']['type'] === 'guest' &&
-			'guest/' . Attendee::ACTOR_ID_CLI === $parsedParameters['actor']['id'];
+			'guest/' . Attendee::CLI_ACTOR_ID === $parsedParameters['actor']['id'];
 
 		if ($message === 'conversation_created') {
 			$systemIsActor = $parsedParameters['actor']['type'] === 'guest' &&
-				'guest/' . Attendee::ACTOR_ID_SYSTEM === $parsedParameters['actor']['id'];
+				'guest/' . Attendee::SYSTEM_ACTOR_ID === $parsedParameters['actor']['id'];
 
 			$parsedMessage = $this->l->t('{actor} created the conversation');
 			if ($currentUserIsActor) {
@@ -655,7 +655,7 @@ protected function parseMessage(Message $chatMessage): void {
 			$parsedMessage = $this->l->t('Someone voted on the poll {poll}');
 			unset($parsedParameters['actor']);
 
-			$chatMessage->setActor(Attendee::ACTOR_GUESTS, Attendee::ACTOR_ID_SYSTEM, '');
+			$chatMessage->setActor(Attendee::ACTOR_GUESTS, Attendee::SYSTEM_ACTOR_ID, '');
 		} else {
 			throw new \OutOfBoundsException('Unknown subject');
 		}
@@ -1015,7 +1015,7 @@ protected function getGuest(Room $room, string $actorType, string $actorId): arr
 	}
 
 	protected function getGuestName(Room $room, string $actorType, string $actorId): string {
-		if ($actorId === Attendee::ACTOR_ID_CLI) {
+		if ($actorId === Attendee::CLI_ACTOR_ID) {
 			return $this->l->t('Guest');
 		}
 

lib/Chat/SystemMessage/Listener.php

@@ -428,15 +428,15 @@ protected function sendSystemMessage(Room $room, string $message, array $paramet
 			$actorId = $participant->getAttendee()->getActorId();
 		} elseif ($forceSystemAsActor) {
 			$actorType = Attendee::ACTOR_GUESTS;
-			$actorId = Attendee::ACTOR_ID_SYSTEM;
+			$actorId = Attendee::SYSTEM_ACTOR_ID;
 		} else {
 			$user = $this->userSession->getUser();
 			if ($user instanceof IUser) {
 				$actorType = Attendee::ACTOR_USERS;
 				$actorId = $user->getUID();
 			} elseif (\OC::$CLI || $this->session->exists('talk-overwrite-actor-cli')) {
 				$actorType = Attendee::ACTOR_GUESTS;
-				$actorId = Attendee::ACTOR_ID_CLI;
+				$actorId = Attendee::CLI_ACTOR_ID;
 			} elseif ($this->session->exists('talk-overwrite-actor-type')) {
 				$actorType = $this->session->get('talk-overwrite-actor-type');
 				$actorId = $this->session->get('talk-overwrite-actor-id');

lib/Controller/BotController.php

@@ -150,7 +150,7 @@ public function sendMessage(string $token, string $message, string $referenceId
 		$room = $this->manager->getRoomByToken($token);
 
 		$actorType = Attendee::ACTOR_BOTS;
-		$actorId = Attendee::ACTOR_BOT_PREFIX . $bot->getBotServer()->getUrlHash();
+		$actorId = Attendee::BOT_ACTOR_PREFIX . $bot->getBotServer()->getUrlHash();
 
 		$parent = null;
 		if ($replyTo !== 0) {
@@ -209,7 +209,7 @@ public function react(string $token, int $messageId, string $reaction): DataResp
 		$room = $this->manager->getRoomByToken($token);
 
 		$actorType = Attendee::ACTOR_BOTS;
-		$actorId = Attendee::ACTOR_BOT_PREFIX . $bot->getBotServer()->getUrlHash();
+		$actorId = Attendee::BOT_ACTOR_PREFIX . $bot->getBotServer()->getUrlHash();
 
 		try {
 			$this->reactionManager->addReactionMessage(
@@ -262,7 +262,7 @@ public function deleteReaction(string $token, int $messageId, string $reaction):
 		$room = $this->manager->getRoomByToken($token);
 
 		$actorType = Attendee::ACTOR_BOTS;
-		$actorId = Attendee::ACTOR_BOT_PREFIX . $bot->getBotServer()->getUrlHash();
+		$actorId = Attendee::BOT_ACTOR_PREFIX . $bot->getBotServer()->getUrlHash();
 
 		try {
 			$this->reactionManager->deleteReactionMessage(

lib/Model/Attendee.php

@@ -59,7 +59,8 @@
  * @method int getLastAttendeeActivity()
  */
 class Attendee extends Entity {
-	public const ACTOR_USERS = 'users';
+	public const ACTOR_USERS = 'users';lib/Chat/SystemMessage/Listener.php
+
 	public const ACTOR_GROUPS = 'groups';
 	public const ACTOR_GUESTS = 'guests';
 	public const ACTOR_EMAILS = 'emails';
@@ -70,10 +71,10 @@ class Attendee extends Entity {
 	public const ACTOR_PHONES = 'phones';
 
 	// Special actor IDs
-	public const ACTOR_BOT_PREFIX = 'bot-';
-	public const ACTOR_ID_CLI = 'cli';
-	public const ACTOR_ID_SYSTEM = 'system';
-	public const ACTOR_ID_CHANGELOG = 'changelog';
+	public const BOT_ACTOR_PREFIX = 'bot-';
+	public const CLI_ACTOR_ID = 'cli';
+	public const SYSTEM_ACTOR_ID = 'system';
+	public const CHANGELOG_ACTOR_ID = 'changelog';
 
 	public const PERMISSIONS_DEFAULT = 0;
 	public const PERMISSIONS_CUSTOM = 1;

lib/Model/BotServer.php

@@ -12,26 +12,34 @@
 use OCP\AppFramework\Db\Entity;
 
 /**
+ * @psalm-method int<1, max> getId()
  * @method void setName(string $name)
  * @method string getName()
+ * @psalm-method non-empty-string getName()
  * @method void setUrl(string $url)
  * @method string getUrl()
+ * @psalm-method non-empty-string getUrl()
  * @method void setUrlHash(string $urlHash)
  * @method string getUrlHash()
+ * @psalm-method non-empty-string getUrlHash()
  * @method void setDescription(?string $description)
  * @method null|string getDescription()
  * @method void setSecret(string $secret)
  * @method string getSecret()
+ * @psalm-method non-empty-string getSecret()
  * @method void setErrorCount(int $errorCount)
  * @method int getErrorCount()
+ * @psalm-method int<0, max> getErrorCount()
  * @method void setLastErrorDate(?\DateTimeImmutable $lastErrorDate)
- * @method ?\DateTimeImmutable getLastErrorDate()
+ * @method null|\DateTimeImmutable getLastErrorDate()
  * @method void setLastErrorMessage(string $lastErrorMessage)
  * @method string getLastErrorMessage()
  * @method void setState(int $state)
  * @method int getState()
+ * @psalm-method Bot::STATE_* getState()
  * @method void setFeatures(int $features)
  * @method int getFeatures()
+ * @psalm-method int-mask<1, 2> getFeatures()
  *
  * @psalm-import-type TalkBotWithDetailsAndSecret from ResponseDefinitions
  */
@@ -72,7 +80,7 @@ public function jsonSerialize(): array {
 			'description' => $this->getDescription(),
 			'secret' => $this->getSecret(),
 			'error_count' => $this->getErrorCount(),
-			'last_error_date' => $this->getLastErrorDate() ? $this->getLastErrorDate()->getTimestamp() : 0,
+			'last_error_date' => $this->getLastErrorDate() ? max(0, $this->getLastErrorDate()->getTimestamp()) : 0,
 			'last_error_message' => $this->getLastErrorMessage(),
 			'state' => $this->getState(),
 			'features' => $this->getFeatures(),

lib/Model/Poll.php

@@ -13,28 +13,37 @@
 use OCP\AppFramework\Db\Entity;
 
 /**
+ * @psalm-method int<1, max> getId()
  * @method void setRoomId(int $roomId)
  * @method int getRoomId()
  * @method void setQuestion(string $question)
  * @method string getQuestion()
+ * @psalm-method non-empty-string getQuestion()
  * @method void setOptions(string $options)
  * @method string getOptions()
  * @method void setVotes(string $votes)
  * @method string getVotes()
  * @method void setNumVoters(int $numVoters)
  * @method int getNumVoters()
+ * @psalm-method int<0, max> getNumVoters()
  * @method void setActorType(string $actorType)
  * @method string getActorType()
+ * @psalm-method Attendee::ACTOR_* getActorType()
  * @method void setActorId(string $actorId)
  * @method string getActorId()
+ * @psalm-method non-empty-string getActorId()
  * @method void setDisplayName(string $displayName)
  * @method string getDisplayName()
+ * @psalm-method non-empty-string getDisplayName()
  * @method void setStatus(int $status)
  * @method int getStatus()
+ * @psalm-method self::STATUS_* getStatus()
  * @method void setResultMode(int $resultMode)
  * @method int getResultMode()
+ * @psalm-method self::MODE_* getResultMode()
  * @method void setMaxVotes(int $maxVotes)
  * @method int getMaxVotes()
+ * @psalm-method int<0, max> getMaxVotes()
  *
  * @psalm-import-type TalkPoll from ResponseDefinitions
  */
@@ -80,6 +89,7 @@ public function asArray(): array {
 		// Because PHP is turning arrays with sequent numeric keys "{"0":x,"1":y,"2":z}" into "[x,y,z]"
 		// when json_encode() is used we have to prefix the keys with a string,
 		// to prevent breaking in the mobile apps.
+		/** @var array<string, int<0, max>> $prefixedVotes */
 		$prefixedVotes = [];
 		foreach ($votes as $option => $count) {
 			$prefixedVotes['option-' . $option] = $count;

lib/Model/Reminder.php

@@ -14,10 +14,13 @@
 /**
  * @method void setUserId(string $userId)
  * @method string getUserId()
+ * @psalm-method non-empty-string getUserId()
  * @method void setToken(string $token)
  * @method string getToken()
+ * @psalm-method non-empty-string getToken()
  * @method void setMessageId(int $messageId)
  * @method int getMessageId()
+ * @psalm-method int<1, max> getMessageId()
  * @method void setDateTime(\DateTime $dateTime)
  * @method \DateTime getDateTime()
  *
@@ -44,7 +47,7 @@ public function jsonSerialize(): array {
 			'userId' => $this->getUserId(),
 			'token' => $this->getToken(),
 			'messageId' => $this->getMessageId(),
-			'timestamp' => $this->getDateTime()->getTimestamp(),
+			'timestamp' => max(0, $this->getDateTime()->getTimestamp()),
 		];
 	}
 }