fix(session): tie directory ownership to the live connection

Ownership is claimed with a Lua check-and-set keyed on the instance holding the websocket, routing prefers a live controller over a local copy, the session list deduplicates by owner, removal is ownership-checked, undelivered routed messages surface, single-session lookups stop scanning the keyspace and directory writes leave the request path bounded by a timeout.
2026-09-24 23:50:01 +10:00
parent 6f362c33c9
commit 9e66708d87
17 changed files with 613 additions and 123 deletions
@@ -1,5 +1,6 @@
 using System;
 using System.Text.Json;
+using System.Threading;
 using System.Threading.Tasks;
 using Jellyfin.Extensions.Json;
 using MediaBrowser.Controller.Session;
@@ -16,6 +17,8 @@ public sealed class RedisPodMessageBus : IPodMessageBus
 {
    private const string ChannelPrefix = "jellyfin:pod:";

+    private static readonly TimeSpan _publishTimeout = TimeSpan.FromSeconds(5);
+
    private static readonly JsonSerializerOptions _jsonOptions = JsonDefaults.Options;

    private readonly ISubscriber _subscriber;
@@ -39,7 +42,7 @@ public sealed class RedisPodMessageBus : IPodMessageBus
    public string PodId { get; }

    /// <inheritdoc />
-    public void Publish(string targetPod, PodMessage message)
+    public async Task<long> PublishAsync(string targetPod, PodMessage message, CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrEmpty(targetPod);
        ArgumentNullException.ThrowIfNull(message);
@@ -48,14 +51,14 @@ public sealed class RedisPodMessageBus : IPodMessageBus

        try
        {
-            _subscriber.Publish(
+            return await _subscriber.PublishAsync(
                RedisChannel.Literal(ChannelPrefix + targetPod),
-                JsonSerializer.Serialize(message, _jsonOptions),
-                CommandFlags.FireAndForget);
+                JsonSerializer.Serialize(message, _jsonOptions)).WaitAsync(_publishTimeout, cancellationToken).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Failed to send a {Kind} message to {TargetPod}.", message.Kind, targetPod);
+            return 0;
        }
    }

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using System.Linq;
 using System.Text.Json;
 using System.Threading;
@@ -13,12 +14,47 @@ using StackExchange.Redis;
 namespace Emby.Server.Implementations.Session;

 /// <summary>
-/// A Redis-backed <see cref="ISessionDirectory"/>. Each entry is a key with an expiry, so the sessions of
-/// an instance that stops refreshing them disappear on their own.
+/// A Redis-backed <see cref="ISessionDirectory"/>. A session is owned by the instance holding its
+/// connection: ownership is claimed through a check-and-set, so an instance that only served a request
+/// for the session cannot take it from the instance the device is actually connected to. Each entry is a
+/// key with an expiry, so the sessions of an instance that stops refreshing them disappear on their own.
 /// </summary>
 public sealed class RedisSessionDirectory : ISessionDirectory
 {
    private const string KeyPrefix = "jellyfin:session:";
+    private const string OwnerKeyPrefix = "jellyfin:sessionowner:";
+
+    /// <summary>
+    /// Lua script for an atomic ownership claim. The owner key holds <c>pod|connectedTicks</c>, where
+    /// the ticks are zero for an instance that holds no connection. A claim by another instance is
+    /// refused unless its connection is newer than the recorded one, so the instance holding the live
+    /// connection keeps ownership however many requests the others serve.
+    /// </summary>
+    private const string ClaimScript = @"
+local current = redis.call('GET', KEYS[1])
+if current then
+    local separator = string.find(current, '|', 1, true)
+    local owner = string.sub(current, 1, separator - 1)
+    local connected = tonumber(string.sub(current, separator + 1))
+    if owner ~= ARGV[1] and connected > 0 and tonumber(ARGV[2]) <= connected then
+        return 0
+    end
+end
+redis.call('SET', KEYS[1], ARGV[1] .. '|' .. ARGV[2], 'PX', ARGV[4])
+redis.call('SET', KEYS[2], ARGV[3], 'PX', ARGV[4])
+return 1";
+
+    /// <summary>
+    /// Lua script for an atomic, ownership-checked removal, so that an instance ending its own copy of a
+    /// session cannot erase the entry of the instance still holding the connection.
+    /// </summary>
+    private const string ReleaseScript = @"
+local current = redis.call('GET', KEYS[1])
+if not current then return 0 end
+local separator = string.find(current, '|', 1, true)
+if string.sub(current, 1, separator - 1) ~= ARGV[1] then return 0 end
+redis.call('DEL', KEYS[1], KEYS[2])
+return 1";

    private static readonly JsonSerializerOptions _jsonOptions = JsonDefaults.Options;

@@ -47,35 +83,52 @@ public sealed class RedisSessionDirectory : ISessionDirectory
        _logger = logger;
    }

-    private TimeSpan EntryTtl => TimeSpan.FromSeconds(Math.Max(1, _options.EntryTtlSeconds));
+    private long EntryTtlMs => Math.Max(1, _options.EntryTtlSeconds) * 1000L;
+
+    private TimeSpan OperationTimeout => TimeSpan.FromSeconds(Math.Max(1, _options.OperationTimeoutSeconds));

    /// <inheritdoc />
-    public async Task PublishAsync(SessionDirectoryEntry entry, CancellationToken cancellationToken = default)
+    public async Task<bool> PublishAsync(SessionDirectoryEntry entry, long connectedUtcTicks, CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(entry);

        var sessionId = entry.Session?.Id;
        if (string.IsNullOrEmpty(sessionId))
        {
-            return;
+            return false;
        }

        try
        {
-            await _db.StringSetAsync(KeyPrefix + sessionId, JsonSerializer.Serialize(entry, _jsonOptions), EntryTtl).ConfigureAwait(false);
+            var claimed = (long?)await _db.ScriptEvaluateAsync(
+                ClaimScript,
+                keys: new RedisKey[] { OwnerKeyPrefix + sessionId, KeyPrefix + sessionId },
+                values: new RedisValue[]
+                {
+                    entry.OwnerPod,
+                    connectedUtcTicks.ToString(CultureInfo.InvariantCulture),
+                    JsonSerializer.Serialize(entry, _jsonOptions),
+                    EntryTtlMs
+                }).WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);
+
+            return claimed == 1;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Failed to publish session {SessionId}; it stays invisible to the other instances.", sessionId);
+            return false;
        }
    }

    /// <inheritdoc />
