mudis 0.8.1 → 0.9.0

data/sig/mudis_expiry.rbs

@@ -0,0 +1,13 @@
+class Mudis
+  module Expiry
+    def start_expiry_thread: (?interval: Integer) -> void
+
+    def stop_expiry_thread: () -> void
+
+    def cleanup_expired!: () -> void
+
+    private
+
+    def effective_ttl: (?expires_in: Integer?) -> Integer?
+  end
+end

data/sig/mudis_ipc_config.rbs

@@ -0,0 +1,10 @@
+# Shared configuration for IPC mode (server and client)
+module MudisIPCConfig
+  SOCKET_PATH: String
+
+  TCP_HOST: String
+
+  TCP_PORT: Integer
+
+  def self.use_tcp?: () -> bool
+end

data/sig/mudis_lru.rbs

@@ -0,0 +1,21 @@
+class Mudis
+  class LRUNode
+    attr_accessor key: String
+    attr_accessor prev: LRUNode?
+    attr_accessor next: LRUNode?
+
+    def initialize: (String) -> void
+  end
+
+  module LRU
+    private
+
+    def evict_key: (Integer, String) -> void
+
+    def insert_lru: (Integer, LRUNode) -> void
+
+    def promote_lru: (Integer, String) -> void
+
+    def remove_node: (Integer, LRUNode) -> void
+  end
+end

data/sig/mudis_metrics.rbs

@@ -0,0 +1,11 @@
+class Mudis
+  module Metrics
+    def metrics: () -> Hash[Symbol, untyped]
+
+    def reset_metrics!: () -> void
+
+    private
+
+    def metric: (Symbol) -> void
+  end
+end

data/sig/mudis_namespace.rbs

@@ -0,0 +1,13 @@
+class Mudis
+  module Namespace
+    def keys: (namespace: String) -> Array[String]
+
+    def clear_namespace: (namespace: String) -> void
+
+    def with_namespace: (namespace: String) { () -> untyped } -> untyped
+
+    private
+
+    def namespaced_key: (String, ?namespace: String?) -> String
+  end
+end

data/sig/mudis_persistence.rbs

@@ -0,0 +1,19 @@
+class Mudis
+  module Persistence
+    def save_snapshot!: () -> void
+
+    def load_snapshot!: () -> void
+
+    def install_persistence_hook!: () -> void
+
+    private
+
+    def snapshot_dump: () -> Hash[String, untyped]
+
+    def snapshot_restore: (Hash[String, untyped]) -> void
+
+    def safe_write_snapshot: (Hash[String, untyped]) -> void
+
+    def read_snapshot: () -> Hash[String, untyped]
+  end
+end

data/sig/mudis_server.rbs

@@ -1,7 +1,17 @@
 class MudisServer
-  SOCKET_PATH: String
+  include MudisIPCConfig
 
   def self.start!: () -> void
 
-  def self.handle_client: (sock: UNIXSocket) -> void
+  def self.start_tcp_server!: () -> void
+
+  def self.start_unix_server!: () -> void
+
+  def self.accept_connections: (server: (TCPServer | UNIXServer)) -> void
+
+  def self.handle_client: (socket: (TCPSocket | UNIXSocket)) -> void
+
+  def self.process_request: (req: Hash[String, untyped]) -> Hash[Symbol, untyped]
+
+  def self.write_response: (socket: (TCPSocket | UNIXSocket), payload: Hash[Symbol, untyped]) -> void
 end

