mudis 0.9.1 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ed8c4f85642ad10c8fc1d4213838004b647cd5a8f9da17dc4f9e8d99f45cb8b
-  data.tar.gz: 4eed96ebdb4e701b9ba3b3d9b3e79d08b928215e2bd848f618775a48304160f2
+  metadata.gz: 987b789b060c3e66ed1ce29fc8fc868f9955e986349a48da34f2d06f29bf21f4
+  data.tar.gz: cb846d56202f3934cb1f4e47ede9d12ef3cd8af050cedd6e5f901945b95c41ef
 SHA512:
-  metadata.gz: 98fe4110f82ba005e3f5b9d93e751341b6568d15e6052ee14544508ac3258912542d5e9a25a0c2b15c69326ee23e47885c6739bb93d946ae1443df6e740cc8e6
-  data.tar.gz: e67673464ae604cd40e3c92d032757dd383a5f28b661fa5f630f9329d55c6f2b06096440495b91e9fcf91c55cc3b5943f7956a59b47104c9c8f4ce77fbb33bff
+  metadata.gz: c14266d9bf5121b085f79029678ca4bf429451adf9335710d2046d152a9a17618051d141e2091fc6a260d5bcf9ec522680462037f9576d2d2504d09ddc8418e2
+  data.tar.gz: 217d6a415f9f7b9bea4240d6300337e4ea86e7aa10308a92dfb8c673ad8410f13cefb77c424bd00c7b2b138c698aefec030d47709fa78bd0b87dcb1e797874e7

data/README.md

@@ -157,9 +157,10 @@ sequenceDiagram
 - **LRU Eviction**: Automatically evicts least recently used items as memory fills up.
 - **Expiry Support**: Optional TTL per key with background cleanup thread.
 - **Compression**: Optional Zlib compression for large values.
-- **Metrics**: Tracks hits, misses, and evictions.
+- **Metrics**: Tracks hits, misses, and evictions, with optional per-namespace counters.
 - **IPC Mode**: Shared cross-process caching for multi-process aplications.
 - **Soft-persistence**: Data snapshot and reload.
+- **Caller Binding**: Optional scoped cache wrappers via `Mudis.bind`.
 
 ---
 
@@ -189,6 +190,7 @@ Mudis.configure do |c|
   c.max_value_bytes = 2_000_000  # Reject values > 2MB
   c.hard_memory_limit = true # enforce hard memory limits
   c.max_bytes = 1_073_741_824 # set maximum cache size
+  c.eviction_threshold = 0.9 # evict when a bucket exceeds 90% of max_bytes
 end
 
 Mudis.start_expiry_thread(interval: 60) # Cleanup every 60s
@@ -206,6 +208,7 @@ Mudis.compress = true          # Compress values using Zlib
 Mudis.max_value_bytes = 2_000_000  # Reject values > 2MB
 Mudis.hard_memory_limit = true # enforce hard memory limits
 Mudis.max_bytes = 1_073_741_824 # set maximum cache size
+Mudis.eviction_threshold = 0.9 # evict when a bucket exceeds 90% of max_bytes
 
 Mudis.start_expiry_thread(interval: 60) # Cleanup every 60s
 
@@ -331,11 +334,31 @@ Mudis.exists?('user:123') # => true
 
 # Atomically update
 Mudis.update('user:123') { |data| data.merge(age: 30) }
+# Note: update refreshes TTL based on the original TTL duration.
 
 # Delete a key
 Mudis.delete('user:123')
 ```
 
+### Caller-Scoped Cache (Bound)
+
+For caller-bound caching (per-tenant or per-service scoping), use `Mudis.bind` to create a scoped wrapper:
+
+```ruby
+cache = Mudis.bind(
+  namespace: "caller:123",
+  default_ttl: 60,
+  max_ttl: 300,
+  max_value_bytes: 128_000
+)
+
+cache.write("profile", { name: "Alice" })
+cache.read("profile") # => { "name" => "Alice" }
+cache.fetch("expensive", singleflight: true) { expensive_query }
+```
+
+The wrapper delegates to Mudis but automatically applies the namespace and optional per-caller guardrails.
+
 ### Developer Utilities
 
 Mudis provides utility methods to help with test environments, console debugging, and dev tool resets.
@@ -461,7 +484,7 @@ class MudisService
   # @param force [Boolean] force recomputation
   # @yield return value if key is missing
   def fetch(expires_in: nil, force: false)
-    Mudis.fetch(cache_key, expires_in: expires_in, force: force, namespace: namespace) do
+    Mudis.fetch(cache_key, expires_in: expires_in, force: force, namespace: namespace, singleflight: true) do
       yield
     end
   end
@@ -519,6 +542,13 @@ Mudis.metrics
 
 ```
 