-    public async Task RemoveAsync(string sessionId, CancellationToken cancellationToken = default)
+    public async Task RemoveAsync(string sessionId, string ownerPod, CancellationToken cancellationToken = default)
    {
        try
        {
-            await _db.KeyDeleteAsync(KeyPrefix + sessionId).ConfigureAwait(false);
+            await _db.ScriptEvaluateAsync(
+                ReleaseScript,
+                keys: new RedisKey[] { OwnerKeyPrefix + sessionId, KeyPrefix + sessionId },
+                values: new RedisValue[] { ownerPod }).WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
@@ -83,6 +136,22 @@ public sealed class RedisSessionDirectory : ISessionDirectory
        }
    }

+    /// <inheritdoc />
+    public async Task<SessionDirectoryEntry?> GetAsync(string sessionId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var raw = await _db.StringGetAsync(KeyPrefix + sessionId).WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);
+
+            return raw.HasValue ? Deserialize(raw) : null;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to read session {SessionId} from the directory.", sessionId);
+            return null;
+        }
+    }
+
    /// <inheritdoc />
    public async Task<IReadOnlyList<SessionDirectoryEntry>> GetAllAsync(CancellationToken cancellationToken = default)
    {
@@ -103,7 +172,8 @@ public sealed class RedisSessionDirectory : ISessionDirectory
                    keys.Add(key);
                }

