discord_rda 0.1.3

data/lib/discord_rda/cache/configurable_cache.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module DiscordRDA
+  # Configurable cache manager.
+  # By default, caches NOTHING - follows Discordeno philosophy.
+  # Users can opt-in to caching only what they need.
+  #
+  class ConfigurableCache
+    # Cache nothing strategy
+    STRATEGY_NONE = :none
+
+    # Cache everything strategy
+    STRATEGY_FULL = :full
+
+    # Custom strategy - user specifies what to cache
+    STRATEGY_CUSTOM = :custom
+
+    # @return [Symbol] Current cache strategy
+    attr_reader :strategy
+
+    # @return [CacheStore] Cache store backend
+    attr_reader :store
+
+    # @return [Logger] Logger instance
+    attr_reader :logger
+
+    # @return [Hash] Enabled cache types
+    attr_reader :enabled_caches
+
+    # @return [Array<Symbol>] Properties to cache per entity
+    attr_reader :cached_properties
+
+    # Initialize configurable cache
+    # @param strategy [Symbol] Cache strategy (:none, :full, :custom)
+    # @param store [CacheStore] Cache store backend
+    # @param logger [Logger] Logger instance
+    # @param enabled_caches [Array<Symbol>] Which entity types to cache (for :custom)
+    # @param cached_properties [Hash] Which properties to cache per entity
+    def initialize(
+      strategy: STRATEGY_NONE,
+      store: nil,
+      logger: nil,
+      enabled_caches: [],
+      cached_properties: {}
+    )
+      @strategy = strategy
+      @store = store || MemoryStore.new
+      @logger = logger
+      @enabled_caches = enabled_caches
+      @cached_properties = cached_properties
+
+      @logger&.info('Cache initialized', strategy: strategy, enabled: enabled_caches)
+    end
+
+    # Cache an entity (only if enabled for this type)
+    # @param type [Symbol] Entity type
+    # @param id [String, Snowflake] Entity ID
+    # @param entity [Entity] Entity to cache
+    # @param ttl [Integer] Time to live in seconds
+    # @return [void]
+    def cache(type, id, entity, ttl: 300)
+      return unless should_cache?(type)
+
+      # If custom properties specified, only cache those
+      if @cached_properties[type]
+        entity = filter_properties(entity, @cached_properties[type])
+      end
+
+      key = "#{type}:#{id}"
+      @store.set(key, entity, ttl: ttl)
+
+      @logger&.debug('Cached entity', type: type, id: id, strategy: @strategy)
+    end
+
+    # Get cached entity
+    # @param type [Symbol] Entity type
+    # @param id [String, Snowflake] Entity ID
+    # @return [Entity, nil] Cached entity or nil
+    def get(type, id)
+      return nil unless should_cache?(type)
+
+      key = "#{type}:#{id}"
+      @store.get(key)
+    end
+
+    # Check if entity should be cached
+    # @param type [Symbol] Entity type
+    # @return [Boolean] True if should cache
+    def should_cache?(type)
+      case @strategy
+      when STRATEGY_NONE
+        false
+      when STRATEGY_FULL
+        true
+      when STRATEGY_CUSTOM
+        @enabled_caches.include?(type)
+      else
+        false
+      end
+    end
+
+    # Invalidate an entity
+    # @param type [Symbol] Entity type
+    # @param id [String, Snowflake] Entity ID
+    # @return [void]
+    def invalidate(type, id)
+      key = "#{type}:#{id}"
+      @store.delete(key)
+    end
+
+    # Clear all cached data
+    # @return [void]
+    def clear
+      @store.clear
+    end
+
+    # Get cache statistics
+    # @return [Hash] Statistics
+    def stats
+      base_stats = @store.respond_to?(:stats) ? @store.stats : {}
+
+      {
+        strategy: @strategy,
+        enabled_caches: @enabled_caches,
+        **base_stats
+      }
+    end
+
+    # Create a new cache with different settings (immutable)
+    # @param overrides [Hash] Settings to override
+    # @return [ConfigurableCache] New cache instance
+    def with(**overrides)
+      self.class.new(
+        strategy: overrides.fetch(:strategy, @strategy),
+        store: overrides.fetch(:store, @store),
+        logger: overrides.fetch(:logger, @logger),
+        enabled_caches: overrides.fetch(:enabled_caches, @enabled_caches),
+        cached_properties: overrides.fetch(:cached_properties, @cached_properties)
+      )
+    end
+
+    private
+
+    def filter_properties(entity, properties)
+      return entity unless entity.respond_to?(:to_h)
+      return entity if properties.nil? || properties.empty?
+
+      data = entity.to_h
+      # Support nested property selection with dot notation (e.g., "author.username")
+      filtered = {}
+      properties.each do |prop|
+        if prop.to_s.include?('.')
+          parts = prop.to_s.split('.')
+          current = data
+          current_filtered = filtered
+
+          parts.each_with_index do |part, idx|
+            if idx == parts.length - 1
+              current_filtered[part] = current[part] if current && current.key?(part)
+            else
+              current_filtered[part] ||= {}
+              current = current&.dig(part)
+              current_filtered = current_filtered[part]
+            end
+          end
+        else
+          filtered[prop.to_s] = data[prop.to_s] if data.key?(prop.to_s)
+        end
+      end
+
+      # Preserve ID if it's a filtered entity
+      filtered['id'] = data['id'] if data.key?('id') && !filtered.key?('id')
+
+      # Create new entity with filtered data
+      entity.class.new(filtered)
+    end
+
+    # Advanced property filtering with transforms
+    # @param entity [Entity] Entity to filter
+    # @param config [Hash] Filter config with :only, :except, :transform options
+    # @return [Entity] Filtered entity
+    def advanced_filter(entity, config = {})
+      return entity unless entity.respond_to?(:to_h)
+
+      data = entity.to_h
+
+      # Apply :only filter
+      if config[:only]
+        data = data.slice(*config[:only].map(&:to_s))
+      end
+
+      # Apply :except filter
+      if config[:except]
+        data = data.except(*config[:except].map(&:to_s))
+      end
+
+      # Apply transforms
+      if config[:transform]
+        config[:transform].each do |key, transform|
+          key_str = key.to_s
+          data[key_str] = transform.call(data[key_str]) if data.key?(key_str)
+        end
+      end
+
+      entity.class.new(data)
+    end
+
+    # Filter entities by custom predicate
+    # @param type [Symbol] Entity type
+    # @yield Block to filter entities
+    # @return [Array<Entity>] Filtered entities
+    def filter_by(type)
+      return [] unless block_given?
+      return [] unless should_cache?(type)
+
+      pattern = "#{type}:*"
+      all = @store.scan(pattern)
+      all.select { |_, entity| yield(entity) }.map { |_, entity| entity }
+    end
+
+    # Get filtered properties configuration for an entity type
+    # @param type [Symbol] Entity type
+    # @return [Array<Symbol>, nil] Properties to cache, or nil for all
+    def filter_for(type)
+      @cached_properties[type]
+    end
+
+    # Set filtered properties for an entity type
+    # @param type [Symbol] Entity type
+    # @param properties [Array<Symbol>] Properties to cache
+    # @return [void]
+    def set_filter(type, *properties)
+      @cached_properties[type] = properties.flatten
+    end
+
+    # Clear filter for an entity type
+    # @param type [Symbol] Entity type
+    # @return [void]
+    def clear_filter(type)
+      @cached_properties.delete(type)
+    end
+
+    # Batch cache entities with property filtering
+    # @param type [Symbol] Entity type
+    # @param entities [Array<Entity>] Entities to cache
+    # @param ttl [Integer] Time to live in seconds
+    # @return [void]
+    def cache_batch(type, entities, ttl: 300)
+      return unless should_cache?(type)
+
+      entities.each do |entity|
+        cache(type, entity.id, entity, ttl: ttl) if entity.respond_to?(:id)
+      end
+    end
+
+    # Get multiple entities by IDs
+    # @param type [Symbol] Entity type
+    # @param ids [Array<String, Snowflake>] Entity IDs
+    # @return [Array<Entity>] Found entities
+    def get_many(type, ids)
+      return [] unless should_cache?(type)
+
+      ids.map { |id| get(type, id) }.compact
+    end
+
+    # Invalidate multiple entities
+    # @param type [Symbol] Entity type
+    # @param ids [Array<String, Snowflake>] Entity IDs
+    # @return [void]
+    def invalidate_many(type, ids)
+      ids.each { |id| invalidate(type, id) }
+    end
+
+    # Invalidate by pattern
+    # @param pattern [String] Pattern to match (e.g., "guild:*:members")
+    # @return [Integer] Number of entries invalidated
+    def invalidate_pattern(pattern)
+      keys = @store.scan(pattern).map { |k, _| k }
+      keys.each { |k| @store.delete(k) }
+      keys.size
+    end
+  end
+end

