mudis 0.4.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b180000138c976ee0e0c7a7cdc068550c5f33f39f363c63ba6397b84fe8f6cbe
-  data.tar.gz: ee6de323fd9dcc5914ec0fde68da5fff7289e6c830395b9d4be4271d389b2c15
+  metadata.gz: aeea820874569fe79af99d53f2a3ae3a7a9b74dc8a2d9dccbfbaa3f4ebab3967
+  data.tar.gz: 211d8c786790478e861461aab7444bd4bd1342afa07039ef3608f66dbd401cd6
 SHA512:
-  metadata.gz: e7d2c14ca2b2dce8ed23f5fb371fe73456d92d9613e25d75fb645d1a6903259a21dd31dc7e3acca8f4336dc77990d5f33fce9254e3becdbcc59d7c19c526a302
-  data.tar.gz: 6619380f6d7206caec28c0e1f3f5450bb8991817fff6c08d6e7b5ceff2c82edc8a7c7b51b38894e5fb5a09e5f41a0546c50b951d088accfc1dc70a91935d398d
+  metadata.gz: b93779c0990a328a3d24f4741b9934833e5524e099e2ddcdd2ae38f297e599f2cd49bd4fbc43d3cd1d1f81d2655220760b2573138ade72b289b785fc718c9bcd
+  data.tar.gz: bf25460f6237402793327d4bb04aef416d39f240e80350b8428433aa4245036cac0582f75e25b79c6902d21751403be9def2df01b9ebe54536ee39d229571590

data/README.md

