Allow referees to join matches via the lazer client to spectate (#453)

* Allow referees to join matches via the lazer client to spectate

* Allow referees to perform room management actions via multiplayer hub too

* Do not allow referees to perform actions related to direct gameplay

* Document spectating-while-refereeing & its limitations

* Fix spectating referee being removed from users on leaving room inside client

* Allow referee to start match from client even when not readied up

* Fix referee's player state getting into half broken state if the room gets closed via referee commands

* Re-do referee kick/leave pathways

I realised that my previous fixes weren't going far enough and really to
avoid breakage *any* departure of the referee from their refereed room
should prompt a kick from spectate in lazer as well.

Author: bdach

osu.Server.Spectator.PublicAPIDocs/referee-hub-api.md

@@ -127,4 +127,34 @@ in cases of known failures related to user input or other cases wherein the oper
 adjusted or it is performed in a different state of the room.
 These errors are listed in [`ThrowHelper`](xref:osu.Server.Spectator.Hubs.Referee.ThrowHelper).
 
+## Spectating your match
+
+In order to facilitate spectating or streaming of the match, referees are permitted to join matches using one account
+in a dual capacity: firstly via a refereeing client in order to invoke refereeing commands, and secondly, via the lazer
+client in order to spectate the match.
+
+> [!WARNING]
+> Currently, to achieve this setup, a referee must join the room via the referee hub **first** and join the room via
+> the lazer client **second**. Attempting to perform these operations in the reverse order will not succeed.
+>
+> Similarly, disconnecting from the referee hub in any way (by leaving the room willfully, getting removed as referee,
+> or a transient disconnection), as well as closing the room, will kick the user from the room in the lazer client.
+> 
+> In other words, the spectating session in lazer should be considered **completely secondary** to the refereeing
+> session in the referee hub.
+
+In this setup:
+- Referees can perform room management actions both via the referee API and via the lazer client,
+  to identical effect.
+- Some operations available via the referee API may not be exposed in the client.
+  Currently that list includes:
+  - [banning players](xref:osu.Server.Spectator.Hubs.Referee.IRefereeHubServer.BanUser(System.Int64,System.Int32)),
+  - [adding](xref:osu.Server.Spectator.Hubs.Referee.IRefereeHubServer.AddReferee(System.Int64,System.Int32)) and
+    [removing](xref:osu.Server.Spectator.Hubs.Referee.IRefereeHubServer.RemoveReferee(System.Int64,System.Int32))
+    referees,
+  - [moving users to a given team](xref:osu.Server.Spectator.Hubs.Referee.IRefereeHubServer.MoveUser(System.Int64,osu.Server.Spectator.Hubs.Referee.Models.Requests.MoveUserRequest)),
+  - [(un)locking the room](xref:osu.Server.Spectator.Hubs.Referee.IRefereeHubServer.SetLockState(System.Int64,osu.Server.Spectator.Hubs.Referee.Models.Requests.SetLockStateRequest)).
+- Referees cannot participate in gameplay or perform actions relevant to gameplay participation, such as: readying up,
+  progressing to gameplay, joining teams, selecting user mods or user style.
+
 <!-- TODO: handling disconnections -->

osu.Server.Spectator/Extensions/MultiplayerRoomUserExtensions.cs

@@ -12,6 +12,8 @@ public static class MultiplayerRoomUserExtensions
         /// Whether a user is in a state capable of starting gameplay.
         /// </summary>
         public static bool IsReadyForGameplay(this MultiplayerRoomUser user)
-            => user.BeatmapAvailability.State == DownloadState.LocallyAvailable && (user.State == MultiplayerUserState.Ready || user.State == MultiplayerUserState.Idle);
+            => user.Role == MultiplayerRoomUserRole.Player
+               && user.BeatmapAvailability.State == DownloadState.LocallyAvailable
+               && (user.State == MultiplayerUserState.Ready || user.State == MultiplayerUserState.Idle);
     }
 }

osu.Server.Spectator/Hubs/Multiplayer/MultiplayerEventDispatcher.cs

@@ -294,6 +294,14 @@ await logToDatabase(new multiplayer_realtime_room_event
             });
         }
 
+        /// <summary>
+        /// A referee spectating the match inside the lazer client needs to be kicked from spectate.
+        /// </summary>
+        public async Task PostSpectatingRefereeKickedFromOwnMatchAsync(MultiplayerRoomUser user)
+        {
+            await multiplayerHubContext.Clients.User(user.UserID.ToString()).SendAsync(nameof(IMultiplayerClient.UserKicked), user);
+        }
+
         /// <summary>
         /// A user has been banned from the room.
         /// </summary>

