mudis 0.8.0 → 0.9.0

data/lib/mudis_client.rb

@@ -1,65 +1,107 @@
-# frozen_string_literal: true
-
-require "socket"
-require "json"
-
-# thread-safe client for communicating with the MudisServer via UNIX socket.
-class MudisClient
-  SOCKET_PATH = "/tmp/mudis.sock"
-
-  def initialize
-    @mutex = Mutex.new
-  end
-
-  def request(payload) # rubocop:disable Metrics/MethodLength
-    @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"
-      nil
-    end
-  end
-
-  def read(key, namespace: nil)
-    request(cmd: "read", key: key, namespace: namespace)
-  end
-
-  def write(key, value, expires_in: nil, namespace: nil)
-    request(cmd: "write", key: key, value: value, ttl: expires_in, namespace: namespace)
-  end
-
-  def delete(key, namespace: nil)
-    request(cmd: "delete", key: key, namespace: namespace)
-  end
-
-  def exists?(key, namespace: nil)
-    request(cmd: "exists", key: key, namespace: namespace)
-  end
-
-  def fetch(key, expires_in: nil, namespace: nil)
-    val = read(key, namespace: namespace)
-    return val if val
-
-    new_val = yield
-    write(key, new_val, expires_in: expires_in, namespace: namespace)
-    new_val
-  end
-
-  def metrics
-    request(cmd: "metrics")
-  end
-
-  def reset_metrics!
-    request(cmd: "reset_metrics")
-  end
-
-  def reset!
-    request(cmd: "reset")
-  end
-end
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require_relative "mudis_ipc_config"
+
+# Thread-safe client for communicating with the MudisServer
+# Automatically uses UNIX sockets on Linux/macOS and TCP on Windows
+class MudisClient
+  include MudisIPCConfig
+
+  def initialize
+    @mutex = Mutex.new
+  end
+
+  # 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
+      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)
+    command("read", key:, namespace:)
+  end
+
+  # Write a value to the Mudis server
+  def write(key, value, expires_in: nil, namespace: nil)
+    command("write", key:, value:, ttl: expires_in, namespace:)
+  end
+
+  # Delete a value from the Mudis server
+  def delete(key, namespace: nil)
+    command("delete", key:, namespace:)
+  end
+
+  # Check if a key exists in the Mudis server
+  def exists?(key, namespace: nil)
+    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:)
+    return val if val
+
+    new_val = yield
+    write(key, new_val, expires_in:, namespace:)
+    new_val
+  end
+
+  # Retrieve metrics from the Mudis server
+  def metrics
+    command("metrics")
+  end
+
+  # Reset metrics on the Mudis server
+  def reset_metrics!
+    command("reset_metrics")
+  end
+
+  # Reset the Mudis server cache state
+  def reset!
+    command("reset")
+  end
+
+  private
+
+  # Helper to send a command with options
+  def command(cmd, **opts)
+    request({ cmd:, **opts })
+  end
+
+end

data/lib/mudis_config.rb

@@ -1,35 +1,35 @@
-# frozen_string_literal: true
-
-# MudisConfig holds all configuration values for Mudis,
-# and provides defaults that can be overridden via Mudis.configure.
-class MudisConfig
-  attr_accessor :serializer,
-                :compress,
-                :max_value_bytes,
-                :hard_memory_limit,
-                :max_bytes,
-                :buckets,
-                :max_ttl,
-                :default_ttl,
-                # Persistence settings
-                :persistence_enabled,
-                :persistence_path,
-                :persistence_format,
-                :persistence_safe_write
-
-  def initialize
-    @serializer = JSON                        # Default serialization strategy
-    @compress = false                         # Whether to compress values with Zlib
-    @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
-    @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)
-    # Persistence settings
-    @persistence_enabled = false              # Whether persistence is enabled
-    @persistence_path = 'mudis_data'          # Default path for persistence files
-    @persistence_format = :json               # Default persistence file format
-    @persistence_safe_write = true            # Whether to use safe write for persistence
-  end
-end
+# frozen_string_literal: true
+
+# MudisConfig holds all configuration values for Mudis,
+# and provides defaults that can be overridden via Mudis.configure.
+class MudisConfig
+  attr_accessor :serializer,
+                :compress,
+                :max_value_bytes,
+                :hard_memory_limit,
+                :max_bytes,
+                :buckets,
+                :max_ttl,
+                :default_ttl,
+                # Persistence settings
+                :persistence_enabled,
+                :persistence_path,
+                :persistence_format,
+                :persistence_safe_write
+
+  def initialize # rubocop:disable Metrics/MethodLength
+    @serializer = JSON                        # Default serialization strategy
+    @compress = false                         # Whether to compress values with Zlib
+    @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
+    @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)
+    # Persistence settings
+    @persistence_enabled = false              # Whether persistence is enabled
+    @persistence_path = "mudis_data"          # Default path for persistence files
+    @persistence_format = :json               # Default persistence file format
+    @persistence_safe_write = true            # Whether to use safe write for persistence
+  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

