Allow specifying list of user ids in SocketGuild.DownloadUsersAsync

src/Discord.Net.Core/Entities/Guilds/IGuild.cs

@@ -959,6 +959,17 @@ public interface IGuild : IDeletable, ISnowflakeEntity
         /// </returns>
         Task DownloadUsersAsync();
         /// <summary>
+        ///     Downloads specific users for this guild.
+        /// </summary>
+        /// <remarks>
+        ///     This method downloads all users specified in <paramref name="userIds" /> through the Gateway and caches them.
+        /// </remarks>
+        /// <param name="userIds">The list of Discord user IDs to download</param>
+        /// <returns>
+        ///     A task that represents the asynchronous download operation.
+        /// </returns>
+        Task DownloadUsersAsync(IEnumerable<ulong> userIds);
+        /// <summary>
         ///     Prunes inactive users.
         /// </summary>
         /// <remarks>

src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs

@@ -1512,6 +1512,10 @@ async Task<IReadOnlyCollection<IGuildUser>> IGuild.GetUsersAsync(CacheMode mode,
         Task IGuild.DownloadUsersAsync() =>
             throw new NotSupportedException();
         /// <inheritdoc />
+        /// <exception cref="NotSupportedException">Downloading users is not supported for a REST-based guild.</exception>
+        Task IGuild.DownloadUsersAsync(IEnumerable<ulong> userIds) =>
+            throw new NotSupportedException();
+        /// <inheritdoc />
         async Task<IReadOnlyCollection<IGuildUser>> IGuild.SearchUsersAsync(string query, int limit, CacheMode mode, RequestOptions options)
         {
             if (mode == CacheMode.AllowDownload)
@@ -1604,7 +1608,7 @@ async Task<IAutoModRule[]> IGuild.GetAutoModRulesAsync(RequestOptions options)
         /// <inheritdoc/>
         async Task<IAutoModRule> IGuild.CreateAutoModRuleAsync(Action<AutoModRuleProperties> props, RequestOptions options)
             => await CreateAutoModRuleAsync(props, options).ConfigureAwait(false);
-        
+
         /// <inheritdoc/>
         async Task<IGuildOnboarding> IGuild.GetOnboardingAsync(RequestOptions options)
             => await GetOnboardingAsync(options);

src/Discord.Net.WebSocket/API/Gateway/GuildMembersChunkEvent.cs

@@ -1,4 +1,5 @@
 using Newtonsoft.Json;
+using System.Collections.Generic;
 
 namespace Discord.API.Gateway
 {
@@ -8,5 +9,15 @@ internal class GuildMembersChunkEvent
         public ulong GuildId { get; set; }
         [JsonProperty("members")]
         public GuildMember[] Members { get; set; }
+        [JsonProperty("chunk_index")]
+        public int ChunkIndex { get; set; }
+        [JsonProperty("chunk_count")]
+        public int ChunkCount { get; set; }
+        [JsonProperty("not_found")]
+        public Optional<IEnumerable<ulong>> NotFound { get; set; }
+        [JsonProperty("presences")]
+        public Optional<IEnumerable<Presence>> Presences { get; set; }
+        [JsonProperty("nonce")]
+        public Optional<string> Nonce { get; set; }
     }
 }

src/Discord.Net.WebSocket/API/Gateway/RequestMembersParams.cs

@@ -6,12 +6,17 @@ namespace Discord.API.Gateway
     [JsonObject(MemberSerialization = MemberSerialization.OptIn)]
     internal class RequestMembersParams
     {
+        [JsonProperty("guild_id")]
+        public ulong GuildId { get; set; }
         [JsonProperty("query")]
-        public string Query { get; set; }
+        public Optional<string> Query { get; set; }
         [JsonProperty("limit")]
         public int Limit { get; set; }
-
-        [JsonProperty("guild_id")]
-        public IEnumerable<ulong> GuildIds { get; set; }
+        [JsonProperty("presences")]
+        public Optional<bool> Presences { get; set; }
+        [JsonProperty("user_ids")]
+        public Optional<IEnumerable<ulong>> UserIds { get; set; }
+        [JsonProperty("nonce")]
+        public Optional<string> Nonce { get; set; }
     }
 }

src/Discord.Net.WebSocket/BaseSocketClient.cs

@@ -235,6 +235,15 @@ private static DiscordSocketApiClient CreateApiClient(DiscordSocketConfig config
         ///     A task that represents the asynchronous download operation.
         /// </returns>
         public abstract Task DownloadUsersAsync(IEnumerable<IGuild> guilds);
+        /// <summary>
+        ///     Attempts to download specific users into the user cache for the selected guild.
+        /// </summary>
+        /// <param name="guild">The guild to download the members from.</param>
+        /// <param name="userIds">The list of Discord user IDs to download.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous download operation.
+        /// </returns>
+        public abstract Task DownloadUsersAsync(IGuild guild, IEnumerable<ulong> userIds);
 
         /// <summary>
         ///     Creates a guild for the logged-in user who is in less than 10 active guilds.

src/Discord.Net.WebSocket/DiscordShardedClient.cs

@@ -381,6 +381,24 @@ public override async Task DownloadUsersAsync(IEnumerable<IGuild> guilds)
             }
         }
 
