mudis 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5cae2113816ed18a4d28661643657f0ddb64ec111a953df361c6e759c4d5869
-  data.tar.gz: bcd55c7e26ba1b4c2446f9236a764381f5a72de0f45f4b6088306798847c0da1
+  metadata.gz: 283e3b629449e6324d30dd19450d4d363a5d415ad45ace27569d4d82fb7e8066
+  data.tar.gz: 5fe63b61e7526eb90c66c9a5f9da721c5156ec40a144398cedb89e11adc7b35e
 SHA512:
-  metadata.gz: 1186f39ba21ea5facd7c589cf536f576584fac1dff2cad4fdb5567264b236f40100413d0e32edfeaf13d2f05ac9d10061f72c83bd4c12304abb998246caf1ed7
-  data.tar.gz: 742ab271a73b033dc746ff3426bcfccea808c996a0fff7d6d6ffd0182375e2c7d904c44c1899d9bb39dc4c5d092f92744c31adbac88b8f9dc57e286cab27dcfb
+  metadata.gz: cfc3db7ea2a80a03af39738a6700bbd07b525dbd101bf7b3b8f11b1fa711fdc14a9ad248dcdeff5b469e55bca24efd15d08ac5bf3ff91c83b6614c5ddc925521
+  data.tar.gz: 4923b6e5ccb935914e0c5811be65fbe358304db5f6e8d76097b08f25db939e441b0b72557695981ffdae7e300d36dd4a66c3d2b3d2fd163c1e3735dbddbd61e6

data/README.md

@@ -3,6 +3,7 @@
 [![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)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/mudis)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 **Mudis** is a fast, thread-safe, in-memory, sharded LRU (Least Recently Used) cache for Ruby applications. Inspired by Redis, it provides value serialization, optional compression, per-key expiry, and metric tracking in a lightweight, dependency-free package that lives inside your Ruby process.
