mudis 0.9.1 → 0.9.4

data/lib/mudis_client.rb

@@ -2,6 +2,7 @@
 
 require "socket"
 require "json"
+require "timeout"
 require_relative "mudis_ipc_config"
 
 # Thread-safe client for communicating with the MudisServer
@@ -25,28 +26,41 @@ class MudisClient
   # Send a request to the MudisServer and return the response
   # @param payload [Hash] The request payload
   # @return [Object] The response value from the server
-  def request(payload) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+  def request(payload) # rubocop:disable Metrics/MethodLength
     @mutex.synchronize do
-      sock = open_connection
-      sock.puts(JSON.dump(payload))
-      response = sock.gets
-      sock.close
-
-      return nil unless response
-
-      res = JSON.parse(response, symbolize_names: true)
-      raise res[:error] unless res[:ok]
-
-      res[:value]
-    rescue Errno::ENOENT, Errno::ECONNREFUSED
-      warn "[MudisClient] Cannot connect to MudisServer. Is it running?"
-      nil
-    rescue JSON::ParserError
-      warn "[MudisClient] Invalid JSON response from server"
-      nil
-    rescue IOError, SystemCallError => e
-      warn "[MudisClient] Connection error: #{e.message}"
-      nil
+      attempts = 0
+
+      begin
+        attempts += 1
+        response = nil
+
+        Timeout.timeout(MudisIPCConfig.timeout) do
+          sock = open_connection
+          sock.puts(JSON.dump(payload))
+          response = sock.gets
+          sock.close
+        end
+
+        return nil unless response
+
+        res = JSON.parse(response, symbolize_names: true)
+        raise res[:error] unless res[:ok]
+
+        res[:value]
+      rescue Errno::ENOENT, Errno::ECONNREFUSED, Timeout::Error
+        if attempts <= MudisIPCConfig.retries
+          retry
+        end
+
+        warn "[MudisClient] Cannot connect to MudisServer. Is it running?"
+        nil
+      rescue JSON::ParserError
+        warn "[MudisClient] Invalid JSON response from server"
+        nil
+      rescue IOError, SystemCallError => e
+        warn "[MudisClient] Connection error: #{e.message}"
+        nil
+      end
     end
   end
 
@@ -82,19 +96,44 @@ class MudisClient
     new_val
   end
 
-  # Retrieve metrics from the Mudis server
-  def metrics
-    command("metrics")
+  # Inspect metadata for a key
+  def inspect(key, namespace: nil)
+    command("inspect", key:, namespace:)
+  end
+
+  # Return keys for a namespace
+  def keys(namespace:)
+    command("keys", namespace:)
+  end
+
+  # Clear keys in a namespace
+  def clear_namespace(namespace:)
+    command("clear_namespace", namespace:)
+  end
+
+  # Return least touched keys
+  def least_touched(limit = 10)
+    command("least_touched", limit:)
   end
 
-  # Reset metrics on the Mudis server
-  def reset_metrics!
-    command("reset_metrics")
+  # Return all keys
+  def all_keys
+    command("all_keys")
   end
 
-  # Reset the Mudis server cache state
-  def reset!
-    command("reset")
+  # Return current memory usage
+  def current_memory_bytes
+    command("current_memory_bytes")
+  end
+
+  # Return max memory configured
+  def max_memory_bytes
+    command("max_memory_bytes")
+  end
+
+  # Retrieve metrics from the Mudis server
+  def metrics
+    command("metrics")
   end
 
   private
@@ -103,5 +142,4 @@ class MudisClient
   def command(cmd, **opts)
     request({ cmd:, **opts })
   end
-
 end

data/lib/mudis_config.rb

@@ -8,6 +8,7 @@ class MudisConfig
                 :max_value_bytes,
                 :hard_memory_limit,
                 :max_bytes,
+                :eviction_threshold,
                 :buckets,
                 :max_ttl,
                 :default_ttl,
@@ -23,6 +24,7 @@ class MudisConfig
     @max_value_bytes = nil                    # Max size per value (optional)
     @hard_memory_limit = false                # Enforce max_bytes as hard cap
     @max_bytes = 1_073_741_824                # 1 GB default max cache size
+    @eviction_threshold = 0.9                # Evict when bucket exceeds threshold
     @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)

data/lib/mudis_ipc_config.rb

@@ -5,9 +5,19 @@ module MudisIPCConfig
   SOCKET_PATH = "/tmp/mudis.sock"
   TCP_HOST = "127.0.0.1"
   TCP_PORT = 9876