+You can also query metrics for a specific namespace:
+
+```ruby
+Mudis.metrics(namespace: "users")
+# => { hits: 10, misses: 2, evictions: 1, rejected: 0, namespace: "users" }
+```
+
 Optionally, expose Mudis metrics from a controller or action for remote analysis and monitoring.
 
 **Rails:**
@@ -588,6 +618,7 @@ 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.eviction_threshold` | Evict when a bucket exceeds this ratio of max_bytes | `0.9` |
 | `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` |
 
@@ -695,7 +726,7 @@ This design allows multiple workers to share the same cache without duplicating
 | **Shared Cache Across Processes** | All Puma workers share one Mudis instance via IPC.                                       |
 | **Zero External Dependencies**    | No Redis, Memcached, or separate daemon required.                                        |
 | **Memory Efficient**              | Cache data stored only once, not duplicated per worker.                                  |
-| **Full Feature Support**          | All Mudis features (TTL, compression, metrics, etc.) work transparently.                 |
+| **Feature Coverage**              | Core cache ops + introspection (keys, inspect, least_touched) and metrics are supported. |
 | **Safe & Local**                  | Communication is limited to the host system’s UNIX socket, ensuring isolation and speed. |
 
 ```mermaid
@@ -763,13 +794,18 @@ if defined?($mudis) && $mudis
     def self.delete(*a, **k) = $mudis.delete(*a, **k)
     def self.fetch(*a, **k, &b) = $mudis.fetch(*a, **k, &b)
     def self.metrics = $mudis.metrics
