legion-cache 1.3.0 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e74d63805b57a8da13750d3a281d1ef6b25989454bd7dfa385da9d0ba3087a0b
-  data.tar.gz: 2949f0b310c3653516e4dedd0f1def27e8cc9621baf1bace393fcb439c722ace
+  metadata.gz: '0295f21258e4a7d824099be9c2c12a7c594d0db3e72dd8d5b5f823bb332e6869'
+  data.tar.gz: 5e581fc50c7bb13e52e9a38ae99a085af836ae21ec6d126d3a0d1fc6c79ad5aa
 SHA512:
-  metadata.gz: 9f549b3501d9bdfe38e9a3fb19cb5afba9418be9676dfa6a1a0086f7d1f8dbfe6a9e9a64a19dc8a6f60be4282b91096cabcd404cff7a0938257073fdd224fbec
-  data.tar.gz: 7c2a1d4d2adf6357d619961f6bc02d4945a6d23b43807079f4c58ebaaf939b38128965f21934538cfaff64833892acb92f6b9bbe2b5ecacd9c8eb4e978c33698
+  metadata.gz: dc08f391040cab62c39795bd1d477f7d8e47ba4b5ffe3e88856957b829876d37ae06e15a48ff5469652e3c3574d5da529bccb7f00e9df162caadcc4d50fd93e1
+  data.tar.gz: 67717d9fd58c0669e319f0b0de94dee0d8178f17d78ba3fac2afc142660e26668b6700ccbb370b88274f1295d7ab534627768f981f3e1c4f98f9aa5ac86ae3db

data/.gitignore

@@ -16,3 +16,4 @@ legionio.key
 # logs and OS artifacts
 legion.log
 .DS_Store
+.worktrees/

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [1.3.2] - 2026-03-20
+
+### Added
+- `Legion::Cache::Cacheable` module for transparent method-level caching
+- `cache_method` DSL: declare cached methods with TTL, scope, and key exclusions
+- `build_cache_key`: deterministic MD5-based cache keys from module path + method + filtered args
+- `bypass_local_method_cache:` kwarg for force-refresh on cached methods
+- In-memory fallback store with TTL expiry when no cache backend is available
+- `memory_clear!` class method for test isolation
+
+## [1.3.1] - 2026-03-20
+
+### Added
+- `Settings.normalize_driver` — maps `:memcached`, `:dalli`, `:redis` to internal gem names
+- `Settings.resolve_servers` — merges `server:` (string) and `servers:` (array), injects default port per driver (memcached: 11211, redis: 6379), deduplicates
+- `Settings::DEFAULT_PORTS` constant for driver default ports
+
+### Fixed
+- Redis driver now uses configured `server:`/`servers:` instead of hardcoded localhost
+- Memcached driver accepts `server:` (singular) in addition to `servers:` (plural)
+
+### Changed
+- `Settings.default` and `Settings.local` use `resolve_servers` for driver-aware server defaults
+- Driver selection in `cache.rb` and `local.rb` uses `normalize_driver` for consistent name handling
+
 ## [1.3.0] - 2026-03-16
 
 ### Added

data/CLAUDE.md

@@ -8,6 +8,7 @@
 Caching wrapper for the LegionIO framework. Provides a consistent interface for Memcached (via `dalli`) and Redis (via `redis` gem) with connection pooling. Driver selection is config-driven.
 
 **GitHub**: https://github.com/LegionIO/legion-cache
+**Version**: 1.3.0
 **License**: Apache-2.0
 
 ## Architecture

data/README.md

@@ -2,7 +2,7 @@
 
 Caching wrapper for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides a consistent interface for Memcached (via `dalli`) and Redis (via `redis` gem) with connection pooling. Driver selection is config-driven.
 
-**Version**: 1.3.0
+**Version**: 1.3.2
 
 ## Installation
 
@@ -80,6 +80,24 @@ Local uses a separate namespace (`legion_local`) and independent connection pool
 
 The driver is auto-detected at load time: prefers `dalli` (Memcached) if available, falls back to `redis`. Override with `"driver": "redis"` and update `servers` to point at your Redis instance.
 
+### Driver Names
+
+Supported driver names: `memcached` (or `dalli`), `redis`. All names are normalized internally — `"memcached"` and `"dalli"` are equivalent.
+
+### Server Resolution
+
+Both `server` (singular string) and `servers` (array) are accepted and merged. Default ports are injected per driver when omitted: 11211 for memcached, 6379 for redis. Duplicates are removed.
+
+```json
+{
+  "cache": {
+    "driver": "memcached",
+    "server": "10.0.0.5",
+    "servers": ["10.0.0.6", "10.0.0.7:22122"]
+  }
+}
+```
+
 ### Memcached notes
 
 - `value_max_bytes` defaults to **8MB**. Dalli enforces a 1MB client-side limit by default, which silently rejects large values. This default overrides that. Your Memcached server should also be started with `-I 8m` to match.
@@ -99,6 +117,33 @@ The driver is auto-detected at load time: prefers `dalli` (Memcached) if availab
 
 Override via `Legion::Settings[:cache_local]`.
 
