mudis 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeea820874569fe79af99d53f2a3ae3a7a9b74dc8a2d9dccbfbaa3f4ebab3967
-  data.tar.gz: 211d8c786790478e861461aab7444bd4bd1342afa07039ef3608f66dbd401cd6
+  metadata.gz: c8d2af60ebd6e5423bd7864ccaa02e597d90fa047bdc2f4b766c0772c16d9dd8
+  data.tar.gz: 23a3524cca4ee8b520e4984a24950962aaa3ee52543f95634016f8a7cdc45488
 SHA512:
-  metadata.gz: b93779c0990a328a3d24f4741b9934833e5524e099e2ddcdd2ae38f297e599f2cd49bd4fbc43d3cd1d1f81d2655220760b2573138ade72b289b785fc718c9bcd
-  data.tar.gz: bf25460f6237402793327d4bb04aef416d39f240e80350b8428433aa4245036cac0582f75e25b79c6902d21751403be9def2df01b9ebe54536ee39d229571590
+  metadata.gz: abc5c28bd8c7bc0b2da2e3f9ca42cbcf458e4d2c3009654c24ee5a17c4b68b447f4f3866916bf8d8abd4b06d3790faca5ed5bc98190008277a1f4489e944d4d1
+  data.tar.gz: eaaa49a62a501f12fa5f1ebf46d2acc0c1d42fdaac0538aa015088fc4a9ae05ed18be298bffb4ffe7a7a3c5fae8369cd22b723bd16191cba1ce0cd676a751624

data/README.md

