From 4c5128dc22af05217df9e9d044515dbf921e05dc Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Fri, 10 Nov 2023 13:22:48 +0100 Subject: [PATCH 1/4] fix(API): Add more specific int-types Signed-off-by: Joas Schilling --- lib/Controller/BreakoutRoomController.php | 7 +++- lib/Controller/CallController.php | 7 +++- lib/Controller/ChatController.php | 33 +++++++++++---- lib/Controller/FederationController.php | 2 + lib/Controller/PollController.php | 7 +++- lib/Controller/ReactionController.php | 3 ++ lib/Controller/RecordingController.php | 5 +++ lib/Controller/RoomController.php | 50 ++++++++++++++++------- lib/Controller/SettingsController.php | 2 +- lib/Controller/SignalingController.php | 1 + lib/Service/BreakoutRoomService.php | 4 +- 11 files changed, 90 insertions(+), 31 deletions(-) diff --git a/lib/Controller/BreakoutRoomController.php b/lib/Controller/BreakoutRoomController.php index 492f62342fa..297d9253197 100644 --- 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|DataResponse * diff --git a/lib/Controller/CallController.php b/lib/Controller/CallController.php index 1df85d601fb..fb3a038f65c 100644 --- 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|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|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 $flags New flags * @return DataResponse, array{}> * * 200: In-call flags updated successfully diff --git a/lib/Controller/ChatController.php b/lib/Controller/ChatController.php index 0233bbea43b..18b21c97c8d 100644 --- 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|DataResponse, 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 * * 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 * * 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|DataResponse, 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|DataResponse, 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|DataResponse, 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, 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, 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, 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 * * 200: List of shared objects messages returned diff --git a/lib/Controller/FederationController.php b/lib/Controller/FederationController.php index 0f293ae6ea3..3657bb9faea 100644 --- a/lib/Controller/FederationController.php +++ b/lib/Controller/FederationController.php @@ -61,6 +61,7 @@ public function __construct( * Accept a federation invites * * @param int $id ID of the share + * @psalm-param non-negative-int $id * @return DataResponse, array{}> * @throws UnauthorizedException * @throws DBException @@ -82,6 +83,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, array{}> * @throws UnauthorizedException * @throws DBException diff --git a/lib/Controller/PollController.php b/lib/Controller/PollController.php index 517de228bf8..762529e08e3 100644 --- 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 $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|DataResponse, 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|DataResponse, 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|DataResponse, 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|DataResponse, array{}> * * 200: Poll closed successfully diff --git a/lib/Controller/ReactionController.php b/lib/Controller/ReactionController.php index 684f9f6dd29..8ba20cc8c40 100644 --- 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|\stdClass, array{}>|DataResponse, 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|\stdClass, array{}>|DataResponse, 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|\stdClass, array{}>|DataResponse, array{}> * diff --git a/lib/Controller/RecordingController.php b/lib/Controller/RecordingController.php index 2b8a135d6b3..e612e9f3d7b 100644 --- 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|DataResponse, array{}>|DataResponse * * 200: Welcome message returned @@ -317,6 +318,7 @@ private function backendFailed(array $failed): DataResponse { * Start the recording * * @param int $status Type of the recording + * @psalm-param Room::RECORDING_* $status * @return DataResponse, array{}>|DataResponse * * 200: Recording started successfully @@ -392,6 +394,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, array{}>|DataResponse * * 200: Notification dismissed successfully @@ -416,7 +419,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, array{}>|DataResponse * * 200: Recording shared to chat successfully diff --git a/lib/Controller/RoomController.php b/lib/Controller/RoomController.php index 67736e0ee6d..a4e37316bd3 100644 --- a/lib/Controller/RoomController.php +++ b/lib/Controller/RoomController.php @@ -164,9 +164,10 @@ protected function getTalkHashHeader(): array { /** * Get all currently existent rooms which the user has joined * - * @param int $noStatusUpdate When the user status should not be automatically set to online set to 1 (default 0) + * @param 0|1 $noStatusUpdate When the user status should not be automatically set to online set to 1 (default 0) * @param bool $includeStatus Include the user status * @param int $modifiedSince Filter rooms modified after a timestamp + * @psalm-param non-negative-int $modifiedSince * @return DataResponse * * 200: Return list of rooms @@ -447,9 +448,10 @@ protected function formatRoom(Room $room, ?Participant $currentParticipant, ?arr * Create a room with a user, a group or a circle * * @param int $roomType Type of the room + * @psalm-param Room::TYPE_* $roomType * @param string $invite User, group, … ID to invite * @param string $roomName Name of the room - * @param string $source Source of the invite ID ('circles' to create a room with a circle, etc.) + * @param 'groups'|'circles'|'' $source Source of the invite ID ('circles' to create a room with a circle, etc.) * @param string $objectType Type of the object * @param string $objectId ID of the object * @return DataResponse|DataResponse|DataResponse, array{}> @@ -693,6 +695,7 @@ public function removeFromFavorites(): DataResponse { * Update the notification level for a room * * @param int $level New level + * @psalm-param Participant::NOTIFY_* $level * @return DataResponse, array{}> * * 200: Notification level updated successfully @@ -714,6 +717,7 @@ public function setNotificationLevel(int $level): DataResponse { * Update call notifications * * @param int $level New level + * @psalm-param Participant::NOTIFY_CALLS_* $level * @return DataResponse, array{}> * * 200: Call notification level updated successfully @@ -1016,7 +1020,7 @@ protected function formatParticipantList(array $participants, bool $includeStatu * Add a participant to a room * * @param string $newParticipant New participant - * @param string $source Source of the participant + * @param 'users'|'groups'|'circles'|'emails'|'remotes'|'phones' $source Source of the participant * @return DataResponse, array{}>|DataResponse, array{}>|DataResponse * * 200: Participant successfully added @@ -1030,7 +1034,7 @@ public function addParticipantToRoom(string $newParticipant, string $source = 'u if ($this->room->getType() === Room::TYPE_ONE_TO_ONE || $this->room->getType() === Room::TYPE_ONE_TO_ONE_FORMER || $this->room->getType() === Room::TYPE_NOTE_TO_SELF - || $this->room->getObjectType() === 'share:password') { + || $this->room->getObjectType() === Room::OBJECT_TYPE_VIDEO_VERIFICATION) { return new DataResponse([], Http::STATUS_BAD_REQUEST); } @@ -1256,6 +1260,7 @@ protected function removeSelfFromRoomLogic(Room $room, Participant $participant) * Remove an attendee from a room * * @param int $attendeeId ID of the attendee + * @psalm-param non-negative-int $attendeeId * @return DataResponse, array{}> * * 200: Attendee removed successfully @@ -1332,7 +1337,8 @@ public function makePrivate(): DataResponse { /** * Set read-only state of a room * - * @param int $state New read-only state + * @param 0|1 $state New read-only state + * @psalm-param Room::READ_* $state * @return DataResponse, array{}> * * 200: Read-only state updated successfully @@ -1360,7 +1366,8 @@ public function setReadOnly(int $state): DataResponse { /** * Make a room listable * - * @param int $scope Scope where the room is listable + * @param 0|1|2 $scope Scope where the room is listable + * @psalm-param Room::LISTABLE_* $scope * @return DataResponse, array{}> * * 200: Made room listable successfully @@ -1642,6 +1649,7 @@ public function createGuestByDialIn(): DataResponse { /** * Reset call ID of a dial-out participant when the SIP gateway rejected it * + * @param string $callId The call ID provided by the SIP bridge earlier to uniquely identify the call to terminate * @param array{actorId?: string, actorType?: string, attendeeId?: int} $options Additional details to verify the validity of the request * @return DataResponse, array{}> * @@ -1690,7 +1698,8 @@ public function rejectedDialOutRequest(string $callId, array $options = []): Dat /** * Set active state for a session * - * @param int $state of the room + * @param 0|1 $state of the room + * @psalm-param Session::STATE_* $state * @return DataResponse|DataResponse, array{}> * * 200: Session state set successfully @@ -1757,6 +1766,7 @@ public function leaveRoom(string $token): DataResponse { * Promote an attendee to moderator * * @param int $attendeeId ID of the attendee + * @psalm-param non-negative-int $attendeeId * @return DataResponse, array{}> * * 200: Attendee promoted to moderator successfully @@ -1774,6 +1784,7 @@ public function promoteModerator(int $attendeeId): DataResponse { * Demote an attendee from moderator * * @param int $attendeeId ID of the attendee + * @psalm-param non-negative-int $attendeeId * @return DataResponse, array{}> * * 200: Attendee demoted from moderator successfully @@ -1792,6 +1803,7 @@ public function demoteModerator(int $attendeeId): DataResponse { * attendeeId * * @param int $attendeeId + * @psalm-param non-negative-int $attendeeId * @param bool $promote Shall the attendee be promoted or demoted * @return DataResponse, array{}> */ @@ -1844,8 +1856,9 @@ protected function changeParticipantType(int $attendeeId, bool $promote): DataRe /** * Update the permissions of a room * - * @param string $mode Level of the permissions ('call', 'default') - * @param int $permissions New permissions + * @param 'call'|'default' $mode Level of the permissions ('call', 'default') + * @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 $permissions New permissions + * @psalm-param int-mask-of $permissions * @return DataResponse|DataResponse, array{}> * * 200: Permissions updated successfully @@ -1865,8 +1878,10 @@ public function setPermissions(string $mode, int $permissions): DataResponse { * Update the permissions of an attendee * * @param int $attendeeId ID of the attendee - * @param string $method Method of updating permissions ('set', 'remove', 'add') - * @param int $permissions New permissions + * @psalm-param non-negative-int $attendeeId + * @param 'set'|'remove'|'add' $method Method of updating permissions ('set', 'remove', 'add') + * @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 $permissions New permissions + * @psalm-param int-mask-of $permissions * @return DataResponse, array{}> * * 200: Permissions updated successfully @@ -1899,8 +1914,10 @@ public function setAttendeePermissions(int $attendeeId, string $method, int $per /** * Update the permissions of all attendees * - * @param string $method Method of updating permissions ('set', 'remove', 'add') - * @param int $permissions New permissions + * @param 'set'|'remove'|'add' $method Method of updating permissions ('set', 'remove', 'add') + * @psalm-param Attendee::PERMISSIONS_MODIFY_* $method + * @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 $permissions New permissions + * @psalm-param int-mask-of $permissions * @return DataResponse|DataResponse, array{}> * * 200: Permissions updated successfully @@ -1920,7 +1937,9 @@ public function setAllAttendeesPermissions(string $method, int $permissions): Da * Update the lobby state for a room * * @param int $state New state + * @psalm-param Webinary::LOBBY_* $state * @param int|null $timer Timer when the lobby will be removed + * @psalm-param non-negative-int|null $timer * @return DataResponse|DataResponse, array{}> * * 200: Lobby state updated successfully @@ -1965,7 +1984,8 @@ public function setLobby(int $state, ?int $timer = null): DataResponse { /** * Update SIP enabled state * - * @param int $state New state + * @param 0|1|2 $state New state + * @psalm-param Webinary::SIP_* $state * @return DataResponse|DataResponse, array{}> * * 200: SIP enabled state updated successfully @@ -2029,6 +2049,7 @@ public function setRecordingConsent(int $recordingConsent): DataResponse { * Resend invitations * * @param int|null $attendeeId ID of the attendee + * @psalm-param non-negative-int|null $attendeeId * @return DataResponse, array{}> * * 200: Invitation resent successfully @@ -2065,6 +2086,7 @@ public function resendInvitations(?int $attendeeId): DataResponse { * Update message expiration time * * @param int $seconds New time + * @psalm-param non-negative-int $seconds * @return DataResponse, array{}>|DataResponse * * 200: Message expiration time updated successfully diff --git a/lib/Controller/SettingsController.php b/lib/Controller/SettingsController.php index 94a224e30ce..8dafa05f9a8 100644 --- a/lib/Controller/SettingsController.php +++ b/lib/Controller/SettingsController.php @@ -62,7 +62,7 @@ public function __construct( /** * Update user setting * - * @param string $key Key to update + * @param 'attachment_folder'|'read_status_privacy'|'typing_privacy'|'play_sounds' $key Key to update * @param string|int|null $value New value for the key * @return DataResponse, array{}> * diff --git a/lib/Controller/SignalingController.php b/lib/Controller/SignalingController.php index 04de72acfb7..74247477697 100644 --- a/lib/Controller/SignalingController.php +++ b/lib/Controller/SignalingController.php @@ -227,6 +227,7 @@ public function getSettings(string $token = ''): DataResponse { * right now. * * @param int $serverId ID of the signaling server + * @psalm-param non-negative-int $serverId * @return DataResponse, array{}>|DataResponse, array{}>|DataResponse * * 200: Welcome message returned diff --git a/lib/Service/BreakoutRoomService.php b/lib/Service/BreakoutRoomService.php index 06682ca182a..834612be8d9 100644 --- a/lib/Service/BreakoutRoomService.php +++ b/lib/Service/BreakoutRoomService.php @@ -103,8 +103,8 @@ protected function parseAttendeeMap(string $map, int $max): array { /** * @param Room $parent - * @param int $mode - * @psalm-param 0|1|2|3 $mode + * @param 0|1|2|3 $mode + * @psalm-param BreakoutRoom::MODE_* $mode * @param int $amount * @param string $attendeeMap * @return Room[] From 3933d1946b69e4944f295b0ac0a089a08b656228 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Fri, 17 Nov 2023 11:11:18 +0100 Subject: [PATCH 2/4] fix(OpenAPI): Ignore federation until final Signed-off-by: Joas Schilling --- lib/Controller/FederationController.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/Controller/FederationController.php b/lib/Controller/FederationController.php index 3657bb9faea..4f1e97173ff 100644 --- a/lib/Controller/FederationController.php +++ b/lib/Controller/FederationController.php @@ -35,6 +35,7 @@ use OCA\Talk\ResponseDefinitions; use OCP\AppFramework\Db\MultipleObjectsReturnedException; use OCP\AppFramework\Http; +use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI; use OCP\AppFramework\Http\Attribute\NoAdminRequired; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\OCSController; @@ -44,8 +45,11 @@ use OCP\IUserSession; /** + * Ignored from OpenAPI until the implementation is finished and the API stable + * * @psalm-import-type TalkFederationInvite from ResponseDefinitions */ +#[IgnoreOpenAPI] class FederationController extends OCSController { public function __construct( From f736767435eb859541660b5f1d51f8c8816fdad1 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Fri, 17 Nov 2023 11:11:39 +0100 Subject: [PATCH 3/4] fix(openapi): Improve wordings of docs Signed-off-by: Joas Schilling --- lib/Controller/FilesIntegrationController.php | 2 +- lib/Controller/PublicShareAuthController.php | 2 +- lib/Controller/RoomController.php | 4 +++- lib/Controller/SettingsController.php | 2 +- lib/Controller/TempAvatarController.php | 4 ++-- 5 files changed, 8 insertions(+), 6 deletions(-) diff --git a/lib/Controller/FilesIntegrationController.php b/lib/Controller/FilesIntegrationController.php index a454d08a278..0684503b22c 100644 --- a/lib/Controller/FilesIntegrationController.php +++ b/lib/Controller/FilesIntegrationController.php @@ -135,7 +135,7 @@ public function getRoomByFileId(string $fileId): DataResponse { } /** - * Returns the token of the room associated to the file id of the given + * Returns the token of the room associated to the file of the given * share token * * This is the counterpart of self::getRoomByFileId() for share tokens diff --git a/lib/Controller/PublicShareAuthController.php b/lib/Controller/PublicShareAuthController.php index 20b16caae0a..e7bcfea07ab 100644 --- a/lib/Controller/PublicShareAuthController.php +++ b/lib/Controller/PublicShareAuthController.php @@ -54,7 +54,7 @@ public function __construct( } /** - * Creates a new room for requesting the password of a share + * Creates a new room for video verification (requesting the password of a share) * * The new room is a public room associated with a "share:password" object * with the ID of the share token. Unlike normal rooms in which the owner is diff --git a/lib/Controller/RoomController.php b/lib/Controller/RoomController.php index a4e37316bd3..2696c01e1ec 100644 --- a/lib/Controller/RoomController.php +++ b/lib/Controller/RoomController.php @@ -268,7 +268,9 @@ public function getListedRooms(string $searchTerm = ''): DataResponse { } /** - * Get all (for moderators and in case of "free selection") or the assigned breakout room + * Get breakout rooms + * + * All for moderators and in case of "free selection", or the assigned breakout room for other participants * * @return DataResponse|DataResponse * diff --git a/lib/Controller/SettingsController.php b/lib/Controller/SettingsController.php index 8dafa05f9a8..245103de216 100644 --- a/lib/Controller/SettingsController.php +++ b/lib/Controller/SettingsController.php @@ -120,7 +120,7 @@ protected function validateUserSetting(string $setting, $value): bool { } /** - * Update SIP settings + * Update SIP bridge settings * * @param string[] $sipGroups New SIP groups * @param string $dialInInfo New dial info diff --git a/lib/Controller/TempAvatarController.php b/lib/Controller/TempAvatarController.php index a1a283cc70d..f9053247158 100644 --- a/lib/Controller/TempAvatarController.php +++ b/lib/Controller/TempAvatarController.php @@ -51,7 +51,7 @@ public function __construct( } /** - * Upload a temporary avatar + * Upload your avatar as a user * * @return DataResponse, array{}>|DataResponse * @@ -125,7 +125,7 @@ public function postAvatar(): DataResponse { } /** - * Delete a temporary avatar + * Delete your avatar as a user * * @return DataResponse, array{}> * From 38cd5e8ee2f56a411d02c3c7990f0fc05c9a23d2 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Fri, 17 Nov 2023 11:19:24 +0100 Subject: [PATCH 4/4] chore(openapi): Rebuild Signed-off-by: Joas Schilling --- openapi.json | 305 +++++++-------------------------------------------- 1 file changed, 39 insertions(+), 266 deletions(-) diff --git a/openapi.json b/openapi.json index 9c22fb48923..d66e95cf006 100644 --- a/openapi.json +++ b/openapi.json @@ -6999,262 +6999,6 @@ } } }, - "/ocs/v2.php/apps/spreed/api/{apiVersion}/federation/invitation/{id}": { - "post": { - "operationId": "federation-accept-share", - "summary": "Accept a federation invites", - "tags": [ - "federation" - ], - "security": [ - { - "bearer_auth": [] - }, - { - "basic_auth": [] - } - ], - "parameters": [ - { - "name": "apiVersion", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "v1" - ], - "default": "v1" - } - }, - { - "name": "id", - "in": "path", - "description": "ID of the share", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - }, - { - "name": "OCS-APIRequest", - "in": "header", - "description": "Required to be true for the API request to pass", - "required": true, - "schema": { - "type": "boolean", - "default": true - } - } - ], - "responses": { - "200": { - "description": "Invite accepted successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "text/plain": { - "schema": { - "type": "string" - } - } - } - } - } - }, - "delete": { - "operationId": "federation-reject-share", - "summary": "Decline a federation invites", - "tags": [ - "federation" - ], - "security": [ - { - "bearer_auth": [] - }, - { - "basic_auth": [] - } - ], - "parameters": [ - { - "name": "apiVersion", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "v1" - ], - "default": "v1" - } - }, - { - "name": "id", - "in": "path", - "description": "ID of the share", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - }, - { - "name": "OCS-APIRequest", - "in": "header", - "description": "Required to be true for the API request to pass", - "required": true, - "schema": { - "type": "boolean", - "default": true - } - } - ], - "responses": { - "200": { - "description": "Invite declined successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "text/plain": { - "schema": { - "type": "string" - } - } - } - } - } - } - }, - "/ocs/v2.php/apps/spreed/api/{apiVersion}/federation/invitation": { - "get": { - "operationId": "federation-get-shares", - "summary": "Get a list of federation invites", - "tags": [ - "federation" - ], - "security": [ - { - "bearer_auth": [] - }, - { - "basic_auth": [] - } - ], - "parameters": [ - { - "name": "apiVersion", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "v1" - ], - "default": "v1" - } - }, - { - "name": "OCS-APIRequest", - "in": "header", - "description": "Required to be true for the API request to pass", - "required": true, - "schema": { - "type": "boolean", - "default": true - } - } - ], - "responses": { - "200": { - "description": "Get list of received federation invites successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FederationInvite" - } - } - } - } - } - } - } - } - } - } - } - }, "/ocs/v2.php/apps/spreed/api/{apiVersion}/file/{fileId}": { "get": { "operationId": "files_integration-get-room-by-file-id", @@ -7388,7 +7132,7 @@ "/ocs/v2.php/apps/spreed/api/{apiVersion}/publicshare/{shareToken}": { "get": { "operationId": "files_integration-get-room-by-share-token", - "summary": "Returns the token of the room associated to the file id of the given share token", + "summary": "Returns the token of the room associated to the file of the given share token", "description": "This is the counterpart of self::getRoomByFileId() for share tokens instead of file ids, although both return the same room token if the given file id and share token refer to the same file.\nIf there is no room associated to the file id of the given share token a new room is created; the new room is a public room associated with a \"file\" object with the file id of the given share token. Unlike normal rooms in which the owner is the user that created the room these are special rooms without owner (although self joined users with direct access to the file become persistent participants automatically when they join until they explicitly leave or no longer have access to the file).\nIn any case, to create or even get the token of the room, the file must be publicly shared (like a link share, for example); an error is returned otherwise.\nBesides the token of the room this also returns the current user ID and display name, if any; this is needed by the Talk sidebar to know the actual current user, as the public share page uses the incognito mode and thus logged-in users as seen as guests.", "tags": [ "files_integration" @@ -9322,7 +9066,7 @@ "/ocs/v2.php/apps/spreed/api/{apiVersion}/publicshareauth": { "post": { "operationId": "public_share_auth-create-room", - "summary": "Creates a new room for requesting the password of a share", + "summary": "Creates a new room for video verification (requesting the password of a share)", "description": "The new room is a public room associated with a \"share:password\" object with the ID of the share token. Unlike normal rooms in which the owner is the user that created the room these are special rooms always created by a guest or user on behalf of a registered user, the sharer, who will be the owner of the room.\nThe share must have \"send password by Talk\" enabled; an error is returned otherwise.", "tags": [ "public_share_auth" @@ -11701,7 +11445,8 @@ "/ocs/v2.php/apps/spreed/api/{apiVersion}/room/{token}/breakout-rooms": { "get": { "operationId": "room-get-breakout-rooms", - "summary": "Get all (for moderators and in case of \"free selection\") or the assigned breakout room", + "summary": "Get breakout rooms", + "description": "All for moderators and in case of \"free selection\", or the assigned breakout room for other participants", "tags": [ "room" ], @@ -12597,6 +12342,10 @@ "required": true, "schema": { "type": "string", + "enum": [ + "call", + "default" + ], "pattern": "^(call|default)$" } }, @@ -12832,7 +12581,15 @@ "description": "Source of the participant", "schema": { "type": "string", - "default": "users" + "default": "users", + "enum": [ + "users", + "groups", + "circles", + "emails", + "remotes", + "phones" + ] } }, { @@ -13521,7 +13278,12 @@ "description": "Method of updating permissions ('set', 'remove', 'add')", "required": true, "schema": { - "type": "string" + "type": "string", + "enum": [ + "set", + "remove", + "add" + ] } }, { @@ -13705,7 +13467,12 @@ "description": "Method of updating permissions ('set', 'remove', 'add')", "required": true, "schema": { - "type": "string" + "type": "string", + "enum": [ + "set", + "remove", + "add" + ] } }, { @@ -15728,7 +15495,7 @@ "/ocs/v2.php/apps/spreed/api/{apiVersion}/settings/sip": { "post": { "operationId": "settings-setsip-settings", - "summary": "Update SIP settings", + "summary": "Update SIP bridge settings", "description": "This endpoint requires admin access", "tags": [ "settings" @@ -15849,7 +15616,13 @@ "description": "Key to update", "required": true, "schema": { - "type": "string" + "type": "string", + "enum": [ + "attachment_folder", + "read_status_privacy", + "typing_privacy", + "play_sounds" + ] } }, { @@ -16610,7 +16383,7 @@ "/ocs/v2.php/apps/spreed/temp-user-avatar": { "post": { "operationId": "temp_avatar-post-avatar", - "summary": "Upload a temporary avatar", + "summary": "Upload your avatar as a user", "tags": [ "temp_avatar" ], @@ -16705,7 +16478,7 @@ }, "delete": { "operationId": "temp_avatar-delete-avatar", - "summary": "Delete a temporary avatar", + "summary": "Delete your avatar as a user", "tags": [ "temp_avatar" ],