-    def self.reset_metrics! = $mudis.reset_metrics!
-    def self.reset! = $mudis.reset!
   end
 
 end
 ```
 
+**IPC safety limitations:**
+
+- Administrative operations are **not** exposed over IPC (e.g., `reset!`, `reset_metrics!`, `save_snapshot!`, `load_snapshot!`).
+- IPC client requests use timeouts and retries:
+  - `MUDIS_IPC_TIMEOUT` (seconds, default: `1`)
+  - `MUDIS_IPC_RETRIES` (default: `1`)
+
 **Use IPC mode when:**
 
 - Running Rails or Rack apps under Puma cluster or multi-process background job workers.

data/lib/mudis/bound.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+class Mudis
+  # Scoped wrapper for caller-bound access with optional per-caller policy.
+  class Bound
+    def initialize(namespace:, default_ttl: nil, max_ttl: nil, max_value_bytes: nil)
+      raise ArgumentError, "namespace is required" if namespace.nil? || namespace.to_s.empty?
+
+      @namespace = namespace
+      @default_ttl = default_ttl
+      @max_ttl = max_ttl
+      @max_value_bytes = max_value_bytes
+      @inflight_mutexes_lock = Mutex.new
+      @inflight_mutexes = {}
+    end
+
+    attr_reader :namespace
+
+    def read(key)
+      Mudis.read(key, namespace: @namespace)
+    end
+
+    def write(key, value, expires_in: nil)
+      return if exceeds_max_value_bytes?(value)
+
+      Mudis.write(key, value, expires_in: effective_ttl(expires_in), namespace: @namespace)
+    end
+
+    def update(key)
+      Mudis.update(key, namespace: @namespace) do |current|
+        next_value = yield(current)
+        exceeds_max_value_bytes?(next_value) ? current : next_value
+      end
+    end
+
+    def delete(key)
+      Mudis.delete(key, namespace: @namespace)
+    end
+
+    def exists?(key)
+      Mudis.exists?(key, namespace: @namespace)
+    end
+
+    def fetch(key, expires_in: nil, force: false, singleflight: false)
+      return fetch_without_lock(key, expires_in:, force:) { yield } unless singleflight
+
+      with_inflight_lock(key) do
+        fetch_without_lock(key, expires_in:, force:) { yield }
+      end
+    end
+
+    def clear(key)
+      delete(key)
+    end
+
+    def replace(key, value, expires_in: nil)
+      return if exceeds_max_value_bytes?(value)
+
+      Mudis.replace(key, value, expires_in: effective_ttl(expires_in), namespace: @namespace)
+    end
+
+    def inspect(key)
+      Mudis.inspect(key, namespace: @namespace)
+    end
+
+    def keys
+      Mudis.keys(namespace: @namespace)
+    end
+
+    def metrics
+      Mudis.metrics(namespace: @namespace)
+    end
+
+    def clear_namespace
+      Mudis.clear_namespace(namespace: @namespace)
+    end
+
+    private
+
+    def effective_ttl(expires_in)
+      ttl = expires_in || @default_ttl
+      return nil unless ttl
+      return ttl unless @max_ttl
+
+      [ttl, @max_ttl].min
+    end
+
+    def exceeds_max_value_bytes?(value)
+      return false unless @max_value_bytes
+
+      raw = Mudis.serializer.dump(value)
+      raw = Zlib::Deflate.deflate(raw) if Mudis.compress
+      raw.bytesize > @max_value_bytes
+    end
+
+    def fetch_without_lock(key, expires_in:, force:)
+      unless force
+        cached = read(key)
+        return cached if cached
+      end
+
+      value = yield
+      return nil if exceeds_max_value_bytes?(value)
+
+      write(key, value, expires_in: expires_in)
+      value
+    end
+
+    def with_inflight_lock(lock_key)
+      entry = nil
+      @inflight_mutexes_lock.synchronize do
+        entry = (@inflight_mutexes[lock_key] ||= { mutex: Mutex.new, count: 0 })
+        entry[:count] += 1
+      end
+
+      entry[:mutex].synchronize { yield }
+    ensure
+      @inflight_mutexes_lock.synchronize do
+        next unless entry
+
+        entry[:count] -= 1
+        @inflight_mutexes.delete(lock_key) if entry[:count] <= 0
+      end
+    end
+  end
+end

data/lib/mudis/metrics.rb

@@ -4,7 +4,9 @@ class Mudis
   # Metrics module handles tracking of cache hits, misses, evictions and memory usage
   module Metrics
     # Returns a snapshot of metrics (thread-safe)
-    def metrics # rubocop:disable Metrics/MethodLength
+    def metrics(namespace: nil) # rubocop:disable Metrics/MethodLength
+      return namespace_metrics(namespace) if namespace
+
       @metrics_mutex.synchronize do
         {
           hits: @metrics[:hits],
@@ -30,13 +32,30 @@ class Mudis
       @metrics_mutex.synchronize do
         @metrics = { hits: 0, misses: 0, evictions: 0, rejected: 0 }
       end
+
+      @metrics_by_namespace_mutex.synchronize do
+        @metrics_by_namespace = {}
+      end
     end
 
     private
 
     # Thread-safe metric increment
-    def metric(name)
+    def metric(name, namespace: nil)
       @metrics_mutex.synchronize { @metrics[name] += 1 }
+      return unless namespace
+
+      @metrics_by_namespace_mutex.synchronize do
+        @metrics_by_namespace[namespace] ||= { hits: 0, misses: 0, evictions: 0, rejected: 0 }
+        @metrics_by_namespace[namespace][name] += 1
+      end
+    end
+
+    def namespace_metrics(namespace)
+      @metrics_by_namespace_mutex.synchronize do
+        entry = @metrics_by_namespace[namespace] || { hits: 0, misses: 0, evictions: 0, rejected: 0 }
+        entry.merge(namespace: namespace)
+      end
     end
   end
 end

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.9.1"
+MUDIS_VERSION = "0.9.4"

data/lib/mudis.rb

@@ -10,6 +10,7 @@ require_relative "mudis/persistence"
 require_relative "mudis/metrics"
 require_relative "mudis/namespace"
 require_relative "mudis/expiry"
+require_relative "mudis/bound"
 
 # Mudis is a thread-safe, in-memory, sharded, LRU cache with optional compression and expiry.
 # It is designed for high concurrency and performance within a Ruby application.
@@ -26,6 +27,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
   @compress = false                             # Whether to compress values with Zlib
   @metrics = { hits: 0, misses: 0, evictions: 0, rejected: 0 } # Metrics tracking read/write behaviour
   @metrics_mutex = Mutex.new                    # Mutex for synchronizing access to metrics
+  @metrics_by_namespace = {}                    # Per-namespace metrics
+  @metrics_by_namespace_mutex = Mutex.new       # Mutex for synchronizing namespace 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
@@ -34,13 +37,20 @@ class Mudis # rubocop:disable Metrics/ClassLength
   # --- Configuration Management ---
 
   class << self
-    attr_accessor :serializer, :compress, :hard_memory_limit, :max_ttl, :default_ttl
+    attr_accessor :serializer, :compress, :hard_memory_limit, :max_ttl, :default_ttl, :eviction_threshold
     attr_reader :max_bytes, :max_value_bytes
 
     # Configures Mudis with a block, allowing customization of settings
     def configure
-      yield(config)
+      new_config = config.dup
+      yield(new_config)
+
+      old_config = @config
+      @config = new_config
       apply_config!
+    rescue StandardError
+      @config = old_config
+      raise
     end
 
     # Returns the current configuration object
@@ -48,6 +58,15 @@ class Mudis # rubocop:disable Metrics/ClassLength
       @config ||= MudisConfig.new
     end
 
+    def bind(namespace:, default_ttl: nil, max_ttl: nil, max_value_bytes: nil)
+      Bound.new(
+        namespace: namespace,
+        default_ttl: default_ttl,
+        max_ttl: max_ttl,
+        max_value_bytes: max_value_bytes
+      )
+    end
+
     # Applies the current configuration to Mudis
     def apply_config! # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
       validate_config!
@@ -57,6 +76,7 @@ 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.eviction_threshold = config.eviction_threshold
       self.max_ttl = config.max_ttl
       self.default_ttl = config.default_ttl
 
@@ -85,6 +105,9 @@ 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
+      if config.eviction_threshold && (config.eviction_threshold <= 0 || config.eviction_threshold > 1)
+        raise ArgumentError, "eviction_threshold must be > 0 and <= 1"
+      end
       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
@@ -102,6 +125,7 @@ class Mudis # rubocop:disable Metrics/ClassLength
       @lru_tails     = Array.new(b) { nil }
       @lru_nodes     = Array.new(b) { {} }
       @current_bytes = Array.new(b, 0)
+      @inflight_mutexes = {}
 
       reset_metrics!
     end
@@ -111,7 +135,16 @@ class Mudis # rubocop:disable Metrics/ClassLength
       raise ArgumentError, "max_bytes must be > 0" if value.to_i <= 0
 
       @max_bytes = value
-      @threshold_bytes = (@max_bytes * 0.9).to_i
+      threshold = @eviction_threshold || 0.9
+      @threshold_bytes = (@max_bytes * threshold).to_i
+    end
+
+    def eviction_threshold=(value)
+      return @eviction_threshold = nil if value.nil?
+      raise ArgumentError, "eviction_threshold must be > 0 and <= 1" if value <= 0 || value > 1
+
+      @eviction_threshold = value
+      @threshold_bytes = (@max_bytes * @eviction_threshold).to_i
     end
 
     # Sets the maximum size for a single value in bytes, raising an error if invalid
@@ -141,9 +174,12 @@ class Mudis # rubocop:disable Metrics/ClassLength
   @lru_nodes = Array.new(buckets) { {} }        # Map of key => LRU node
   @current_bytes = Array.new(buckets, 0)        # Memory usage per bucket
   @max_bytes = 1_073_741_824                    # 1 GB global max cache size
-  @threshold_bytes = (@max_bytes * 0.9).to_i # Eviction threshold at 90%
+  @eviction_threshold = 0.9
+  @threshold_bytes = (@max_bytes * @eviction_threshold).to_i # Eviction threshold at 90%
   @expiry_thread = nil # Background thread for expiry cleanup
   @hard_memory_limit = false # Whether to enforce hard memory cap
+  @inflight_mutexes_lock = Mutex.new
+  @inflight_mutexes = {}
 
   # --- Core Cache Operations ---
 
@@ -161,6 +197,7 @@ class Mudis # rubocop:disable Metrics/ClassLength
     # Reads and returns the value for a key, updating LRU and metrics
     def read(key, namespace: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
       key = namespaced_key(key, namespace)
+      ns = namespace || Thread.current[:mudis_namespace]
       raw_entry = nil
       idx = bucket_index(key)
       mutex = @mutexes[idx]
@@ -178,26 +215,26 @@ class Mudis # rubocop:disable Metrics/ClassLength
           promote_lru(idx, key)
         end
 
-        metric(:hits) if raw_entry
-        metric(:misses) unless raw_entry
+        metric(:hits, namespace: ns) if raw_entry
+        metric(:misses, namespace: ns) unless raw_entry
       end
 
       return nil unless raw_entry
 
-      value = decompress_and_deserialize(raw_entry[:value])
-      value
+      decompress_and_deserialize(raw_entry[:value])
     end
 
     # Writes a value to the cache with optional expiry and LRU tracking
     def write(key, value, expires_in: nil, namespace: nil) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/PerceivedComplexity
       key = namespaced_key(key, namespace)
+      ns = namespace || Thread.current[:mudis_namespace]
       raw = serializer.dump(value)
       raw = Zlib::Deflate.deflate(raw) if compress
       size = key.bytesize + raw.bytesize
       return if max_value_bytes && raw.bytesize > max_value_bytes
 
       if hard_memory_limit && current_memory_bytes + size > max_memory_bytes
-        metric(:rejected)
+        metric(:rejected, namespace: ns)
         return
       end
 
@@ -212,15 +249,18 @@ class Mudis # rubocop:disable Metrics/ClassLength
         evict_key(idx, key) if store[key]
 
         while @current_bytes[idx] + size > (@threshold_bytes / buckets) && @lru_tails[idx]
-          evict_key(idx, @lru_tails[idx].key)
-          metric(:evictions)
+          evict_key_name = @lru_tails[idx].key
+          evict_ns = store[evict_key_name] && store[evict_key_name][:namespace]
+          evict_key(idx, evict_key_name)
+          metric(:evictions, namespace: evict_ns)
         end
 
         store[key] = {
           value: raw,
           expires_at: expires_in ? Time.now + expires_in : nil,
           created_at: Time.now,
-          touches: 0
+          touches: 0,
+          namespace: ns
         }
 
         insert_lru(idx, key)
@@ -254,19 +294,29 @@ class Mudis # rubocop:disable Metrics/ClassLength
         old_size = key.bytesize + current_entry[:value].bytesize
         new_size = key.bytesize + new_raw.bytesize
 
+        ns = current_entry[:namespace]
+
         if hard_memory_limit && (current_memory_bytes - old_size + new_size) > max_memory_bytes
-          metric(:rejected)
+          metric(:rejected, namespace: ns)
           return
         end
 
         while (@current_bytes[idx] - old_size + new_size) > (@threshold_bytes / buckets) && @lru_tails[idx]
           break if @lru_tails[idx].key == key
 
-          evict_key(idx, @lru_tails[idx].key)
-          metric(:evictions)
+          evict_key_name = @lru_tails[idx].key
+          evict_ns = store[evict_key_name] && store[evict_key_name][:namespace]
+          evict_key(idx, evict_key_name)
+          metric(:evictions, namespace: evict_ns)
         end
 
         store[key][:value] = new_raw
+
+        # Refresh TTL on update. If no TTL applies, keep existing expiry (possibly nil).
+        now = Time.now
+        ttl = current_entry[:expires_at] ? (current_entry[:expires_at] - current_entry[:created_at]) : nil
+        store[key][:created_at] = now
+        store[key][:expires_at] = ttl ? now + ttl : nil
         @current_bytes[idx] += (new_size - old_size)
         promote_lru(idx, key)
       end
@@ -287,15 +337,13 @@ class Mudis # rubocop:disable Metrics/ClassLength
     # The block is executed to generate the value if it doesn't exist
     # Optionally accepts an expiration time
     # If force is true, it always fetches and writes the value
-    def fetch(key, expires_in: nil, force: false, namespace: nil)
-      unless force
-        cached = read(key, namespace: namespace)
-        return cached if cached
-      end
+    def fetch(key, expires_in: nil, force: false, namespace: nil, singleflight: false) # rubocop:disable Metrics/MethodLength
+      return fetch_without_lock(key, expires_in:, force:, namespace:) { yield } unless singleflight
 
-      value = yield
-      write(key, value, expires_in: expires_in, namespace: namespace)
-      value
+      lock_key = namespaced_key(key, namespace)
+      with_inflight_lock(lock_key) do
+        fetch_without_lock(key, expires_in:, force:, namespace:) { yield }
+      end
     end
 
     # Clears a specific key from the cache, a semantic synonym for delete
@@ -383,5 +431,33 @@ class Mudis # rubocop:disable Metrics/ClassLength
       val = compress ? Zlib::Inflate.inflate(raw) : raw
       serializer.load(val)
     end
+
+    def fetch_without_lock(key, expires_in:, force:, namespace:)
+      unless force
+        cached = read(key, namespace: namespace)
+        return cached if cached
+      end
+
+      value = yield
+      write(key, value, expires_in: expires_in, namespace: namespace)
+      value
+    end
+
+    def with_inflight_lock(lock_key)
+      entry = nil
+      @inflight_mutexes_lock.synchronize do
+        entry = (@inflight_mutexes[lock_key] ||= { mutex: Mutex.new, count: 0 })
+        entry[:count] += 1
+      end
+
+      entry[:mutex].synchronize { yield }
+    ensure
+      @inflight_mutexes_lock.synchronize do
+        next unless entry
+
+        entry[:count] -= 1
+        @inflight_mutexes.delete(lock_key) if entry[:count] <= 0
+      end
+    end
   end
 end