@@ -1,12 +1,53 @@
 ![mudis_signet](design/mudis.png "Mudis")
 
 [![Gem Version](https://badge.fury.io/rb/mudis.svg?icon=si%3Arubygems&refresh=1&cachebust=0)](https://badge.fury.io/rb/mudis)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 **Mudis** is a fast, thread-safe, in-memory, sharded LRU (Least Recently Used) cache for Ruby applications. Inspired by Redis, it provides value serialization, optional compression, per-key expiry, and metric tracking in a lightweight, dependency-free package that lives inside your Ruby process.
 
 It’s ideal for scenarios where performance and process-local caching are critical, and where a full Redis setup is overkill or otherwise not possible/desirable.
 
-Alternatively, Mudis can be upscaled with higher sharding and resources in a dedicated Rails app to provide a [Mudis server](#create-a-mudis-server).
+Alternatively, Mudis can be upscaled with higher sharding and resources in a dedicated Rails app to provide a [Mudis Web Cache Server](#create-a-mudis-web-cache-server).
+
+Mudis also works naturally in Hanami because it’s a pure Ruby in-memory cache. Whether used as a singleton within a process or via IPC in cluster mode, it preserves Hanami’s lightweight and modular architecture.
+
+---
+
+## Table of Contents
+
+- [Why Another Caching Gem?](#why-another-caching-gem)
+  - [Similar Gems](#similar-gems)
+  - [Feature / Function Comparison](#feature--function-comparison)
+- [Design](#design)
+  - [Internal Structure and Behaviour](#internal-structure-and-behaviour)
+  - [Write - Read - Eviction](#write---read---eviction)
+  - [Cache Key Lifecycle](#cache-key-lifecycle)
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration (Rails)](#configuration-rails)
+- [Configuration (Hanami)](#configuration-hanami)
+- [Basic Usage](#basic-usage)
+  - [Developer Utilities](#developer-utilities)
+    - [`Mudis.reset!`](#mudisreset)
+    - [`Mudis.reset_metrics!`](#mudisreset_metrics)
+    - [`Mudis.least_touched`](#mudisleast_touched)
+    - [`Mudis.keys(namespace:)`](#mudiskeysnamespace)
+    - [`Mudis.clear_namespace(namespace:)`](#mudisclear_namespacenamespace)
+- [Rails Service Integration](#rails-service-integration)
+- [Metrics](#metrics)
+- [Advanced Configuration](#advanced-configuration)
+- [Benchmarks](#benchmarks)
+- [Graceful Shutdown](#graceful-shutdown)
+- [Known Limitations](#known-limitations)
+- [Inter-Process Caching (IPC Mode)](#inter-process-caching-ipc-mode)
+  - [Overview](#overview)
+  - [Setup (Puma)](#setup-puma)
+- [Create a Mudis Web Cache Server](#create-a-mudis-web-cache-server)
+  - [Minimal Setup](#minimal-setup)
+- [Project Philosophy](#project-philosophy)
+- [Roadmap](#roadmap)
+
+---
 
 ### Why another Caching Gem?
 
@@ -41,6 +82,7 @@ There are plenty out there, in various states of maintenance and in many shapes
 | **Concurrency model**                  | ✅                | ❌                               | ✅              | ❌             | ❌             | ❌              |
 | **Maintenance level**                  | ✅                | ✅                               | ✅              | ⚠️            | ⚠️            | ⚠️             |
 | **Suitable for APIs or microservices** | ✅                | ⚠️ Limited                      | ✅              | ⚠️ Small apps | ⚠️ Small apps | ❌ |
+| **Inter-process Caching** | ✅                | ❌                     | ❌              | ❌ | ❌ | ❌ |
 
 ---
 
@@ -68,6 +110,7 @@ There are plenty out there, in various states of maintenance and in many shapes
 - **Expiry Support**: Optional TTL per key with background cleanup thread.
 - **Compression**: Optional Zlib compression for large values.
 - **Metrics**: Tracks hits, misses, and evictions.
+- **IPC Mode**: Shared cross-process caching for multi-process aplications.
 
 ---
 
@@ -124,6 +167,79 @@ Mudis.start_expiry_thread(interval: 60) # Cleanup every 60s
 
 ---
 
+## Configuration (Hanami)
+
+Mudis integrates seamlessly with [Hanami](https://hanamirb.org) applications. It provides the same configuration flexibility and thread-safe caching capabilities as in Rails, with minimal setup differences.
+
+Create a boot file:
+
+```ruby
+# config/boot/mudis.rb
+require "mudis"
+
+Mudis.configure do |c|
+  c.serializer = JSON
+  c.compress = true
+  c.max_value_bytes = 2_000_000
+  c.hard_memory_limit = true
+  c.max_bytes = 1_073_741_824
+end
+
+Mudis.start_expiry_thread(interval: 60)
+
+at_exit { Mudis.stop_expiry_thread }
+```
+
+Then require it from `config/app.rb`:
+
+```ruby
+# config/app.rb
+require_relative "./boot/mudis"
+
+module MyApp
+  class App < Hanami::App
+  end
+end
+```
+
+This ensures Mudis is initialized and available globally throughout your Hanami application in the same as it would in Rails.
+
+---
+
+### Using Mudis with Hanami’s Dependency Container
+
+You can register Mudis as a dependency in the Hanami container to access it via dependency injection:
+
+```ruby
+# config/container.rb
+require "mudis"
+
+MyApp::Container.register(:cache, Mudis)
+```
+
+Then use it inside your actions, repositories, or services:
+
+```ruby
+# apps/main/actions/users/show.rb
+module Main
+  module Actions
+    module Users
+      class Show < Main::Action
+        include Deps[cache: "cache"]
+
+        def handle(req, res)
+          res[:user] = cache.fetch("user:#{req.params[:id]}", expires_in: 60) do
+            UserRepo.new.find(req.params[:id])
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
 ## Basic Usage
 
 ```ruby
@@ -299,6 +415,8 @@ cache.fetch(expires_in: 60) { expensive_query }
 cache.inspect_meta               # => { key: "users:user:42:profile", ... }
 ```
 
+*This pattern can also be applied in Hanami services using the registered Mudis dependency*
+
 ---
 
 ## Metrics
@@ -326,7 +444,9 @@ Mudis.metrics
 
 ```
 
-Optionally, return these metrics from a controller for remote analysis and monitoring if using Rails.
+Optionally, expose Mudis metrics from a controller or action for remote analysis and monitoring.
+
+**Rails:**
 
 ```ruby
 class MudisController < ApplicationController
@@ -337,6 +457,49 @@ class MudisController < ApplicationController
 end
 ```
 
+**Hanami:**
+
+*Mudis Registered in the container*
+
+```ruby
+# apps/main/actions/metrics/show.rb
+module Main::Actions::Metrics
+  class Show < Main::Action
+    include Deps[cache: "cache"]
+
+    def handle(*, res)
+      res.format = :json
+      res.body = { mudis: cache.metrics }.to_json
+    end
+  end
+end
+```
+
+*Mudis not registered in the container*
+
+```ruby
+# apps/main/actions/metrics/show.rb
+module Main::Actions::Metrics
+  class Show < Main::Action
+    def handle(*, res)
+      res.format = :json
+      res.body = { mudis: Mudis.metrics }.to_json
+    end
+  end
+end
+```
+
+```ruby
+# config/routes.rb
+module Main
+  class Routes < Hanami::Routes
+    root { "OK" }
+
+    get "/metrics", to: "metrics.show"
+  end
+end
+```
+
 ---
 
 ## Advanced Configuration
@@ -395,7 +558,7 @@ _10000 iterations of 1MB, Marshal (to match MemoryStore default), compression ON
 
 > For context: a typical database query or HTTP call takes 10–50ms. A difference of less than 1ms per operation is negligible for most apps.
 
-###### **Why this overhead exists**
+#### **Why this overhead exists**
 
 Mudis includes features that MemoryStore doesn’t:
 
@@ -408,6 +571,7 @@ Mudis includes features that MemoryStore doesn’t:
 | Thread safety      | ✅ Bucket-level mutexes | ✅ Global mutex              |
 | Observability      | ✅         | ❌           |
 | Namespacing        | ✅           | ❌ Manual scoping        |
+| IPC Aware        | ✅ (if enabled) | ❌ Requires manual configuration and additional gems       |
 
 It will be down to the developer to decide if a fraction of a millisecond is worth
 
@@ -426,6 +590,22 @@ _10000 iterations of 1MB, Marshal (to match MemoryStore default), compression OF
 
 With compression disabled, Mudis writes significanty faster and reads are virtually identical. Optimisation and configuration of Mudis will be determined by your individual needs.
 
+#### Other Benchmarks
+
+_10000 iterations of 512KB, JSON, compression OFF (to match MemoryStore default)_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta         |
+| --------- | ------------- | ----------- | ------------- |
+| Write     | 1.291 ms/op   | 0.32 ms/op | **−0.971 ms** |
+| Read      | 0.011 ms/op   | 0.048 ms/op | +0.037 ms     |
+
+_10000 iterations of 512KB, JSON, compression ON_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta         |
+| --------- | ------------- | ----------- | ------------- |
+| Write     | 1.11 ms/op   | 1.16 ms/op |  +0.05 ms |
+| Read      | 0.07 ms/op   | 0.563 ms/op | +0.493 ms     |
+
 ---
 
 ## Graceful Shutdown
@@ -445,7 +625,92 @@ at_exit { Mudis.stop_expiry_thread }
 
 ---
 
-## Create a Mudis Server
+## Inter-Process Caching (IPC Mode)
+
+While Mudis was originally designed as an in-process cache, it can also operate as a shared inter-process cache when running in environments that use concurrent processes (such as Puma in cluster mode). This is achieved through a local UNIX socket server that allows all workers to access a single, centralized Mudis instance.
+
+### Overview
+
+In IPC mode, Mudis runs as a singleton server within the master process.
+
+Each worker connects to that server through a lightweight client (`MudisClient`) using a local UNIX domain socket (default: `/tmp/mudis.sock`).
+All cache operations, e.g., read, write, delete, fetch, etc., are transparently proxied to the master process, which holds the authoritative cache state.
+
+This design allows multiple workers to share the same cache without duplicating memory or losing synchronization, while retaining Mudis’ performance, configurability, and thread safety.
+
+| **Benefit**                       | **Description**                                                                          |
+| --------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Shared Cache Across Processes** | All Puma workers share one Mudis instance via IPC.                                       |
+| **Zero External Dependencies**    | No Redis, Memcached, or separate daemon required.                                        |
+| **Memory Efficient**              | Cache data stored only once, not duplicated per worker.                                  |
+| **Full Feature Support**          | All Mudis features (TTL, compression, metrics, etc.) work transparently.                 |
+| **Safe & Local**                  | Communication is limited to the host system’s UNIX socket, ensuring isolation and speed. |
+
+![mudis_ipc](design/mudis_ipc.png "Mudis IPC")
+
+### Setup (Puma)
+
+Enable IPC mode by adding the following to your Puma configuration:
+
+```ruby
+# config/puma.rb
+preload_app!
+
+before_fork do
+  require "mudis"
+  require "mudis_server"
+
+  # typical Mudis configuration
+  Mudis.configure do |c|
+    c.serializer = JSON
+    c.compress = true
+    c.max_value_bytes = 2_000_000
+    c.hard_memory_limit = true
+    c.max_bytes = 1_073_741_824
+  end
+
+  Mudis.start_expiry_thread(interval: 60)
+  MudisServer.start!
+
+  at_exit { Mudis.stop_expiry_thread }
+end
+
+on_worker_boot do
+  require "mudis_client"
+  $mudis = MudisClient.new
+  require "mudis_proxy" # optionally require the default mudis proxy to invisibly patch Mudis
+end
+```
+
+For more granular control over Mudis, adding the Proxy manually to `initializers` (Rails) or `boot` (Hanami) allows seamless use of the API as documented. 
+
+**Do not require `mudis_proxy` if following this method**
+
+```ruby
+# config/<<initializers|boot>>/mudis_proxy.rb
+unless defined?(MudisServer)
+  class Mudis
+    def self.read(*a, **k) = $mudis.read(*a, **k)
+    def self.write(*a, **k) = $mudis.write(*a, **k)
+    def self.delete(*a, **k) = $mudis.delete(*a, **k)
+    def self.fetch(*a, **k, &b) = $mudis.fetch(*a, **k, &b)
+    def self.metrics = $mudis.metrics
+    def self.reset_metrics! = $mudis.reset_metrics!
+    def self.reset! = $mudis.reset!
+  end
+
+end
+```
+
+**Use IPC mode when:**
+
+- Running Rails or Rack apps under Puma cluster or multi-process background job workers.
+- You need cache consistency and memory efficiency without standing up Redis.
+- You want to preserve Mudis’s observability, configurability, and in-process simplicity at a larger scale.
+
+---
+
+## Create a Mudis Web Cache Server
 
 ### Minimal Setup
 
@@ -548,7 +813,7 @@ The primary use cases are:
 
 Mudis is not intended to be a general-purpose, distributed caching platform. You are, however, welcome to build on top of Mudis if you want its functionality in such projects. E.g.,
 
-- mudis-server – expose Mudis via HTTP, web sockets, hooks, etc
+- mudis-web-cache-server – expose Mudis via HTTP, web sockets, hooks, etc
 - mudis-broker – distributed key routing layer for coordinating multiple Mudis nodes
 - mudis-activejob-store – adapter for using Mudis in job queues or retry buffers
 
@@ -569,6 +834,12 @@ Mudis is not intended to be a general-purpose, distributed caching platform. You
 
 - [x] clear_namespace(namespace): Remove all keys in a namespace in one call
 
+#### Refactor Mudis 
+
+- [x] Review Mudis for improved readability and reduce complexity in top-level functions
+- [x] Enhanced guards
+- [ ] Review for functionality gaps and enhance as needed 
+
 ---
 
 ## License

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.6.0"
+MUDIS_VERSION = "0.7.1"

data/lib/mudis_client.rb

@@ -0,0 +1,65 @@
+# 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

data/lib/mudis_proxy.rb

@@ -0,0 +1,33 @@
+# 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_server"
+require_relative "mudis_client"
+
+if defined?(MudisServer)
+  # In the master process — no proxy needed.
+  return
+end
+
+unless defined?(MudisClient)
+  warn "[MudisProxy] MudisClient not loaded — 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

data/lib/mudis_server.rb

@@ -0,0 +1,81 @@
+# 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

data/sig/mudis_client.rbs

@@ -0,0 +1,23 @@
+class MudisClient
+  SOCKET_PATH: String
+
+  def initialize: () -> void
+
+  def request: (payload: { cmd: String, key?: String, value?: untyped, ttl?: Integer?, namespace?: String? }) -> untyped
+
+  def read: (key: String, namespace?: String?) -> untyped
+
+  def write: (key: String, value: untyped, expires_in?: Integer?, namespace?: String?) -> untyped
+
+  def delete: (key: String, namespace?: String?) -> untyped
+
+  def exists?: (key: String, namespace?: String?) -> bool
+
+  def fetch: (key: String, expires_in?: Integer?, namespace?: String?, &block: { () -> untyped }) -> untyped
+
+  def metrics: () -> { reads: Integer, writes: Integer, deletes: Integer, exists: Integer }
+
+  def reset_metrics!: () -> void
+
+  def reset!: () -> void
+end

data/sig/mudis_server.rbs

@@ -0,0 +1,7 @@
+class MudisServer
+  SOCKET_PATH: String
+
+  def self.start!: () -> void
+
+  def self.handle_client: (sock: UNIXSocket) -> void
+end

data/spec/mudis_client_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+RSpec.describe MudisClient do # rubocop:disable Metrics/BlockLength
+  let(:socket_path) { "/tmp/mudis.sock" }
+  let(:mock_socket) { instance_double(UNIXSocket) }
+  let(:client) { MudisClient.new }
+
+  around do |example|
+    ClimateControl.modify("SOCKET_PATH" => socket_path) do
+      example.run
+    end
+  end
+
+  before do
+    allow(UNIXSocket).to receive(:open).and_yield(mock_socket)
+  end
+
+  describe "#read" do
+    it "sends a read command and returns the value" do
+      payload = { cmd: "read", key: "test_key", namespace: nil }
+      response = { ok: true, value: "test_value" }.to_json
+
+      expect(mock_socket).to receive(:puts).with(payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect(client.read("test_key")).to eq("test_value")
+    end
+  end
+
+  describe "#write" do
+    it "sends a write command and returns the value" do
+      payload = { cmd: "write", key: "test_key", value: "test_value", ttl: nil, namespace: nil }
+      response = { ok: true, value: nil }.to_json
+
+      expect(mock_socket).to receive(:puts).with(payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect(client.write("test_key", "test_value")).to be_nil
+    end
+  end
+
+  describe "#delete" do
+    it "sends a delete command and returns the value" do
+      payload = { cmd: "delete", key: "test_key", namespace: nil }
+      response = { ok: true, value: nil }.to_json
+
+      expect(mock_socket).to receive(:puts).with(payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect(client.delete("test_key")).to be_nil
+    end
+  end
+
+  describe "#exists?" do
+    it "sends an exists command and returns true" do
+      payload = { cmd: "exists", key: "test_key", namespace: nil }
+      response = { ok: true, value: true }.to_json
+
+      expect(mock_socket).to receive(:puts).with(payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect(client.exists?("test_key")).to eq(true)
+    end
+  end
+
+  describe "#fetch" do
+    it "fetches an existing value or writes a new one" do
+      read_response = { ok: true, value: nil }.to_json
+      write_payload = { cmd: "write", key: "test_key", value: "new_value", ttl: nil, namespace: nil }
+      write_response = { ok: true, value: nil }.to_json
+
+      expect(mock_socket).to receive(:puts).with({ cmd: "read", key: "test_key", namespace: nil }.to_json)
+      expect(mock_socket).to receive(:gets).and_return(read_response)
+      expect(mock_socket).to receive(:puts).with(write_payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(write_response)
+
+      result = client.fetch("test_key") { "new_value" } # rubocop:disable Style/RedundantFetchBlock
+      expect(result).to eq("new_value")
+    end
+  end
+
+  describe "#metrics" do
+    it "sends a metrics command and returns the metrics" do
+      payload = { cmd: "metrics" }
+      response = { ok: true, value: { reads: 10, writes: 5 } }.to_json
+
+      expect(mock_socket).to receive(:puts).with(payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect(client.metrics).to eq({ reads: 10, writes: 5 })
+    end
+  end
+
+  describe "#reset_metrics!" do
+    it "sends a reset_metrics command" do
+      payload = { cmd: "reset_metrics" }
+      response = { ok: true, value: nil }.to_json
+
+      expect(mock_socket).to receive(:puts).with(payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect(client.reset_metrics!).to be_nil
+    end
+  end
+
+  describe "#reset!" do
+    it "sends a reset command" do
+      payload = { cmd: "reset" }
+      response = { ok: true, value: nil }.to_json
+
+      expect(mock_socket).to receive(:puts).with(payload.to_json)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect(client.reset!).to be_nil
+    end
+  end
+
+  describe "error handling" do
+    it "warns when the socket is missing" do
+      allow(UNIXSocket).to receive(:open).and_raise(Errno::ENOENT)
+
+      expect { client.read("test_key") }.to output(/Socket missing/).to_stderr
+      expect(client.read("test_key")).to be_nil
+    end
+
+    it "raises an error when the server returns an error" do
+      response = { ok: false, error: "Something went wrong" }.to_json
+
+      expect(mock_socket).to receive(:puts)
+      expect(mock_socket).to receive(:gets).and_return(response)
+
+      expect { client.read("test_key") }.to raise_error("Something went wrong")
+    end
+  end
+end

data/spec/mudis_server_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+
+require_relative "spec_helper"
+
+RSpec.describe MudisServer do # rubocop:disable Metrics/BlockLength
+  let(:socket_path) { MudisServer::SOCKET_PATH }
+
+  before do
+    allow(Mudis).to receive(:read).and_return("mock_value")
+    allow(Mudis).to receive(:write)
+    allow(Mudis).to receive(:delete)
+    allow(Mudis).to receive(:exists?).and_return(true)
+    allow(Mudis).to receive(:fetch).and_return("mock_fetched_value")
+    allow(Mudis).to receive(:metrics).and_return({ reads: 1, writes: 1 })
+    allow(Mudis).to receive(:reset_metrics!)
+    allow(Mudis).to receive(:reset!)
+
+    # Start the server in a separate thread
+    Thread.new { MudisServer.start! }
+    sleep 0.1 # Allow the server to start
+  end
+
+  after do
+    File.unlink(socket_path) if File.exist?(socket_path)
+  end
+
+  def send_request(request)
+    UNIXSocket.open(socket_path) do |sock|
+      sock.puts(JSON.dump(request))
+      JSON.parse(sock.gets, symbolize_names: true)
+    end
+  end
+
+  it "handles the 'read' command" do
+    response = send_request({ cmd: "read", key: "test_key", namespace: "test_ns" })
+    expect(response).to eq({ ok: true, value: "mock_value" })
+    expect(Mudis).to have_received(:read).with("test_key", namespace: "test_ns")
+  end
+
+  it "handles the 'write' command" do
+    response = send_request({ cmd: "write", key: "test_key", value: "test_value", ttl: 60, namespace: "test_ns" })
+    expect(response).to eq({ ok: true })
+    expect(Mudis).to have_received(:write).with("test_key", "test_value", expires_in: 60, namespace: "test_ns")
+  end
+
+  it "handles the 'delete' command" do
+    response = send_request({ cmd: "delete", key: "test_key", namespace: "test_ns" })
+    expect(response).to eq({ ok: true })
+    expect(Mudis).to have_received(:delete).with("test_key", namespace: "test_ns")
+  end
+
+  it "handles the 'exists' command" do
+    response = send_request({ cmd: "exists", key: "test_key", namespace: "test_ns" })
+    expect(response).to eq({ ok: true, value: true })
+    expect(Mudis).to have_received(:exists?).with("test_key", namespace: "test_ns")
+  end
+
+  it "handles the 'fetch' command" do
+    response = send_request({ cmd: "fetch", key: "test_key", ttl: 60, namespace: "test_ns",
+                              fallback: "fallback_value" })
+    expect(response).to eq({ ok: true, value: "mock_fetched_value" })
+    expect(Mudis).to have_received(:fetch).with("test_key", expires_in: 60, namespace: "test_ns")
+  end
+
+  it "handles the 'metrics' command" do
+    response = send_request({ cmd: "metrics" })
+    expect(response).to eq({ ok: true, value: { reads: 1, writes: 1 } })
+    expect(Mudis).to have_received(:metrics)
+  end
+
+  it "handles the 'reset_metrics' command" do
+    response = send_request({ cmd: "reset_metrics" })
+    expect(response).to eq({ ok: true })
+    expect(Mudis).to have_received(:reset_metrics!)
+  end
+
+  it "handles the 'reset' command" do
+    response = send_request({ cmd: "reset" })
+    expect(response).to eq({ ok: true })
+    expect(Mudis).to have_received(:reset!)
+  end
+
+  it "handles unknown commands" do
+    response = send_request({ cmd: "unknown_command" })
+    expect(response).to eq({ ok: false, error: "unknown command: unknown_command" })
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - kiebor81
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-17 00:00:00.000000000 Z
+date: 2025-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: climate_control
@@ -46,18 +46,27 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - sig/mudis.rbs
+- sig/mudis_client.rbs
 - sig/mudis_config.rbs
+- sig/mudis_server.rbs
 files:
 - README.md
 - lib/mudis.rb
 - lib/mudis/version.rb
+- lib/mudis_client.rb
 - lib/mudis_config.rb
+- lib/mudis_proxy.rb
+- lib/mudis_server.rb
 - sig/mudis.rbs
+- sig/mudis_client.rbs
 - sig/mudis_config.rbs
+- sig/mudis_server.rbs
 - spec/eviction_spec.rb
 - spec/guardrails_spec.rb
 - spec/memory_guard_spec.rb
 - spec/metrics_spec.rb
+- spec/mudis_client_spec.rb
+- spec/mudis_server_spec.rb
 - spec/mudis_spec.rb
 - spec/namespace_spec.rb
 - spec/reset_spec.rb
@@ -90,6 +99,8 @@ test_files:
 - spec/guardrails_spec.rb
 - spec/memory_guard_spec.rb
 - spec/metrics_spec.rb
+- spec/mudis_client_spec.rb
+- spec/mudis_server_spec.rb
 - spec/mudis_spec.rb
 - spec/namespace_spec.rb
 - spec/reset_spec.rb