+  DEFAULT_TIMEOUT = 1
+  DEFAULT_RETRIES = 1
 
   # Check if TCP mode should be used (Windows or forced via ENV)
   def self.use_tcp?
     ENV["MUDIS_FORCE_TCP"] == "true" || Gem.win_platform?
   end
+
+  def self.timeout
+    (ENV["MUDIS_IPC_TIMEOUT"] || DEFAULT_TIMEOUT).to_f
+  end
+
+  def self.retries
+    (ENV["MUDIS_IPC_RETRIES"] || DEFAULT_RETRIES).to_i
+  end
 end

data/lib/mudis_server.rb

@@ -13,14 +13,19 @@ class MudisServer
   # Define command handlers mapping
   # Each command maps to a lambda that takes a request hash and performs the corresponding Mudis operation.
   COMMANDS = {
-    "read"          => ->(r) { Mudis.read(r[:key], namespace: r[:namespace]) },
-    "write"         => ->(r) { Mudis.write(r[:key], r[:value], expires_in: r[:ttl], namespace: r[:namespace]) },
-    "delete"        => ->(r) { Mudis.delete(r[:key], namespace: r[:namespace]) },
-    "exists"        => ->(r) { Mudis.exists?(r[:key], namespace: r[:namespace]) },
-    "fetch"         => ->(r) { Mudis.fetch(r[:key], expires_in: r[:ttl], namespace: r[:namespace]) { r[:fallback] } },
-    "metrics"       => ->(_) { Mudis.metrics },
-    "reset_metrics" => ->(_) { Mudis.reset_metrics! },
-    "reset"         => ->(_) { Mudis.reset! }
+    "read" => ->(r) { Mudis.read(r[:key], namespace: r[:namespace]) },
+    "write" => ->(r) { Mudis.write(r[:key], r[:value], expires_in: r[:ttl], namespace: r[:namespace]) },
+    "delete" => ->(r) { Mudis.delete(r[:key], namespace: r[:namespace]) },
+    "exists" => ->(r) { Mudis.exists?(r[:key], namespace: r[:namespace]) },
+    "fetch" => ->(r) { Mudis.fetch(r[:key], expires_in: r[:ttl], namespace: r[:namespace]) { r[:fallback] } },
+    "inspect" => ->(r) { Mudis.inspect(r[:key], namespace: r[:namespace]) },
+    "keys" => ->(r) { Mudis.keys(namespace: r[:namespace]) },
+    "clear_namespace" => ->(r) { Mudis.clear_namespace(namespace: r[:namespace]) },
+    "least_touched" => ->(r) { Mudis.least_touched(r[:limit]) },
+    "all_keys" => ->(_) { Mudis.all_keys },
+    "current_memory_bytes" => ->(_) { Mudis.current_memory_bytes },
+    "max_memory_bytes" => ->(_) { Mudis.max_memory_bytes },
+    "metrics" => ->(_) { Mudis.metrics }
   }.freeze
 
   # Start the MudisServer
@@ -43,7 +48,7 @@ class MudisServer
   end
 
   # Start UNIX socket server (production mode for Linux/macOS)
-  def self.start_unix_server! # rubocop:disable Metrics/MethodLength
+  def self.start_unix_server!
     File.unlink(SOCKET_PATH) if File.exist?(SOCKET_PATH)
     server = UNIXServer.new(SOCKET_PATH)
     server.listen(128)

data/sig/mudis.rbs

@@ -14,6 +14,7 @@ class Mudis
     attr_reader max_value_bytes : Integer?
     attr_accessor max_ttl: Integer?
     attr_accessor default_ttl: Integer?
+    attr_accessor eviction_threshold: Float?
     
     def configure: () { (config: MudisConfig) -> void } -> void
     def config: () -> MudisConfig
@@ -21,6 +22,13 @@ class Mudis
     def validate_config!: () -> void
 
     def buckets: () -> Integer
+
+    def bind: (
+      namespace: String,
+      ?default_ttl: Integer?,
+      ?max_ttl: Integer?,
+      ?max_value_bytes: Integer?
+    ) -> Mudis::Bound
   end
 
   # Lifecycle
@@ -39,7 +47,8 @@ class Mudis
     String,
     ?expires_in: Integer,
     ?force: bool,
-    ?namespace: String
+    ?namespace: String,
+    ?singleflight: bool
   ) { () -> untyped } -> untyped
 
   def self.clear: (String, ?namespace: String) -> void