-                var values = await Task.WhenAll(keys.Select(key => _db.StringGetAsync(key))).ConfigureAwait(false);
+                var values = await Task.WhenAll(keys.Select(key => _db.StringGetAsync(key)))
+                    .WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);

                foreach (var raw in values)
                {
@@ -112,17 +182,10 @@ public sealed class RedisSessionDirectory : ISessionDirectory
                        continue;
                    }

-                    try
+                    var entry = Deserialize(raw);
+                    if (entry?.Session is not null)
                    {
-                        var entry = JsonSerializer.Deserialize<SessionDirectoryEntry>(raw.ToString(), _jsonOptions);
-                        if (entry?.Session is not null)
-                        {
-                            entries.Add(entry);
-                        }
-                    }
-                    catch (JsonException ex)
-                    {
-                        _logger.LogWarning(ex, "Failed to deserialize a session directory entry.");
+                        entries.Add(entry);
                    }
                }
            }
@@ -136,4 +199,17 @@ public sealed class RedisSessionDirectory : ISessionDirectory

        return entries;
    }
+
+    private SessionDirectoryEntry? Deserialize(RedisValue raw)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize<SessionDirectoryEntry>(raw.ToString(), _jsonOptions);
+        }
+        catch (JsonException ex)
+        {
+            _logger.LogWarning(ex, "Failed to deserialize a session directory entry.");
+            return null;
+        }
+    }
 }
@@ -1,10 +1,13 @@
 using System;
+using System.Globalization;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
 using Jellyfin.Extensions.Json;
+using MediaBrowser.Common.Extensions;
 using MediaBrowser.Controller.Session;
 using MediaBrowser.Model.Session;
+using Microsoft.Extensions.Logging;

 namespace Emby.Server.Implementations.Session;

@@ -15,6 +18,7 @@ namespace Emby.Server.Implementations.Session;
 public sealed class RemoteSessionController : ISessionController
 {
    private readonly IPodMessageBus _bus;
+    private readonly ILogger _logger;
    private readonly string _ownerPod;
    private readonly string _sessionId;

@@ -22,27 +26,27 @@ public sealed class RemoteSessionController : ISessionController
    /// Initializes a new instance of the <see cref="RemoteSessionController"/> class.
    /// </summary>
    /// <param name="bus">The cross-instance bus.</param>
+    /// <param name="logger">The logger.</param>
    /// <param name="ownerPod">The instance holding the connection.</param>
    /// <param name="sessionId">The session identifier.</param>
-    /// <param name="isSessionActive">Whether the owner reported the session as active.</param>
    /// <param name="supportsMediaControl">Whether the owner reported the session as controllable.</param>
-    public RemoteSessionController(IPodMessageBus bus, string ownerPod, string sessionId, bool isSessionActive, bool supportsMediaControl)
+    public RemoteSessionController(IPodMessageBus bus, ILogger logger, string ownerPod, string sessionId, bool supportsMediaControl)
    {
        _bus = bus;
+        _logger = logger;
        _ownerPod = ownerPod;
        _sessionId = sessionId;
-        IsSessionActive = isSessionActive;
        SupportsMediaControl = supportsMediaControl;
    }

    /// <inheritdoc />
-    public bool IsSessionActive { get; }
+    public bool IsSessionActive => true;

    /// <inheritdoc />
    public bool SupportsMediaControl { get; }

    /// <inheritdoc />
-    public Task SendMessage<T>(SessionMessageType name, Guid messageId, T data, CancellationToken cancellationToken)
+    public async Task SendMessage<T>(SessionMessageType name, Guid messageId, T data, CancellationToken cancellationToken)
    {
        var routed = new RoutedSessionMessage
        {
@@ -52,14 +56,21 @@ public sealed class RemoteSessionController : ISessionController
            Data = JsonSerializer.Serialize(data, JsonDefaults.Options)
        };

-        _bus.Publish(
+        var delivered = await _bus.PublishAsync(
            _ownerPod,
            new PodMessage
            {
                Kind = RoutedSessionMessage.Kind,
                Payload = JsonSerializer.Serialize(routed, JsonDefaults.Options)
-            });
+            },
+            cancellationToken).ConfigureAwait(false);

-        return Task.CompletedTask;
+        if (delivered == 0)
+        {
+            _logger.LogWarning("Instance {OwnerPod} holds session {SessionId} but is not listening; the {MessageType} message was not delivered.", _ownerPod, _sessionId, name);
+
+            throw new ResourceNotFoundException(
+                string.Format(CultureInfo.InvariantCulture, "The instance holding session {0} is unreachable.", _sessionId));
+        }
    }
 }