@@ -176,6 +176,42 @@ 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
+```
+
+#### `Mudis.keys(namespace:)`
+
+Returns all keys for a given namespace.
+
+```ruby
+Mudis.write("u1", "alpha", namespace: "users")
+Mudis.write("u2", "beta", namespace: "users")
+
+Mudis.keys(namespace: "users")
+# => ["u1", "u2"]
+
+```
+
+#### `Mudis.clear_namespace(namespace:)`
+
+Deletes all keys within a namespace.
+
+```ruby
+Mudis.clear_namespace("users")
+Mudis.read("u1", namespace: "users") # => nil
+```
+
 ---
 
 ## Rails Service Integration
@@ -277,6 +313,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 +350,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.
 
@@ -515,16 +558,16 @@ Mudis is not intended to be a general-purpose, distributed caching platform. You
 
 #### API Enhancements
 
-- [ ] bulk_read(keys, namespace:): Batch retrieval of multiple keys with a single method call
+- [x] bulk_read(keys, namespace:): Batch retrieval of multiple keys with a single method call
 
 #### 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
 
-- [ ] clear_namespace(namespace): Remove all keys in a namespace in one call
+- [x] clear_namespace(namespace): Remove all keys in a namespace in one call
 
 ---
 

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.4.4"
+MUDIS_VERSION = "0.6.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,48 @@ class Mudis # rubocop:disable Metrics/ClassLength
       keys
     end
 
+    # Returns all keys in a specific namespace
+    def keys(namespace:)
+      raise ArgumentError, "namespace is required" unless namespace
+
+      prefix = "#{namespace}:"
+      all_keys.select { |key| key.start_with?(prefix) }.map { |key| key.delete_prefix(prefix) }
+    end
+
+    # Clears all keys in a specific namespace
+    def clear_namespace(namespace:)
+      raise ArgumentError, "namespace is required" unless namespace
+
+      prefix = "#{namespace}:"
+      buckets.times do |idx|
+        mutex = @mutexes[idx]
+        store = @stores[idx]
+
+        mutex.synchronize do
+          keys_to_delete = store.keys.select { |key| key.start_with?(prefix) }
+          keys_to_delete.each { |key| evict_key(idx, key) }
+        end
+      end
+    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 +508,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
@@ -36,6 +39,8 @@ class Mudis
   def self.clear: (String, ?namespace: String) -> void
   def self.replace: (String, untyped, ?expires_in: Integer, ?namespace: String) -> void
   def self.inspect: (String, ?namespace: String) -> Hash[Symbol, untyped]?
+  def self.keys: (?namespace: String) -> Array[String]
+  def self.clear_namespace: (?namespace: String) -> void
 
   # Introspection & management
   def self.metrics: () -> Hash[Symbol, untyped]
@@ -43,6 +48,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/eviction_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Mudis LRU Eviction" do
+  before do
+    Mudis.reset!
+    Mudis.stop_expiry_thread
+
+    Mudis.instance_variable_set(:@buckets, 1)
+    Mudis.instance_variable_set(:@stores, [{}])
+    Mudis.instance_variable_set(:@mutexes, [Mutex.new])
+    Mudis.instance_variable_set(:@lru_heads, [nil])
+    Mudis.instance_variable_set(:@lru_tails, [nil])
+    Mudis.instance_variable_set(:@lru_nodes, [{}])
+    Mudis.instance_variable_set(:@current_bytes, [0])
+    Mudis.hard_memory_limit = false
+    Mudis.instance_variable_set(:@threshold_bytes, 60)
+    Mudis.max_value_bytes = 100
+  end
+
+  it "evicts old entries when size limit is reached" do
+    Mudis.write("a", "a" * 50)
+    Mudis.write("b", "b" * 50)
+
+    expect(Mudis.read("a")).to be_nil
+    expect(Mudis.read("b")).not_to be_nil
+  end
+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/memory_guard_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Mudis Memory Guardrails" do
+  before do
+    Mudis.reset!
+    Mudis.stop_expiry_thread
+    Mudis.instance_variable_set(:@buckets, 1)
+    Mudis.instance_variable_set(:@stores, [{}])
+    Mudis.instance_variable_set(:@mutexes, [Mutex.new])
+    Mudis.instance_variable_set(:@lru_heads, [nil])
+    Mudis.instance_variable_set(:@lru_tails, [nil])
+    Mudis.instance_variable_set(:@lru_nodes, [{}])
+    Mudis.instance_variable_set(:@current_bytes, [0])
+
+    Mudis.max_value_bytes = nil
+    Mudis.instance_variable_set(:@threshold_bytes, 1_000_000)
+    Mudis.hard_memory_limit = true
+    Mudis.instance_variable_set(:@max_bytes, 100)
+  end
+
+  it "rejects writes that exceed max memory" do
+    big_value = "a" * 90
+    Mudis.write("a", big_value)
+    expect(Mudis.read("a")).to eq(big_value)
+
+    big_value2 = "b" * 90
+    Mudis.write("b", big_value2)
+    expect(Mudis.read("b")).to be_nil
+    expect(Mudis.metrics[:rejected]).to be > 0
+  end
+end

data/spec/metrics_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+RSpec.describe "Mudis Metrics" do # rubocop:disable Metrics/BlockLength
+  it "tracks hits and misses" do
+    Mudis.write("hit_me", "value")
+    Mudis.read("hit_me")
+    Mudis.read("miss_me")
+    metrics = Mudis.metrics
+    expect(metrics[:hits]).to eq(1)
+    expect(metrics[:misses]).to eq(1)
+  end
+
+  it "includes per-bucket stats" do
+    Mudis.write("a", "x" * 50)
+    metrics = Mudis.metrics
+    expect(metrics).to include(:buckets)
+    expect(metrics[:buckets]).to be_an(Array)
+    expect(metrics[:buckets].first).to include(:index, :keys, :memory_bytes, :lru_size)
+  end
+
+  it "resets only the metrics without clearing cache" do
+    Mudis.write("metrics_key", "value")
+    Mudis.read("metrics_key")
+    Mudis.read("missing_key")
+    expect(Mudis.metrics[:hits]).to eq(1)
+    expect(Mudis.metrics[:misses]).to eq(1)
+    Mudis.reset_metrics!
+    expect(Mudis.metrics[:hits]).to eq(0)
+    expect(Mudis.metrics[:misses]).to eq(0)
+    expect(Mudis.read("metrics_key")).to eq("value")
+  end
+end

data/spec/mudis_spec.rb

@@ -114,24 +114,6 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     end
   end
 
-  describe "namespacing" do
-    it "uses thread-local namespace in block" do
-      Mudis.with_namespace("test") do
-        Mudis.write("foo", "bar")
-      end
-      expect(Mudis.read("foo", namespace: "test")).to eq("bar")
-      expect(Mudis.read("foo")).to be_nil
-    end
-
-    it "supports explicit namespace override" do
-      Mudis.write("x", 1, namespace: "alpha")
-      Mudis.write("x", 2, namespace: "beta")
-      expect(Mudis.read("x", namespace: "alpha")).to eq(1)
-      expect(Mudis.read("x", namespace: "beta")).to eq(2)
-      expect(Mudis.read("x")).to be_nil
-    end
-  end
-
   describe "expiry handling" do
     it "expires values after specified time" do
       Mudis.write("short_lived", "gone soon", expires_in: 1)
@@ -140,74 +122,6 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     end
   end
 
-  describe ".metrics" do
-    it "tracks hits and misses" do
-      Mudis.write("hit_me", "value")
-      Mudis.read("hit_me")   # hit
-      Mudis.read("miss_me")  # miss
-      metrics = Mudis.metrics
-      expect(metrics[:hits]).to eq(1)
-      expect(metrics[:misses]).to eq(1)
-    end
-  end
-
-  describe "memory guards" do
-    before do
-      Mudis.stop_expiry_thread
-      Mudis.instance_variable_set(:@buckets, 1)
-      Mudis.instance_variable_set(:@stores, [{}])
-      Mudis.instance_variable_set(:@mutexes, [Mutex.new])
-      Mudis.instance_variable_set(:@lru_heads, [nil])
-      Mudis.instance_variable_set(:@lru_tails, [nil])
-      Mudis.instance_variable_set(:@lru_nodes, [{}])
-      Mudis.instance_variable_set(:@current_bytes, [0])
-
-      Mudis.max_value_bytes = nil
-      Mudis.instance_variable_set(:@threshold_bytes, 1_000_000) # optional
-      Mudis.hard_memory_limit = true
-      Mudis.instance_variable_set(:@max_bytes, 100) # artificially low
-    end
-
-    it "rejects writes that exceed max memory" do
-      big_value = "a" * 90
-      Mudis.write("a", big_value)
-      expect(Mudis.read("a")).to eq(big_value)
-
-      big_value_2 = "b" * 90 # rubocop:disable Naming/VariableNumber
-      Mudis.write("b", big_value_2)
-      expect(Mudis.read("b")).to be_nil
-      expect(Mudis.metrics[:rejected]).to be > 0
-    end
-  end
-
-  describe "LRU eviction" do
-    it "evicts old entries when size limit is reached" do
-      Mudis.stop_expiry_thread
-
-      # Force one bucket
-      Mudis.instance_variable_set(:@buckets, 1)
-      Mudis.instance_variable_set(:@stores, [{}])
-      Mudis.instance_variable_set(:@mutexes, [Mutex.new])
-      Mudis.instance_variable_set(:@lru_heads, [nil])
-      Mudis.instance_variable_set(:@lru_tails, [nil])
-      Mudis.instance_variable_set(:@lru_nodes, [{}])
-      Mudis.instance_variable_set(:@current_bytes, [0])
-      Mudis.hard_memory_limit = false
-      # Set very small threshold
-      Mudis.instance_variable_set(:@threshold_bytes, 60)
-      Mudis.max_value_bytes = 100
-
-      big_val1 = "a" * 50
-      big_val2 = "b" * 50
-
-      Mudis.write("a", big_val1)
-      Mudis.write("b", big_val2)
-
-      expect(Mudis.read("a")).to be_nil
-      expect(Mudis.read("b")).not_to be_nil
-    end
-  end
-
   describe ".all_keys" do
     it "lists all stored keys" do
       Mudis.write("k1", 1)
@@ -223,19 +137,30 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
 
   describe ".current_memory_bytes" do
     it "returns a non-zero byte count after writes" do
+      Mudis.configure do |c|
+        c.max_value_bytes = nil
+        c.hard_memory_limit = false
+      end
+
       Mudis.write("size_test", "a" * 100)
       expect(Mudis.current_memory_bytes).to be > 0
     end
   end
 
-  describe ".metrics" do
-    it "includes per-bucket stats" do
-      Mudis.write("a", "x" * 50)
-      metrics = Mudis.metrics
+  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)
 
-      expect(metrics).to include(:buckets)
-      expect(metrics[:buckets]).to be_an(Array)
-      expect(metrics[:buckets].first).to include(:index, :keys, :memory_bytes, :lru_size)
+      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
 
@@ -255,43 +180,4 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
       expect(Mudis.max_bytes).to eq(987_654)
     end
   end
-
-  describe ".reset!" do
-    it "clears all stores, memory, and metrics" do
-      Mudis.write("reset_key", "value")
-      expect(Mudis.read("reset_key")).to eq("value")
-      expect(Mudis.current_memory_bytes).to be > 0
-      expect(Mudis.metrics[:hits]).to be >= 0
-
-      Mudis.reset!
-
-      metrics = Mudis.metrics
-      expect(metrics[:hits]).to eq(0)
-      expect(metrics[:misses]).to eq(0)
-      expect(metrics[:evictions]).to eq(0)
-      expect(metrics[:rejected]).to eq(0)
-      expect(Mudis.current_memory_bytes).to eq(0)
-      expect(Mudis.all_keys).to be_empty
-
-      # Optionally confirm reset_key is now gone
-      expect(Mudis.read("reset_key")).to be_nil
-    end
-  end
-
-  describe ".reset_metrics!" do
-    it "resets only the metrics without clearing cache" do
-      Mudis.write("metrics_key", "value")
-      Mudis.read("metrics_key")  # generates :hits
-      Mudis.read("missing_key")  # generates :misses
-
-      expect(Mudis.metrics[:hits]).to eq(1)
-      expect(Mudis.metrics[:misses]).to eq(1)
-
-      Mudis.reset_metrics!
-
-      expect(Mudis.metrics[:hits]).to eq(0)
-      expect(Mudis.metrics[:misses]).to eq(0)
-      expect(Mudis.read("metrics_key")).to eq("value") # still exists
-    end
-  end
 end

data/spec/namespace_spec.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Mudis Namespace Operations" do # rubocop:disable Metrics/BlockLength
+  before(:each) do
+    Mudis.reset!
+  end
+
+  it "uses thread-local namespace in block" do
+    Mudis.with_namespace("test") do
+      Mudis.write("foo", "bar")
+    end
+    expect(Mudis.read("foo", namespace: "test")).to eq("bar")
+    expect(Mudis.read("foo")).to be_nil
+  end
+
+  it "supports explicit namespace override" do
+    Mudis.write("x", 1, namespace: "alpha")
+    Mudis.write("x", 2, namespace: "beta")
+    expect(Mudis.read("x", namespace: "alpha")).to eq(1)
+    expect(Mudis.read("x", namespace: "beta")).to eq(2)
+    expect(Mudis.read("x")).to be_nil
+  end
+
+  describe ".keys" do
+    it "returns only keys for the given namespace" do
+      Mudis.write("user:1", "Alice", namespace: "users")
+      Mudis.write("user:2", "Bob", namespace: "users")
+      Mudis.write("admin:1", "Charlie", namespace: "admins")
+
+      result = Mudis.keys(namespace: "users")
+      expect(result).to contain_exactly("user:1", "user:2")
+    end
+
+    it "returns an empty array if no keys exist for namespace" do
+      expect(Mudis.keys(namespace: "nonexistent")).to eq([])
+    end
+
+    it "raises an error if namespace is missing" do
+      expect { Mudis.keys(namespace: nil) }.to raise_error(ArgumentError, /namespace is required/)
+    end
+  end
+
+  describe ".clear_namespace" do
+    it "deletes all keys in the given namespace" do
+      Mudis.write("a", 1, namespace: "ns1")
+      Mudis.write("b", 2, namespace: "ns1")
+      Mudis.write("x", 9, namespace: "ns2")
+
+      expect(Mudis.read("a", namespace: "ns1")).to eq(1)
+      expect(Mudis.read("b", namespace: "ns1")).to eq(2)
+
+      Mudis.clear_namespace(namespace: "ns1")
+
+      expect(Mudis.read("a", namespace: "ns1")).to be_nil
+      expect(Mudis.read("b", namespace: "ns1")).to be_nil
+      expect(Mudis.read("x", namespace: "ns2")).to eq(9)
+    end
+
+    it "does nothing if namespace has no keys" do
+      expect { Mudis.clear_namespace(namespace: "ghost") }.not_to raise_error
+    end
+
+    it "raises an error if namespace is nil" do
+      expect { Mudis.clear_namespace(namespace: nil) }.to raise_error(ArgumentError, /namespace is required/)
+    end
+  end
+end

data/spec/reset_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Mudis Reset Features" do
+  before { Mudis.reset! }
+
+  describe ".reset!" do
+    it "clears all stores, memory, and metrics" do
+      Mudis.write("reset_key", "value")
+      expect(Mudis.read("reset_key")).to eq("value")
+      Mudis.reset!
+      expect(Mudis.metrics[:hits]).to eq(0)
+      expect(Mudis.all_keys).to be_empty
+      expect(Mudis.read("reset_key")).to be_nil
+    end
+  end
+
+  describe ".reset_metrics!" do
+    it "resets only the metrics without clearing cache" do
+      Mudis.write("metrics_key", "value")
+      Mudis.read("metrics_key")
+      Mudis.read("missing_key")
+      expect(Mudis.metrics[:hits]).to eq(1)
+      expect(Mudis.metrics[:misses]).to eq(1)
+      Mudis.reset_metrics!
+      expect(Mudis.metrics[:hits]).to eq(0)
+      expect(Mudis.read("metrics_key")).to eq("value")
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.6.0
 platform: ruby
 authors:
 - kiebor81
@@ -54,8 +54,13 @@ files:
 - lib/mudis_config.rb
 - sig/mudis.rbs
 - sig/mudis_config.rbs
+- spec/eviction_spec.rb
 - spec/guardrails_spec.rb
+- spec/memory_guard_spec.rb
+- spec/metrics_spec.rb
 - spec/mudis_spec.rb
+- spec/namespace_spec.rb
+- spec/reset_spec.rb
 homepage: https://github.com/kiebor81/mudis
 licenses:
 - MIT
@@ -81,5 +86,10 @@ specification_version: 4
 summary: A fast in-memory, thread-safe and high performance Ruby LRU cache with compression
   and auto-expiry.
 test_files:
+- spec/eviction_spec.rb
 - spec/guardrails_spec.rb
+- spec/memory_guard_spec.rb
+- spec/metrics_spec.rb
 - spec/mudis_spec.rb
+- spec/namespace_spec.rb
+- spec/reset_spec.rb