@@ -50,7 +59,7 @@ class Mudis
   def self.with_namespace: (namespace: String) { () -> untyped } -> untyped
 
   # Introspection & management
-  def self.metrics: () -> Hash[Symbol, untyped]
+  def self.metrics: (?namespace: String) -> Hash[Symbol, untyped]
   def self.cleanup_expired!: () -> void
   def self.all_keys: () -> Array[String]
   def self.current_memory_bytes: () -> Integer

data/sig/mudis_bound.rbs

@@ -0,0 +1,25 @@
+class Mudis
+  class Bound
+    attr_reader namespace: String
+
+    def initialize: (
+      namespace: String,
+      ?default_ttl: Integer?,
+      ?max_ttl: Integer?,
+      ?max_value_bytes: Integer?
+    ) -> void
+
+    def read: (String) -> untyped?
+    def write: (String, untyped, ?expires_in: Integer?) -> void
+    def update: (String) { (untyped) -> untyped } -> void
+    def delete: (String) -> void
+    def exists?: (String) -> bool
+    def fetch: (String, ?expires_in: Integer?, ?force: bool, ?singleflight: bool) { () -> untyped } -> untyped?
+    def clear: (String) -> void
+    def replace: (String, untyped, ?expires_in: Integer?) -> void
+    def inspect: (String) -> Hash[Symbol, untyped]?
+    def keys: () -> Array[String]
+    def metrics: () -> Hash[Symbol, untyped]
+    def clear_namespace: () -> void
+  end
+end

data/sig/mudis_client.rbs

@@ -17,9 +17,19 @@ class MudisClient
 
   def fetch: (key: String, expires_in?: Integer?, namespace?: String?, &block: { () -> untyped }) -> untyped
 
-  def metrics: () -> Hash[Symbol, untyped]
+  def inspect: (key: String, namespace?: String?) -> Hash[Symbol, untyped]?
+
+  def keys: (namespace: String) -> Array[String]
+
+  def clear_namespace: (namespace: String) -> void
+
+  def least_touched: (?Integer) -> Array[[String, Integer]]
 
-  def reset_metrics!: () -> void
+  def all_keys: () -> Array[String]
 
-  def reset!: () -> void
+  def current_memory_bytes: () -> Integer
+
+  def max_memory_bytes: () -> Integer
+
+  def metrics: () -> Hash[Symbol, untyped]
 end

data/sig/mudis_config.rbs

@@ -4,6 +4,7 @@ class MudisConfig
   attr_accessor max_value_bytes: Integer?
   attr_accessor hard_memory_limit: bool
   attr_accessor max_bytes: Integer
+  attr_accessor eviction_threshold: Float?
   attr_accessor max_ttl: Integer?
   attr_accessor default_ttl: Integer?
   attr_accessor buckets: Integer?

data/sig/mudis_ipc_config.rbs

@@ -6,5 +6,13 @@ module MudisIPCConfig
 
   TCP_PORT: Integer
 
+  DEFAULT_TIMEOUT: Integer
+
+  DEFAULT_RETRIES: Integer
+
   def self.use_tcp?: () -> bool
+
+  def self.timeout: () -> Float
+
+  def self.retries: () -> Integer
 end

data/sig/mudis_metrics.rbs

@@ -1,6 +1,6 @@
 class Mudis
   module Metrics
-    def metrics: () -> Hash[Symbol, untyped]
+    def metrics: (?namespace: String) -> Hash[Symbol, untyped]
 
     def reset_metrics!: () -> void
 

data/spec/api_compatibility_spec.rb

@@ -29,6 +29,8 @@ RSpec.describe "Mudis Public API" do
       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(:eviction_threshold)
+      expect(Mudis).to respond_to(:eviction_threshold=)
       expect(Mudis).to respond_to(:max_ttl)
       expect(Mudis).to respond_to(:max_ttl=)
       expect(Mudis).to respond_to(:default_ttl)
@@ -77,6 +79,7 @@ RSpec.describe "Mudis Public API" do
       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])
+      expect(Mudis.method(:fetch).parameters).to include([:key, :singleflight])
     end
 
     it "verifies LRUNode class is still accessible" do

