mudis 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b180000138c976ee0e0c7a7cdc068550c5f33f39f363c63ba6397b84fe8f6cbe
-  data.tar.gz: ee6de323fd9dcc5914ec0fde68da5fff7289e6c830395b9d4be4271d389b2c15
+  metadata.gz: 6207a8171eb9fd9723889d90a5a5e696dafc9a894c29d9b6f99340b7c02ec697
+  data.tar.gz: a18de4b21e8b4116c321393d0ada12da91c06682ff099907be84b6ac78c6f999
 SHA512:
-  metadata.gz: e7d2c14ca2b2dce8ed23f5fb371fe73456d92d9613e25d75fb645d1a6903259a21dd31dc7e3acca8f4336dc77990d5f33fce9254e3becdbcc59d7c19c526a302
-  data.tar.gz: 6619380f6d7206caec28c0e1f3f5450bb8991817fff6c08d6e7b5ceff2c82edc8a7c7b51b38894e5fb5a09e5f41a0546c50b951d088accfc1dc70a91935d398d
+  metadata.gz: e44da4c093e85012cee92cc61be4062c48fe94fe46b22210c1433e47b8eef91755359a658f936075ee514a5adcbf5ea2dae184031042532d13907d619ab77876
+  data.tar.gz: 79c1703d2d03938d801d752c7cc3c7c98ed777933e85b091ece31180d1dd2b9eaf0af8e8b8bd30221750cd89aa5cfb2989e8914aa4ef09fe6d1316a3ee678024

data/README.md

