mudis 0.8.1 → 0.9.0

data/lib/mudis.rb

@@ -5,10 +5,21 @@ require "thread" # rubocop:disable Lint/RedundantRequireStatement
 require "zlib"
 
 require_relative "mudis_config"
+require_relative "mudis/lru"
+require_relative "mudis/persistence"
+require_relative "mudis/metrics"
+require_relative "mudis/namespace"
+require_relative "mudis/expiry"
 
 # Mudis is a thread-safe, in-memory, sharded, LRU cache with optional compression and expiry.
 # It is designed for high concurrency and performance within a Ruby application.
 class Mudis # rubocop:disable Metrics/ClassLength
+  extend LRU
+  extend Persistence
+  extend Metrics
+  extend Namespace
+  extend Expiry
+
   # --- Global Configuration and State ---
 
   @serializer = JSON                            # Default serializer (can be changed to Marshal or Oj)
@@ -20,6 +31,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
   @max_ttl = nil                                # Optional maximum TTL for cache entries
   @default_ttl = nil                            # Default TTL for cache entries if not specified
 
+  # --- Configuration Management ---
+
   class << self
     attr_accessor :serializer, :compress, :hard_memory_limit, :max_ttl, :default_ttl
     attr_reader :max_bytes, :max_value_bytes
@@ -76,35 +89,6 @@ class Mudis # rubocop:disable Metrics/ClassLength
       raise ArgumentError, "default_ttl must be > 0" if config.default_ttl && config.default_ttl <= 0
     end
 
-    # 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
-
     # Fully resets all internal state (except config)
     def reset!
       stop_expiry_thread
@@ -138,17 +122,6 @@ class Mudis # rubocop:disable Metrics/ClassLength
     end
   end
 
-  # 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
-
   # Number of cache buckets (shards). Default: 32
   def self.buckets
     return @buckets if @buckets
@@ -172,29 +145,9 @@ class Mudis # rubocop:disable Metrics/ClassLength
   @expiry_thread = nil # Background thread for expiry cleanup
   @hard_memory_limit = false # Whether to enforce hard memory cap
 
-  class << self
-    # 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
+  # --- Core Cache Operations ---
 
+  class << self
     # Computes which bucket a key belongs to
     def bucket_index(key)
       key.hash % buckets
@@ -367,20 +320,6 @@ class Mudis # rubocop:disable Metrics/ClassLength
       end
     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
-
     # Returns an array of all cache keys
     def all_keys
       keys = []
@@ -392,30 +331,6 @@ class Mudis # rubocop:disable Metrics/ClassLength
       keys
     end
 
-    # 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
-
     # Returns the least-touched keys across all buckets
     def least_touched(n = 10) # rubocop:disable Metrics/MethodLength,Naming/MethodParameterName
       keys_with_touches = []
@@ -444,15 +359,6 @@ class Mudis # rubocop:disable Metrics/ClassLength
       @max_bytes
     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
 
     # Decompresses and deserializes a raw value
@@ -460,181 +366,5 @@ class Mudis # rubocop:disable Metrics/ClassLength
       val = compress ? Zlib::Inflate.inflate(raw) : raw
       serializer.load(val)
     end
-
-    # Thread-safe metric increment
-    def metric(name)
-      @metrics_mutex.synchronize { @metrics[name] += 1 }
-    end
-
-    # 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
-
-    # Namespaces a key with an optional namespace
-    def namespaced_key(key, namespace = nil)
-      ns = namespace || Thread.current[:mudis_namespace]
-      ns ? "#{ns}:#{key}" : key
-    end
-
-    # 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
-
-  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 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
-  end
-
-  class << self
-    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
-        serializer_for_snapshot.load(File.binread(@persistence_path))
-      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_client.rb

@@ -2,64 +2,106 @@
 
 require "socket"
 require "json"
+require_relative "mudis_ipc_config"
 
-# thread-safe client for communicating with the MudisServer via UNIX socket.
+# Thread-safe client for communicating with the MudisServer
+# Automatically uses UNIX sockets on Linux/macOS and TCP on Windows
 class MudisClient
-  SOCKET_PATH = "/tmp/mudis.sock"
+  include MudisIPCConfig
 
   def initialize
     @mutex = Mutex.new
   end
 
-  def request(payload) # rubocop:disable Metrics/MethodLength
+  # Open a connection to the server (TCP or UNIX)
+  def open_connection
+    if MudisIPCConfig.use_tcp?
+      TCPSocket.new(TCP_HOST, TCP_PORT)
+    else
+      UNIXSocket.open(SOCKET_PATH)
+    end
+  end
+
+  # 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
     @mutex.synchronize do
