mudis 0.9.0 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 283e3b629449e6324d30dd19450d4d363a5d415ad45ace27569d4d82fb7e8066
-  data.tar.gz: 5fe63b61e7526eb90c66c9a5f9da721c5156ec40a144398cedb89e11adc7b35e
+  metadata.gz: 987b789b060c3e66ed1ce29fc8fc868f9955e986349a48da34f2d06f29bf21f4
+  data.tar.gz: cb846d56202f3934cb1f4e47ede9d12ef3cd8af050cedd6e5f901945b95c41ef
 SHA512:
-  metadata.gz: cfc3db7ea2a80a03af39738a6700bbd07b525dbd101bf7b3b8f11b1fa711fdc14a9ad248dcdeff5b469e55bca24efd15d08ac5bf3ff91c83b6614c5ddc925521
-  data.tar.gz: 4923b6e5ccb935914e0c5811be65fbe358304db5f6e8d76097b08f25db939e441b0b72557695981ffdae7e300d36dd4a66c3d2b3d2fd163c1e3735dbddbd61e6
+  metadata.gz: c14266d9bf5121b085f79029678ca4bf429451adf9335710d2046d152a9a17618051d141e2091fc6a260d5bcf9ec522680462037f9576d2d2504d09ddc8418e2
+  data.tar.gz: 217d6a415f9f7b9bea4240d6300337e4ea86e7aa10308a92dfb8c673ad8410f13cefb77c424bd00c7b2b138c698aefec030d47709fa78bd0b87dcb1e797874e7

data/README.md