@@ -71,6 +71,9 @@ namespace Emby.Server.Implementations.Session
        private readonly ConcurrentDictionary<string, SessionInfo> _activeConnections
            = new(StringComparer.OrdinalIgnoreCase);

+        private readonly ConcurrentDictionary<string, long> _connectionEpochs = new(StringComparer.Ordinal);
+        private readonly ConcurrentDictionary<string, long> _lastDirectoryPublish = new(StringComparer.Ordinal);
+
        private readonly ConcurrentDictionary<string, ConcurrentDictionary<string, string>> _activeLiveStreamSessions
            = new(StringComparer.OrdinalIgnoreCase);

@@ -316,13 +319,13 @@ namespace Emby.Server.Implementations.Session
                    });
            }

-            await PublishToDirectoryAsync(session).ConfigureAwait(false);
+            QueueDirectoryPublish(session);

            return session;
        }

        /// <inheritdoc />
-        public void OnSessionControllerConnected(SessionInfo session)
+        public async Task OnSessionControllerConnected(SessionInfo session)
        {
            EventHelper.QueueEventIfNotNull(
                SessionControllerConnected,
@@ -333,9 +336,32 @@ namespace Emby.Server.Implementations.Session
                },
                _logger);

-            // The session only becomes remote-controllable once it has a connection, so the other
-            // instances have to be told again now that it does.
-            _ = PublishToDirectoryAsync(session);
+            // Ownership of the session belongs to whichever instance holds its connection, so this one
+            // claims it before the connection is used.
+            _lastDirectoryPublish[session.Id] = Environment.TickCount64;
+            await PublishToDirectoryAsync(session).ConfigureAwait(false);
+        }
+
+        // Keeps the directory write off the request path: the caller does not wait for Redis, and a
+        // session reporting playback every few seconds does not write on every report.
+        private void QueueDirectoryPublish(SessionInfo session)
+        {
+            if (!_directoryEnabled || string.IsNullOrEmpty(session.Id))
+            {
+                return;
+            }
+
+            var now = Environment.TickCount64;
+            var throttleMs = Math.Max(1000L, _sessionDirectoryOptions.RefreshIntervalSeconds * 500L);
+            var scheduled = _lastDirectoryPublish.AddOrUpdate(
+                session.Id,
+                now,
+                (_, last) => now - last >= throttleMs ? now : last);
+
+            if (scheduled == now)
+            {
+                _ = PublishToDirectoryAsync(session);
+            }
        }

        private async Task PublishToDirectoryAsync(SessionInfo session)
@@ -347,12 +373,16 @@ namespace Emby.Server.Implementations.Session

            try
            {
+                var connectedUtcTicks = GetConnectionEpoch(session);
+
                await _sessionDirectory.PublishAsync(
                    new SessionDirectoryEntry
                    {
                        OwnerPod = _podMessageBus.PodId,
+                        HoldsConnection = connectedUtcTicks > 0,
                        Session = ToSessionInfoDto(session)
-                    }).ConfigureAwait(false);
+                    },
+                    connectedUtcTicks).ConfigureAwait(false);
            }
            catch (Exception ex)
            {
@@ -360,14 +390,30 @@ namespace Emby.Server.Implementations.Session
            }
        }