-      UNIXSocket.open(SOCKET_PATH) do |sock|
-        sock.puts(JSON.dump(payload))
-        response = sock.gets
-        res = JSON.parse(response, symbolize_names: true)
-        raise res[:error] unless res[:ok] # rubocop:disable Layout/EmptyLineAfterGuardClause
-        res[:value]
-      end
-    rescue Errno::ENOENT
-      warn "[MudisClient] Socket missing; master likely not running MudisServer"
+      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
     end
   end
 
+  # --- Forwarded Mudis methods ---
+
+  # Read a value from the Mudis server
   def read(key, namespace: nil)
-    request(cmd: "read", key: key, namespace: namespace)
+    command("read", key:, namespace:)
   end
 
+  # Write a value to the Mudis server
   def write(key, value, expires_in: nil, namespace: nil)
-    request(cmd: "write", key: key, value: value, ttl: expires_in, namespace: namespace)
+    command("write", key:, value:, ttl: expires_in, namespace:)
   end
 
+  # Delete a value from the Mudis server
   def delete(key, namespace: nil)
-    request(cmd: "delete", key: key, namespace: namespace)
+    command("delete", key:, namespace:)
   end
 
+  # Check if a key exists in the Mudis server
   def exists?(key, namespace: nil)
-    request(cmd: "exists", key: key, namespace: namespace)
+    command("exists", key:, namespace:)
   end
 
+  # Fetch a value, computing and storing it if not present
   def fetch(key, expires_in: nil, namespace: nil)
-    val = read(key, namespace: namespace)
+    val = read(key, namespace:)
     return val if val
 
     new_val = yield
-    write(key, new_val, expires_in: expires_in, namespace: namespace)
+    write(key, new_val, expires_in:, namespace:)
     new_val
   end
 
+  # Retrieve metrics from the Mudis server
   def metrics
-    request(cmd: "metrics")
+    command("metrics")
   end
 
+  # Reset metrics on the Mudis server
   def reset_metrics!
-    request(cmd: "reset_metrics")
+    command("reset_metrics")
   end
 
+  # Reset the Mudis server cache state
   def reset!
-    request(cmd: "reset")
+    command("reset")
+  end
+
+  private
+
+  # Helper to send a command with options
+  def command(cmd, **opts)
+    request({ cmd:, **opts })
   end
+
 end

data/lib/mudis_ipc_config.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Shared configuration for IPC mode (server and client)
+module MudisIPCConfig
+  SOCKET_PATH = "/tmp/mudis.sock"
+  TCP_HOST = "127.0.0.1"
+  TCP_PORT = 9876
+
+  # 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
+end

data/lib/mudis_proxy.rb

@@ -24,6 +24,8 @@ unless defined?($mudis) && $mudis # rubocop:disable Style/GlobalVars
   return
 end
 
+# --- Proxy method forwarding ---
+
 class << Mudis
   def read(*a, **k) = $mudis.read(*a, **k) # rubocop:disable Naming/MethodParameterName,Style/GlobalVars
   def write(*a, **k) = $mudis.write(*a, **k) # rubocop:disable Naming/MethodParameterName,Style/GlobalVars

data/lib/mudis_server.rb

@@ -3,19 +3,56 @@
 require "socket"
 require "json"
 require_relative "mudis"
+require_relative "mudis_ipc_config"
 
-# Simple UNIX socket server for handling Mudis operations via IPC mode
+# Socket server for handling Mudis operations via IPC mode
+# Automatically uses UNIX sockets on Linux/macOS and TCP on Windows
 class MudisServer
-  SOCKET_PATH = "/tmp/mudis.sock"
+  include MudisIPCConfig
+
+  # 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! }
+  }.freeze
+
+  # Start the MudisServer
+  # Automatically selects TCP on Windows, UNIX sockets elsewhere
+  # This will run in a separate thread and handle incoming client connections.
+  def self.start!
+    if MudisIPCConfig.use_tcp?
+      start_tcp_server!
+    else
+      start_unix_server!
+    end
+  end
 
-  def self.start! # rubocop:disable Metrics/MethodLength
-    # Clean up old socket if it exists
-    File.unlink(SOCKET_PATH) if File.exist?(SOCKET_PATH)
+  # Start TCP server (for Windows or development)
+  def self.start_tcp_server!
+    warn "[MudisServer] Using TCP mode - recommended for development only"
+    server = TCPServer.new(TCP_HOST, TCP_PORT)
+    puts "[MudisServer] Listening on TCP #{TCP_HOST}:#{TCP_PORT}"
+    accept_connections(server)
+  end
 