data/spec/api_compatibility_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+RSpec.describe "Mudis Public API" do
+  describe "ensures no breaking changes" do
+    it "exposes all core cache operations" do
+      expect(Mudis).to respond_to(:read)
+      expect(Mudis).to respond_to(:write)
+      expect(Mudis).to respond_to(:delete)
+      expect(Mudis).to respond_to(:exists?)
+      expect(Mudis).to respond_to(:update)
+      expect(Mudis).to respond_to(:fetch)
+      expect(Mudis).to respond_to(:clear)
+      expect(Mudis).to respond_to(:replace)
+      expect(Mudis).to respond_to(:inspect)
+    end
+
+    it "exposes all configuration methods" do
+      expect(Mudis).to respond_to(:configure)
+      expect(Mudis).to respond_to(:config)
+      expect(Mudis).to respond_to(:serializer)
+      expect(Mudis).to respond_to(:serializer=)
+      expect(Mudis).to respond_to(:compress)
+      expect(Mudis).to respond_to(:compress=)
+      expect(Mudis).to respond_to(:max_bytes)
+      expect(Mudis).to respond_to(:max_bytes=)
+      expect(Mudis).to respond_to(:max_value_bytes)
+      expect(Mudis).to respond_to(:max_value_bytes=)
+      expect(Mudis).to respond_to(:hard_memory_limit)
+      expect(Mudis).to respond_to(:hard_memory_limit=)
+      expect(Mudis).to respond_to(:max_ttl)
+      expect(Mudis).to respond_to(:max_ttl=)
+      expect(Mudis).to respond_to(:default_ttl)
+      expect(Mudis).to respond_to(:default_ttl=)
+    end
+
+    it "exposes all metrics methods" do
+      expect(Mudis).to respond_to(:metrics)
+      expect(Mudis).to respond_to(:reset_metrics!)
+    end
+
+    it "exposes all expiry methods" do
+      expect(Mudis).to respond_to(:start_expiry_thread)
+      expect(Mudis).to respond_to(:stop_expiry_thread)
+      expect(Mudis).to respond_to(:cleanup_expired!)
+    end
+
+    it "exposes all namespace methods" do
+      expect(Mudis).to respond_to(:keys)
+      expect(Mudis).to respond_to(:clear_namespace)
+      expect(Mudis).to respond_to(:with_namespace)
+    end
+
+    it "exposes all persistence methods" do
+      expect(Mudis).to respond_to(:save_snapshot!)
+      expect(Mudis).to respond_to(:load_snapshot!)
+    end
+
+    it "exposes all utility methods" do
+      expect(Mudis).to respond_to(:reset!)
+      expect(Mudis).to respond_to(:all_keys)
+      expect(Mudis).to respond_to(:current_memory_bytes)
+      expect(Mudis).to respond_to(:max_memory_bytes)
+      expect(Mudis).to respond_to(:least_touched)
+      expect(Mudis).to respond_to(:buckets)
+    end
+
+    it "maintains backward compatibility with method signatures" do
+      # Core operations accept namespace parameter
+      expect(Mudis.method(:read).parameters).to include([:key, :namespace])
+      expect(Mudis.method(:write).parameters).to include([:key, :namespace])
+      expect(Mudis.method(:delete).parameters).to include([:key, :namespace])
+      expect(Mudis.method(:exists?).parameters).to include([:key, :namespace])
+      
+      # Fetch accepts expires_in, force, and namespace
+      expect(Mudis.method(:fetch).parameters).to include([:key, :expires_in])
+      expect(Mudis.method(:fetch).parameters).to include([:key, :force])
+      expect(Mudis.method(:fetch).parameters).to include([:key, :namespace])
+    end
+
+    it "verifies LRUNode class is still accessible" do
+      expect(defined?(Mudis::LRUNode)).to be_truthy
+      node = Mudis::LRUNode.new("test_key")
+      expect(node).to respond_to(:key)
+      expect(node).to respond_to(:prev)
+      expect(node).to respond_to(:next)
+    end
+
+    it "verifies all public methods work correctly" do
+      Mudis.reset!
+      
+      # Write and read
+      Mudis.write("test", "value")
+      expect(Mudis.read("test")).to eq("value")
+      
+      # Exists
+      expect(Mudis.exists?("test")).to be true
+      
+      # Update
+      Mudis.update("test") { |v| v.upcase }
+      expect(Mudis.read("test")).to eq("VALUE")
+      
+      # Fetch
+      result = Mudis.fetch("new_key") { "new_value" }
+      expect(result).to eq("new_value")
+      
+      # Replace
+      Mudis.replace("test", "replaced")
+      expect(Mudis.read("test")).to eq("replaced")
+      
+      # Inspect
+      meta = Mudis.inspect("test")
+      expect(meta).to include(:key, :bucket, :created_at, :size_bytes)
+      
+      # Namespace operations
+      Mudis.write("k1", "v1", namespace: "ns1")
+      expect(Mudis.keys(namespace: "ns1")).to include("k1")
+      
+      Mudis.with_namespace("ns2") do
+        Mudis.write("k2", "v2")
+      end
+      expect(Mudis.keys(namespace: "ns2")).to include("k2")
+      
+      # Clear namespace
+      Mudis.clear_namespace(namespace: "ns1")
+      expect(Mudis.keys(namespace: "ns1")).to be_empty
+      
+      # Metrics
+      metrics = Mudis.metrics
+      expect(metrics).to include(:hits, :misses, :evictions, :total_memory, :buckets)
+      
+      # Least touched
+      touched = Mudis.least_touched(5)
+      expect(touched).to be_an(Array)
+      
+      # All keys
+      keys = Mudis.all_keys
+      expect(keys).to be_an(Array)
+      
+      # Memory tracking
+      expect(Mudis.current_memory_bytes).to be > 0
+      expect(Mudis.max_memory_bytes).to be > 0
+      
+      # Delete
+      Mudis.delete("test")
+      expect(Mudis.exists?("test")).to be false
+      
+      # Clear (alias for delete)
+      Mudis.write("to_clear", "value")
+      Mudis.clear("to_clear")
+      expect(Mudis.exists?("to_clear")).to be false
+    end
+  end
+end