@@ -26,7 +27,7 @@ Mudis also works naturally in Hanami because it’s a pure Ruby in-memory cache.
   - [Cache Key Lifecycle](#cache-key-lifecycle)
 - [Features](#features)
 - [Installation](#installation)
-- [Configuration (Rails)](#configuration-rails)
+- [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)
@@ -133,15 +134,13 @@ Or install it manually:
 ```bash
 gem install mudis
 ```
-
 ---
 
-## Configuration (Rails)
+## Configuration (Ruby/Rails)
 
-In your Rails app, create an initializer:
+In your Rails app, create an initializer (in your entry point if using Ruby outside of Rails):
 
 ```ruby
-# config/initializers/mudis.rb
 Mudis.configure do |c|
   c.serializer = JSON        # or Marshal | Oj
   c.compress = true          # Compress values using Zlib
@@ -276,9 +275,15 @@ require 'mudis'
 # Write a value with optional TTL
 Mudis.write('user:123', { name: 'Alice' }, expires_in: 600)
 
+# Write a value with explicit namespace separation
+Mudis.write('123', { name: 'Alice' }, expires_in: 600, namespace:'user')
+
 # Read it back
 Mudis.read('user:123') # => { "name" => "Alice" }
 
+# Read back from namespace
+Mudis.read('123', namespace:'user') # => { "name" => "Alice" }
+
 # Check if it exists
 Mudis.exists?('user:123') # => true
 
@@ -929,6 +934,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
 - [ ] Review for functionality gaps and enhance as needed 
 
 ---

data/lib/mudis/expiry.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class Mudis
+  # Expiry module handles TTL-based expiration and background cleanup
+  module Expiry
+    # Starts a thread that periodically removes expired entries
+    def start_expiry_thread(interval: 60)
+      return if @expiry_thread&.alive?
+
+      @stop_expiry = false
+      @expiry_thread = Thread.new do
+        loop do
+          break if @stop_expiry
+
+          sleep interval
+          cleanup_expired!
+        end
+      end
+    end
+
+    # Signals and joins the expiry thread
+    def stop_expiry_thread
+      @stop_expiry = true
+      @expiry_thread&.join
+      @expiry_thread = nil
+    end
+
+    # Removes expired keys across all buckets
+    def cleanup_expired!
+      now = Time.now
+      buckets.times do |idx|
+        mutex = @mutexes[idx]
+        store = @stores[idx]
+        mutex.synchronize do
+          store.keys.each do |key| # rubocop:disable Style/HashEachMethods
+            evict_key(idx, key) if store[key][:expires_at] && now > store[key][:expires_at]
+          end
+        end
+      end
+    end
+
+    private
+
+    # 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/lru.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class Mudis
+  # Node structure for the LRU doubly-linked list
+  class LRUNode
+    attr_accessor :key, :prev, :next
+
+    def initialize(key)
+      @key = key
+      @prev = nil
+      @next = nil
+    end
+  end
+
+  # LRU module handles the Least Recently Used eviction strategy
+  # Maintains doubly-linked lists per bucket for O(1) promote/evict operations
+  module LRU
+    private
+
+    # Removes a key from storage and LRU
+    def evict_key(idx, key)
+      store = @stores[idx]
+      entry = store.delete(key)
+      return unless entry
+
+      @current_bytes[idx] -= (key.bytesize + entry[:value].bytesize)
+
+      node = @lru_nodes[idx].delete(key)
+      remove_node(idx, node) if node
+    end
+
+    # Inserts a key at the head of the LRU list
+    def insert_lru(idx, key)
+      node = LRUNode.new(key)
+      node.next = @lru_heads[idx]
+      @lru_heads[idx].prev = node if @lru_heads[idx]
+      @lru_heads[idx] = node
+      @lru_tails[idx] ||= node
+      @lru_nodes[idx][key] = node
+    end
+
+    # Promotes a key to the front of the LRU list
+    def promote_lru(idx, key)
+      node = @lru_nodes[idx][key]
+      return unless node && @lru_heads[idx] != node
+
+      remove_node(idx, node)
+      insert_lru(idx, key)
+    end
+
+    # Removes a node from the LRU list
+    def remove_node(idx, node)
+      if node.prev
+        node.prev.next = node.next
+      else
+        @lru_heads[idx] = node.next
+      end
+
+      if node.next
+        node.next.prev = node.prev
+      else
+        @lru_tails[idx] = node.prev
+      end
+    end
+  end
+end

data/lib/mudis/metrics.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+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
+      @metrics_mutex.synchronize do
+        {
+          hits: @metrics[:hits],
+          misses: @metrics[:misses],
+          evictions: @metrics[:evictions],
+          rejected: @metrics[:rejected],
+          total_memory: current_memory_bytes,
+          least_touched: least_touched(10),
+          buckets: buckets.times.map do |idx|
+            {
+              index: idx,
+              keys: @stores[idx].size,
+              memory_bytes: @current_bytes[idx],
+              lru_size: @lru_nodes[idx].size
+            }
+          end
+        }
+      end
+    end
+
+    # Resets metric counters (thread-safe)
+    def reset_metrics!
+      @metrics_mutex.synchronize do
+        @metrics = { hits: 0, misses: 0, evictions: 0, rejected: 0 }
+      end
+    end
+
+    private
+
+    # Thread-safe metric increment
+    def metric(name)
+      @metrics_mutex.synchronize { @metrics[name] += 1 }
+    end
+  end
+end

data/lib/mudis/namespace.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class Mudis
+  # Namespace module handles logical key separation and scoping
+  module Namespace
+    # 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
+
+    # Executes a block with a specific namespace, restoring the old namespace afterwards
+    def with_namespace(namespace)
+      old_ns = Thread.current[:mudis_namespace]
+      Thread.current[:mudis_namespace] = namespace
+      yield
+    ensure
+      Thread.current[:mudis_namespace] = old_ns
+    end
+
+    private
+
+    # Namespaces a key with an optional namespace
+    def namespaced_key(key, namespace = nil)
+      ns = namespace || Thread.current[:mudis_namespace]
+      ns ? "#{ns}:#{key}" : key
+    end
+  end
+end

data/lib/mudis/persistence.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+class Mudis
+  # Persistence module handles snapshot save/load operations for warm boot support
+  module Persistence
+    # Saves the current cache state to disk for persistence
+    def save_snapshot!
+      return unless @persistence_enabled
+
+      data = snapshot_dump
+      safe_write_snapshot(data)
+    rescue StandardError => 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 StandardError => 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
+
+    private
+
+    # Collect a JSON/Marshal-safe array of { key, value, expires_in }
+    def snapshot_dump # rubocop:disable Metrics/MethodLength
+      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 # rubocop:disable Style/RedundantBegin
+          write(e[:key], e[:value], expires_in: e[:expires_in])
+        rescue StandardError => 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) # rubocop:disable Metrics/MethodLength
+      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
+        # Use JSON.parse instead of JSON.load to support symbolize_names option
+        serializer_for_snapshot.parse(File.binread(@persistence_path), symbolize_names: true)
+      else
+        ## safe to use Marshal here as we control the file
+        Marshal.load(File.binread(@persistence_path)) # rubocop:disable Security/MarshalLoad
+      end
+    end
+  end
+end

data/lib/mudis/version.rb

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