+## Method Caching
+
+Runner modules can use `cache_method` to transparently cache method results with TTL:
+
+```ruby
+module Runners::Presence
+  extend Legion::Cache::Cacheable
+
+  cache_method :get_presence, ttl: 300, exclude_from_key: [:token]
+
+  def get_presence(user_id: 'me', **)
+    conn = graph_connection(**)
+    response = conn.get("#{user_path(user_id)}/presence")
+    { availability: response.body['availability'], activity: response.body['activity'] }
+  end
+end
+```
+
+Every caller of `get_presence` gets cached results for 5 minutes. Use `bypass_local_method_cache: true` to force-refresh:
+
+```ruby
+runner.get_presence(user_id: 'me')                                    # cached
+runner.get_presence(user_id: 'me', bypass_local_method_cache: true)   # fresh
+```
+
+Options: `ttl:` (seconds), `scope:` (`:local` or `:global`), `exclude_from_key:` (args to ignore in cache key). Falls back to in-memory store when no cache backend is available.
+
 ## Pool API
 
 ```ruby

data/lib/legion/cache/cacheable.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Legion
+  module Cache
+    module Cacheable
+      def self.extended(base)
+        base.instance_variable_set(:@cached_methods, {})
+      end
+
+      def cached_methods
+        @cached_methods ||= {}
+      end
+
+      def cache_method(method_name, ttl:, scope: :local, exclude_from_key: [])
+        exclude_from_key |= %i[token bypass_local_method_cache]
+        cached_methods[method_name] = { ttl: ttl, scope: scope, exclude_from_key: exclude_from_key }
+
+        mod_name = name || 'Anonymous'
+        config = cached_methods[method_name]
+
+        wrapper = Module.new do
+          define_method(method_name) do |bypass_local_method_cache: false, **kwargs|
+            key = Legion::Cache::Cacheable.build_cache_key(
+              mod_name, method_name, exclude: config[:exclude_from_key], **kwargs
+            )
+
+            unless bypass_local_method_cache
+              cached = Legion::Cache::Cacheable.cache_read(key, scope: config[:scope])
+              return cached unless cached.nil?
+            end
+
+            result = super(**kwargs)
+            Legion::Cache::Cacheable.cache_write(key, result, ttl: config[:ttl], scope: config[:scope])
+            result
+          end
+        end
+
+        prepend wrapper
+      end
+
+      def self.build_cache_key(mod_name, method_name, exclude:, **kwargs)
+        filtered = kwargs.except(*exclude)
+        args_hash = Digest::MD5.hexdigest(filtered.sort.to_s)
+        "#{mod_name}.#{method_name}.#{args_hash}"
+      end
+
+      def self.cache_read(key, scope:)
+        case scope
+        when :global
+          return Legion::Cache.get(key) if global_cache_available?
+
+          memory_read(key)
+        else
+          local_cache_read(key) || memory_read(key)
+        end
+      end
+
+      def self.cache_write(key, value, ttl:, scope:)
+        case scope
+        when :global
+          if global_cache_available?
+            Legion::Cache.set(key, value, ttl)
+          else
+            memory_write(key, value, ttl)
+          end
+        else
+          if local_cache_available?
+            local_cache_write(key, value, ttl)
+          else
+            memory_write(key, value, ttl)
+          end
+        end
+      end
+
+      def self.global_cache_available?
+        defined?(Legion::Cache) && Legion::Cache.respond_to?(:connected?) && Legion::Cache.connected?
+      end
+
+      def self.local_cache_available?
+        defined?(Legion::Cache::Local) && Legion::Cache::Local.respond_to?(:connected?) && Legion::Cache::Local.connected?
+      end
+
+      def self.local_cache_read(key)
+        return nil unless local_cache_available?
+
+        Legion::Cache::Local.get(key)
+      rescue StandardError
+        nil
+      end
+
+      def self.local_cache_write(key, value, ttl)
+        return unless local_cache_available?
+
+        Legion::Cache::Local.set(key, value, ttl)
+      rescue StandardError
+        nil
+      end
+
+      # In-memory fallback store (class-level, process-wide)
+      def self.memory_store
+        @memory_store ||= {}
+      end
+
+      def self.memory_read(key)
+        entry = memory_store[key]
+        return nil unless entry
+        return nil if Time.now.utc > entry[:expires_at]
+
+        entry[:value]
+      end
+
+      def self.memory_write(key, value, ttl)
+        memory_store[key] = { value: value, expires_at: Time.now.utc + ttl }
+      end
+
+      def self.memory_clear!
+        @memory_store = {}
+      end
+    end
+  end
+end

data/lib/legion/cache/local.rb

@@ -94,7 +94,7 @@ module Legion
         private
 
         def build_driver(driver_name)
-          case driver_name
+          case Legion::Cache::Settings.normalize_driver(driver_name)
           when 'redis'
             require 'legion/cache/redis'
             Legion::Cache::Redis.dup

data/lib/legion/cache/memcached.rb

@@ -9,18 +9,25 @@ module Legion
       include Legion::Cache::Pool
       extend self # rubocop:disable Style/ModuleFunction
 
-      def client(servers: Legion::Settings[:cache][:servers], **opts)
+      def client(server: nil, servers: nil, **opts)
         return @client unless @client.nil?
 
-        @pool_size = opts.key?(:pool_size) ? opts[:pool_size] : Legion::Settings[:cache][:pool_size] || 10
-        @timeout = opts.key?(:timeout) ? opts[:timeout] : Legion::Settings[:cache][:timeout] || 5
+        settings = defined?(Legion::Settings) ? Legion::Settings[:cache] : {}
+        servers ||= settings[:servers] || []
+
+        @pool_size = opts.key?(:pool_size) ? opts[:pool_size] : settings[:pool_size] || 10
+        @timeout = opts.key?(:timeout) ? opts[:timeout] : settings[:timeout] || 5
+
+        resolved = Legion::Cache::Settings.resolve_servers(
+          driver: 'memcached', server: server, servers: Array(servers)
+        )
 
         Dalli.logger = Legion::Logging
-        cache_opts = Legion::Settings[:cache].merge(opts)
+        cache_opts = settings.merge(opts)
         cache_opts[:value_max_bytes] ||= 8 * 1024 * 1024
 
         @client = ConnectionPool.new(size: pool_size, timeout: timeout) do
-          Dalli::Client.new(servers, cache_opts)
+          Dalli::Client.new(resolved, cache_opts)
         end
 
         @connected = true

data/lib/legion/cache/redis.rb

@@ -2,6 +2,7 @@
 
 require 'redis'
 require 'legion/cache/pool'
+require 'legion/cache/settings'
 
 module Legion
   module Cache
@@ -9,14 +10,19 @@ module Legion
       include Legion::Cache::Pool
       extend self # rubocop:disable Style/ModuleFunction
 
-      def client(pool_size: 20, timeout: 5, **)
+      def client(pool_size: 20, timeout: 5, server: nil, servers: [], **)
         return @client unless @client.nil?
 
         @pool_size = pool_size
         @timeout = timeout
 
+        resolved = Legion::Cache::Settings.resolve_servers(
+          driver: 'redis', server: server, servers: servers
+        )
+        host, port = resolved.first.split(':')
+
         @client = ConnectionPool.new(size: pool_size, timeout: timeout) do
-          ::Redis.new
+          ::Redis.new(host: host, port: port.to_i)
         end
         @connected = true
         @client

data/lib/legion/cache/settings.rb

@@ -14,7 +14,7 @@ module Legion
       def self.default
         {
           driver:     driver,
-          servers:    ['127.0.0.1:11211'],
+          servers:    resolve_servers(driver: driver),
           connected:  false,
           enabled:    true,
           namespace:  'legion',
@@ -32,7 +32,7 @@ module Legion
       def self.local
         {
           driver:     driver,
-          servers:    ['127.0.0.1:11211'],
+          servers:    resolve_servers(driver: driver),
           connected:  false,
           enabled:    true,
           namespace:  'legion_local',
@@ -47,6 +47,27 @@ module Legion
         }
       end
 
+      DEFAULT_PORTS = { 'dalli' => 11_211, 'redis' => 6379 }.freeze
+
+      def self.resolve_servers(driver:, server: nil, servers: [], port: nil)
+        gem_driver = normalize_driver(driver)
+        port ||= DEFAULT_PORTS.fetch(gem_driver, 11_211)
+
+        all = Array(servers) + Array(server)
+        all = ["127.0.0.1:#{port}"] if all.empty?
+
+        all.map! { |s| s.include?(':') ? s : "#{s}:#{port}" }
+        all.uniq
+      end
+
+      def self.normalize_driver(name)
+        case name.to_s
+        when 'redis' then 'redis'
+        when 'memcached', 'dalli' then 'dalli'
+        else name.to_s
+        end
+      end
+
       def self.driver(prefer = 'dalli')
         secondary = prefer == 'dalli' ? 'redis' : 'dalli'
         if Gem::Specification.find_all_by_name(prefer).any?

data/lib/legion/cache/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Cache
-    VERSION = '1.3.0'
+    VERSION = '1.3.2'
   end
 end

data/lib/legion/cache.rb

@@ -2,6 +2,7 @@
 
 require 'legion/cache/version'
 require 'legion/cache/settings'
+require 'legion/cache/cacheable'
 
 require 'legion/cache/memcached'
 require 'legion/cache/redis'
@@ -9,7 +10,7 @@ require 'legion/cache/local'
 
 module Legion
   module Cache
-    if Legion::Settings[:cache][:driver] == 'redis'
+    if Legion::Cache::Settings.normalize_driver(Legion::Settings[:cache][:driver]) == 'redis'
       extend Legion::Cache::Redis
     else
       extend Legion::Cache::Memcached

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-cache
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.2
 platform: ruby
 authors:
 - Esity
@@ -100,6 +100,7 @@ files:
 - README.md
 - legion-cache.gemspec
 - lib/legion/cache.rb
+- lib/legion/cache/cacheable.rb
 - lib/legion/cache/local.rb
 - lib/legion/cache/memcached.rb
 - lib/legion/cache/pool.rb