+        // Ownership follows the connection, not the last request served: an instance without a live
+        // controller claims with epoch zero, which never displaces an instance that has one.
+        private long GetConnectionEpoch(SessionInfo session)
+        {
+            if (!session.SessionControllers.Any(i => i.IsSessionActive))
+            {
+                _connectionEpochs.TryRemove(session.Id, out _);
+                return 0;
+            }
+
+            return _connectionEpochs.GetOrAdd(session.Id, _ => DateTime.UtcNow.Ticks);
+        }
+
        private async ValueTask RemoveFromDirectoryAsync(SessionInfo session)
        {
+            _connectionEpochs.TryRemove(session.Id, out _);
+            _lastDirectoryPublish.TryRemove(session.Id, out _);
+
            if (!_directoryEnabled || string.IsNullOrEmpty(session.Id))
            {
                return;
            }

-            await _sessionDirectory.RemoveAsync(session.Id).ConfigureAwait(false);
+            await _sessionDirectory.RemoveAsync(session.Id, _podMessageBus.PodId).ConfigureAwait(false);
        }

        private async void RefreshSessionDirectory(object state)
@@ -402,10 +448,15 @@ namespace Emby.Server.Implementations.Session

        private async Task<SessionInfo> GetRemoteSession(string sessionId)
        {
-            var entries = await GetRemoteEntriesAsync(CancellationToken.None).ConfigureAwait(false);
-            var entry = entries.FirstOrDefault(i => string.Equals(i.Session.Id, sessionId, StringComparison.Ordinal));
+            if (!_directoryEnabled)
+            {
+                return null;
+            }

-            if (entry is null)
+            var entry = await _sessionDirectory.GetAsync(sessionId).ConfigureAwait(false);
+
+            if (entry?.Session is null
+                || string.Equals(entry.OwnerPod, _podMessageBus.PodId, StringComparison.Ordinal))
            {
                return null;
            }
@@ -428,18 +479,30 @@ namespace Emby.Server.Implementations.Session
                Capabilities = dto.Capabilities?.ToClientCapabilities()
            };

-            session.AddController(new RemoteSessionController(_podMessageBus, entry.OwnerPod, dto.Id, dto.IsActive, dto.SupportsMediaControl));
+            if (entry.HoldsConnection)
+            {
+                session.AddController(new RemoteSessionController(_podMessageBus, _logger, entry.OwnerPod, dto.Id, dto.SupportsMediaControl));
+            }

            return session;
        }

-        private async Task OnPodMessage(PodMessage message)
+        private Task OnPodMessage(PodMessage message)
        {
-            if (!string.Equals(message.Kind, RoutedSessionMessage.Kind, StringComparison.Ordinal))
+            switch (message.Kind)
            {
-                return;
+                case RoutedSessionMessage.Kind:
+                    return OnRoutedSessionMessage(message);
+                case RoutedAdditionalUserChange.Kind:
+                    OnRoutedAdditionalUserChange(message);
+                    return Task.CompletedTask;
+                default:
+                    return Task.CompletedTask;
            }
+        }

+        private async Task OnRoutedSessionMessage(PodMessage message)
+        {
            var routed = JsonSerializer.Deserialize<RoutedSessionMessage>(message.Payload, JsonDefaults.Options);
            if (routed is null)
            {
@@ -447,19 +510,46 @@ namespace Emby.Server.Implementations.Session
            }

            var session = Sessions.FirstOrDefault(i => string.Equals(i.Id, routed.SessionId, StringComparison.Ordinal));
-            if (session is null)
+            var controllers = session?.SessionControllers.Where(i => i.IsSessionActive).ToList();
+
+            if (controllers is null || controllers.Count == 0)
            {
-                _logger.LogDebug("Session {Session} was routed here but is no longer held by this instance.", routed.SessionId);
+                _logger.LogWarning(
+                    "A {MessageType} message for session {Session} was routed to this instance, which no longer holds its connection.",
+                    routed.MessageType,
+                    routed.SessionId);
                return;
            }

            using var data = JsonDocument.Parse(routed.Data);
-            foreach (var controller in session.SessionControllers)
+            foreach (var controller in controllers)
            {
                await controller.SendMessage(routed.MessageType, routed.MessageId, data.RootElement, CancellationToken.None).ConfigureAwait(false);
            }
        }

