Release 6.4.2

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 6.4.2
+__05.10.2024__
+
+- bug: Prevent caches from growing forever.
+
 ## 6.4.1
 __04.10.2024__
 

lib/src/api_options.dart

@@ -6,7 +6,7 @@ import 'package:oauth2/oauth2.dart';
 /// Options for connecting to the Discord API.
 abstract class ApiOptions {
   /// The version of nyxx used in [defaultUserAgent].
-  static const nyxxVersion = '6.4.1';
+  static const nyxxVersion = '6.4.2';
 
   /// The URL to the nyxx repository used in [defaultUserAgent].
   static const nyxxRepositoryUrl = 'https://github.com/nyxx-discord/nyxx';

lib/src/client_options.dart

@@ -18,11 +18,42 @@ import 'package:nyxx/src/models/role.dart';
 import 'package:nyxx/src/models/sku.dart';
 import 'package:nyxx/src/models/sticker/global_sticker.dart';
 import 'package:nyxx/src/models/sticker/guild_sticker.dart';
+import 'package:nyxx/src/models/subscription.dart';
 import 'package:nyxx/src/models/user/user.dart';
 import 'package:nyxx/src/models/voice/voice_state.dart';
 import 'package:nyxx/src/models/webhook.dart';
 import 'package:nyxx/src/plugin/plugin.dart';
 
+/// The default [CacheConfig].
+///
+/// 2500 is a relatively arbitrary value that corresponds to the maximum number
+/// of guilds a single shard can handle. This doesn't mean a client can cache
+/// all the guilds it is in as it may have more than one shard. However, 2500
+/// is a large enough value that the cache will contain the most important
+/// entities to avoid making network requests:
+/// - The most active guilds.
+/// - The most active channels.
+/// - The most commonly used entitlements.
+/// - (etc)
+const _defaultCacheConfig = CacheConfig<Never>(maxSize: 2500);
+
+/// A [CacheConfig] with a smaller maximum size than [_defaultCacheConfig],
+/// ideal for certain caches.
+///
+/// Notably, the following types of caches may want to default to a smaller
+/// maximum size:
+/// - Caches that are not global (e.g that belong to a specific guild), as the
+///   total number of entities cached is multiplied by the number of "parent"
+///   entities. For example, setting the maximum member cache size to 100 on a
+///   client which is in 1000 guilds means the total number of cached members
+///   may still approach 100000.
+/// - Caches that see a lot of ephemeral entries, for example the users cache.
+///   Users are generally not needed over a long period of time, but rather for
+///   a short burst (e.g when processing a command) before being discarded. We
+///   don't need to cache these entities longer than the operations they are
+///   involved in.
+const _smallCacheConfig = CacheConfig<Never>(maxSize: 100);
+
 /// Options for controlling the behavior of a [Nyxx] client.
 abstract class ClientOptions {
   /// The plugins to use for this client.
@@ -97,7 +128,7 @@ class RestClientOptions extends ClientOptions {
   /// The [CacheConfig] to use for the [Guild.auditLogs] manager.
   final CacheConfig<AuditLogEntry> auditLogEntryConfig;
 
-  /// The [CacheConfig] to use for the [NyxxRest.voice] manager.
+  /// The [CacheConfig] to use for the [PartialGuild.voiceStates] cache.
   final CacheConfig<VoiceState> voiceStateConfig;
 
   /// The [CacheConfig] to use for the [NyxxRest.commands] manager.
@@ -112,31 +143,50 @@ class RestClientOptions extends ClientOptions {
   /// The [CacheConfig] to use for the [Application.skus] manager.
   final CacheConfig<Sku> skuConfig;
 
+  /// Tje [CacheConfig] to use for the [Sku.subscriptions] manager.
+  final CacheConfig<Subscription> subscriptionConfig;
+
   /// Create a new [RestClientOptions].
   const RestClientOptions({
     super.plugins,
     super.loggerName,
     super.rateLimitWarningThreshold,
-    this.userCacheConfig = const CacheConfig(),
-    this.channelCacheConfig = const CacheConfig(),
-    this.messageCacheConfig = const CacheConfig(),
-    this.webhookCacheConfig = const CacheConfig(),
-    this.guildCacheConfig = const CacheConfig(),
-    this.memberCacheConfig = const CacheConfig(),
-    this.roleCacheConfig = const CacheConfig(),
-    this.emojiCacheConfig = const CacheConfig(),
-    this.stageInstanceCacheConfig = const CacheConfig(),
-    this.scheduledEventCacheConfig = const CacheConfig(),
-    this.autoModerationRuleConfig = const CacheConfig(),
-    this.integrationConfig = const CacheConfig(),
-    this.auditLogEntryConfig = const CacheConfig(),
-    this.voiceStateConfig = const CacheConfig(),
-    this.stickerCacheConfig = const CacheConfig(),
-    this.globalStickerCacheConfig = const CacheConfig(),
-    this.applicationCommandConfig = const CacheConfig(),
-    this.commandPermissionsConfig = const CacheConfig(),
-    this.entitlementConfig = const CacheConfig(),
-    this.skuConfig = const CacheConfig(),
+    // Users are generally not needed over long periods of time; use a small
+    // cache.
+    this.userCacheConfig = _smallCacheConfig,
+    this.channelCacheConfig = _defaultCacheConfig,
+    // Messages are generally not needed over long periods of time and are
+    // cached per channel anyway; use a small cache.
+    this.messageCacheConfig = _smallCacheConfig,
+    this.webhookCacheConfig = _defaultCacheConfig,
+    this.guildCacheConfig = _defaultCacheConfig,
+    // Members are generally not needed over long periods of time and are
+    // cached per guild anyway; use a small cache.
+    this.memberCacheConfig = _smallCacheConfig,
+    // Guilds tend not to have a large amount of roles (relatively speaking),
+    // but we also want to access all of a guild's roles during e.g permission
+    // calculations; use a larger cache.
+    this.roleCacheConfig = _defaultCacheConfig,
+    // Bots don't tend to use emoji or sticker data. Don't bother caching too
+    // many.
+    this.emojiCacheConfig = _smallCacheConfig,
+    this.stickerCacheConfig = _smallCacheConfig,
+    // ...but there are not too many global stickers, and they are the most
+    // used, so use a larger cache for these.
+    this.globalStickerCacheConfig = _defaultCacheConfig,
+    this.stageInstanceCacheConfig = _defaultCacheConfig,
+    this.scheduledEventCacheConfig = _smallCacheConfig,
+    this.autoModerationRuleConfig = _smallCacheConfig,
+    this.integrationConfig = _smallCacheConfig,
+    this.auditLogEntryConfig = _smallCacheConfig,
+    // Voice states are saved per guild, so we don't need to store large amount
+    // of them at a time.
+    this.voiceStateConfig = _smallCacheConfig,
+    this.applicationCommandConfig = _defaultCacheConfig,
+    this.commandPermissionsConfig = _smallCacheConfig,
+    this.entitlementConfig = _defaultCacheConfig,
+    this.skuConfig = _defaultCacheConfig,
+    this.subscriptionConfig = _defaultCacheConfig,
   });
 }
 

lib/src/http/managers/subscription_manager.dart

@@ -10,7 +10,7 @@ class SubscriptionManager extends ReadOnlyManager<Subscription> {
   final Snowflake applicationId;
   final Snowflake skuId;
 
-  SubscriptionManager(super.client, super.config, {required this.applicationId, required this.skuId})
+  SubscriptionManager(super.config, super.client, {required this.applicationId, required this.skuId})
       : super(identifier: '$applicationId.$skuId.subscriptions');
 
   @override

lib/src/models/sku.dart

@@ -1,4 +1,5 @@
 import 'package:nyxx/src/http/managers/sku_manager.dart';
+import 'package:nyxx/src/http/managers/subscription_manager.dart';
 import 'package:nyxx/src/models/application.dart';
 import 'package:nyxx/src/models/snowflake.dart';
 import 'package:nyxx/src/models/snowflake_entity/snowflake_entity.dart';
@@ -10,6 +11,10 @@ class PartialSku extends ManagedSnowflakeEntity<Sku> {
   @override
   final SkuManager manager;
 
+  /// A manager for this [Sku]'s [Subscription]s.
+  SubscriptionManager get subscriptions =>
+      SubscriptionManager(manager.client.options.subscriptionConfig, manager.client, applicationId: manager.applicationId, skuId: id);
+
   /// @nodoc
   PartialSku({required this.manager, required super.id});
 }

pubspec.yaml

@@ -1,5 +1,5 @@
 name: nyxx
-version: 6.4.1
+version: 6.4.2
 description: A complete, robust and efficient wrapper around Discord's API for bots & applications.
 homepage: https://github.com/nyxx-discord/nyxx
 repository: https://github.com/nyxx-discord/nyxx