data/lib/discord_rda/cache/entity_cache.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module DiscordRDA
+  # Typed entity cache with automatic invalidation.
+  # Provides methods for caching and retrieving Discord entities.
+  #
+  class EntityCache
+    # @return [CacheStore] Cache store
+    attr_reader :store
+
+    # @return [Logger] Logger instance
+    attr_reader :logger
+
+    # Entity TTLs in seconds
+    TTL = {
+      user: 300,
+      guild: 60,
+      channel: 300,
+      message: 60,
+      role: 300,
+      member: 120
+    }.freeze
+
+    # Initialize entity cache
+    # @param store [CacheStore] Cache store instance
+    # @param logger [Logger] Logger instance
+    def initialize(store, logger: nil)
+      @store = store
+      @logger = logger
+    end
+
+    # Cache a user
+    # @param user [User] User to cache
+    # @return [void]
+    def cache_user(user)
+      cache(:user, user.id, user)
+    end
+
+    # Get a cached user
+    # @param user_id [String, Snowflake] User ID
+    # @return [User, nil] Cached user
+    def user(user_id)
+      get(:user, user_id)
+    end
+
+    # Cache a guild
+    # @param guild [Guild] Guild to cache
+    # @return [void]
+    def cache_guild(guild)
+      cache(:guild, guild.id, guild)
+    end
+
+    # Get a cached guild
+    # @param guild_id [String, Snowflake] Guild ID
+    # @return [Guild, nil] Cached guild
+    def guild(guild_id)
+      get(:guild, guild_id)
+    end
+
+    # Cache a channel
+    # @param channel [Channel] Channel to cache
+    # @return [void]
+    def cache_channel(channel)
+      cache(:channel, channel.id, channel)
+    end
+
+    # Get a cached channel
+    # @param channel_id [String, Snowflake] Channel ID
+    # @return [Channel, nil] Cached channel
+    def channel(channel_id)
+      get(:channel, channel_id)
+    end
+
+    # Cache a message
+    # @param message [Message] Message to cache
+    # @return [void]
+    def cache_message(message)
+      cache(:message, message.id, message)
+    end
+
+    # Get a cached message
+    # @param message_id [String, Snowflake] Message ID
+    # @return [Message, nil] Cached message
+    def message(message_id)
+      get(:message, message_id)
+    end
+
+    # Cache a role
+    # @param role [Role] Role to cache
+    # @return [void]
+    def cache_role(role)
+      cache(:role, role.id, role)
+    end
+
+    # Get a cached role
+    # @param role_id [String, Snowflake] Role ID
+    # @return [Role, nil] Cached role
+    def role(role_id)
+      get(:role, role_id)
+    end
+
+    # Cache a member
+    # @param member [Member] Member to cache
+    # @param guild_id [String, Snowflake] Guild ID
+    # @return [void]
+    def cache_member(member, guild_id)
+      key = "#{guild_id}:#{member.id}"
+      cache(:member, key, member)
+    end
+
+    # Get a cached member
+    # @param user_id [String, Snowflake] User ID
+    # @param guild_id [String, Snowflake] Guild ID
+    # @return [Member, nil] Cached member
+    def member(user_id, guild_id)
+      key = "#{guild_id}:#{user_id}"
+      get(:member, key)
+    end
+
+    # Invalidate an entity
+    # @param type [Symbol] Entity type
+    # @param id [String, Snowflake] Entity ID
+    # @return [void]
+    def invalidate(type, id)
+      key = build_key(type, id)
+      @store.delete(key)
+      @logger&.debug('Invalidated cache', type: type, id: id)
+    end
+
+    # Invalidate by guild ID
+    # @param guild_id [String, Snowflake] Guild ID
+    # @return [void]
+    def invalidate_guild(guild_id)
+      guild_key = guild_id.to_s
+      deleted_count = 0
+
+      # Delete the guild itself
+      @store.delete("guild:#{guild_key}")
+      deleted_count += 1
+
+      # Delete all members associated with this guild
+      if @store.respond_to?(:keys)
+        member_keys = @store.keys("member:#{guild_key}:*")
+        member_keys.each do |key|
+          @store.delete(key)
+          deleted_count += 1
+        end
+      end
+
+      @logger&.debug('Invalidated guild cache', guild_id: guild_id, deleted: deleted_count)
+    end
+
+    # Clear all cached entities
+    # @return [void]
+    def clear
+      @store.clear
+      @logger&.info('Cleared entity cache')
+    end
+
+    # Get cache statistics
+    # @return [Hash] Statistics
+    def stats
+      @store.respond_to?(:stats) ? @store.stats : {}
+    end
+
+    private
+
+    def cache(type, id, entity)
+      key = build_key(type, id)
+      ttl = TTL[type]
+      @store.set(key, entity, ttl: ttl)
+      @logger&.debug('Cached entity', type: type, id: id)
+    end
+
+    def get(type, id)
+      key = build_key(type, id)
+      @store.get(key)
+    end
+
+    def build_key(type, id)
+      "#{type}:#{id}"
+    end
+  end
+end