data/spec/modules/expiry_spec.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "../spec_helper"
+
+RSpec.describe Mudis::Expiry do
+  let(:test_class) do
+    Class.new do
+      extend Mudis::Expiry
+      
+      @expiry_thread = nil
+      @stop_expiry = false
+      @buckets = 2
+      @mutexes = Array.new(2) { Mutex.new }
+      @stores = Array.new(2) { {} }
+      @max_ttl = nil
+      @default_ttl = nil
+      
+      class << self
+        attr_accessor :expiry_thread, :stop_expiry, :buckets, :mutexes, :stores, :max_ttl, :default_ttl
+        
+        def evict_key(idx, key)
+          @stores[idx].delete(key)
+        end
+      end
+    end
+  end
+
+  after do
+    test_class.stop_expiry_thread if test_class.expiry_thread&.alive?
+  end
+
+  describe "#start_expiry_thread" do
+    it "starts a background cleanup thread" do
+      test_class.start_expiry_thread(interval: 0.1)
+      
+      expect(test_class.expiry_thread).to be_alive
+    end
+
+    it "does not start duplicate thread if already running" do
+      test_class.start_expiry_thread(interval: 0.1)
+      first_thread = test_class.expiry_thread
+      
+      test_class.start_expiry_thread(interval: 0.1)
+      
+      expect(test_class.expiry_thread).to eq(first_thread)
+    end
+
+    it "periodically calls cleanup_expired!" do
+      allow(test_class).to receive(:cleanup_expired!)
+      
+      test_class.start_expiry_thread(interval: 0.05)
+      sleep 0.15
+      
+      expect(test_class).to have_received(:cleanup_expired!).at_least(:once)
+    end
+  end
+
+  describe "#stop_expiry_thread" do
+    it "stops the background thread" do
+      test_class.start_expiry_thread(interval: 0.1)
+      
+      test_class.stop_expiry_thread
+      
+      expect(test_class.expiry_thread).to be_nil
+    end
+
+    it "sets stop signal" do
+      test_class.start_expiry_thread(interval: 0.1)
+      
+      test_class.stop_expiry_thread
+      
+      expect(test_class.stop_expiry).to be true
+    end
+
+    it "does nothing if thread is not running" do
+      expect { test_class.stop_expiry_thread }.not_to raise_error
+    end
+  end
+
+  describe "#cleanup_expired!" do
+    it "removes expired keys from all buckets" do
+      now = Time.now
+      test_class.stores[0]["expired"] = { expires_at: now - 10 }
+      test_class.stores[0]["valid"] = { expires_at: now + 10 }
+      test_class.stores[1]["also_expired"] = { expires_at: now - 5 }
+      
+      test_class.cleanup_expired!
+      
+      expect(test_class.stores[0]).not_to have_key("expired")
+      expect(test_class.stores[0]).to have_key("valid")
+      expect(test_class.stores[1]).not_to have_key("also_expired")
+    end
+
+    it "keeps keys without expiration" do
+      test_class.stores[0]["no_expiry"] = { expires_at: nil }
+      
+      test_class.cleanup_expired!
+      
+      expect(test_class.stores[0]).to have_key("no_expiry")
+    end
+
+    it "is thread-safe" do
+      10.times do |i|
+        test_class.stores[0]["key#{i}"] = { expires_at: Time.now - 1 }
+      end
+      
+      threads = 3.times.map do
+        Thread.new { test_class.cleanup_expired! }
+      end
+      
+      expect { threads.each(&:join) }.not_to raise_error
+    end
+  end
+
+  describe "#effective_ttl (private)" do
+    it "returns provided expires_in when no constraints" do
+      result = test_class.send(:effective_ttl, 300)
+      
+      expect(result).to eq(300)
+    end
+
+    it "returns nil when expires_in is nil and no default" do
+      result = test_class.send(:effective_ttl, nil)
+      
+      expect(result).to be_nil
+    end
+
+    it "uses default_ttl when expires_in is nil" do
+      test_class.default_ttl = 600
+      
+      result = test_class.send(:effective_ttl, nil)
+      
+      expect(result).to eq(600)
+    end
+
+    it "clamps to max_ttl when expires_in exceeds it" do
+      test_class.max_ttl = 100
+      
+      result = test_class.send(:effective_ttl, 500)
+      
+      expect(result).to eq(100)
+    end
+
+    it "allows expires_in below max_ttl" do
+      test_class.max_ttl = 1000
+      
+      result = test_class.send(:effective_ttl, 500)
+      
+      expect(result).to eq(500)
+    end
+
+    it "applies max_ttl over default_ttl" do
+      test_class.max_ttl = 100
+      test_class.default_ttl = 500
+      
+      result = test_class.send(:effective_ttl, nil)
+      
+      expect(result).to eq(100)
+    end
+
+    it "returns nil when both expires_in and default_ttl are nil" do
+      test_class.max_ttl = 1000
+      test_class.default_ttl = nil
+      
+      result = test_class.send(:effective_ttl, nil)
+      
+      expect(result).to be_nil
+    end
+  end
+end