@@ -29,8 +29,8 @@ Mudis also works naturally in Hanami because it’s a pure Ruby in-memory cache.
 - [Installation](#installation)
 - [Configuration (Ruby/Rails)](#configuration-rubyrails)
 - [Configuration (Hanami)](#configuration-hanami)
-- [Start and Stop Exipry Thread](#start-and-stop-exipry-thread)
-  - [Starting Exipry Thread](#starting-exipry-thread)
+- [Start and Stop Expiry Thread](#start-and-stop-expiry-thread)
+  - [Starting Expiry Thread](#starting-expiry-thread)
   - [Graceful Shutdown](#graceful-shutdown)
 - [Basic Usage](#basic-usage)
   - [Developer Utilities](#developer-utilities)
@@ -96,15 +96,57 @@ There are plenty out there, in various states of maintenance and in many shapes
 
 #### Internal Structure and Behaviour
 
-![mudis_flow](design/mudis_obj.png "Mudis Internals")
+```mermaid
+flowchart TD
+  A[Mudis] --> C[Config]
+  A --> B[Shards/Buckets]
+  B --> S[Store Hash]
+  B --> L[LRU List]
+  B --> M[Mutex]
+  A --> E[Expiry Thread]
+  A --> P[Persistence]
+  A --> R[Metrics]
+  A --> N[Namespace]
+```
 
 #### Write - Read - Eviction
 
-![mudis_flow](design/mudis_flow.png "Write - Read - Eviction")
+```mermaid
+flowchart TD
+  W[Write] --> S[Serialize]
+  S --> Z{Compress?}
+  Z -- Yes --> ZL[Zlib Deflate]
+  Z -- No --> SZ[Raw]
+  ZL --> G[Size/Memory Guardrails]
+  SZ --> G
+  G --> T[Set TTL]
+  T --> I[Insert in Bucket]
+  I --> L[LRU Insert]
+  L --> M[Update Bytes]
+  R[Read] --> LK[Lookup]
+  LK --> X{Expired?}
+  X -- Yes --> EV[Evict]
+  X -- No --> D[Deserialize/Inflate]
+  D --> PR[Promote LRU]
+  PR --> OUT[Return Value]
+  E[Evict] --> LRU[LRU Tail]
+```
 
 #### Cache Key Lifecycle
 
-![mudis_lru](design/mudis_lru.png "Mudis Cache Key Lifecycle")
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Mudis
+  participant LRU as LRU List
+  Client->>Mudis: write(key, value)
+  Mudis->>LRU: insert(key) at head
+  Client->>Mudis: read(key)
+  Mudis->>LRU: promote(key) to head
+  Note over Mudis: if over threshold, evict tail
+  Mudis->>LRU: evict(tail)
+  Mudis-->>Client: value or nil
+```
 
 ---
 
@@ -115,9 +157,10 @@ There are plenty out there, in various states of maintenance and in many shapes
 - **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`.
 
 ---
 
@@ -147,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
@@ -164,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
 
@@ -245,11 +290,11 @@ end
 
 ---
 
-## Start and Stop Exipry Thread
+## Start and Stop Expiry Thread
 
 The expiry thread is not triggered automatically when your application starts. You must add the start and stop in the respective process hooks.
 
-### Starting Exipry Thread
+### Starting Expiry Thread
 
 To enable background expiration and removal, you must start the expiry thread at start up after configuration.
 
@@ -289,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.
@@ -419,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
@@ -477,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:**
@@ -546,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` |
 
@@ -611,7 +684,16 @@ Mudis.load_snapshot!
 
 #### Example Flow
 
-![mudis_persistence](design/mudis_persistence.png "Mudis Persistence Strategy")
+```mermaid
+flowchart LR
+  A[App Boot] --> B[Configure Mudis]
+  B --> C[Load Snapshot]
+  C --> D[Cache Warm]
+  D --> E[Normal Operations]
+  E --> F[Exit Hook]
+  F --> G[Save Snapshot]
+  G --> H[Snapshot File]
+```
 
 1. On startup, `Mudis.load_snapshot!` repopulates the cache.  
 2. Your app uses the cache as normal (`write`, `read`, `fetch`, etc.).  
@@ -644,10 +726,21 @@ 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. |
 
-![mudis_ipc](design/mudis_ipc.png "Mudis IPC")
+```mermaid
+flowchart LR
+  M[Master Process] --> S[MudisServer]
+  W1[Worker 1] --> C1[MudisClient]
+  W2[Worker 2] --> C2[MudisClient]
+  W3[Worker 3] --> C3[MudisClient]
+  C1 --> U[Unix Socket/TCP]
+  C2 --> U
+  C3 --> U
+  U --> S
+  S --> Cache[Mudis Cache]
+```
 
 ### Setup (Puma)
 
@@ -701,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.
@@ -799,7 +897,7 @@ _10000 iterations of 512KB, JSON, compression ON_
 ## Known Limitations
 
 - Data is **non-persistent**; only soft-persistence is optionally provided.
-- No SQL or equivallent query interface for cached data. Data is per Key retrieval only.
+- No SQL or equivallent query interface for cached data. Data is per Key retrieval only (see [Mudis-QL](https://github.com/kiebor81/mudis-ql)).
 - Compression introduces CPU overhead.
 
 ---
@@ -934,7 +1032,7 @@ Mudis is not intended to be a general-purpose, distributed caching platform. You
 
 - [x] Review Mudis for improved readability and reduce complexity in top-level functions
 - [x] Enhanced guards
-- [ ] Refactor main classes for enhanced readability
+- [x] Refactor main classes for enhanced readability
 - [ ] Review for functionality gaps and enhance as needed 
 
 ---

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/persistence.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 class Mudis
   # Persistence module handles snapshot save/load operations for warm boot support
   module Persistence
@@ -80,7 +82,7 @@ class Mudis
     def safe_write_snapshot(data) # rubocop:disable Metrics/MethodLength
       path = @persistence_path
       dir = File.dirname(path)
-      Dir.mkdir(dir) unless Dir.exist?(dir)
+      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
 
       payload =
         if (@persistence_format || :marshal).to_sym == :json

data/lib/mudis/version.rb

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