legion-cache 1.3.1 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 657e7afe142d9420c0414c416fdf612ef75456262c91165d545112960bf44e71
-  data.tar.gz: 137d4eb307b337bcda85f91db10fddc42319793a99cde3038fbf9799db960d78
+  metadata.gz: '0295f21258e4a7d824099be9c2c12a7c594d0db3e72dd8d5b5f823bb332e6869'
+  data.tar.gz: 5e581fc50c7bb13e52e9a38ae99a085af836ae21ec6d126d3a0d1fc6c79ad5aa
 SHA512:
-  metadata.gz: e167c6f650ad38373f8794f9cfc209857fd5053b9751375cf77f7ae9537eab23c40cd33947cc656c64dd77e7832f1312987739b4c95c1d2873b5cdf377aeff0d
-  data.tar.gz: 7e38075e7257b4b04fbdefb22de3da21d0055be631f8a6ca4f17d0c78f5669e153d0590aabd3742c05990f88c4e7c55d85409dfae90a5ec6741f36913af54f92
+  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,15 @@
 # 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

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.1
+**Version**: 1.3.2
 
 ## Installation
 
@@ -117,6 +117,33 @@ Both `server` (singular string) and `servers` (array) are accepted and merged. D
 
 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/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Cache
-    VERSION = '1.3.1'
+    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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-cache
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  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