osu.Server.Spectator/Hubs/Multiplayer/MultiplayerHub.cs

@@ -184,7 +184,7 @@ public async Task TransferHost(int userId)
 
                     room.Log($"Transferring host from {room.Host?.UserID} to {userId}");
 
-                    ensureIsHost(room);
+                    ensureIsHostOrReferee(room);
 
                     await room.SetHost(userId);
                 }
@@ -209,7 +209,7 @@ public async Task KickUser(int userId)
                     if (userId == userUsage.Item.UserId)
                         throw new InvalidStateException("Can't kick self");
 
-                    ensureIsHost(room);
+                    ensureIsHostOrReferee(room);
 
                     var kickTarget = room.Users.FirstOrDefault(u => u.UserID == userId);
 
@@ -325,12 +325,12 @@ public async Task SendMatchRequest(MatchUserRequest request)
                     switch (request)
                     {
                         case StartMatchCountdownRequest startMatchCountdownRequest:
-                            ensureIsHost(room);
+                            ensureIsHostOrReferee(room);
                             await room.StartMatchCountdown(startMatchCountdownRequest.Duration);
                             break;
 
                         case StopCountdownRequest stopCountdownRequest:
-                            ensureIsHost(room);
+                            ensureIsHostOrReferee(room);
                             await room.StopCountdown(stopCountdownRequest.ID);
                             break;
 
@@ -355,9 +355,9 @@ public async Task StartMatch()
                     if (room == null)
                         throw new InvalidOperationException("Attempted to operate on a null room");
 
-                    ensureIsHost(room);
+                    ensureIsHostOrReferee(room);
 
-                    if (room.Host != null && room.Host.State != MultiplayerUserState.Spectating && room.Host.State != MultiplayerUserState.Ready)
+                    if (room.Host != null && room.Host.State != MultiplayerUserState.Spectating && room.Host.State != MultiplayerUserState.Ready && room.Host.Role != MultiplayerRoomUserRole.Referee)
                         throw new InvalidStateException("Can't start match when the host is not ready.");
 
                     if (room.Users.All(u => u.State != MultiplayerUserState.Ready))
@@ -380,7 +380,7 @@ public async Task AbortMatch()
                     if (room == null)
                         throw new InvalidOperationException("Attempted to operate on a null room");
 
-                    ensureIsHost(room);
+                    ensureIsHostOrReferee(room);
 
                     await room.AbortMatch();
                 }
@@ -485,7 +485,7 @@ public async Task ChangeSettings(MultiplayerRoomSettings settings)
                     if (room == null)
                         throw new InvalidOperationException("Attempted to operate on a null room");
 
-                    ensureIsHost(room);
+                    ensureIsHostOrReferee(room);
 
                     settings.Name = await chatFilters.FilterAsync(settings.Name);
                     await room.ChangeRoomSettings(settings);
