legion-cache 1.3.17 → 1.3.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d0de0aa53a2886b16a2d2e10bb18e37128a0e0d50d118d689c8f87aa15fcb72
-  data.tar.gz: 49387e7f795a779e595b700c2afe8eda19b7bc0e07273306ae57ca9ec71b2782
+  metadata.gz: d491473adc0cc25e2737e471f1dbc644544e2bbc25c67d9ab8e1402836c9f9a7
+  data.tar.gz: dd72aaf34ad2f97c37117a9b882a9cf76a34a4bd6d1701316a42eff5dafb1317
 SHA512:
-  metadata.gz: af05e3b8f771a81307f9c3fb81c6dcb6a9fad154bd127660d71a9e645c44636fb1317ef70db618fa5e139fb617d012747bb477017226b829cc5d26ff3db6cd5a
-  data.tar.gz: 0e31e8c387e44ff1c8e4089cabd04536df39e373cbc38bc90dc1beba85b080d92d77887ee1f4faccf4ef96bb0a02bc51d43bdebda53231e627d26f57e014775f
+  metadata.gz: 756116bb625d9aafc055c12c835777e91d1defbe9cc1308a1021789ac27a64382fcc1fb5378d78afb365cc96f0f6a403330d2c4694d151be2bd2c13631303f4c
+  data.tar.gz: 117f46e60ca535ee8ce0c4080e3a6f8c71e2cade0ea023ff6edd1fff6ad96cce2ee43448184400f90d5ce58980f58a54f00dc710c5f1fd53127e9a59745a624c

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [1.3.19] - 2026-03-31
+
+### Added
+- `cache_mget` / `cache_mset` (and `local_cache_mget` / `local_cache_mset`) on `Helper` mixin — delegates to Redis batch ops, falls back to sequential get/set on Memcached (closes #3)
+- `cache_hset`, `cache_hgetall`, `cache_hdel`, `cache_zadd`, `cache_zrangebyscore`, `cache_zrem`, `cache_expire` on `Helper` mixin — delegates to `RedisHash` with namespace prefixing; hash ops fall back to JSON-serialized Memcached values, sorted-set ops raise `NotImplementedError`, expire is a no-op on Memcached (closes #4)
+
+## [1.3.18] - 2026-03-29
+
+### Added
+- Layered TTL resolution in Helper (per-call → LEX override → Settings → FALLBACK_TTL)
+- `cache_default_ttl` / `local_cache_default_ttl` — LEX-overridable default TTL methods
+- `cache_exist?` / `local_cache_exist?` — key existence checks
+- `cache_connected?` / `local_cache_connected?` — connection status helpers
+- `cache_pool_size` / `cache_pool_available` — pool info (shared tier)
+- `local_cache_pool_size` / `local_cache_pool_available` — pool info (local tier)
+- `phi:` keyword argument on `cache_set` / `local_cache_set` for PHI TTL enforcement
+- `default_ttl` key in Settings.default and Settings.local (defaults to 60)
+
 ## [1.3.17] - 2026-03-25
 
 ### Added

data/CLAUDE.md

@@ -8,7 +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.12
+**Version**: 1.3.17
 **License**: Apache-2.0
 
 ## Architecture
@@ -39,6 +39,7 @@ Legion::Cache (singleton module)
 ├── Memory                  # Lite mode adapter: pure in-memory cache, TTL expiry, Mutex thread-safety
 │   └── Activated by LEGION_MODE=lite env var; no Redis/Memcached required
 ├── Helper                  # Injectable cache mixin for LEX extensions (namespaced cache_*/local_cache_*)
+├── RedisHash               # Redis-specific sorted set + hash operations (hset/hgetall/hdel/zadd/zrangebyscore/zrem/expire); Redis-only, module_function pattern
 ├── Local                   # Local cache tier (localhost Redis/Memcached, fallback target)
 │   ├── .setup              # Connect to local cache server (auto-detect driver)
 │   ├── .shutdown           # Close local connection
@@ -134,10 +135,25 @@ Dalli enforces a 1MB client-side limit by default (`value_max_bytes: 1_048_576`)
 | `lib/legion/cache/memory.rb` | Lite mode Memory adapter: in-memory store with TTL + Mutex thread-safety |
 | `lib/legion/cache/helper.rb` | Injectable cache mixin for LEX extensions |
 | `lib/legion/cache/local.rb` | Local cache tier (localhost, fallback target) |
+| `lib/legion/cache/redis_hash.rb` | Redis sorted set + hash operations (hset/hgetall/hdel/zadd/zrangebyscore/zrem/expire) |
 | `lib/legion/cache/pool.rb` | Connection pool management |
 | `lib/legion/cache/settings.rb` | Default configuration + local defaults |
 | `lib/legion/cache/version.rb` | VERSION constant |
 
+## PHI TTL Cap
+
+When `phi: true` is passed to `set`, the TTL is capped at `cache.compliance.phi_max_ttl` (default 3600s). This enforces the HIPAA PHI TTL policy in legion-logging. The `enforce_phi_ttl(ttl, phi: false)` method applies the cap; without `phi: true` the TTL is passed through unchanged.
+
+```json
+{
+  "cache": {
+    "compliance": {
+      "phi_max_ttl": 3600
+    }
+  }
+}
+```
+
 ## Role in LegionIO
 
 Optional caching layer initialized during `Legion::Service` startup. Used by `legion-data` for model caching (Sequel caching plugin) and by extensions for general-purpose caching.

data/Gemfile

@@ -8,5 +8,6 @@ group :test do
   gem 'rspec'
   gem 'rspec_junit_formatter'
   gem 'rubocop'
+  gem 'rubocop-legion'
   gem 'simplecov'
 end

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.12
+**Version**: 1.3.17
 
 ## Installation
 

data/lib/legion/cache/helper.rb

@@ -3,12 +3,38 @@
 module Legion
   module Cache
     module Helper
+      FALLBACK_TTL = 60
+
+      # --- TTL Resolution ---
+      # Override in your LEX to set a custom default TTL for the extension.
+      # Resolution chain: per-call ttl: kwarg -> LEX override -> Settings -> FALLBACK_TTL
+      def cache_default_ttl
+        return FALLBACK_TTL unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:cache, :default_ttl) || FALLBACK_TTL
+      rescue StandardError
+        FALLBACK_TTL
+      end
+
+      def local_cache_default_ttl
+        return cache_default_ttl unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:cache_local, :default_ttl) || cache_default_ttl
+      rescue StandardError
+        cache_default_ttl
+      end
+
+      # --- Namespace ---
+
       def cache_namespace
         @cache_namespace ||= derive_cache_namespace
       end
 