@@ -1,37 +1,39 @@
-# frozen_string_literal: true
-
-# Optional Mudis proxy layer for IPC mode.
-#
-# To enable:
-#   require "mudis_proxy"
-#
-# The proxy will forward calls to `$mudis` (an instance of MudisClient)
-# if it is defined, otherwise fallback to standard in-process behaviour.
-
-require_relative "mudis"
-require_relative "mudis_client"
-
-# Note that this file must be required after MudisServer
-# has been loaded, otherwise the proxy will not be activated.
-
-unless defined?(MudisClient)
-  warn "[MudisProxy] MudisClient not loaded: proxy not activated"
-  return
-end
-
-unless defined?($mudis) && $mudis # rubocop:disable Style/GlobalVars
-  warn "[MudisProxy] $mudis not set: proxy not activated"
-  return
-end
-
-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
-  def delete(*a, **k) = $mudis.delete(*a, **k) # rubocop:disable Naming/MethodParameterName,Style/GlobalVars
-  def fetch(*a, **k, &b) = $mudis.fetch(*a, **k, &b) # rubocop:disable Naming/MethodParameterName,Style/GlobalVars
-  def metrics = $mudis.metrics # rubocop:disable Style/GlobalVars
-  def reset_metrics! = $mudis.reset_metrics! # rubocop:disable Style/GlobalVars
-  def reset! = $mudis.reset! # rubocop:disable Style/GlobalVars
-end
-
-warn "[MudisProxy] Proxy activated: forwarding calls to $mudis"
+# frozen_string_literal: true
+
+# Optional Mudis proxy layer for IPC mode.
+#
+# To enable:
+#   require "mudis_proxy"
+#
+# The proxy will forward calls to `$mudis` (an instance of MudisClient)
+# if it is defined, otherwise fallback to standard in-process behaviour.
+
+require_relative "mudis"
+require_relative "mudis_client"
+
+# Note that this file must be required after MudisServer
+# has been loaded, otherwise the proxy will not be activated.
+
+unless defined?(MudisClient)
+  warn "[MudisProxy] MudisClient not loaded: proxy not activated"
+  return
+end
+
+unless defined?($mudis) && $mudis # rubocop:disable Style/GlobalVars
+  warn "[MudisProxy] $mudis not set: proxy not activated"
+  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
+  def delete(*a, **k) = $mudis.delete(*a, **k) # rubocop:disable Naming/MethodParameterName,Style/GlobalVars
+  def fetch(*a, **k, &b) = $mudis.fetch(*a, **k, &b) # rubocop:disable Naming/MethodParameterName,Style/GlobalVars
+  def metrics = $mudis.metrics # rubocop:disable Style/GlobalVars
+  def reset_metrics! = $mudis.reset_metrics! # rubocop:disable Style/GlobalVars
+  def reset! = $mudis.reset! # rubocop:disable Style/GlobalVars
+end
+
+warn "[MudisProxy] Proxy activated: forwarding calls to $mudis"

data/lib/mudis_server.rb