@@ -510,9 +510,12 @@ protected override async Task CleanUpState(ItemUsage<MultiplayerClientState> sta
         /// <summary>
         /// Ensure the local user is the host of the room, and throw if they are not.
         /// </summary>
-        private void ensureIsHost(MultiplayerRoom room)
+        private void ensureIsHostOrReferee(MultiplayerRoom room)
         {
-            if (room.Host?.UserID != Context.GetUserId())
+            bool isHost = room.Host?.UserID == Context.GetUserId();
+            bool isReferee = room.Users.FirstOrDefault(u => u.UserID == Context.GetUserId())?.Role == MultiplayerRoomUserRole.Referee;
+
+            if (!isHost && !isReferee)
                 throw new NotHostException();
         }
 

osu.Server.Spectator/Hubs/Multiplayer/MultiplayerRoomController.cs

@@ -73,11 +73,6 @@ private async Task<MultiplayerRoom> joinOrCreateRoom(long roomId, IMultiplayerUs
                     {
                         room = roomUsage.Item ??= await ServerMultiplayerRoom.InitialiseAsync(roomId, this, databaseFactory, eventDispatcher, loggerFactory);
 
-                        // this is a sanity check to keep *rooms* in a good state.
-                        // in theory the connection clean-up code should handle this correctly.
-                        if (room.Users.Any(u => u.UserID == roomUser.UserID))
-                            throw new InvalidOperationException($"User {roomUser.UserID} attempted to join room {room.RoomID} they are already present in.");
-
                         if (!await room.UserCanJoin(roomUser.UserID))
                             throw new InvalidStateException("Not eligible to join this room.");
 
@@ -92,7 +87,13 @@ private async Task<MultiplayerRoom> joinOrCreateRoom(long roomId, IMultiplayerUs
 
                         userState.AssociateWithRoom(roomId);
 
-                        await room.AddUser(roomUser);
+                        var existingUser = room.Users.FirstOrDefault(u => u.UserID == roomUser.UserID);
+
+                        if (existingUser == null)
+                            await room.AddUser(roomUser);
+                        else if (!isRefereeSpectatingOwnMatch(userState, existingUser))
+                            throw new InvalidOperationException($"User {roomUser.UserID} attempted to join room {room.RoomID} they are already present in.");
+
                         await userState.SubscribeToEvents(eventDispatcher, roomId);
 
                         room.Log(roomUser, "User joined");
@@ -208,7 +209,18 @@ private async Task removeUserFromRoom(IMultiplayerUserState state, ItemUsage<Ser
 
                 await state.UnsubscribeFromEvents(eventDispatcher, room.RoomID);
 
-                var user = await room.RemoveUser(state.UserId);
+                var user = room.Users.FirstOrDefault(u => u.UserID == state.UserId);
+                if (user == null)
+                    throw new InvalidStateException("User is not in the room.");
+
+                if (isRefereeSpectatingOwnMatch(state, user))
+                {
+                    await eventDispatcher.PostSpectatingRefereeKickedFromOwnMatchAsync(user);
+                    return;
+                }
+
+                await room.RemoveUser(state.UserId);
+
                 bool wasKick = removingUserId != user.UserID;
                 room.Log(user, wasKick ? "User kicked" : "User left");
 
@@ -254,6 +266,14 @@ private async Task removeUserFromRoom(IMultiplayerUserState state, ItemUsage<Ser
             }
         }
 
+        /// <remarks>
+        /// We want to allow exceptions wherein existing referees can also join their refereed rooms via the client to spectate them.
+        /// In that case, hook up all associations but don't add/remove the user in the room model.
+        /// Notably this flow requires the user to join as referee <i>first</i> and as spectator in client <i>second</i>.
+        /// </remarks>
+        private static bool isRefereeSpectatingOwnMatch(IMultiplayerUserState state, MultiplayerRoomUser user)
+            => user.Role == MultiplayerRoomUserRole.Referee && state is MultiplayerClientState;
+
         private async Task endMatch(MultiplayerRoom room, int disbandingUserId)
         {
             using (var db = databaseFactory.GetInstance())

osu.Server.Spectator/Hubs/Multiplayer/ServerMultiplayerRoom.cs

@@ -358,7 +358,7 @@ public async Task AddUser(MultiplayerRoomUser user)
         /// </summary>
         /// <returns>The <see cref="MultiplayerRoomUser"/> who was removed.</returns>
         /// <exception cref="InvalidStateException">The user with the supplied <paramref name="userId"/> was not in the room.</exception>
-        public async Task<MultiplayerRoomUser> RemoveUser(int userId)
+        public async Task RemoveUser(int userId)
         {
             var user = Users.FirstOrDefault(u => u.UserID == userId);
 
@@ -373,7 +373,6 @@ public async Task<MultiplayerRoomUser> RemoveUser(int userId)
 
             await MatchController.HandleUserLeft(user);
             await UpdateRoomStateIfRequired();
-            return user;
         }
 
         /// <summary>
@@ -463,7 +462,7 @@ public async Task ChangeUserState(int userId, MultiplayerUserState newState)
 
             Log(user, $"User changing state from {user.State} to {newState}");
 
-            ensureValidStateSwitch(user.State, newState);
+            ensureValidStateSwitch(user.Role, user.State, newState);
 
             await ChangeAndBroadcastUserState(user, newState);
 
@@ -480,9 +479,10 @@ public async Task ChangeUserState(int userId, MultiplayerUserState newState)
         /// <summary>
         /// Given this room and a state transition, throw if there's an issue with the sequence of events.
         /// </summary>
+        /// <param name="userRole">The user's role.</param>
         /// <param name="oldState">The old state.</param>
         /// <param name="newState">The new state.</param>
-        private void ensureValidStateSwitch(MultiplayerUserState oldState, MultiplayerUserState newState)
+        private void ensureValidStateSwitch(MultiplayerRoomUserRole userRole, MultiplayerUserState oldState, MultiplayerUserState newState)
         {
             switch (newState)
             {
@@ -541,6 +541,13 @@ private void ensureValidStateSwitch(MultiplayerUserState oldState, MultiplayerUs
                 default:
                     throw new ArgumentOutOfRangeException(nameof(newState), newState, null);
             }
+
+            if (userRole == MultiplayerRoomUserRole.Referee
+                && newState != MultiplayerUserState.Idle
+                && newState != MultiplayerUserState.Spectating)
+            {
+                throw new InvalidStateException("Referees cannot participate in the match.");
+            }
         }
 
         public async Task ChangeAndBroadcastUserState(MultiplayerRoomUser user, MultiplayerUserState state)
@@ -619,6 +626,9 @@ public async Task ChangeUserStyle(int userId, int? beatmapId, int? rulesetId)
             if (user == null)
                 throw new InvalidStateException("User is not in the room.");
 
+            if (user.Role == MultiplayerRoomUserRole.Referee)
+                throw new InvalidStateException("Referees do not participate in the match and cannot set their own style.");
+
             await changeUserStyle(user, beatmapId, rulesetId);
         }
 
@@ -681,6 +691,9 @@ public async Task ChangeUserMods(int userId, IEnumerable<APIMod> newMods)
             if (user == null)
                 throw new InvalidStateException("User is not in the room.");
 
+            if (user.Role == MultiplayerRoomUserRole.Referee)
+                throw new InvalidStateException("Referees do not participate in the match and cannot set their own mods.");
+
             await changeUserMods(user, newMods);
         }
 
@@ -919,6 +932,9 @@ public async Task VoteToSkipIntro(int userId)
             if (user == null)
                 throw new InvalidStateException("User is not in the room.");
 
+            if (user.Role == MultiplayerRoomUserRole.Referee)
+                throw new InvalidStateException("Referees do not participate in the match and cannot vote to skip.");
+
             if (!user.State.IsGameplayState())
                 throw new InvalidStateException("Cannot skip while not in gameplay.");
 

osu.Server.Spectator/Hubs/Multiplayer/Standard/StandardMatchController.cs

@@ -133,6 +133,9 @@ public virtual Task HandleUserStateChanged(MultiplayerRoomUser user)
             return Task.CompletedTask;
         }
 
+        private bool isHostOrReferee(MultiplayerRoomUser user)
+            => user.Equals(room.Host) || user.Role == MultiplayerRoomUserRole.Referee;
+
         /// <summary>
         /// Add a playlist item to the room's queue.
         /// </summary>
@@ -143,12 +146,11 @@ public virtual Task HandleUserStateChanged(MultiplayerRoomUser user)
         public virtual async Task AddPlaylistItem(MultiplayerPlaylistItem item, MultiplayerRoomUser user)
         {
             bool isHostOnly = room.Settings.QueueMode == QueueMode.HostOnly;
-            bool isHostOrReferee = user.Equals(room.Host) || user.Role == MultiplayerRoomUserRole.Referee;
 
-            if (isHostOnly && !isHostOrReferee)
+            if (isHostOnly && !isHostOrReferee(user))
                 throw new NotHostException();
 
-            int limit = isHostOrReferee ? HOST_PLAYLIST_LIMIT : GUEST_PLAYLIST_LIMIT;
+            int limit = isHostOrReferee(user) ? HOST_PLAYLIST_LIMIT : GUEST_PLAYLIST_LIMIT;
 
             if (room.Playlist.Count(i => i.OwnerID == user.UserID && !i.Expired) >= limit)
                 throw new InvalidStateException($"Can't enqueue more than {limit} items at once.");
@@ -218,8 +220,7 @@ public virtual async Task EditPlaylistItem(MultiplayerPlaylistItem item, Multipl
                 if (existingItem == null)
                     throw new InvalidStateException("Attempted to change an item that doesn't exist.");
 
-                bool isHostOrReferee = user.Equals(room.Host) || user.Role == MultiplayerRoomUserRole.Referee;
-                if (existingItem.OwnerID != user.UserID && !isHostOrReferee)
+                if (existingItem.OwnerID != user.UserID && !isHostOrReferee(user))
                     throw new InvalidStateException("Attempted to change an item which is not owned by the user.");
 
                 if (existingItem.Expired)
@@ -243,7 +244,6 @@ public virtual async Task EditPlaylistItem(MultiplayerPlaylistItem item, Multipl
         public virtual async Task RemovePlaylistItem(long playlistItemId, MultiplayerRoomUser user)
         {
             var item = room.Playlist.FirstOrDefault(item => item.ID == playlistItemId);
-            bool isHostOrReferee = user.Equals(room.Host) || user.Role == MultiplayerRoomUserRole.Referee;
 
             if (item == null)
                 throw new InvalidStateException("Item does not exist in the room.");
@@ -258,7 +258,7 @@ public virtual async Task RemovePlaylistItem(long playlistItemId, MultiplayerRoo
                     throw new InvalidStateException("The current item in the room cannot be removed when currently being played.");
             }
 
-            if (item.OwnerID != user.UserID && !isHostOrReferee)
+            if (item.OwnerID != user.UserID && !isHostOrReferee(user))
                 throw new InvalidStateException("Attempted to remove an item which is not owned by the user.");
 
             if (item.Expired)