mudis 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff59084c07925cd39d362eb387e32ecd6c1c5038c92bbef4e7782f4fa37cdf23
-  data.tar.gz: b9e4db5c9faf2cb426d2c941377ee2617abd335cf77d94aa8817fc726560bb89
+  metadata.gz: ae292b0f546008c9be0a96ef33f4e6a2f8c3a79fdd5545da375eafd435d9f36b
+  data.tar.gz: eee866d44d874439535fab0778e41a17f6bb10b2043dfec8ee7493c083811a75
 SHA512:
-  metadata.gz: e0a426f20bae0e68cf840783e1fa131039e2ccfaa17dbb1c557ead4a34da878f43f17a7d4c6753039687a2a7722865f6f4198dc74990f4004ccde1395deaac6a
-  data.tar.gz: 0d40c4e492fdca8539f95e983c0e28890e882d846c4068d8fd679d0d0868bb15387a17b5c3dea52a3ca50e0c443e3d587212d93b9e8f5f7c2087c8ac5f141407
+  metadata.gz: d24edc845960b0c56b9bdf286d51863c919960d8270fabe9acb6729ad1faa173a9dd40b810e89e766360fe383787ebc89e03c8a84234b65d2202a44705e80cfb
+  data.tar.gz: f260429d8a394eefdc0a2d637c646b175ce22b48ed1a9fdf04e225d908022656d985ce67041d8762a0cadf95484b4b29e63114b4ae55227f0060c60be97347ad

data/README.md

@@ -1,5 +1,7 @@
 ![mudis_signet](design/mudis.png "Mudis")
 
