mudis 0.8.0 → 0.9.0

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.0"
+# frozen_string_literal: true
+
+MUDIS_VERSION = "0.9.0"