+  # Start UNIX socket server (production mode for Linux/macOS)
+  def self.start_unix_server! # rubocop:disable Metrics/MethodLength
+    File.unlink(SOCKET_PATH) if File.exist?(SOCKET_PATH)
     server = UNIXServer.new(SOCKET_PATH)
     server.listen(128)
-    puts "[MudisServer] Listening on #{SOCKET_PATH}"
+    puts "[MudisServer] Listening on UNIX socket #{SOCKET_PATH}"
+    accept_connections(server)
+  end
 
+  # Accept connections in a loop (works for both TCP and UNIX)
+  def self.accept_connections(server)
     Thread.new do
       loop do
         client = server.accept
@@ -26,56 +63,38 @@ class MudisServer
     end
   end
 
-  def self.handle_client(sock) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/MethodLength
-    request_line = sock.gets
-    return unless request_line
-
-    req = JSON.parse(request_line, symbolize_names: true)
-    cmd  = req[:cmd]
-    key  = req[:key]
-    ns   = req[:namespace]
-    val  = req[:value]
-    ttl  = req[:ttl]
-
-    begin
-      case cmd
-      when "read"
-        result = Mudis.read(key, namespace: ns)
-        sock.puts(JSON.dump({ ok: true, value: result }))
-
-      when "write"
-        Mudis.write(key, val, expires_in: ttl, namespace: ns)
-        sock.puts(JSON.dump({ ok: true }))
-
-      when "delete"
-        Mudis.delete(key, namespace: ns)
-        sock.puts(JSON.dump({ ok: true }))
-
-      when "exists"
-        sock.puts(JSON.dump({ ok: true, value: Mudis.exists?(key, namespace: ns) }))
-
-      when "fetch"
-        result = Mudis.fetch(key, expires_in: ttl, namespace: ns) { req[:fallback] }
-        sock.puts(JSON.dump({ ok: true, value: result }))
-
-      when "metrics"
-        sock.puts(JSON.dump({ ok: true, value: Mudis.metrics }))
+  # Handle a single client connection
+  # Reads the request, processes it, and sends back the response
+  # @param socket [Socket] The client socket (TCP or UNIX)
+  # @return [void]
+  def self.handle_client(socket)
+    request = JSON.parse(socket.gets, symbolize_names: true)
+    return unless request
+
+    response = process_request(request)
+    write_response(socket, ok: true, value: response)
+  rescue StandardError => e
+    write_response(socket, ok: false, error: e.message)
+  ensure
+    socket.close
+  end
 
-      when "reset_metrics"
-        Mudis.reset_metrics!
-        sock.puts(JSON.dump({ ok: true }))
+  # Process a request hash and return the result
+  # Raises an error if the command is unknown
+  # @param req [Hash] The request hash containing :cmd and other parameters
+  # @return [Object] The result of the command execution
+  def self.process_request(req)
+    handler = COMMANDS[req[:cmd]]
+    raise "Unknown command: #{req[:cmd]}" unless handler
 
-      when "reset"
-        Mudis.reset!
-        sock.puts(JSON.dump({ ok: true }))
+    handler.call(req)
+  end
 
-      else
-        sock.puts(JSON.dump({ ok: false, error: "unknown command: #{cmd}" }))
-      end
-    rescue StandardError => e
-      sock.puts(JSON.dump({ ok: false, error: e.message }))
-    ensure
-      sock.close
-    end
+  # Write a response to the client socket
+  # @param socket [Socket] The client socket
+  # @param payload [Hash] The response payload
+  # @return [void]
+  def self.write_response(socket, payload)
+    socket.puts(JSON.dump(payload))
   end
 end

data/sig/mudis.rbs

@@ -1,4 +1,10 @@
 class Mudis
+  extend LRU
+  extend Persistence
+  extend Metrics
+  extend Namespace
+  extend Expiry
+
   # Configuration
   class << self
     attr_accessor serializer : Object

data/sig/mudis_client.rbs

@@ -1,8 +1,10 @@
 class MudisClient
-  SOCKET_PATH: String
+  include MudisIPCConfig
 
   def initialize: () -> void
 
+  def open_connection: () -> (TCPSocket | UNIXSocket)
+
   def request: (payload: { cmd: String, key?: String, value?: untyped, ttl?: Integer?, namespace?: String? }) -> untyped
 
   def read: (key: String, namespace?: String?) -> untyped