data/spec/bound_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+RSpec.describe Mudis::Bound do
+  before do
+    Mudis.reset!
+    Mudis.serializer = JSON
+    Mudis.compress = false
+  end
+
+  it "scopes reads and writes to the bound namespace" do
+    bound = Mudis.bind(namespace: "caller")
+    bound.write("k", "v")
+
+    expect(Mudis.read("k")).to be_nil
+    expect(bound.read("k")).to eq("v")
+    expect(Mudis.read("k", namespace: "caller")).to eq("v")
+  end
+
+  it "applies default_ttl and max_ttl within the scope" do
+    bound = Mudis.bind(namespace: "caller", default_ttl: 120, max_ttl: 30)
+    bound.write("k", "v")
+
+    meta = bound.inspect("k")
+    expect(meta[:expires_at]).not_to be_nil
+    expect(meta[:expires_at]).to be_within(5).of(Time.now + 30)
+  end
+
+  it "rejects values that exceed max_value_bytes" do
+    bound = Mudis.bind(namespace: "caller", max_value_bytes: 10)
+    bound.write("k", "a" * 20)
+
+    expect(bound.read("k")).to be_nil
+  end
+
+  it "rejects updates that exceed max_value_bytes" do
+    bound = Mudis.bind(namespace: "caller", max_value_bytes: 10)
+    bound.write("k", "ok")
+
+    bound.update("k") { "a" * 20 }
+    expect(bound.read("k")).to eq("ok")
+  end
+
+  it "fetches within the bound namespace" do
+    bound = Mudis.bind(namespace: "caller")
+    value = bound.fetch("k") { "v" }
+
+    expect(value).to eq("v")
+    expect(Mudis.read("k")).to be_nil
+    expect(bound.read("k")).to eq("v")
+  end
+
+  it "executes the block once with singleflight: true" do
+    bound = Mudis.bind(namespace: "caller")
+    count = 0
+    count_mutex = Mutex.new
+    results = []
+    results_mutex = Mutex.new
+
+    threads = 5.times.map do
+      Thread.new do
+        value = bound.fetch("sf", singleflight: true) do
+          count_mutex.synchronize { count += 1 }
+          sleep 0.05
+          "v"
+        end
+        results_mutex.synchronize { results << value }
+      end
+    end
+
+    threads.each(&:join)
+    expect(count).to eq(1)
+    expect(results).to all(eq("v"))
+    expect(bound.read("sf")).to eq("v")
+  end
+
+  it "exposes metrics scoped to the bound namespace" do
+    bound = Mudis.bind(namespace: "caller")
+    bound.write("k", "v")
+    bound.read("k")
+    bound.read("missing")
+
+    metrics = bound.metrics
+    expect(metrics[:namespace]).to eq("caller")
+    expect(metrics[:hits]).to eq(1)
+    expect(metrics[:misses]).to eq(1)
+  end
+end

data/spec/guardrails_spec.rb

@@ -134,5 +134,19 @@ RSpec.describe "Mudis Configuration Guardrails" do # rubocop:disable Metrics/Blo
         end
       end.to raise_error(ArgumentError, /max_value_bytes cannot exceed max_bytes/)
     end
+
+    it "raises if eviction_threshold is <= 0 or > 1" do
+      expect do
+        Mudis.configure do |c|
+          c.eviction_threshold = 0
+        end
+      end.to raise_error(ArgumentError, /eviction_threshold must be > 0 and <= 1/)
+
+      expect do
+        Mudis.configure do |c|
+          c.eviction_threshold = 1.5
+        end
+      end.to raise_error(ArgumentError, /eviction_threshold must be > 0 and <= 1/)
+    end
   end
 end

data/spec/metrics_spec.rb

@@ -31,4 +31,25 @@ RSpec.describe "Mudis Metrics" do # rubocop:disable Metrics/BlockLength
     expect(Mudis.metrics[:misses]).to eq(0)
     expect(Mudis.read("metrics_key")).to eq("value")
   end
+
+  it "tracks metrics per namespace" do
+    Mudis.write("k1", "v1", namespace: "ns1")
+    Mudis.write("k2", "v2", namespace: "ns2")
+
+    Mudis.read("k1", namespace: "ns1")
+    Mudis.read("k1", namespace: "ns1")
+    Mudis.read("missing", namespace: "ns1")
+    Mudis.read("k2", namespace: "ns2")
+
+    ns1 = Mudis.metrics(namespace: "ns1")
+    ns2 = Mudis.metrics(namespace: "ns2")
+
+    expect(ns1[:hits]).to eq(2)
+    expect(ns1[:misses]).to eq(1)
+    expect(ns1[:namespace]).to eq("ns1")
+
+    expect(ns2[:hits]).to eq(1)
+    expect(ns2[:misses]).to eq(0)
+    expect(ns2[:namespace]).to eq("ns2")
+  end
 end

data/spec/modules/metrics_spec.rb