@@ -1,81 +1,100 @@
-# frozen_string_literal: true
-
-require "socket"
-require "json"
-require_relative "mudis"
-
-# Simple UNIX socket server for handling Mudis operations via IPC mode
-class MudisServer
-  SOCKET_PATH = "/tmp/mudis.sock"
-
-  def self.start! # rubocop:disable Metrics/MethodLength
-    # Clean up old socket if it exists
-    File.unlink(SOCKET_PATH) if File.exist?(SOCKET_PATH)
-
-    server = UNIXServer.new(SOCKET_PATH)
-    server.listen(128)
-    puts "[MudisServer] Listening on #{SOCKET_PATH}"
-
-    Thread.new do
-      loop do
-        client = server.accept
-        Thread.new(client) do |sock|
-          handle_client(sock)
-        end
-      end
-    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 }))
-
-      when "reset_metrics"
-        Mudis.reset_metrics!
-        sock.puts(JSON.dump({ ok: true }))
-
-      when "reset"
-        Mudis.reset!
-        sock.puts(JSON.dump({ ok: true }))
-
-      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
-  end
-end
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require_relative "mudis"
+require_relative "mudis_ipc_config"
+
+# Socket server for handling Mudis operations via IPC mode
+# Automatically uses UNIX sockets on Linux/macOS and TCP on Windows
+class MudisServer
+  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
+
+  # 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 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
+        Thread.new(client) do |sock|
+          handle_client(sock)
+        end
+      end
+    end
+  end
+
+  # 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
+
+  # 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
+
+    handler.call(req)
+  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,56 +1,62 @@
-class Mudis
-  # Configuration
-  class << self
-    attr_accessor serializer : Object
-    attr_accessor compress : bool
-    attr_accessor hard_memory_limit : bool
-    attr_reader max_bytes : Integer
-    attr_reader max_value_bytes : Integer?
-    attr_accessor max_ttl: Integer?
-    attr_accessor default_ttl: Integer?
-    
-    def configure: () { (config: MudisConfig) -> void } -> void
-    def config: () -> MudisConfig
-    def apply_config!: () -> void
-    def validate_config!: () -> void
-
-    def buckets: () -> Integer
-  end
-
-  # Lifecycle
-  def self.start_expiry_thread: (?interval: Integer) -> void
-  def self.stop_expiry_thread: () -> void
-
-  # Core operations
-  def self.write: (String, untyped, ?expires_in: Integer, ?namespace: String) -> void
-  def self.read: (String, ?namespace: String) -> untyped?
-  def self.update: (String, ?namespace: String) { (untyped) -> untyped } -> void
-  def self.delete: (String, ?namespace: String) -> void
-  def self.exists?: (String, ?namespace: String) -> bool
-
-  # DSL & Helpers
-  def self.fetch: (
-    String,
-    ?expires_in: Integer,
-    ?force: bool,
-    ?namespace: String
-  ) { () -> untyped } -> untyped
-
-  def self.clear: (String, ?namespace: String) -> void
-  def self.replace: (String, untyped, ?expires_in: Integer, ?namespace: String) -> void
-  def self.inspect: (String, ?namespace: String) -> Hash[Symbol, untyped]?
-  def self.keys: (?namespace: String) -> Array[String]
-  def self.clear_namespace: (?namespace: String) -> void
-
-  # Introspection & management
-  def self.metrics: () -> Hash[Symbol, untyped]
-  def self.cleanup_expired!: () -> void
-  def self.all_keys: () -> Array[String]
-  def self.current_memory_bytes: () -> Integer
-  def self.max_memory_bytes: () -> Integer
-  def self.least_touched: (?Integer) -> Array[[String, Integer]]
-
-  # State reset
-  def self.reset!: () -> void
-  def self.reset_metrics!: () -> void
-end
+class Mudis
+  extend LRU
+  extend Persistence
+  extend Metrics
+  extend Namespace
+  extend Expiry
+
+  # Configuration
+  class << self
+    attr_accessor serializer : Object
+    attr_accessor compress : bool
+    attr_accessor hard_memory_limit : bool
+    attr_reader max_bytes : Integer
+    attr_reader max_value_bytes : Integer?
+    attr_accessor max_ttl: Integer?
+    attr_accessor default_ttl: Integer?
+    
+    def configure: () { (config: MudisConfig) -> void } -> void
+    def config: () -> MudisConfig
+    def apply_config!: () -> void
+    def validate_config!: () -> void
+
+    def buckets: () -> Integer
+  end
+
+  # Lifecycle
+  def self.start_expiry_thread: (?interval: Integer) -> void
+  def self.stop_expiry_thread: () -> void
+
+  # Core operations
+  def self.write: (String, untyped, ?expires_in: Integer, ?namespace: String) -> void
+  def self.read: (String, ?namespace: String) -> untyped?
+  def self.update: (String, ?namespace: String) { (untyped) -> untyped } -> void
+  def self.delete: (String, ?namespace: String) -> void
+  def self.exists?: (String, ?namespace: String) -> bool
+
+  # DSL & Helpers
+  def self.fetch: (
+    String,
+    ?expires_in: Integer,
+    ?force: bool,
+    ?namespace: String
+  ) { () -> untyped } -> untyped
+
+  def self.clear: (String, ?namespace: String) -> void
+  def self.replace: (String, untyped, ?expires_in: Integer, ?namespace: String) -> void
+  def self.inspect: (String, ?namespace: String) -> Hash[Symbol, untyped]?
+  def self.keys: (?namespace: String) -> Array[String]
+  def self.clear_namespace: (?namespace: String) -> void
+
+  # Introspection & management
+  def self.metrics: () -> Hash[Symbol, untyped]
+  def self.cleanup_expired!: () -> void
+  def self.all_keys: () -> Array[String]
+  def self.current_memory_bytes: () -> Integer
+  def self.max_memory_bytes: () -> Integer
+  def self.least_touched: (?Integer) -> Array[[String, Integer]]
+
+  # State reset
+  def self.reset!: () -> void
+  def self.reset_metrics!: () -> void
+end