+[![RubyMine](https://www.elegantobjects.org/rubymine.svg)](https://www.jetbrains.com/ruby/)
+
 [![Gem Version](https://badge.fury.io/rb/mudis.svg?icon=si%3Arubygems&refresh=1&cachebust=0)](https://badge.fury.io/rb/mudis)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
@@ -36,12 +38,13 @@ Mudis also works naturally in Hanami because it’s a pure Ruby in-memory cache.
 - [Rails Service Integration](#rails-service-integration)
 - [Metrics](#metrics)
 - [Advanced Configuration](#advanced-configuration)
-- [Benchmarks](#benchmarks)
-- [Graceful Shutdown](#graceful-shutdown)
-- [Known Limitations](#known-limitations)
+- [Soft Persistence (Snapshots)](#soft-persistence-snapshots)
 - [Inter-Process Caching (IPC Mode)](#inter-process-caching-ipc-mode)
   - [Overview](#overview)
   - [Setup (Puma)](#setup-puma)
+- [Benchmarks](#benchmarks)
+- [Graceful Shutdown](#graceful-shutdown)
+- [Known Limitations](#known-limitations)
 - [Create a Mudis Web Cache Server](#create-a-mudis-web-cache-server)
   - [Minimal Setup](#minimal-setup)
 - [Project Philosophy](#project-philosophy)
@@ -528,100 +531,69 @@ When setting `serializer`, be mindful of the below
 
 ---
 
-## Benchmarks
-
-#### Serializer(s)
-
-_100000 iterations_
-
-| Serializer     | Total Time (s) | Ops/sec |
-|----------------|------------|----------------|
-| oj         | 0.1342         | 745320  |
-| marshal        | 0.3228         | 309824  |
-| json           | 0.9035         | 110682  |
-| oj + zlib    | 1.8050         | 55401   |
-| marshal + zlib   | 1.8057         | 55381   |
-| json + zlib      | 2.7949         | 35780   |
-
-> If opting for OJ, you will need to install the dependency in your project and configure as needed.
-
-#### Mudis vs Rails.cache
-
-Mudis is marginally slower than `Rails.cache` by design; it trades raw speed for control, observability, and safety.
-
-_10000 iterations of 1MB, Marshal (to match MemoryStore default), compression ON_
-
-| Operation | `Rails.cache` | `Mudis`     | Delta     |
-| --------- | ------------- | ----------- | --------- |
-| Write     | 2.139 ms/op   | 2.417 ms/op | +0.278 ms |
-| Read      | 0.007 ms/op   | 0.810 ms/op | +0.803 ms |
+## Soft Persistence (Snapshots)
 
-> For context: a typical database query or HTTP call takes 10–50ms. A difference of less than 1ms per operation is negligible for most apps.
-
-#### **Why this overhead exists**
-
-Mudis includes features that MemoryStore doesn’t:
-
-| Feature            | Mudis                  | Rails.cache (MemoryStore)   |
-| ------------------ | ---------------------- | --------------------------- |
-| Per-key TTL expiry | ✅    | ⚠️ on access |
-| True LRU eviction  | ✅     | ❌          |
-| Hard memory limits | ✅                   | ❌         |
-| Value compression  | ✅     | ❌             |
-| Thread safety      | ✅ Bucket-level mutexes | ✅ Global mutex              |
-| Observability      | ✅         | ❌           |
-| Namespacing        | ✅           | ❌ Manual scoping        |
-| IPC Aware        | ✅ (if enabled) | ❌ Requires manual configuration and additional gems       |
+Mudis can optionally soft-persist its in-memory cache to disk between process restarts.  
+When enabled, it will automatically:
 
-It will be down to the developer to decide if a fraction of a millisecond is worth
+- **Save** a snapshot of the current cache at shutdown  
+- **Reload** it on startup
 
-- Predictable eviction
-- Configurable expiry
-- Memory protection
-- Namespace scoping
-- Real-time metrics for hits, misses, evictions, memory usage
+This feature is **off by default** and can be enabled via configuration.
 
-_10000 iterations of 1MB, Marshal (to match MemoryStore default), compression OFF (to match MemoryStore default)_
+Example configuration:
 
-| Operation | `Rails.cache` | `Mudis`     | Delta         |
-| --------- | ------------- | ----------- | ------------- |
-| Write     | 2.342 ms/op   | 0.501 ms/op | **−1.841 ms** |
-| Read      | 0.007 ms/op   | 0.011 ms/op | +0.004 ms     |
+```ruby
+Mudis.configure do |config|
+  config.persistence_enabled = true
+  config.persistence_path = "tmp/mudis_snapshot.dump"
+  config.persistence_format = :marshal   # or :json
+  config.persistence_safe_write = true   # atomic temp write + rename
+end
 
-With compression disabled, Mudis writes significanty faster and reads are virtually identical. Optimisation and configuration of Mudis will be determined by your individual needs.
+## Optionally install the exit hook manually (usually automatic)
+# Mudis.install_persistence_hook!
+```
 
-#### Other Benchmarks
+From your startup routine:
 
-_10000 iterations of 512KB, JSON, compression OFF (to match MemoryStore default)_
+```ruby
+# Restore snapshot on startup
+Mudis.load_snapshot!
+```
 
-| Operation | `Rails.cache` | `Mudis`     | Delta         |
-| --------- | ------------- | ----------- | ------------- |
-| Write     | 1.291 ms/op   | 0.32 ms/op | **−0.971 ms** |
-| Read      | 0.011 ms/op   | 0.048 ms/op | +0.037 ms     |
+*This feature works identically in Rails, Hanami, and standalone Ruby scripts, as long as `Mudis.configure` is called prior to `Mudis.load_snapshot!`.*
 
-_10000 iterations of 512KB, JSON, compression ON_
+### Behavior
 
-| Operation | `Rails.cache` | `Mudis`     | Delta         |
-| --------- | ------------- | ----------- | ------------- |
-| Write     | 1.11 ms/op   | 1.16 ms/op |  +0.05 ms |
-| Read      | 0.07 ms/op   | 0.563 ms/op | +0.493 ms     |
+| Operation | Description |
+|------------|-------------|
+| `save_snapshot!` | Dumps all non-expired cache entries to disk. |
+| `load_snapshot!` | Reads snapshot and restores entries via normal write path. |
+| `install_persistence_hook!` | Registers an `at_exit` hook to automatically save on process exit. |
 
----
+#### Notes
 
-## Graceful Shutdown
+- Disabled by default for backward compatibility.  
+- Uses Ruby’s `Marshal` by default for fastest serialization; `:json` also supported.  
+- Respects TTLs: expired entries are never written to disk.  
+- Thread-safe: snapshots are taken under shard-level locks.  
+- Safe write: when `persistence_safe_write = true`, Mudis writes to a temp file and renames it atomically.
 
-Don’t forget to stop the expiry thread when your app exits:
+#### Example Flow
 
-```ruby
-at_exit { Mudis.stop_expiry_thread }
-```
+![mudis_persistence](design/mudis_persistence.png "Mudis Persistence Strategy")
 
----
+1. On startup, `Mudis.load_snapshot!` repopulates the cache.  
+2. Your app uses the cache as normal (`write`, `read`, `fetch`, etc.).  
+3. When the process exits, `at_exit` automatically triggers `save_snapshot!`.  
+4. A file (e.g., `tmp/mudis_snapshot.dump`) holds your persisted cache.
 
-## Known Limitations
+#### Safety
 
-- Data is **non-persistent**.
-- Compression introduces CPU overhead.
+If the snapshot file is **missing** or **corrupted**, Mudis will:
+- Log a warning via `warn "[Mudis] Failed to load snapshot..."`, and  
+- Continue booting normally with an empty cache.
 
 ---
 
@@ -712,6 +684,103 @@ end
 
 ---
 
+## Benchmarks
+
+#### Serializer(s)
+
+_100000 iterations_
+
+| Serializer     | Total Time (s) | Ops/sec |
+|----------------|------------|----------------|
+| oj         | 0.1342         | 745320  |
+| marshal        | 0.3228         | 309824  |
+| json           | 0.9035         | 110682  |
+| oj + zlib    | 1.8050         | 55401   |
+| marshal + zlib   | 1.8057         | 55381   |
+| json + zlib      | 2.7949         | 35780   |
+
+> If opting for OJ, you will need to install the dependency in your project and configure as needed.
+
+#### Mudis vs Rails.cache
+
+Mudis is marginally slower than `Rails.cache` by design; it trades raw speed for control, observability, and safety.
+
+_10000 iterations of 1MB, Marshal (to match MemoryStore default), compression ON_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta     |
+| --------- | ------------- | ----------- | --------- |
+| Write     | 2.139 ms/op   | 2.417 ms/op | +0.278 ms |
+| Read      | 0.007 ms/op   | 0.810 ms/op | +0.803 ms |
+
+> For context: a typical database query or HTTP call takes 10–50ms. A difference of less than 1ms per operation is negligible for most apps.
+
+#### **Why this overhead exists**
+
+Mudis includes features that MemoryStore doesn’t:
+
+| Feature            | Mudis                  | Rails.cache (MemoryStore)   |
+| ------------------ | ---------------------- | --------------------------- |
+| Per-key TTL expiry | ✅    | ⚠️ on access |
+| True LRU eviction  | ✅     | ❌          |
+| Hard memory limits | ✅                   | ❌         |
+| Value compression  | ✅     | ❌             |
+| Thread safety      | ✅ Bucket-level mutexes | ✅ Global mutex              |
+| Observability      | ✅         | ❌           |
+| Namespacing        | ✅           | ❌ Manual scoping        |
+| IPC Aware        | ✅ (if enabled) | ❌ Requires manual configuration and additional gems       |
+
+It will be down to the developer to decide if a fraction of a millisecond is worth
+
+- Predictable eviction
+- Configurable expiry
+- Memory protection
+- Namespace scoping
+- Real-time metrics for hits, misses, evictions, memory usage
+
+_10000 iterations of 1MB, Marshal (to match MemoryStore default), compression OFF (to match MemoryStore default)_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta         |
+| --------- | ------------- | ----------- | ------------- |
+| Write     | 2.342 ms/op   | 0.501 ms/op | **−1.841 ms** |
+| Read      | 0.007 ms/op   | 0.011 ms/op | +0.004 ms     |
+
+With compression disabled, Mudis writes significanty faster and reads are virtually identical. Optimisation and configuration of Mudis will be determined by your individual needs.
+
+#### Other Benchmarks
+
+_10000 iterations of 512KB, JSON, compression OFF (to match MemoryStore default)_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta         |
+| --------- | ------------- | ----------- | ------------- |
+| Write     | 1.291 ms/op   | 0.32 ms/op | **−0.971 ms** |
+| Read      | 0.011 ms/op   | 0.048 ms/op | +0.037 ms     |
+
+_10000 iterations of 512KB, JSON, compression ON_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta         |
+| --------- | ------------- | ----------- | ------------- |
+| Write     | 1.11 ms/op   | 1.16 ms/op |  +0.05 ms |
+| Read      | 0.07 ms/op   | 0.563 ms/op | +0.493 ms     |
+
+---
+
+## Graceful Shutdown
+
+Don’t forget to stop the expiry thread when your app exits:
+
+```ruby
+at_exit { Mudis.stop_expiry_thread }
+```
+
+---
+
+## Known Limitations
+
+- Data is **non-persistent**; only soft-persistence is optionally provided.
+- Compression introduces CPU overhead.
+
+---
+
 ## Create a Mudis Web Cache Server
 
 ### Minimal Setup

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.7.3"
+MUDIS_VERSION = "0.8.0"

data/lib/mudis.rb

@@ -47,6 +47,11 @@ class Mudis # rubocop:disable Metrics/ClassLength
       self.max_ttl = config.max_ttl
       self.default_ttl = config.default_ttl
 
+      @persistence_enabled    = config.persistence_enabled
+      @persistence_path       = config.persistence_path
+      @persistence_format     = config.persistence_format
+      @persistence_safe_write = config.persistence_safe_write
+
       if config.buckets # rubocop:disable Style/GuardClause
         @buckets = config.buckets
         reset!
@@ -518,4 +523,109 @@ class Mudis # rubocop:disable Metrics/ClassLength
       [ttl, @max_ttl].min
     end
   end
+
+  class << self
+
+    # Saves the current cache state to disk for persistence
+    def save_snapshot!
+      return unless @persistence_enabled
+      data = snapshot_dump
+      safe_write_snapshot(data)
+    rescue => e
+      warn "[Mudis] Failed to save snapshot: #{e.class}: #{e.message}"
+    end
+
+    # Loads the cache state from disk for persistence
+    def load_snapshot!
+      return unless @persistence_enabled
+      return unless File.exist?(@persistence_path)
+      data = read_snapshot
+      snapshot_restore(data)
+    rescue => e
+      warn "[Mudis] Failed to load snapshot: #{e.class}: #{e.message}"
+    end
+
+    # Installs an at_exit hook to save the snapshot on process exit
+    def install_persistence_hook!
+      return unless @persistence_enabled
+      return if defined?(@persistence_hook_installed) && @persistence_hook_installed
+      at_exit { save_snapshot! }
+      @persistence_hook_installed = true
+    end
+  end
+
+  class << self
+    private
+    # Collect a JSON/Marshal-safe array of { key, value, expires_in }
+    def snapshot_dump
+      entries = []
+      now = Time.now
+      @buckets.times do |idx|
+        mutex = @mutexes[idx]
+        store = @stores[idx]
+        mutex.synchronize do
+          store.each do |key, raw|
+            exp_at = raw[:expires_at]
+            next if exp_at && now > exp_at
+            value = decompress_and_deserialize(raw[:value])
+            expires_in = exp_at ? (exp_at - now).to_i : nil
+            entries << { key: key, value: value, expires_in: expires_in }
+          end
+        end
+      end
+      entries
+    end
+
+    # Restore via existing write-path so LRU/limits/compression/TTL are honored
+    def snapshot_restore(entries)
+      return unless entries && !entries.empty?
+      entries.each do |e|
+        begin
+          write(e[:key], e[:value], expires_in: e[:expires_in])
+        rescue => ex
+          warn "[Mudis] Failed to restore key #{e[:key].inspect}: #{ex.message}"
+        end
+      end
+    end
+
+    # Serializer for snapshot persistence
+    # Defaults to Marshal if not JSON
+    def serializer_for_snapshot
+      (@persistence_format || :marshal).to_sym == :json ? JSON : :marshal
+    end
+
+    # Safely writes snapshot data to disk
+    # Uses safe write if configured
+    def safe_write_snapshot(data)
+      path = @persistence_path
+      dir = File.dirname(path)
+      Dir.mkdir(dir) unless Dir.exist?(dir)
+
+      payload =
+        if (@persistence_format || :marshal).to_sym == :json
+          serializer_for_snapshot.dump(data)
+        else
+          Marshal.dump(data)
+        end
+
+      if @persistence_safe_write
+        tmp = "#{path}.tmp-#{$$}-#{Thread.current.object_id}"
+        File.open(tmp, "wb") { |f| f.write(payload) }
+        File.rename(tmp, path)
+      else
+        File.open(path, "wb") { |f| f.write(payload) }
+      end
+    end
+
+    # Reads snapshot data from disk
+    # Uses safe read if configured
+    def read_snapshot
+      if (@persistence_format || :marshal).to_sym == :json
+        serializer_for_snapshot.load(File.binread(@persistence_path))
+      else
+        Marshal.load(File.binread(@persistence_path))
+      end
+    end
+  end
+
 end

data/lib/mudis_config.rb

@@ -10,7 +10,12 @@ class MudisConfig
                 :max_bytes,
                 :buckets,
                 :max_ttl,
-                :default_ttl
+                :default_ttl,
+                # Persistence settings
+                :persistence_enabled,
+                :persistence_path,
+                :persistence_format,
+                :persistence_safe_write
 
   def initialize
     @serializer = JSON                        # Default serialization strategy
@@ -21,5 +26,10 @@ class MudisConfig
     @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)
+    # Persistence settings
+    @persistence_enabled = false              # Whether persistence is enabled
+    @persistence_path = 'mudis_data'          # Default path for persistence files
+    @persistence_format = :json               # Default persistence file format
+    @persistence_safe_write = true            # Whether to use safe write for persistence
   end
 end

data/lib/mudis_proxy.rb

@@ -19,7 +19,7 @@ unless defined?(MudisClient)
   return
 end
 
-unless defined?($mudis) && $mudis
+unless defined?($mudis) && $mudis # rubocop:disable Style/GlobalVars
   warn "[MudisProxy] $mudis not set: proxy not activated"
   return
 end
@@ -34,4 +34,4 @@ class << Mudis
   def reset! = $mudis.reset! # rubocop:disable Style/GlobalVars
 end
 
-warn "[MudisProxy] Proxy activated: forwarding calls to $mudis"
+warn "[MudisProxy] Proxy activated: forwarding calls to $mudis"

data/spec/persistence_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+require "spec_helper"
+require "fileutils"
+
+RSpec.describe "Mudis soft persistence" do
+  let(:path) { "tmp/test_mudis_snapshot.dump" }
+
+  before do
+    FileUtils.rm_f(path)
+    Mudis.reset!
+    Mudis.configure do |c|
+      c.persistence_enabled = true
+      c.persistence_path    = path
+      c.persistence_format  = :marshal
+    end
+  end
+
+  it "saves on exit and loads on next boot" do
+    Mudis.write("k1", "v1", expires_in: 60)
+    # simulate shutdown
+    Mudis.save_snapshot!
+    Mudis.reset!
+
+    # simulate fresh boot (apply config + load)
+    Mudis.apply_config! # if not public, re-configure to trigger load
+    Mudis.load_snapshot!
+
+    expect(Mudis.read("k1")).to eq("v1")
+  end
+
+  it "does nothing when file missing" do
+    Mudis.reset!
+    Mudis.configure { |c| c.persistence_enabled = true; c.persistence_path = path }
+    Mudis.load_snapshot! # no file
+    expect(Mudis.read("any")).to be_nil
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - kiebor81
 bindir: bin
 cert_chain: []
-date: 2025-10-24 00:00:00.000000000 Z
+date: 2025-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: climate_control
@@ -67,6 +67,7 @@ files:
 - spec/mudis_server_spec.rb
 - spec/mudis_spec.rb
 - spec/namespace_spec.rb
+- spec/persistence_spec.rb
 - spec/reset_spec.rb
 homepage: https://github.com/kiebor81/mudis
 licenses:
@@ -99,4 +100,5 @@ test_files:
 - spec/mudis_server_spec.rb
 - spec/mudis_spec.rb
 - spec/namespace_spec.rb
+- spec/persistence_spec.rb
 - spec/reset_spec.rb