@@ -9,13 +9,16 @@ RSpec.describe Mudis::Metrics do
       
       @metrics = { hits: 5, misses: 3, evictions: 2, rejected: 1 }
       @metrics_mutex = Mutex.new
+      @metrics_by_namespace = {}
+      @metrics_by_namespace_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
+        attr_accessor :metrics, :metrics_mutex, :metrics_by_namespace, :metrics_by_namespace_mutex,
+                      :buckets, :stores, :current_bytes, :lru_nodes
         
         def current_memory_bytes
           @current_bytes.sum

data/spec/modules/persistence_spec.rb

@@ -2,11 +2,10 @@
 
 require_relative "../spec_helper"
 
-RSpec.describe Mudis::Persistence do
-  let(:test_class) do
+RSpec.describe Mudis::Persistence do # rubocop:disable Metrics/BlockLength
+  let(:test_class) do # rubocop:disable Metrics/BlockLength
     Class.new do
       extend Mudis::Persistence
-      
       @persistence_enabled = true
       @persistence_path = "tmp/test_persistence.json"
       @persistence_format = :json
@@ -20,15 +19,14 @@ RSpec.describe Mudis::Persistence do
       @current_bytes = Array.new(2, 0)
       @compress = false
       @serializer = JSON
-      
       class << self
-        attr_accessor :persistence_enabled, :persistence_path, :persistence_format, 
+        attr_accessor :persistence_enabled, :persistence_path, :persistence_format,
                       :persistence_safe_write, :buckets, :mutexes, :stores, :compress, :serializer
-        
+
         def decompress_and_deserialize(raw)
           JSON.load(raw)
         end
-        
+
         def write(key, value, expires_in: nil)
           # Stub write method
           @stores[0][key] = { value: JSON.dump(value), expires_at: nil, created_at: Time.now }
@@ -43,28 +41,28 @@ RSpec.describe Mudis::Persistence do
 
   describe "#save_snapshot!" do
     it "saves cache data to disk" do
-      test_class.stores[0]["key1"] = { 
-        value: JSON.dump("value1"), 
-        expires_at: nil, 
-        created_at: Time.now 
+      test_class.stores[0]["key1"] = {
+        value: JSON.dump("value1"),
+        expires_at: nil,
+        created_at: Time.now
       }
-      
+
       test_class.save_snapshot!
-      
+
       expect(File.exist?(test_class.persistence_path)).to be true
     end
 
     it "handles errors gracefully" do
       allow(test_class).to receive(:snapshot_dump).and_raise("Test error")
-      
+
       expect { test_class.save_snapshot! }.to output(/Failed to save snapshot/).to_stderr
     end
 
     it "does nothing when persistence is disabled" do
       test_class.persistence_enabled = false
-      
+
       test_class.save_snapshot!
-      
+
       expect(File.exist?(test_class.persistence_path)).to be false
     end
   end
@@ -73,9 +71,9 @@ RSpec.describe Mudis::Persistence do
     it "loads cache data from disk" do
       data = [{ key: "test_key", value: "test_value", expires_in: nil }]
       File.write(test_class.persistence_path, JSON.dump(data))
-      
+
       expect(test_class).to receive(:write).with("test_key", "test_value", expires_in: nil)
-      
+
       test_class.load_snapshot!
     end
 
@@ -85,16 +83,16 @@ RSpec.describe Mudis::Persistence do
 
     it "handles errors gracefully" do
       File.write(test_class.persistence_path, "invalid json")
-      
+
       expect { test_class.load_snapshot! }.to output(/Failed to load snapshot/).to_stderr
     end
 
     it "does nothing when persistence is disabled" do
       test_class.persistence_enabled = false
       File.write(test_class.persistence_path, JSON.dump([]))
-      
+
       expect(test_class).not_to receive(:write)
-      
+
       test_class.load_snapshot!
     end
   end
@@ -102,23 +100,23 @@ RSpec.describe Mudis::Persistence do
   describe "#install_persistence_hook!" do
     it "installs at_exit hook" do
       expect(test_class).to receive(:at_exit)
-      
+
       test_class.install_persistence_hook!
     end
 
     it "only installs hook once" do
       test_class.install_persistence_hook!
-      
+
       expect(test_class).not_to receive(:at_exit)
-      
+
       test_class.install_persistence_hook!
     end
 
     it "does nothing when persistence is disabled" do
       test_class.persistence_enabled = false
-      
+
       expect(test_class).not_to receive(:at_exit)
-      
+
       test_class.install_persistence_hook!
     end
   end