@@ -176,6 +176,20 @@ Mudis.metrics        # => { hits: 0, misses: 0, ... }
 Mudis.read("key")    # => "value" (still cached)
 ```
 
+#### `Mudis.least_touched`
+
+Returns the top `n` (or all) keys that have been read the fewest number of times, across all buckets. This is useful for identifying low-value cache entries that may be safe to remove or exclude from caching altogether.
+
+Each result includes the full key and its access count.
+
+```ruby
+Mudis.least_touched
+# => [["foo", 0], ["user:42", 1], ["product:123", 2], ...]
+
+Mudis.least_touched(5)
+# => returns top 5 least accessed keys
+```
+
 ---
 
 ## Rails Service Integration
@@ -277,6 +291,11 @@ Mudis.metrics
 #   evictions: 3,
 #   rejected: 0,
 #   total_memory: 45678,
+#   least_touched: [
+#     ["user:1", 0],
+#     ["post:5", 1],
+#     ...
+#   ],
 #   buckets: [
 #     { index: 0, keys: 12, memory_bytes: 12345, lru_size: 12 },
 #     ...
@@ -309,6 +328,8 @@ end
 | `Mudis.start_expiry_thread`    | Background TTL cleanup loop (every N sec)   | Disabled by default|
 | `Mudis.hard_memory_limit`    | Enforce hard memory limits on key size and reject if exceeded  | `false`|
 | `Mudis.max_bytes`    | Maximum allowed cache size  | `1GB`|
+| `Mudis.max_ttl`    | Set the maximum permitted TTL  | `nil` (no limit) |
+| `Mudis.default_ttl`    | Set the default TTL for fallback when none is provided  | `nil` |
 
 Buckets can also be set using a `MUDIS_BUCKETS` environment variable.
 
@@ -519,8 +540,8 @@ Mudis is not intended to be a general-purpose, distributed caching platform. You
 
 #### Safety & Policy Controls
 
-- [ ] max_ttl: Enforce a global upper bound on expires_in to prevent excessively long-lived keys
-- [ ] default_ttl: Provide a fallback TTL when one is not specified
+- [x] max_ttl: Enforce a global upper bound on expires_in to prevent excessively long-lived keys
+- [x] default_ttl: Provide a fallback TTL when one is not specified
 
 #### Debugging
 

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.4.4"
+MUDIS_VERSION = "0.5.0"

data/lib/mudis.rb

@@ -17,9 +17,11 @@ class Mudis # rubocop:disable Metrics/ClassLength
   @metrics_mutex = Mutex.new                    # Mutex for synchronizing access to metrics
   @max_value_bytes = nil                        # Optional size cap per value
   @stop_expiry = false                          # Signal for stopping expiry thread
+  @max_ttl = nil                                # Optional maximum TTL for cache entries
+  @default_ttl = nil                            # Default TTL for cache entries if not specified
 
   class << self
-    attr_accessor :serializer, :compress, :hard_memory_limit
+    attr_accessor :serializer, :compress, :hard_memory_limit, :max_ttl, :default_ttl
     attr_reader :max_bytes, :max_value_bytes
 
     # Configures Mudis with a block, allowing customization of settings
@@ -34,7 +36,7 @@ class Mudis # rubocop:disable Metrics/ClassLength
     end
 
     # Applies the current configuration to Mudis
-    def apply_config!
+    def apply_config! # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
       validate_config!
 
       self.serializer = config.serializer
@@ -42,10 +44,17 @@ class Mudis # rubocop:disable Metrics/ClassLength
       self.max_value_bytes = config.max_value_bytes
       self.hard_memory_limit = config.hard_memory_limit
       self.max_bytes = config.max_bytes
+      self.max_ttl = config.max_ttl
+      self.default_ttl = config.default_ttl
+
+      if config.buckets # rubocop:disable Style/GuardClause
+        @buckets = config.buckets
+        reset!
+      end
     end
 
     # Validates the current configuration, raising errors for invalid settings
-    def validate_config! # rubocop:disable Metrics/AbcSize
+    def validate_config! # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
       if config.max_value_bytes && config.max_value_bytes > config.max_bytes
         raise ArgumentError,
               "max_value_bytes cannot exceed max_bytes"
@@ -54,6 +63,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
       raise ArgumentError, "max_value_bytes must be > 0" if config.max_value_bytes && config.max_value_bytes <= 0
 
       raise ArgumentError, "buckets must be > 0" if config.buckets && config.buckets <= 0
+      raise ArgumentError, "max_ttl must be > 0" if config.max_ttl && config.max_ttl <= 0
+      raise ArgumentError, "default_ttl must be > 0" if config.default_ttl && config.default_ttl <= 0
     end
 
     # Returns a snapshot of metrics (thread-safe)
@@ -65,6 +76,7 @@ class Mudis # rubocop:disable Metrics/ClassLength
           evictions: @metrics[:evictions],
           rejected: @metrics[:rejected],
           total_memory: current_memory_bytes,
+          least_touched: least_touched(10),
           buckets: buckets.times.map do |idx|
             {
               index: idx,
@@ -186,11 +198,12 @@ class Mudis # rubocop:disable Metrics/ClassLength
     end
 
     # Reads and returns the value for a key, updating LRU and metrics
-    def read(key, namespace: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    def read(key, namespace: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
       key = namespaced_key(key, namespace)
       raw_entry = nil
       idx = bucket_index(key)
       mutex = @mutexes[idx]
+      store = @stores[idx]
 
       mutex.synchronize do
         raw_entry = @stores[idx][key]
@@ -199,6 +212,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
           raw_entry = nil
         end
 
+        store[key][:touches] = (store[key][:touches] || 0) + 1 if store[key]
+
         metric(:hits) if raw_entry
         metric(:misses) unless raw_entry
       end
@@ -223,6 +238,9 @@ class Mudis # rubocop:disable Metrics/ClassLength
         return
       end
 
+      # Ensure expires_in respects max_ttl and default_ttl
+      expires_in = effective_ttl(expires_in)
+
       idx = bucket_index(key)
       mutex = @mutexes[idx]
       store = @stores[idx]
@@ -238,7 +256,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
         store[key] = {
           value: raw,
           expires_at: expires_in ? Time.now + expires_in : nil,
-          created_at: Time.now
+          created_at: Time.now,
+          touches: 0
         }
 
         insert_lru(idx, key)
@@ -364,6 +383,24 @@ class Mudis # rubocop:disable Metrics/ClassLength
       keys
     end
 
+    # Returns the least-touched keys across all buckets
+    def least_touched(n = 10) # rubocop:disable Metrics/MethodLength,Naming/MethodParameterName
+      keys_with_touches = []
+
+      buckets.times do |idx|
+        mutex = @mutexes[idx]
+        store = @stores[idx]
+
+        mutex.synchronize do
+          store.each do |key, entry|
+            keys_with_touches << [key, entry[:touches] || 0]
+          end
+        end
+      end
+
+      keys_with_touches.sort_by { |_, count| count }.first(n)
+    end
+
     # Returns total memory used across all buckets
     def current_memory_bytes
       @current_bytes.sum
@@ -447,5 +484,14 @@ class Mudis # rubocop:disable Metrics/ClassLength
       ns = namespace || Thread.current[:mudis_namespace]
       ns ? "#{ns}:#{key}" : key
     end
+
+    # Calculates the effective TTL for an entry, respecting max_ttl if set
+    def effective_ttl(expires_in)
+      ttl = expires_in || @default_ttl
+      return nil unless ttl
+      return ttl unless @max_ttl
+
+      [ttl, @max_ttl].min
+    end
   end
 end

data/lib/mudis_config.rb

@@ -8,7 +8,9 @@ class MudisConfig
                 :max_value_bytes,
                 :hard_memory_limit,
                 :max_bytes,
-                :buckets
+                :buckets,
+                :max_ttl,
+                :default_ttl
 
   def initialize
     @serializer = JSON                        # Default serialization strategy
@@ -17,5 +19,7 @@ class MudisConfig
     @hard_memory_limit = false                # Enforce max_bytes as hard cap
     @max_bytes = 1_073_741_824                # 1 GB default max cache size
     @buckets = nil                            # use nil to signal fallback to ENV or default
+    @max_ttl = nil                            # Max TTL for cache entries (optional)
+    @default_ttl = nil                        # Default TTL for cache entries (optional)
   end
 end

data/sig/mudis.rbs

@@ -6,10 +6,13 @@ class Mudis
     attr_accessor hard_memory_limit : bool
     attr_reader max_bytes : Integer
     attr_reader max_value_bytes : Integer?
-
+    attr_accessor max_ttl: Integer?
+    attr_accessor default_ttl: Integer?
+    
     def configure: () { (config: MudisConfig) -> void } -> void
     def config: () -> MudisConfig
     def apply_config!: () -> void
+    def validate_config!: () -> void
 
     def buckets: () -> Integer
   end
@@ -43,6 +46,7 @@ class Mudis
   def self.all_keys: () -> Array[String]
   def self.current_memory_bytes: () -> Integer
   def self.max_memory_bytes: () -> Integer
+  def self.least_touched: (?Integer) -> Array[[String, Integer]]
 
   # State reset
   def self.reset!: () -> void

data/sig/mudis_config.rbs

@@ -1,8 +1,10 @@
 class MudisConfig
-  attr_accessor serializer : Object
-  attr_accessor compress : bool
-  attr_accessor max_value_bytes : Integer?
-  attr_accessor hard_memory_limit : bool
-  attr_accessor max_bytes : Integer
-  attr_accessor buckets : Integer?
+  attr_accessor serializer: Object
+  attr_accessor compress: bool
+  attr_accessor max_value_bytes: Integer?
+  attr_accessor hard_memory_limit: bool
+  attr_accessor max_bytes: Integer
+  attr_accessor max_ttl: Integer?
+  attr_accessor default_ttl: Integer?
+  attr_accessor buckets: Integer?
 end

data/spec/guardrails_spec.rb

@@ -3,6 +3,86 @@
 require "spec_helper"
 require "climate_control"
 
+RSpec.describe "Mudis TTL Guardrail" do # rubocop:disable Metrics/BlockLength
+  before do
+    Mudis.reset!
+    Mudis.configure do |c|
+      c.max_ttl = 60 # 60 seconds max
+    end
+  end
+
+  describe "default_ttl configuration" do # rubocop:disable Metrics/BlockLength
+    before do
+      Mudis.reset!
+      Mudis.configure do |c|
+        c.default_ttl = 60
+      end
+    end
+
+    it "applies default_ttl when expires_in is nil" do
+      Mudis.write("foo", "bar") # no explicit expires_in
+      meta = Mudis.inspect("foo")
+      expect(meta[:expires_at]).not_to be_nil
+      expect(meta[:expires_at]).to be_within(5).of(Time.now + 60)
+    end
+
+    it "respects expires_in if explicitly given" do
+      Mudis.write("short_lived", "bar", expires_in: 10)
+      meta = Mudis.inspect("short_lived")
+      expect(meta[:expires_at]).not_to be_nil
+      expect(meta[:expires_at]).to be_within(5).of(Time.now + 10)
+    end
+
+    it "applies max_ttl over default_ttl if both are set" do
+      Mudis.configure do |c|
+        c.default_ttl = 120
+        c.max_ttl = 30
+      end
+
+      Mudis.write("capped", "baz") # no explicit expires_in
+      meta = Mudis.inspect("capped")
+      expect(meta[:expires_at]).not_to be_nil
+      expect(meta[:expires_at]).to be_within(5).of(Time.now + 30)
+    end
+
+    it "stores forever if default_ttl and expires_in are nil" do
+      Mudis.configure do |c|
+        c.default_ttl = nil
+      end
+
+      Mudis.write("forever", "ever")
+      meta = Mudis.inspect("forever")
+      expect(meta[:expires_at]).to be_nil
+    end
+  end
+
+  it "clamps expires_in to max_ttl if it exceeds max_ttl" do
+    Mudis.write("foo", "bar", expires_in: 300) # user requests 5 minutes
+
+    metadata = Mudis.inspect("foo")
+    ttl = metadata[:expires_at] - metadata[:created_at]
+
+    expect(ttl).to be <= 60
+    expect(ttl).to be > 0
+  end
+
+  it "respects expires_in if below max_ttl" do
+    Mudis.write("bar", "baz", expires_in: 30) # under the max_ttl
+
+    metadata = Mudis.inspect("bar")
+    ttl = metadata[:expires_at] - metadata[:created_at]
+
+    expect(ttl).to be_within(1).of(30)
+  end
+
+  it "allows nil expires_in (no expiry) if not required" do
+    Mudis.write("baz", "no expiry")
+
+    metadata = Mudis.inspect("baz")
+    expect(metadata[:expires_at]).to be_nil
+  end
+end
+
 RSpec.describe "Mudis Configuration Guardrails" do # rubocop:disable Metrics/BlockLength
   after { Mudis.reset! }
 

data/spec/mudis_spec.rb

@@ -239,6 +239,23 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     end
   end
 
+  describe ".least_touched" do
+    it "returns keys with lowest read access counts" do
+      Mudis.reset!
+      Mudis.write("a", 1)
+      Mudis.write("b", 2)
+      Mudis.write("c", 3)
+
+      Mudis.read("a")
+      Mudis.read("a")
+      Mudis.read("b")
+
+      least = Mudis.least_touched(2)
+      expect(least.map(&:first)).to include("c") # Never read
+      expect(least.first.last).to eq(0)
+    end
+  end
+
   describe ".configure" do
     it "applies configuration settings correctly" do
       Mudis.configure do |c|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - kiebor81