+        /// <inheritdoc />
+        /// <exception cref="ArgumentNullException"><paramref name="guild"/> is <see langword="null"/></exception>
+        public override async Task DownloadUsersAsync(IGuild guild, IEnumerable<ulong> userIds)
+        {
+            if (guild == null)
+                throw new ArgumentNullException(nameof(guild));
+
+            for (int i = 0; i < _shards.Length; i++)
+            {
+                int id = _shardIds[i];
+                if (GetShardIdFor(guild) == id)
+                {
+                    await _shards[i].DownloadUsersAsync(guild, userIds).ConfigureAwait(false);
+                    break;
+                }
+            }
+        }
+
         private int GetLatency()
         {
             int total = 0;

src/Discord.Net.WebSocket/DiscordSocketApiClient.cs

@@ -379,11 +379,24 @@ public async Task SendPresenceUpdateAsync(UserStatus status, bool isAFK, long? s
             options.BucketId = GatewayBucket.Get(GatewayBucketType.PresenceUpdate).Id;
             await SendGatewayAsync(GatewayOpCode.PresenceUpdate, args, options: options).ConfigureAwait(false);
         }
-        public async Task SendRequestMembersAsync(IEnumerable<ulong> guildIds, RequestOptions options = null)
+        public async Task SendRequestMembersAsync(ulong guildId, RequestOptions options = null)
         {
             options = RequestOptions.CreateOrClone(options);
-            await SendGatewayAsync(GatewayOpCode.RequestGuildMembers, new RequestMembersParams { GuildIds = guildIds, Query = "", Limit = 0 }, options: options).ConfigureAwait(false);
+            await SendGatewayAsync(GatewayOpCode.RequestGuildMembers, new RequestMembersParams { GuildId = guildId, Query = "", Limit = 0 }, options: options).ConfigureAwait(false);
         }
+        public async Task SendRequestMembersAsync(ulong guildId, IEnumerable<ulong> userIds, string nonce, RequestOptions options = null)
+        {
+            var payload = new RequestMembersParams
+            {
+                GuildId = guildId,
+                Limit = 0,
+                UserIds = new Optional<IEnumerable<ulong>>(userIds),
+                Nonce = nonce
+            };
+            options = RequestOptions.CreateOrClone(options);
+            await SendGatewayAsync(GatewayOpCode.RequestGuildMembers, payload, options: options).ConfigureAwait(false);
+        }
+
         public async Task SendVoiceStateUpdateAsync(ulong guildId, ulong? channelId, bool selfDeaf, bool selfMute, RequestOptions options = null)
         {
             var payload = new VoiceStateUpdateParams

src/Discord.Net.WebSocket/DiscordSocketClient.cs

@@ -37,6 +37,7 @@ public partial class DiscordSocketClient : BaseSocketClient, IDiscordClient
         private readonly ConnectionManager _connection;
         private readonly Logger _gatewayLogger;
         private readonly SemaphoreSlim _stateLock;
+        private readonly ConcurrentDictionary<string, TaskCompletionSource<bool>> _guildMembersRequestTasks;
 
         private string _sessionId;
         private int _lastSeq;
@@ -51,6 +52,7 @@ public partial class DiscordSocketClient : BaseSocketClient, IDiscordClient
         private GatewayIntents _gatewayIntents;
         private ImmutableArray<StickerPack<SocketSticker>> _defaultStickers;
         private SocketSelfUser _previousSessionUser;
+        private long _guildMembersRequestCounter;
 
         /// <summary>
         ///     Provides access to a REST-only client with a shared state from this client.
@@ -183,6 +185,8 @@ private DiscordSocketClient(DiscordSocketConfig config, API.DiscordSocketApiClie
                 e.ErrorContext.Handled = true;
             };
 
+            _guildMembersRequestTasks = new ConcurrentDictionary<string, TaskCompletionSource<bool>>();
+
             ApiClient.SentGatewayMessage += async opCode => await _gatewayLogger.DebugAsync($"Sent {opCode}").ConfigureAwait(false);
             ApiClient.ReceivedGatewayEvent += ProcessMessageAsync;
 
@@ -627,30 +631,36 @@ private async Task ProcessUserDownloadsAsync(IEnumerable<SocketGuild> guilds)
         {
             var cachedGuilds = guilds.ToImmutableArray();
 
-            const short batchSize = 1;
-            ulong[] batchIds = new ulong[Math.Min(batchSize, cachedGuilds.Length)];
-            Task[] batchTasks = new Task[batchIds.Length];
-            int batchCount = (cachedGuilds.Length + (batchSize - 1)) / batchSize;
+            foreach (var guild in cachedGuilds)
+            {
+                await ApiClient.SendRequestMembersAsync(guild.Id).ConfigureAwait(false);
+                await guild.DownloaderPromise.ConfigureAwait(false);
+            }
+        }
 
-            for (int i = 0, k = 0; i < batchCount; i++)
+        /// <inheritdoc />
+        public override async Task DownloadUsersAsync(IGuild guild, IEnumerable<ulong> userIds)
+        {
+            if (ConnectionState == ConnectionState.Connected)
             {
-                bool isLast = i == batchCount - 1;
-                int count = isLast ? (cachedGuilds.Length - (batchCount - 1) * batchSize) : batchSize;
+                EnsureGatewayIntent(GatewayIntents.GuildMembers);
 
-                for (int j = 0; j < count; j++, k++)
+                var socketGuild = GetGuild(guild.Id);
+                if (socketGuild != null)
                 {
-                    var guild = cachedGuilds[k];
-                    batchIds[j] = guild.Id;
-                    batchTasks[j] = guild.DownloaderPromise;
+                    await ProcessUserDownloadsAsync(socketGuild, userIds).ConfigureAwait(false);
                 }
+            }
+        }
 
-                await ApiClient.SendRequestMembersAsync(batchIds).ConfigureAwait(false);
 
-                if (isLast && batchCount > 1)
-                    await Task.WhenAll(batchTasks.Take(count)).ConfigureAwait(false);
-                else
-                    await Task.WhenAll(batchTasks).ConfigureAwait(false);
-            }
+        private async Task ProcessUserDownloadsAsync(SocketGuild guild, IEnumerable<ulong> userIds)
+        {
+            var nonce = Interlocked.Increment(ref _guildMembersRequestCounter).ToString();
+            var tcs = new TaskCompletionSource<bool>();
+            _guildMembersRequestTasks.TryAdd(nonce, tcs);
+            await ApiClient.SendRequestMembersAsync(guild.Id, userIds, nonce).ConfigureAwait(false);
+            await tcs.Task.ConfigureAwait(false);
         }
 
         /// <inheritdoc />
@@ -1410,6 +1420,13 @@ private async Task ProcessMessageAsync(GatewayOpCode opCode, int? seq, string ty
                                             guild.CompleteDownloadUsers();
                                             await TimedInvokeAsync(_guildMembersDownloadedEvent, nameof(GuildMembersDownloaded), guild).ConfigureAwait(false);
                                         }
+
+                                        if (data.Nonce.IsSpecified
+                                            && data.ChunkIndex + 1 >= data.ChunkCount
+                                            && _guildMembersRequestTasks.TryRemove(data.Nonce.Value, out var tcs))
+                                        {
+                                            tcs.TrySetResult(true);
+                                        }
                                     }
                                     else
                                     {
@@ -2904,7 +2921,7 @@ private async Task ProcessMessageAsync(GatewayOpCode opCode, int? seq, string ty
                             }
                             break;
                             #endregion
-                            
+
                             #region Auto Moderation
 
                             case "AUTO_MODERATION_RULE_CREATE":

src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs

@@ -383,7 +383,7 @@ public IReadOnlyCollection<SocketCustomSticker> Stickers
         ///         </para>
         ///         <para>
         ///             Otherwise, you may need to enable <see cref="DiscordSocketConfig.AlwaysDownloadUsers"/> to fetch
-        ///             the full user list upon startup, or use <see cref="DownloadUsersAsync"/> to manually download
+        ///             the full user list upon startup, or use <see cref="DownloadUsersAsync()"/> to manually download
         ///             the users.
         ///         </para>
         ///     </note>
@@ -1260,6 +1260,13 @@ public async Task DownloadUsersAsync()
         {
             await Discord.DownloadUsersAsync(new[] { this }).ConfigureAwait(false);
         }
+
+        /// <inheritdoc />
+        public async Task DownloadUsersAsync(IEnumerable<ulong> userIds)
+        {
+            await Discord.DownloadUsersAsync(this, userIds).ConfigureAwait(false);
+        }
+
         internal void CompleteDownloadUsers()
         {
             _downloaderPromise.TrySetResultAsync(true);
@@ -1406,7 +1413,7 @@ public Task<RestGuildEvent> CreateEventAsync(
         /// <returns>
         ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
         ///     of the requested audit log entries.
-        /// </returns>        
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<RestAuditLogEntry>> GetAuditLogsAsync(int limit, RequestOptions options = null, ulong? beforeId = null, ulong? userId = null, ActionType? actionType = null, ulong? afterId = null)
             => GuildHelper.GetAuditLogsAsync(this, Discord, beforeId, limit, options, userId: userId, actionType: actionType, afterId: afterId);