data/lib/discord_rda/cache/memory_store.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'lru_redux'
+
+module DiscordRDA
+  # In-memory LRU cache store.
+  # Provides fast, thread-safe caching with size limits and TTL.
+  #
+  class MemoryStore < CacheStore
+    # Default cache size
+    DEFAULT_SIZE = 10_000
+
+    # @return [Integer] Maximum cache size
+    attr_reader :max_size
+
+    # @return [Hash] TTL tracking
+    attr_reader :ttl_data
+
+    # Initialize memory store
+    # @param max_size [Integer] Maximum cache size
+    def initialize(max_size: DEFAULT_SIZE)
+      @max_size = max_size
+      @cache = LruRedux::Cache.new(max_size)
+      @ttl_data = {}
+      @mutex = Mutex.new
+    end
+
+    # Get a value from cache
+    # @param key [String] Cache key
+    # @return [Object, nil] Cached value or nil if expired/missing
+    def get(key)
+      @mutex.synchronize do
+        check_ttl(key)
+        @cache[key]
+      end
+    end
+
+    # Set a value in cache
+    # @param key [String] Cache key
+    # @param value [Object] Value to cache
+    # @param ttl [Integer] Time to live in seconds
+    # @return [void]
+    def set(key, value, ttl: nil)
+      @mutex.synchronize do
+        @cache[key] = value
+        @ttl_data[key] = Time.now.utc + ttl if ttl
+      end
+    end
+
+    # Delete a value from cache
+    # @param key [String] Cache key
+    # @return [void]
+    def delete(key)
+      @mutex.synchronize do
+        @cache.delete(key)
+        @ttl_data.delete(key)
+      end
+    end
+
+    # Check if key exists and is not expired
+    # @param key [String] Cache key
+    # @return [Boolean] True if exists
+    def exist?(key)
+      @mutex.synchronize do
+        check_ttl(key)
+        @cache.key?(key)
+      end
+    end
+
+    # Clear all cached values
+    # @return [void]
+    def clear
+      @mutex.synchronize do
+        @cache.clear
+        @ttl_data.clear
+      end
+    end
+
+    # Get current cache size
+    # @return [Integer] Number of cached items
+    def size
+      @mutex.synchronize do
+        clean_expired
+        @cache.size
+      end
+    end
+
+    # Get cache statistics
+    # @return [Hash] Statistics
+    def stats
+      @mutex.synchronize do
+        clean_expired
+        {
+          size: @cache.size,
+          max_size: @max_size,
+          ttl_entries: @ttl_data.size
+        }
+      end
+    end
+
+    # Get keys matching a pattern
+    # @param pattern [String, Regexp] Pattern to match (supports globs like "member:123:*")
+    # @return [Array<String>] Matching keys
+    def keys(pattern)
+      @mutex.synchronize do
+        clean_expired
+
+        regex = if pattern.is_a?(Regexp)
+                  pattern
+                else
+                  # Convert glob pattern to regex
+                  regex_str = pattern.gsub('.', '\\.')
+                                   .gsub('*', '.*')
+                                   .gsub('?', '.')
+                  Regexp.new("^#{regex_str}$")
+                end
+
+        @cache.keys.select { |k| k.match?(regex) }
+      end
+    end
+
+    private
+
+    def check_ttl(key)
+      ttl = @ttl_data[key]
+      return unless ttl
+
+      if Time.now.utc > ttl
+        @cache.delete(key)
+        @ttl_data.delete(key)
+      end
+    end
+
+    def clean_expired
+      now = Time.now.utc
+      expired = @ttl_data.select { |_, ttl| now > ttl }.keys
+      expired.each do |key|
+        @cache.delete(key)
+        @ttl_data.delete(key)
+      end
+    end
+  end
+end