data/spec/modules/lru_spec.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "../spec_helper"
+
+RSpec.describe Mudis::LRU do
+  let(:test_class) do
+    Class.new do
+      extend Mudis::LRU
+      
+      @stores = Array.new(2) { {} }
+      @lru_heads = Array.new(2) { nil }
+      @lru_tails = Array.new(2) { nil }
+      @lru_nodes = Array.new(2) { {} }
+      @current_bytes = Array.new(2, 0)
+      
+      class << self
+        attr_accessor :stores, :lru_heads, :lru_tails, :lru_nodes, :current_bytes
+      end
+    end
+  end
+
+  describe "LRUNode" do
+    it "initializes with a key" do
+      node = Mudis::LRUNode.new("test_key")
+      
+      expect(node.key).to eq("test_key")
+      expect(node.prev).to be_nil
+      expect(node.next).to be_nil
+    end
+
+    it "allows setting prev and next" do
+      node1 = Mudis::LRUNode.new("key1")
+      node2 = Mudis::LRUNode.new("key2")
+      
+      node1.next = node2
+      node2.prev = node1
+      
+      expect(node1.next).to eq(node2)
+      expect(node2.prev).to eq(node1)
+    end
+  end
+
+  describe "#insert_lru (private)" do
+    it "inserts a node at the head of the LRU list" do
+      test_class.send(:insert_lru, 0, "key1")
+      
+      expect(test_class.lru_heads[0]).to be_a(Mudis::LRUNode)
+      expect(test_class.lru_heads[0].key).to eq("key1")
+      expect(test_class.lru_tails[0]).to eq(test_class.lru_heads[0])
+      expect(test_class.lru_nodes[0]["key1"]).to be_a(Mudis::LRUNode)
+    end
+
+    it "maintains order when inserting multiple nodes" do
+      test_class.send(:insert_lru, 0, "key1")
+      test_class.send(:insert_lru, 0, "key2")
+      test_class.send(:insert_lru, 0, "key3")
+      
+      expect(test_class.lru_heads[0].key).to eq("key3")
+      expect(test_class.lru_tails[0].key).to eq("key1")
+    end
+  end
+
+  describe "#promote_lru (private)" do
+    it "moves a node to the head of the LRU list" do
+      test_class.send(:insert_lru, 0, "key1")
+      test_class.send(:insert_lru, 0, "key2")
+      test_class.send(:insert_lru, 0, "key3")
+      
+      test_class.send(:promote_lru, 0, "key1")
+      
+      expect(test_class.lru_heads[0].key).to eq("key1")
+    end
+
+    it "does nothing if key is already at head" do
+      test_class.send(:insert_lru, 0, "key1")
+      
+      head_before = test_class.lru_heads[0]
+      test_class.send(:promote_lru, 0, "key1")
+      
+      expect(test_class.lru_heads[0].key).to eq("key1")
+    end
+
+    it "does nothing if node doesn't exist" do
+      expect { test_class.send(:promote_lru, 0, "nonexistent") }.not_to raise_error
+    end
+  end
+
+  describe "#remove_node (private)" do
+    it "removes a node from the middle of the list" do
+      test_class.send(:insert_lru, 0, "key1")
+      test_class.send(:insert_lru, 0, "key2")
+      test_class.send(:insert_lru, 0, "key3")
+      
+      node = test_class.lru_nodes[0]["key2"]
+      test_class.send(:remove_node, 0, node)
+      
+      expect(test_class.lru_heads[0].key).to eq("key3")
+      expect(test_class.lru_heads[0].next.key).to eq("key1")
+    end
+
+    it "updates head when removing head node" do
+      test_class.send(:insert_lru, 0, "key1")
+      test_class.send(:insert_lru, 0, "key2")
+      
+      node = test_class.lru_heads[0]
+      test_class.send(:remove_node, 0, node)
+      
+      expect(test_class.lru_heads[0].key).to eq("key1")
+    end
+
+    it "updates tail when removing tail node" do
+      test_class.send(:insert_lru, 0, "key1")
+      test_class.send(:insert_lru, 0, "key2")
+      
+      node = test_class.lru_tails[0]
+      test_class.send(:remove_node, 0, node)
+      
+      expect(test_class.lru_tails[0].key).to eq("key2")
+    end
+  end
+
+  describe "#evict_key (private)" do
+    it "removes key from store and LRU list" do
+      test_class.stores[0]["key1"] = { value: "test".b, expires_at: nil }
+      test_class.current_bytes[0] = 100
+      test_class.send(:insert_lru, 0, "key1")
+      
+      test_class.send(:evict_key, 0, "key1")
+      
+      expect(test_class.stores[0]).not_to have_key("key1")
+      expect(test_class.lru_nodes[0]).not_to have_key("key1")
+      expect(test_class.current_bytes[0]).to eq(92) # 100 - "key1".bytesize(4) - "test".bytesize(4)
+    end
+
+    it "does nothing if key doesn't exist" do
+      expect { test_class.send(:evict_key, 0, "nonexistent") }.not_to raise_error
+    end
+
+    it "updates memory counter correctly" do
+      test_class.stores[0]["mykey"] = { value: "myvalue".b, expires_at: nil }
+      test_class.current_bytes[0] = 100
+      
+      test_class.send(:evict_key, 0, "mykey")
+      
+      # 100 - ("mykey".bytesize + "myvalue".bytesize) = 100 - 12 = 88
+      expect(test_class.current_bytes[0]).to eq(88)
+    end
+  end
+end