-      def cache_set(key, value, ttl: 60)
-        Legion::Cache.set(cache_namespace + key, value, ttl)
+      # --- Core Operations (shared tier) ---
+
+      def cache_set(key, value, ttl: nil, phi: false)
+        effective_ttl = ttl || cache_default_ttl
+        Legion::Cache.set(cache_namespace + key, value, effective_ttl, phi: phi)
       end
 
       def cache_get(key)
@@ -19,12 +45,177 @@ module Legion
         Legion::Cache.delete(cache_namespace + key)
       end
 
-      def cache_fetch(key, ttl: 60, &)
-        Legion::Cache.fetch(cache_namespace + key, ttl, &)
+      def cache_fetch(key, ttl: nil, &)
+        effective_ttl = ttl || cache_default_ttl
+        Legion::Cache.fetch(cache_namespace + key, effective_ttl, &)
+      end
+
+      def cache_exist?(key)
+        !Legion::Cache.get(cache_namespace + key).nil?
+      end
+
+      # --- Batch Operations (shared tier) ---
+      # Issue #3: mget/mset with Memcached safety
+
+      # Returns a Hash of { key => value } pairs. Prefixes all keys with cache_namespace.
+      # Delegates to Legion::Cache.mget on Redis; falls back to sequential gets on Memcached.
+      def cache_mget(*keys)
+        keys = keys.flatten
+        return {} if keys.empty?
+
+        namespaced = keys.map { |k| cache_namespace + k }
+
+        if cache_redis?
+          raw = Legion::Cache.mget(*namespaced)
+          keys.to_h { |k| [k, raw[cache_namespace + k]] }
+        else
+          keys.to_h { |k| [k, Legion::Cache.get(cache_namespace + k)] }
+        end
+      rescue StandardError => e
+        log_cache_error('cache_mget', e)
+        {}
+      end
+
+      # Stores multiple key-value pairs. Accepts a Hash of { key => value }.
+      # TTL follows the same resolution chain as cache_set.
+      # Delegates to Legion::Cache.mset on Redis; falls back to sequential sets on Memcached.
+      def cache_mset(hash, ttl: nil)
+        return true if hash.empty?
+
+        effective_ttl = ttl || cache_default_ttl
+
+        if cache_redis?
+          namespaced = hash.transform_keys { |k| cache_namespace + k }
+          Legion::Cache.mset(namespaced)
+        else
+          hash.each { |k, v| Legion::Cache.set(cache_namespace + k, v, effective_ttl) }
+          true
+        end
+      rescue StandardError => e
+        log_cache_error('cache_mset', e)
+        false
+      end
+
+      # --- Batch Operations (local tier) ---
+
+      def local_cache_mget(*keys)
+        keys = keys.flatten
+        return {} if keys.empty?
+
+        if local_cache_redis?
+          namespaced = keys.map { |k| cache_namespace + k }
+          raw = Legion::Cache::Local.mget(*namespaced)
+          keys.to_h { |k| [k, raw[cache_namespace + k]] }
+        else
+          keys.to_h { |k| [k, Legion::Cache::Local.get(cache_namespace + k)] }
+        end
+      rescue StandardError => e
+        log_cache_error('local_cache_mget', e)
+        {}
       end
 