+        private void OnRoutedAdditionalUserChange(PodMessage message)
+        {
+            var routed = JsonSerializer.Deserialize<RoutedAdditionalUserChange>(message.Payload, JsonDefaults.Options);
+            var session = routed is null
+                ? null
+                : Sessions.FirstOrDefault(i => string.Equals(i.Id, routed.SessionId, StringComparison.Ordinal));
+
+            if (session is null)
+            {
+                return;
+            }
+
+            if (routed.Add)
+            {
+                AttachAdditionalUser(session, routed.UserId, _userManager.GetUserById(routed.UserId)?.Username);
+            }
+            else
+            {
+                DetachAdditionalUser(session, routed.UserId);
+            }
+        }
+
        /// <inheritdoc />
        public async Task CloseIfNeededAsync(SessionInfo session)
        {
@@ -1375,12 +1465,18 @@ namespace Emby.Server.Implementations.Session
            return session;
        }

-        // A session held by another instance is reachable too: the returned SessionInfo carries a
-        // controller that forwards to its owner instead of writing to a local connection.
+        // A local SessionInfo without a live controller is a copy left behind by a request this instance
+        // happened to serve, not the connection: prefer the owner named by the directory over it.
        private async Task<SessionInfo> GetSessionToRemoteControl(string sessionId)
        {
-            var session = Sessions.FirstOrDefault(i => string.Equals(i.Id, sessionId, StringComparison.Ordinal))
-                ?? await GetRemoteSession(sessionId).ConfigureAwait(false);
+            var local = Sessions.FirstOrDefault(i => string.Equals(i.Id, sessionId, StringComparison.Ordinal));
+
+            if (local is not null && local.SessionControllers.Any(i => i.IsSessionActive))
+            {
+                return local;
+            }
+
+            var session = await GetRemoteSession(sessionId).ConfigureAwait(false) ?? local;

            if (session is null)
            {
@@ -1583,7 +1679,16 @@ namespace Emby.Server.Implementations.Session
        public async Task SendSyncPlayCommand(string sessionId, SendCommand command, CancellationToken cancellationToken)
        {
            CheckDisposed();
-            var session = GetSession(sessionId);
+
+            // SyncPlay group membership is instance-local, so a session listed by another instance is not
+            // reachable from here. It is skipped rather than reported as missing.
+            var session = GetSession(sessionId, false);
+            if (session is null)
+            {
+                _logger.LogDebug("SyncPlay command for session {Session} dropped; it is not held by this instance.", sessionId);
+                return;
+            }
+
            await SendMessageToSession(session, SessionMessageType.SyncPlayCommand, command, cancellationToken).ConfigureAwait(false);
        }

@@ -1591,7 +1696,14 @@ namespace Emby.Server.Implementations.Session
        public async Task SendSyncPlayGroupUpdate<T>(string sessionId, GroupUpdate<T> command, CancellationToken cancellationToken)
        {
            CheckDisposed();
-            var session = GetSession(sessionId);
+
+            var session = GetSession(sessionId, false);
+            if (session is null)
+            {
+                _logger.LogDebug("SyncPlay group update for session {Session} dropped; it is not held by this instance.", sessionId);
+                return;
+            }
+
            await SendMessageToSession(session, SessionMessageType.SyncPlayGroupUpdate, command, cancellationToken).ConfigureAwait(false);
        }

@@ -1764,17 +1876,18 @@ namespace Emby.Server.Implementations.Session
        /// <param name="controllingSessionId">The controlling session identifier.</param>
        /// <param name="sessionId">The session identifier.</param>
        /// <param name="userId">The user identifier.</param>
+        /// <returns>A task representing the operation.</returns>
        /// <exception cref="SecurityException">The controlling user is not allowed to attach the user to the session.</exception>
        /// <exception cref="ArgumentException">The requested user is already the primary user of the session.</exception>
-        public void AddAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
+        public async Task AddAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
        {
            CheckDisposed();

-            var session = GetSession(sessionId);
+            var session = await GetSessionToRemoteControl(sessionId).ConfigureAwait(false);

            if (!string.IsNullOrEmpty(controllingSessionId))
            {
-                var controllingSession = GetSession(controllingSessionId);
+                var controllingSession = await GetSessionToRemoteControl(controllingSessionId).ConfigureAwait(false);
                AssertCanControl(session, controllingSession);
                AssertCanAttachUser(controllingSession, userId);
            }
@@ -1784,18 +1897,16 @@ namespace Emby.Server.Implementations.Session
                throw new ArgumentException("The requested user is already the primary user of the session.");
            }

-            if (session.AdditionalUsers.All(i => !i.UserId.Equals(userId)))
-            {
-                var user = _userManager.GetUserById(userId)
-                    ?? throw new ArgumentException("The requested user does not exist.");
-                var newUser = new SessionUserInfo
-                {
-                    UserId = userId,
-                    UserName = user.Username
-                };
+            var user = _userManager.GetUserById(userId)
+                ?? throw new ArgumentException("The requested user does not exist.");

-                session.AdditionalUsers = [.. session.AdditionalUsers, newUser];
+            var local = GetSession(sessionId, false);
+            if (local is not null)
+            {
+                AttachAdditionalUser(local, userId, user.Username);
            }
+
+            await RouteAdditionalUserChange(sessionId, userId, true).ConfigureAwait(false);
        }

        /// <summary>
@@ -1804,17 +1915,18 @@ namespace Emby.Server.Implementations.Session
        /// <param name="controllingSessionId">The controlling session identifier.</param>
        /// <param name="sessionId">The session identifier.</param>
        /// <param name="userId">The user identifier.</param>
+        /// <returns>A task representing the operation.</returns>
        /// <exception cref="SecurityException">The controlling user is not allowed to control the session.</exception>
        /// <exception cref="ArgumentException">The requested user is already the primary user of the session.</exception>
-        public void RemoveAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
+        public async Task RemoveAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
        {
            CheckDisposed();

-            var session = GetSession(sessionId);
+            var session = await GetSessionToRemoteControl(sessionId).ConfigureAwait(false);

            if (!string.IsNullOrEmpty(controllingSessionId))
            {
-                AssertCanControl(session, GetSession(controllingSessionId));
+                AssertCanControl(session, await GetSessionToRemoteControl(controllingSessionId).ConfigureAwait(false));
            }

            if (session.UserId.Equals(userId))
@@ -1822,17 +1934,73 @@ namespace Emby.Server.Implementations.Session
                throw new ArgumentException("The requested user is already the primary user of the session.");
            }

-            var user = session.AdditionalUsers.FirstOrDefault(i => i.UserId.Equals(userId));
+            var local = GetSession(sessionId, false);
+            if (local is not null)
+            {
+                DetachAdditionalUser(local, userId);
+            }

-            if (user is not null)
+            await RouteAdditionalUserChange(sessionId, userId, false).ConfigureAwait(false);
+        }
+
+        private static void AttachAdditionalUser(SessionInfo session, Guid userId, string userName)
+        {
+            if (session.AdditionalUsers.All(i => !i.UserId.Equals(userId)))
+            {
+                session.AdditionalUsers = [.. session.AdditionalUsers, new SessionUserInfo { UserId = userId, UserName = userName }];
+            }
+        }
+
+        private static void DetachAdditionalUser(SessionInfo session, Guid userId)
+        {
+            var existing = session.AdditionalUsers.FirstOrDefault(i => i.UserId.Equals(userId));
+
+            if (existing is not null)
            {
                var list = session.AdditionalUsers.ToList();
-                list.Remove(user);
+                list.Remove(existing);

                session.AdditionalUsers = list.ToArray();
            }
        }

+        // The owner is the instance whose copy of the session is the one everyone else is shown, so the
+        // change has to be applied there as well as on whichever instance served the request.
+        private async Task RouteAdditionalUserChange(string sessionId, Guid userId, bool add)
+        {
+            if (!_directoryEnabled)
+            {
+                return;
+            }
+
+            var entry = await _sessionDirectory.GetAsync(sessionId).ConfigureAwait(false);
+
+            if (entry is null || string.Equals(entry.OwnerPod, _podMessageBus.PodId, StringComparison.Ordinal))
+            {
+                return;
+            }
+
+            var payload = new RoutedAdditionalUserChange
+            {
+                SessionId = sessionId,
+                UserId = userId,
+                Add = add
+            };
+
+            var delivered = await _podMessageBus.PublishAsync(
+                entry.OwnerPod,
+                new PodMessage
+                {
+                    Kind = RoutedAdditionalUserChange.Kind,
+                    Payload = JsonSerializer.Serialize(payload, JsonDefaults.Options)
+                }).ConfigureAwait(false);
+
+            if (delivered == 0)
+            {
+                _logger.LogWarning("Instance {OwnerPod} holds session {Session} but is not listening; the additional user change was not applied there.", entry.OwnerPod, sessionId);
+            }
+        }
+
        /// <summary>
        /// Authenticates the new session.
        /// </summary>
@@ -2227,8 +2395,12 @@ namespace Emby.Server.Implementations.Session
            CancellationToken cancellationToken)
        {
            var remote = await GetRemoteEntriesAsync(cancellationToken).ConfigureAwait(false);
+            var ownedElsewhere = remote.Select(entry => entry.Session.Id).ToHashSet(StringComparer.Ordinal);

+            // A session this instance only holds a copy of is reported by its owner, whose controllers are
+            // the ones that decide whether it is active and controllable.
            IEnumerable<SessionInfoDto> result = Sessions
+                .Where(i => !ownedElsewhere.Contains(i.Id))
                .Select(ToSessionInfoDto)
                .Concat(remote.Select(entry => entry.Session))
                .OrderByDescending(i => i.LastActivityDate);
@@ -114,11 +114,11 @@ namespace Emby.Server.Implementations.Session
        public async Task ProcessWebSocketConnectedAsync(IWebSocketConnection connection, HttpContext httpContext)
        {
            var session = await RequestHelpers.GetSession(_sessionManager, _userManager, httpContext).ConfigureAwait(false);
-            EnsureController(session, connection);
+            await EnsureController(session, connection).ConfigureAwait(false);
            await KeepAliveWebSocket(connection).ConfigureAwait(false);
        }

-        private void EnsureController(SessionInfo session, IWebSocketConnection connection)
+        private async Task EnsureController(SessionInfo session, IWebSocketConnection connection)
        {
            var controllerInfo = session.EnsureController<WebSocketController>(
                s => new WebSocketController(_loggerFactory.CreateLogger<WebSocketController>(), s, _sessionManager));
@@ -126,7 +126,7 @@ namespace Emby.Server.Implementations.Session
            var controller = (WebSocketController)controllerInfo.Item1;
            controller.AddWebSocket(connection);

-            _sessionManager.OnSessionControllerConnected(session);
+            await _sessionManager.OnSessionControllerConnected(session).ConfigureAwait(false);
        }

        /// <summary>