fix(API): Add more specific int-types

Signed-off-by: Joas Schilling <coding@schilljs.com>
nextcloud · Nov 10, 2023 · 9534481 · 9534481
1 parent cc3d699
commit 9534481
Show file tree

Hide file tree

Showing 10 changed files with 88 additions and 30 deletions.
diff --git a/lib/Controller/BreakoutRoomController.php b/lib/Controller/BreakoutRoomController.php
@@ -30,6 +30,7 @@
 use OCA\Talk\Exceptions\ParticipantNotFoundException;
 use OCA\Talk\Middleware\Attribute\RequireLoggedInModeratorParticipant;
 use OCA\Talk\Middleware\Attribute\RequireLoggedInParticipant;
+use OCA\Talk\Model\BreakoutRoom;
 use OCA\Talk\ResponseDefinitions;
 use OCA\Talk\Service\BreakoutRoomService;
 use OCA\Talk\Service\ParticipantService;
@@ -58,8 +59,10 @@ public function __construct(
 	/**
 	 * Configure the breakout rooms
 	 *
-	 * @param int $mode Mode of the breakout rooms
-	 * @param int $amount Number of breakout rooms
+	 * @param 0|1|2|3 $mode Mode of the breakout rooms
+	 * @psalm-param BreakoutRoom::MODE_* $mode
+	 * @param 1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20 $amount Number of breakout rooms
+	 * @psalm-param int<1, 20> $amount Constants {@see BreakoutRoom::MINIMUM_ROOM_AMOUNT} and {@see BreakoutRoom::MAXIMUM_ROOM_AMOUNT}
 	 * @param string $attendeeMap Mapping of the attendees to breakout rooms
 	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *

diff --git a/lib/Controller/CallController.php b/lib/Controller/CallController.php
@@ -119,8 +119,10 @@ public function getPeersForCall(): DataResponse {
 	/**
 	 * Join a call
 	 *
-	 * @param int|null $flags In-Call flags
-	 * @param int|null $forcePermissions In-call permissions
+	 * @param 0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|null $flags In-Call flags
+	 * @psalm-param int-mask-of<Participant::FLAG_*>|null $flags
+	 * @param 0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64|65|66|67|68|69|70|71|72|73|74|75|76|77|78|79|80|81|82|83|84|85|86|87|88|89|90|91|92|93|94|95|96|97|98|99|100|101|102|103|104|105|106|107|108|109|110|111|112|113|114|115|116|117|118|119|120|121|122|123|124|125|126|127|128|129|130|131|132|133|134|135|136|137|138|139|140|141|142|143|144|145|146|147|148|149|150|151|152|153|154|155|156|157|158|159|160|161|162|163|164|165|166|167|168|169|170|171|172|173|174|175|176|177|178|179|180|181|182|183|184|185|186|187|188|189|190|191|192|193|194|195|196|197|198|199|200|201|202|203|204|205|206|207|208|209|210|211|212|213|214|215|216|217|218|219|220|221|222|223|224|225|226|227|228|229|230|231|232|233|234|235|236|237|238|239|240|241|242|243|244|245|246|247|248|249|250|251|252|253|254|255|null $forcePermissions In-call permissions
+	 * @psalm-param int-mask-of<Attendee::PERMISSIONS_*>|null $forcePermissions
 	 * @param bool $silent Join the call silently
 	 * @param bool $recordingConsent When the user ticked a checkbox and agreed with being recorded
 	 *  (Only needed when the `config => call => recording-consent` capability is set to {@see RecordingService::CONSENT_REQUIRED_YES}
@@ -248,6 +250,7 @@ public function sipDialOut(int $attendeeId): DataResponse {
 	 * Update the in-call flags
 	 *
 	 * @param int $flags New flags
+	 * @psalm-param int-mask-of<Participant::FLAG_*> $flags New flags
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
 	 * 200: In-call flags updated successfully

diff --git a/lib/Controller/ChatController.php b/lib/Controller/ChatController.php
@@ -177,6 +177,7 @@ protected function parseCommentToResponse(IComment $comment, Message $parentMess
 	 * @param string $actorDisplayName for guests
 	 * @param string $referenceId for the message to be able to later identify it again
 	 * @param int $replyTo Parent id which this message is a reply to
+	 * @psalm-param non-negative-int $replyTo
 	 * @param bool $silent If sent silent the chat message will not create any notifications
 	 * @return DataResponse<Http::STATUS_CREATED, ?TalkChatMessageWithParent, array{X-Chat-Last-Common-Read?: numeric-string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array<empty>, array{}>
 	 *
@@ -361,18 +362,21 @@ protected function preloadShares(array $comments): void {
 	 * returned, but it should be used nevertheless as the $lastKnownMessageId
 	 * for the follow-up query.
 	 *
-	 * @param int $lookIntoFuture Polling for new messages (1) or getting the history of the chat (0)
+	 * @param 0|1 $lookIntoFuture Polling for new messages (1) or getting the history of the chat (0)
 	 * @param int $limit Number of chat messages to receive (100 by default, 200 at most)
 	 * @param int $lastKnownMessageId The last known message (serves as offset)
+	 * @psalm-param non-negative-int $lastKnownMessageId
 	 * @param int $lastCommonReadId The last known common read message
 	 *                              (so the response is 200 instead of 304 when
 	 *                              it changes even when there are no messages)
-	 * @param int $timeout Number of seconds to wait for new messages (30 by default, 30 at most)
-	 * @param int $setReadMarker Automatically set the last read marker when 1,
+	 * @psalm-param non-negative-int $lastCommonReadId
+	 * @param 0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30 $timeout Number of seconds to wait for new messages (30 by default, 30 at most)
+	 * @psalm-param int<0, 30> $timeout
+	 * @param 0|1 $setReadMarker Automatically set the last read marker when 1,
 	 *                           if your client does this itself via chat/{token}/read set to 0
-	 * @param int $includeLastKnown Include the $lastKnownMessageId in the messages when 1 (default 0)
-	 * @param int $noStatusUpdate When the user status should not be automatically set to online set to 1 (default 0)
-	 * @param int $markNotificationsAsRead Set to 0 when notifications should not be marked as read (default 1)
+	 * @param 0|1 $includeLastKnown Include the $lastKnownMessageId in the messages when 1 (default 0)
+	 * @param 0|1 $noStatusUpdate When the user status should not be automatically set to online set to 1 (default 0)
+	 * @param 0|1 $markNotificationsAsRead Set to 0 when notifications should not be marked as read (default 1)
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_MODIFIED, TalkChatMessageWithParent[], array{X-Chat-Last-Common-Read?: numeric-string, X-Chat-Last-Given?: string}>
 	 *
 	 * 200: Messages returned
@@ -581,7 +585,9 @@ protected function prepareCommentsAsDataResponse(array $comments, int $lastCommo
 	 * Get the context of a message
 	 *
 	 * @param int $messageId The focused message which should be in the "middle" of the returned context
-	 * @param int $limit Number of chat messages to receive in both directions (50 by default, 100 at most, might return 201 messages)
+	 * @psalm-param non-negative-int $messageId
+	 * @param 1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64|65|66|67|68|69|70|71|72|73|74|75|76|77|78|79|80|81|82|83|84|85|86|87|88|89|90|91|92|93|94|95|96|97|98|99|100 $limit Number of chat messages to receive in both directions (50 by default, 100 at most, might return 201 messages)
+	 * @psalm-param int<1, 100> $limit
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_MODIFIED, TalkChatMessageWithParent[], array{X-Chat-Last-Common-Read?: numeric-string, X-Chat-Last-Given?: string}>
 	 *
 	 * 200: Message context returned
@@ -651,6 +657,7 @@ protected function loadSelfReactions(array $messages, array $commentIdToIndex):
 	 * Delete a chat message
 	 *
 	 * @param int $messageId ID of the message
+	 * @psalm-param non-negative-int $messageId
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_ACCEPTED, TalkChatMessageWithParent, array{X-Chat-Last-Common-Read?: numeric-string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND|Http::STATUS_METHOD_NOT_ALLOWED, array<empty>, array{}>
 	 *
 	 * 200: Message deleted successfully
@@ -732,7 +739,9 @@ public function deleteMessage(int $messageId): DataResponse {
 	 * Set a reminder for a chat message
 	 *
 	 * @param int $messageId ID of the message
+	 * @psalm-param non-negative-int $messageId
 	 * @param int $timestamp Timestamp of the reminder
+	 * @psalm-param non-negative-int $timestamp
 	 * @return DataResponse<Http::STATUS_CREATED, TalkChatReminder, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
 	 * 201: Reminder created successfully
@@ -763,6 +772,7 @@ public function setReminder(int $messageId, int $timestamp): DataResponse {
 	 * Get the reminder for a chat message
 	 *
 	 * @param int $messageId ID of the message
+	 * @psalm-param non-negative-int $messageId
 	 * @return DataResponse<Http::STATUS_OK, TalkChatReminder, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
 	 * 200: Reminder returned
@@ -794,6 +804,7 @@ public function getReminder(int $messageId): DataResponse {
 	 * Delete a chat reminder
 	 *
 	 * @param int $messageId ID of the message
+	 * @psalm-param non-negative-int $messageId
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
 	 * 200: Reminder deleted successfully
@@ -864,6 +875,7 @@ public function clearHistory(): DataResponse {
 	 * Set the read marker to a specific message
 	 *
 	 * @param int $lastReadMessage ID if the last read message
+	 * @psalm-param non-negative-int $lastReadMessage
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{X-Chat-Last-Common-Read?: numeric-string}>
 	 *
 	 * 200: Read marker set successfully
@@ -913,7 +925,8 @@ public function markUnread(): DataResponse {
 	/**
 	 * Get objects that are shared in the room overview
 	 *
-	 * @param int $limit Maximum number of objects
+	 * @param 1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20 $limit Maximum number of objects
+	 * @psalm-param int<1, 20> $limit
 	 * @return DataResponse<Http::STATUS_OK, array<string, TalkChatMessage[]>, array{}>
 	 *
 	 * 200: List of shared objects messages of each type returned
@@ -965,7 +978,9 @@ public function getObjectsSharedInRoomOverview(int $limit = 7): DataResponse {
 	 *
 	 * @param string $objectType Type of the objects
 	 * @param int $lastKnownMessageId ID of the last known message
-	 * @param int $limit Maximum number of objects
+	 * @psalm-param non-negative-int $lastKnownMessageId
+	 * @param 1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64|65|66|67|68|69|70|71|72|73|74|75|76|77|78|79|80|81|82|83|84|85|86|87|88|89|90|91|92|93|94|95|96|97|98|99|100|101|102|103|104|105|106|107|108|109|110|111|112|113|114|115|116|117|118|119|120|121|122|123|124|125|126|127|128|129|130|131|132|133|134|135|136|137|138|139|140|141|142|143|144|145|146|147|148|149|150|151|152|153|154|155|156|157|158|159|160|161|162|163|164|165|166|167|168|169|170|171|172|173|174|175|176|177|178|179|180|181|182|183|184|185|186|187|188|189|190|191|192|193|194|195|196|197|198|199|200 $limit Maximum number of objects
+	 * @psalm-param int<1, 200> $limit
 	 * @return DataResponse<Http::STATUS_OK, TalkChatMessage[], array{X-Chat-Last-Given?: string}>
 	 *
 	 * 200: List of shared objects messages returned

diff --git a/lib/Controller/FederationController.php b/lib/Controller/FederationController.php
@@ -65,6 +65,7 @@ public function __construct(
 	 * Accept a federation invites
 	 *
 	 * @param int $id ID of the share
+	 * @psalm-param non-negative-int $id
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws UnauthorizedException
 	 * @throws DBException
@@ -86,6 +87,7 @@ public function acceptShare(int $id): DataResponse {
 	 * Decline a federation invites
 	 *
 	 * @param int $id ID of the share
+	 * @psalm-param non-negative-int $id
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws UnauthorizedException
 	 * @throws DBException

diff --git a/lib/Controller/PollController.php b/lib/Controller/PollController.php
@@ -71,7 +71,9 @@ public function __construct(
 	 *
 	 * @param string $question Question of the poll
 	 * @param string[] $options Options of the poll
-	 * @param int $resultMode Mode how the results will be shown
+	 * @psalm-param list<string> $options
+	 * @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{}>
 	 *
@@ -132,6 +134,7 @@ public function createPoll(string $question, array $options, int $resultMode, in
 	 * Get a poll
 	 *
 	 * @param int $pollId ID of the poll
+	 * @psalm-param non-negative-int $pollId
 	 * @return DataResponse<Http::STATUS_OK, TalkPoll, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
 	 * 200: Poll returned
@@ -160,6 +163,7 @@ public function showPoll(int $pollId): DataResponse {
 	 * Vote on a poll
 	 *
 	 * @param int $pollId ID of the poll
+	 * @psalm-param non-negative-int $pollId
 	 * @param int[] $optionIds IDs of the selected options
 	 * @return DataResponse<Http::STATUS_OK, TalkPoll, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
@@ -213,6 +217,7 @@ public function votePoll(int $pollId, array $optionIds = []): DataResponse {
 	 * Close a poll
 	 *
 	 * @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{}>
 	 *
 	 * 200: Poll closed successfully

diff --git a/lib/Controller/ReactionController.php b/lib/Controller/ReactionController.php
@@ -58,6 +58,7 @@ public function __construct(
 	 * Add a reaction to a message
 	 *
 	 * @param int $messageId ID of the message
+	 * @psalm-param non-negative-int $messageId
 	 * @param string $reaction Emoji to add
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_CREATED, array<string, TalkReaction[]>|\stdClass, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
@@ -96,6 +97,7 @@ public function react(int $messageId, string $reaction): DataResponse {
 	 * Delete a reaction from a message
 	 *
 	 * @param int $messageId ID of the message
+	 * @psalm-param non-negative-int $messageId
 	 * @param string $reaction Emoji to remove
 	 * @return DataResponse<Http::STATUS_OK, array<string, TalkReaction[]>|\stdClass, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
@@ -131,6 +133,7 @@ public function delete(int $messageId, string $reaction): DataResponse {
 	 * Get a list of reactions for a message
 	 *
 	 * @param int $messageId ID of the message
+	 * @psalm-param non-negative-int $messageId
 	 * @param string|null $reaction Emoji to filter
 	 * @return DataResponse<Http::STATUS_OK, array<string, TalkReaction[]>|\stdClass, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *

diff --git a/lib/Controller/RecordingController.php b/lib/Controller/RecordingController.php
@@ -71,6 +71,7 @@ public function __construct(
 	 * Get the welcome message of a recording server
 	 *
 	 * @param int $serverId ID of the server
+	 * @psalm-param non-negative-int $serverId
 	 * @return DataResponse<Http::STATUS_OK, array{version: float}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}>
 	 *
 	 * 200: Welcome message returned
@@ -318,6 +319,7 @@ private function backendFailed(array $failed): DataResponse {
 	 * Start the recording
 	 *
 	 * @param int $status Type of the recording
+	 * @psalm-param Room::RECORDING_* $status
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Recording started successfully
@@ -394,6 +396,7 @@ public function store(string $owner): DataResponse {
 	 * Dismiss the store call recording notification
 	 *
 	 * @param int $timestamp Timestamp of the notification to be dismissed
+	 * @psalm-param non-negative-int $timestamp
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Notification dismissed successfully
@@ -418,7 +421,9 @@ public function notificationDismiss(int $timestamp): DataResponse {
 	 * Share the recorded file to the chat
 	 *
 	 * @param int $fileId ID of the file
+	 * @psalm-param non-negative-int $fileId
 	 * @param int $timestamp Timestamp of the notification to be dismissed
+	 * @psalm-param non-negative-int $timestamp
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Recording shared to chat successfully