mudis 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 283e3b629449e6324d30dd19450d4d363a5d415ad45ace27569d4d82fb7e8066
-  data.tar.gz: 5fe63b61e7526eb90c66c9a5f9da721c5156ec40a144398cedb89e11adc7b35e
+  metadata.gz: 6ed8c4f85642ad10c8fc1d4213838004b647cd5a8f9da17dc4f9e8d99f45cb8b
+  data.tar.gz: 4eed96ebdb4e701b9ba3b3d9b3e79d08b928215e2bd848f618775a48304160f2
 SHA512:
-  metadata.gz: cfc3db7ea2a80a03af39738a6700bbd07b525dbd101bf7b3b8f11b1fa711fdc14a9ad248dcdeff5b469e55bca24efd15d08ac5bf3ff91c83b6614c5ddc925521
-  data.tar.gz: 4923b6e5ccb935914e0c5811be65fbe358304db5f6e8d76097b08f25db939e441b0b72557695981ffdae7e300d36dd4a66c3d2b3d2fd163c1e3735dbddbd61e6
+  metadata.gz: 98fe4110f82ba005e3f5b9d93e751341b6568d15e6052ee14544508ac3258912542d5e9a25a0c2b15c69326ee23e47885c6739bb93d946ae1443df6e740cc8e6
+  data.tar.gz: e67673464ae604cd40e3c92d032757dd383a5f28b661fa5f630f9329d55c6f2b06096440495b91e9fcf91c55cc3b5943f7956a59b47104c9c8f4ce77fbb33bff

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
+```
 
 ---
 
@@ -245,11 +287,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.
 
@@ -611,7 +653,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.).  
@@ -647,7 +698,18 @@ This design allows multiple workers to share the same cache without duplicating
 | **Full Feature Support**          | All Mudis features (TTL, compression, metrics, etc.) work transparently.                 |
 | **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)
 
@@ -799,7 +861,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 +996,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/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.1"

data/lib/mudis.rb

@@ -155,8 +155,7 @@ class Mudis # rubocop:disable Metrics/ClassLength
 
     # Checks if a key exists and is not expired
     def exists?(key, namespace: nil)
-      key = namespaced_key(key, namespace)
-      !!read(key)
+      !!read(key, namespace: namespace)
     end
 
     # Reads and returns the value for a key, updating LRU and metrics
@@ -174,7 +173,10 @@ class Mudis # rubocop:disable Metrics/ClassLength
           raw_entry = nil
         end
 
-        store[key][:touches] = (store[key][:touches] || 0) + 1 if store[key]
+        if store[key]
+          store[key][:touches] = (store[key][:touches] || 0) + 1
+          promote_lru(idx, key)
+        end
 
         metric(:hits) if raw_entry
         metric(:misses) unless raw_entry
@@ -183,7 +185,6 @@ class Mudis # rubocop:disable Metrics/ClassLength
       return nil unless raw_entry
 
       value = decompress_and_deserialize(raw_entry[:value])
-      promote_lru(idx, key)
       value
     end
 
@@ -244,10 +245,27 @@ class Mudis # rubocop:disable Metrics/ClassLength
       new_value = yield(value)
       new_raw = serializer.dump(new_value)
       new_raw = Zlib::Deflate.deflate(new_raw) if compress
+      return if max_value_bytes && new_raw.bytesize > max_value_bytes
 
       mutex.synchronize do
-        old_size = key.bytesize + raw_entry[:value].bytesize
+        current_entry = store[key]
+        return nil unless current_entry
+
+        old_size = key.bytesize + current_entry[:value].bytesize
         new_size = key.bytesize + new_raw.bytesize
+
+        if hard_memory_limit && (current_memory_bytes - old_size + new_size) > max_memory_bytes
+          metric(:rejected)
+          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)
+        end
+
         store[key][:value] = new_raw
         @current_bytes[idx] += (new_size - old_size)
         promote_lru(idx, key)
@@ -270,14 +288,13 @@ class Mudis # rubocop:disable Metrics/ClassLength
     # 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)
-      key = namespaced_key(key, namespace)
       unless force
-        cached = read(key)
+        cached = read(key, namespace: namespace)
         return cached if cached
       end
 
       value = yield
-      write(key, value, expires_in: expires_in)
+      write(key, value, expires_in: expires_in, namespace: namespace)
       value
     end
 

data/sig/mudis.rbs

@@ -45,8 +45,9 @@ 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
+  def self.keys: (namespace: String) -> Array[String]
+  def self.clear_namespace: (namespace: String) -> void
+  def self.with_namespace: (namespace: String) { () -> untyped } -> untyped
 
   # Introspection & management
   def self.metrics: () -> Hash[Symbol, untyped]
@@ -59,4 +60,9 @@ class Mudis
   # State reset
   def self.reset!: () -> void
   def self.reset_metrics!: () -> void
+
+  # Persistence
+  def self.save_snapshot!: () -> void
+  def self.load_snapshot!: () -> void
+  def self.install_persistence_hook!: () -> void
 end

data/sig/mudis_client.rbs

@@ -5,7 +5,7 @@ class MudisClient
 
   def open_connection: () -> (TCPSocket | UNIXSocket)
 
-  def request: (payload: { cmd: String, key?: String, value?: untyped, ttl?: Integer?, namespace?: String? }) -> untyped
+  def request: (payload: Hash[Symbol, untyped]) -> untyped
 
   def read: (key: String, namespace?: String?) -> untyped
 
@@ -17,9 +17,9 @@ class MudisClient
 
   def fetch: (key: String, expires_in?: Integer?, namespace?: String?, &block: { () -> untyped }) -> untyped
 
-  def metrics: () -> { reads: Integer, writes: Integer, deletes: Integer, exists: Integer }
+  def metrics: () -> Hash[Symbol, untyped]
 
   def reset_metrics!: () -> void
 
   def reset!: () -> void
-end
+end

data/sig/mudis_config.rbs

@@ -7,4 +7,8 @@ class MudisConfig
   attr_accessor max_ttl: Integer?
   attr_accessor default_ttl: Integer?
   attr_accessor buckets: Integer?
+  attr_accessor persistence_enabled: bool
+  attr_accessor persistence_path: String
+  attr_accessor persistence_format: Symbol
+  attr_accessor persistence_safe_write: bool
 end

data/sig/mudis_expiry.rbs

@@ -8,6 +8,6 @@ class Mudis
 
     private
 
-    def effective_ttl: (?expires_in: Integer?) -> Integer?
+    def effective_ttl: (Integer?) -> Integer?
   end
 end

data/sig/mudis_lru.rbs

@@ -12,7 +12,7 @@ class Mudis
 
     def evict_key: (Integer, String) -> void
 
-    def insert_lru: (Integer, LRUNode) -> void
+    def insert_lru: (Integer, String) -> void
 
     def promote_lru: (Integer, String) -> void
 

data/sig/mudis_persistence.rbs

@@ -8,12 +8,12 @@ class Mudis
 
     private
 
-    def snapshot_dump: () -> Hash[String, untyped]
+    def snapshot_dump: () -> Array[{ key: String, value: untyped, expires_in: Integer? }]
 
-    def snapshot_restore: (Hash[String, untyped]) -> void
+    def snapshot_restore: (Array[{ key: String, value: untyped, expires_in: Integer? }]) -> void
 
-    def safe_write_snapshot: (Hash[String, untyped]) -> void
+    def safe_write_snapshot: (Array[{ key: String, value: untyped, expires_in: Integer? }]) -> void
 
-    def read_snapshot: () -> Hash[String, untyped]
+    def read_snapshot: () -> Array[{ key: String, value: untyped, expires_in: Integer? }]
   end
 end

data/sig/mudis_server.rbs

@@ -7,11 +7,11 @@ class MudisServer
 
   def self.start_unix_server!: () -> void
 
-  def self.accept_connections: (server: (TCPServer | UNIXServer)) -> void
+  def self.accept_connections: (server: (TCPServer | UNIXServer)) -> Thread
 
   def self.handle_client: (socket: (TCPSocket | UNIXSocket)) -> void
 
-  def self.process_request: (req: Hash[String, untyped]) -> Hash[Symbol, untyped]
+  def self.process_request: (req: Hash[Symbol, untyped]) -> untyped
 
   def self.write_response: (socket: (TCPSocket | UNIXSocket), payload: Hash[Symbol, untyped]) -> void
-end
+end

data/spec/memory_guard_spec.rb

@@ -30,4 +30,13 @@ RSpec.describe "Mudis Memory Guardrails" do
     expect(Mudis.read("b")).to be_nil
     expect(Mudis.metrics[:rejected]).to be > 0
   end
+
+  it "rejects updates that exceed max memory" do
+    Mudis.write("a", "a" * 10)
+    expect(Mudis.read("a")).to eq("a" * 10)
+
+    Mudis.update("a") { "b" * 200 }
+    expect(Mudis.read("a")).to eq("a" * 10)
+    expect(Mudis.metrics[:rejected]).to be > 0
+  end
 end

data/spec/mudis_client_spec.rb

@@ -18,7 +18,7 @@ RSpec.describe MudisClient do # rubocop:disable Metrics/BlockLength
     if MudisIPCConfig.use_tcp?
       allow(TCPSocket).to receive(:new).and_return(mock_socket)
     else
-      allow(UNIXSocket).to receive(:open).and_yield(mock_socket)
+      allow(UNIXSocket).to receive(:open).and_return(mock_socket)
     end
     allow(mock_socket).to receive(:close)
   end

data/spec/mudis_server_spec.rb

@@ -6,6 +6,13 @@ require "json"
 require_relative "spec_helper"
 
 RSpec.describe MudisServer do # rubocop:disable Metrics/BlockLength
+  unless ENV["MUDIS_RUN_IPC"] == "true"
+    it "skips IPC socket tests unless MUDIS_RUN_IPC=true" do
+      skip "Set MUDIS_RUN_IPC=true to run IPC socket tests"
+    end
+    next
+  end
+
   let(:socket_path) { MudisIPCConfig::SOCKET_PATH }
 
   before(:all) do

data/spec/namespace_spec.rb

@@ -23,6 +23,29 @@ RSpec.describe "Mudis Namespace Operations" do # rubocop:disable Metrics/BlockLe
     expect(Mudis.read("x")).to be_nil
   end
 
+  it "does not double-prefix keys in exists? under thread namespace" do
+    Mudis.with_namespace("ns") do
+      Mudis.write("k", "v")
+      expect(Mudis.exists?("k")).to be true
+    end
+  end
+
+  it "does not double-prefix keys in fetch under thread namespace" do
+    Mudis.with_namespace("ns") do
+      value = Mudis.fetch("k") { "v" }
+      expect(value).to eq("v")
+      expect(Mudis.read("k")).to eq("v")
+    end
+  end
+
+  it "does not double-prefix keys in replace under thread namespace" do
+    Mudis.with_namespace("ns") do
+      Mudis.write("k", "v")
+      Mudis.replace("k", "v2")
+      expect(Mudis.read("k")).to eq("v2")
+    end
+  end
+
   describe ".keys" do
     it "returns only keys for the given namespace" do
       Mudis.write("user:1", "Alice", namespace: "users")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - kiebor81
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-12-02 00:00:00.000000000 Z
+date: 2026-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: climate_control