-      def local_cache_set(key, value, ttl: 60)
-        Legion::Cache::Local.set(cache_namespace + key, value, ttl)
+      def local_cache_mset(hash, ttl: nil)
+        return true if hash.empty?
+
+        effective_ttl = ttl || local_cache_default_ttl
+
+        if local_cache_redis?
+          namespaced = hash.transform_keys { |k| cache_namespace + k }
+          Legion::Cache::Local.mset(namespaced)
+        else
+          hash.each { |k, v| Legion::Cache::Local.set(cache_namespace + k, v, effective_ttl) }
+          true
+        end
+      rescue StandardError => e
+        log_cache_error('local_cache_mset', e)
+        false
+      end
+
+      # --- RedisHash Helpers (shared tier) ---
+      # Issue #4: namespaced wrappers for RedisHash operations with Memcached fallback
+
+      def cache_hset(key, hash)
+        if cache_redis?
+          Legion::Cache::RedisHash.hset(cache_namespace + key, hash)
+        else
+          memcached_hash_merge(cache_namespace + key, hash)
+        end
+      rescue StandardError => e
+        log_cache_error('cache_hset', e)
+        false
+      end
+
+      def cache_hgetall(key)
+        if cache_redis?
+          Legion::Cache::RedisHash.hgetall(cache_namespace + key)
+        else
+          memcached_hash_load(cache_namespace + key)
+        end
+      rescue StandardError => e
+        log_cache_error('cache_hgetall', e)
+        nil
+      end
+
+      def cache_hdel(key, *fields)
+        if cache_redis?
+          Legion::Cache::RedisHash.hdel(cache_namespace + key, *fields)
+        else
+          memcached_hash_delete_fields(cache_namespace + key, fields)
+        end
+      rescue StandardError => e
+        log_cache_error('cache_hdel', e)
+        0
+      end
+
+      def cache_zadd(key, score, member)
+        raise_sorted_set_unsupported('cache_zadd') unless cache_redis?
+
+        Legion::Cache::RedisHash.zadd(cache_namespace + key, score, member)
+      rescue NotImplementedError
+        raise
+      rescue StandardError => e
+        log_cache_error('cache_zadd', e)
+        false
+      end
+
+      def cache_zrangebyscore(key, min, max, limit: nil)
+        raise_sorted_set_unsupported('cache_zrangebyscore') unless cache_redis?
+
+        Legion::Cache::RedisHash.zrangebyscore(cache_namespace + key, min, max, limit: limit)
+      rescue NotImplementedError
+        raise
+      rescue StandardError => e
+        log_cache_error('cache_zrangebyscore', e)
+        []
+      end
+
+      def cache_zrem(key, member)
+        raise_sorted_set_unsupported('cache_zrem') unless cache_redis?
+
+        Legion::Cache::RedisHash.zrem(cache_namespace + key, member)
+      rescue NotImplementedError
+        raise
+      rescue StandardError => e
+        log_cache_error('cache_zrem', e)
+        false
+      end
+
+      # Sets TTL on a key. No-op on Memcached (TTL is set at write time).
+      def cache_expire(key, seconds)
+        return false unless cache_redis?
+
+        Legion::Cache::RedisHash.expire(cache_namespace + key, seconds)
+      rescue StandardError => e
+        log_cache_error('cache_expire', e)
+        false
+      end
+
+      # --- Core Operations (local tier) ---
+
+      def local_cache_set(key, value, ttl: nil, phi: false)
+        effective_ttl = ttl || local_cache_default_ttl
+        effective_ttl = Legion::Cache.enforce_phi_ttl(effective_ttl, phi: phi)
+        Legion::Cache::Local.set(cache_namespace + key, value, effective_ttl)
       end
 
       def local_cache_get(key)
