legion-cache 1.3.16 → 1.3.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b737f804b6327030853b50a1c0fb76a5a06c8c26219ae23a0c0ac767a8d62d53
-  data.tar.gz: 31d960c23bea1c3426c476cce67ce30cee27879b2f3b917fdf98e02aa4d5670a
+  metadata.gz: aded92a74b60ff3cae8cab7d33d38f147bf17ac308dfd78695b2e6e2ed70298e
+  data.tar.gz: 244c88d6428745bd91d949dc7738cf65392e644d2143b3c092ab9b84fc610cd2
 SHA512:
-  metadata.gz: 1828c469b2d162eca345ca255e0489e98fee32249516552c922f56163c4066cb27364215b60a727af7c71b38f021f7d077107df826aadaafb95cbfd36ed04884
-  data.tar.gz: c4303cb9185f7d793fb4d383c690d7b48c90739a574ce2a03d0e1c93af6066cb62d6384738323336ccf3796c197cdd5f382b383e148537dafbccc165965d2670
+  metadata.gz: d6b790d262f8d9735c7d3a31a5222b449408deb00126f5184b8404fafbfa95a30a2eb3826a1cff5c0a44420fe0510399ff47c002ec816b65f596079977d00e4b
+  data.tar.gz: 774eb4fd9532934894e4d38ab52cba094e5fbab03c33eeb12f9aae0a244efebfddf3eea454a97445598143de680e2eac01ddd6b4f256b4ce116408e398c07e50

data/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Auto-generated from team-config.yml
+# Team: core
+#
+# To apply: scripts/apply-codeowners.sh legion-cache
+
+* @LegionIO/maintainers
+* @LegionIO/core

data/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [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
+- `Legion::Cache::RedisHash` module: Redis hash and sorted-set operations (`hset`, `hgetall`, `hdel`, `zadd`, `zrangebyscore`, `zrem`, `expire`) with `redis_available?` guard and safe defaults when Redis is not connected
+- Auto-required from `legion/cache.rb` alongside the existing Redis adapter
+
+## [1.3.16] - 2026-03-25
+
 ### Fixed
 - Accept ttl as positional or keyword argument in Cache.set for caller flexibility
 - Align Redis.set signature to positional ttl arg matching parent module convention

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/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,21 @@ 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
 
-      def local_cache_set(key, value, ttl: 60)
-        Legion::Cache::Local.set(cache_namespace + key, value, ttl)
+      # --- 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 +70,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

data/lib/legion/cache/redis_hash.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Cache
+    module RedisHash
+      module_function
+
+      # Returns true when the Redis driver is loaded and the connection pool is live.
+      def redis_available?
+        pool = Legion::Cache.instance_variable_get(:@client)
+        return false if pool.nil?
+
+        Legion::Cache.connected?
+      rescue StandardError
+        false
+      end
+
+      # Set hash fields from a Ruby Hash.
+      # Uses Redis HSET key field value [field value ...]
+      def hset(key, hash)
+        return false unless redis_available?
+
+        Legion::Cache.instance_variable_get(:@client).with do |conn|
+          flat = hash.flat_map { |k, v| [k.to_s, v.to_s] }
+          conn.hset(key, *flat)
+        end
+        true
+      rescue StandardError => e
+        log_redis_error('hset', e)
+        false
+      end
+
+      # Returns a Ruby Hash (string keys) of all field-value pairs for the key.
+      def hgetall(key)
+        return nil unless redis_available?
+
+        Legion::Cache.instance_variable_get(:@client).with do |conn|
+          conn.hgetall(key)
+        end
+      rescue StandardError => e
+        log_redis_error('hgetall', e)
+        nil
+      end
+
+      # Delete one or more hash fields.
+      def hdel(key, *fields)
+        return 0 unless redis_available?
+
+        Legion::Cache.instance_variable_get(:@client).with do |conn|
+          conn.hdel(key, *fields)
+        end
+      rescue StandardError => e
+        log_redis_error('hdel', e)
+        0
+      end
+
+      # Add a member to a sorted set with the given score.
+      def zadd(key, score, member)
+        return false unless redis_available?
+
+        Legion::Cache.instance_variable_get(:@client).with do |conn|
+          conn.zadd(key, score.to_f, member.to_s)
+        end
+        true
+      rescue StandardError => e
+        log_redis_error('zadd', e)
+        false
+      end
+
+      # Range query on a sorted set by score. Returns an array of members.
+      # limit: accepts [offset, count] array matching Redis LIMIT semantics.
+      def zrangebyscore(key, min, max, limit: nil)
+        return [] unless redis_available?
+
+        opts = {}
+        opts[:limit] = limit if limit
+
+        Legion::Cache.instance_variable_get(:@client).with do |conn|
+          conn.zrangebyscore(key, min, max, **opts)
+        end
+      rescue StandardError => e
+        log_redis_error('zrangebyscore', e)
+        []
+      end
+
+      # Remove a member from a sorted set.
+      def zrem(key, member)
+        return false unless redis_available?
+
+        Legion::Cache.instance_variable_get(:@client).with do |conn|
+          conn.zrem(key, member.to_s)
+        end
+        true
+      rescue StandardError => e
+        log_redis_error('zrem', e)
+        false
+      end
+
+      # Set a TTL (in seconds) on a key.
+      def expire(key, seconds)
+        return false unless redis_available?
+
+        Legion::Cache.instance_variable_get(:@client).with do |conn|
+          conn.expire(key, seconds.to_i) == 1
+        end
+      rescue StandardError => e
+        log_redis_error('expire', e)
+        false
+      end
+
+      def log_redis_error(method, error)
+        return unless defined?(Legion::Logging)
+
+        Legion::Logging.warn "[cache:redis_hash] #{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.16'
+    VERSION = '1.3.18'
   end
 end

data/lib/legion/cache.rb

@@ -6,6 +6,7 @@ require 'legion/cache/cacheable'
 
 require 'legion/cache/memcached'
 require 'legion/cache/redis'
+require 'legion/cache/redis_hash'
 require 'legion/cache/memory'
 require 'legion/cache/local'
 require 'legion/cache/helper'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-cache
 version: !ruby/object:Gem::Version
-  version: 1.3.16
+  version: 1.3.18
 platform: ruby
 authors:
 - Esity
@@ -90,6 +90,8 @@ extra_rdoc_files:
 - LICENSE
 - README.md
 files:
+- ".github/CODEOWNERS"
+- ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rubocop.yml"
@@ -107,6 +109,7 @@ files:
 - lib/legion/cache/memory.rb
 - lib/legion/cache/pool.rb
 - lib/legion/cache/redis.rb
+- lib/legion/cache/redis_hash.rb
 - lib/legion/cache/settings.rb
 - lib/legion/cache/version.rb
 - sonar-project.properties