data/spec/modules/metrics_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../spec_helper"
+
+RSpec.describe Mudis::Metrics do
+  let(:test_class) do
+    Class.new do
+      extend Mudis::Metrics
+      
+      @metrics = { hits: 5, misses: 3, evictions: 2, rejected: 1 }
+      @metrics_mutex = Mutex.new
+      @buckets = 2
+      @stores = [{ "key1" => {} }, { "key2" => {} }]
+      @current_bytes = [100, 200]
+      @lru_nodes = [{ "key1" => nil }, { "key2" => nil }]
+      
+      class << self
+        attr_accessor :metrics, :metrics_mutex, :buckets, :stores, :current_bytes, :lru_nodes
+        
+        def current_memory_bytes
+          @current_bytes.sum
+        end
+        
+        def least_touched(n)
+          [["key1", 5], ["key2", 10]]
+        end
+      end
+    end
+  end
+
+  describe "#metrics" do
+    it "returns a snapshot of current metrics" do
+      result = test_class.metrics
+      
+      expect(result).to include(
+        hits: 5,
+        misses: 3,
+        evictions: 2,
+        rejected: 1
+      )
+      # total_memory and other derived stats depend on full Mudis context
+    end
+
+    it "includes least_touched keys via delegation" do
+      # This method delegates to least_touched which is defined in main class
+      # In integration tests this works, in isolation we just verify the structure
+      expect(test_class).to respond_to(:metrics)
+    end
+
+    it "includes per-bucket stats via delegation" do
+      # Bucket stats require full context from main class
+      # In integration tests this works, in isolation we just verify the method exists
+      expect(test_class).to respond_to(:metrics)
+    end
+
+    it "is thread-safe" do
+      threads = 10.times.map do
+        Thread.new { test_class.metrics }
+      end
+      
+      expect { threads.each(&:join) }.not_to raise_error
+    end
+  end
+
+  describe "#reset_metrics!" do
+    it "resets all metric counters to zero" do
+      test_class.reset_metrics!
+      
+      expect(test_class.metrics[:hits]).to eq(0)
+      expect(test_class.metrics[:misses]).to eq(0)
+      expect(test_class.metrics[:evictions]).to eq(0)
+      expect(test_class.metrics[:rejected]).to eq(0)
+    end
+
+    it "is thread-safe" do
+      threads = 10.times.map do
+        Thread.new { test_class.reset_metrics! }
+      end
+      
+      expect { threads.each(&:join) }.not_to raise_error
+    end
+  end
+
+  describe "#metric (private)" do
+    it "increments metric counters" do
+      initial_hits = test_class.metrics[:hits]
+      
+      test_class.send(:metric, :hits)
+      
+      expect(test_class.metrics[:hits]).to eq(initial_hits + 1)
+    end
+
+    it "is thread-safe" do
+      test_class.reset_metrics!
+      
+      threads = 100.times.map do
+        Thread.new { test_class.send(:metric, :hits) }
+      end
+      
+      threads.each(&:join)
+      
+      expect(test_class.metrics[:hits]).to eq(100)
+    end
+  end
+end