@@ -35,8 +226,57 @@ module Legion
         Legion::Cache::Local.delete(cache_namespace + key)
       end
 
-      def local_cache_fetch(key, ttl: 60, &)
-        Legion::Cache::Local.fetch(cache_namespace + key, ttl, &)
+      def local_cache_fetch(key, ttl: nil, &)
+        effective_ttl = ttl || local_cache_default_ttl
+        Legion::Cache::Local.fetch(cache_namespace + key, effective_ttl, &)
+      end
+
+      def local_cache_exist?(key)
+        !Legion::Cache::Local.get(cache_namespace + key).nil?
+      end
+
+      # --- Status ---
+
+      def cache_connected?
+        Legion::Cache.connected?
+      end
+
+      def local_cache_connected?
+        Legion::Cache::Local.connected?
+      end
+
+      # --- Pool Info ---
+
+      def cache_pool_size
+        return 0 unless cache_connected?
+
+        Legion::Cache.pool_size
+      rescue StandardError
+        0
+      end
+
+      def cache_pool_available
+        return 0 unless cache_connected?
+
+        Legion::Cache.available
+      rescue StandardError
+        0
+      end
+
+      def local_cache_pool_size
+        return 0 unless local_cache_connected?
+
+        Legion::Cache::Local.pool_size
+      rescue StandardError
+        0
+      end
+
+      def local_cache_pool_available
+        return 0 unless local_cache_connected?
+
+        Legion::Cache::Local.available
+      rescue StandardError
+        0
       end
 
       private
@@ -63,6 +303,56 @@ module Legion
               .gsub(/([a-z\d])([A-Z])/, '\1_\2')
               .downcase
       end
+
+      def cache_redis?
+        Legion::Cache::RedisHash.redis_available?
+      end
+
+      def local_cache_redis?
+        defined?(Legion::Cache::Local) &&
+          Legion::Cache::Local.respond_to?(:mget) &&
+          Legion::Cache::Local.connected?
+      end
+
+      def memcached_hash_merge(full_key, new_fields)
+        current = memcached_hash_load(full_key) || {}
+        merged = current.merge(new_fields.transform_keys(&:to_s))
+        Legion::Cache.set(full_key, Legion::JSON.dump(merged), cache_default_ttl)
+        true
+      end
+
+      def memcached_hash_load(full_key)
+        raw = Legion::Cache.get(full_key)
+        return nil if raw.nil?
+
+        parsed = Legion::JSON.load(raw)
+        # Legion::JSON.load returns symbol keys; convert to string keys to mirror Redis hgetall
+        parsed.transform_keys(&:to_s)
+      rescue StandardError
+        nil
+      end
+
+      def memcached_hash_delete_fields(full_key, fields)
+        current = memcached_hash_load(full_key)
+        return 0 if current.nil?
+
+        str_fields = fields.map(&:to_s)
+        removed = str_fields.count { |f| current.key?(f) }
+        str_fields.each { |f| current.delete(f) }
+        Legion::Cache.set(full_key, Legion::JSON.dump(current), cache_default_ttl)
+        removed
+      end
+
+      def raise_sorted_set_unsupported(method)
+        raise NotImplementedError,
+              "#{method} requires a Redis backend — sorted sets are not supported on Memcached"
+      end
+
+      def log_cache_error(method, error)
+        return unless defined?(Legion::Logging)
+
+        Legion::Logging.warn "[cache:helper] #{method} failed: #{error.class} — #{error.message}"
+      end
     end
   end
 end

data/lib/legion/cache/settings.rb

@@ -25,6 +25,7 @@ module Legion
           cache_nils:         false,
           pool_size:          10,
           timeout:            5,
+          default_ttl:        60,
           serializer:         Legion::JSON,
           cluster:            nil,
           replica:            false,
@@ -50,6 +51,7 @@ module Legion
           cache_nils:         false,
           pool_size:          5,
           timeout:            3,
+          default_ttl:        60,
           serializer:         Legion::JSON,
           username:           nil,
           password:           nil,

data/lib/legion/cache/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Cache
-    VERSION = '1.3.17'
+    VERSION = '1.3.19'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-cache
 version: !ruby/object:Gem::Version
-  version: 1.3.17
+  version: 1.3.19
 platform: ruby
 authors:
 - Esity