mudis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1586fbcdac3ae237f88954090971beca8be02f3892f36c25363403d2ac80f34f
+  data.tar.gz: b12179ea11d6f51a3049d3eaa4428648fc088ecb6ade607bbe832227ceb64678
+SHA512:
+  metadata.gz: bff8cda9a3f627f6c94b3f40b737365603ab51fd6edd8e845f058bed517ccfa86a4ad61465fb4b807540525b779586cfbbe77eccd8a16ab59afc69aa2f7cd43a
+  data.tar.gz: 544c25fee1a7346e8c0725ee5e83d5764f3028d76a261666ecdc0d3291c2bccf5a52cf07713d480750cb149e12c52201a2da2a6de0faa8f191ea45b7ba81d47b

data/README.md

@@ -0,0 +1,228 @@
+![mudis_signet](design/mudis.png "Mudis")
+
+**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.
+
+---
+
+## Design
+
+#### Write - Read - Eviction
+
+![mudis_flow](design/mudis_flow.png "Write - Read - Eviction")
+
+#### Cache Key Lifecycle
+
+![mudis_lru](design/mudis_lru.png "Mudis Cache Key Lifecycle")
+
+---
+
+## Features
+
+- **Thread-safe**: Uses per-bucket mutexes for high concurrency.
+- **Sharded**: Buckets data across multiple internal stores to minimize lock contention.
+- **LRU Eviction**: Automatically evicts least recently used items as memory fills up.
+- **Expiry Support**: Optional TTL per key with background cleanup thread.
+- **Compression**: Optional Zlib compression for large values.
+- **Metrics**: Tracks hits, misses, and evictions.
+
+---
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem 'mudis'
+```
+
+Or install it manually:
+
+```bash
+gem install mudis
+```
+
+---
+
+## Configuration (Rails)
+
+In your Rails app, create an initializer:
+
+```ruby
+# config/initializers/mudis.rb
+
+Mudis.serializer = JSON        # or Marshal | Oj
+Mudis.compress = true          # Compress values using Zlib
+Mudis.max_value_bytes = 2_000_000  # Reject values > 2MB
+Mudis.start_expiry_thread(interval: 60) # Cleanup every 60s
+
+at_exit do
+  Mudis.stop_expiry_thread
+end
+```
+
+> If your `lib/` folder isn't eager loaded, explicitly `require 'mudis'` in this file.
+
+---
+
+## Basic Usage
+
+```ruby
+require 'mudis'
+
+# Write a value with optional TTL
+Mudis.write('user:123', { name: 'Alice' }, expires_in: 600)
+
+# Read it back
+Mudis.read('user:123') # => { "name" => "Alice" }
+
+# Check if it exists
+Mudis.exists?('user:123') # => true
+
+# Atomically update
+Mudis.update('user:123') { |data| data.merge(age: 30) }
+
+# Delete a key
+Mudis.delete('user:123')
+```
+
+---
+
+## Rails Service Integration
+
+For simplified or transient use in a controller, you can wrap your cache logic in a reusable thin class:
+
+```ruby
+class MudisService
+  attr_reader :cache_key
+
+  def initialize(cache_key)
+    @cache_key = cache_key
+  end
+
+  def write(data, expires_in: nil)
+    Mudis.write(cache_key, data, expires_in: expires_in)
+  end
+
+  def read(default: nil)
+    Mudis.read(cache_key) || default
+  end
+
+  def update
+    Mudis.update(cache_key) { |current| yield(current) }
+  end
+
+  def delete
+    Mudis.delete(cache_key)
+  end
+
+  def exists?
+    Mudis.exists?(cache_key)
+  end
+end
+```
+
+Use it like:
+
+```ruby
+cache = MudisCacheService.new("user:#{current_user.id}")
+cache.write({ preferences: "dark" }, expires_in: 3600)
+cache.read # => { "preferences" => "dark" }
+```
+
+---
+
+## Metrics
+
+Track cache effectiveness and performance:
+
+```ruby
+Mudis.metrics
+# => { hits: 15, misses: 5, evictions: 3 }
+```
+
+Optionally, return these metrics from a controller for remote analysis and monitoring if using rails.
+
+```ruby
+class MudisController < ApplicationController
+
+  def metrics
+    render json: {
+      mudis_metrics: Mudis.metrics,
+      memory_used_bytes: Mudis.current_memory_bytes,
+      memory_max_bytes: Mudis.max_memory_bytes,
+      keys: Mudis.all_keys.size
+    }
+  end
+
+end
+
+```
+
+---
+
+## Advanced Configuration
+
+| Setting                  | Description                                 | Default            |
+|--------------------------|---------------------------------------------|--------------------|
+| `Mudis.serializer`       | JSON, Marshal, or Oj                        | `JSON`             |
+| `Mudis.compress`         | Enable Zlib compression                     | `false`            |
+| `Mudis.max_value_bytes`  | Max allowed size in bytes for a value       | `nil` (no limit)   |
+| `Mudis.buckets`          | Number of cache shards (via ENV var)        | `32`               |
+| `start_expiry_thread`    | Background TTL cleanup loop (every N sec)   | Disabled by default|
+
+To customize the number of buckets, set the `MUDIS_BUCKETS` environment variable.
+
+---
+
+## Graceful Shutdown
+
+Don’t forget to stop the expiry thread when your app exits:
+
+```ruby
+at_exit { Mudis.stop_expiry_thread }
+```
+
+---
+
+## Known Limitations
+
+- Data is **process-local** and **non-persistent**.
+- Not suitable for cross-process or cross-language use.
+- Keys are globally scoped (no namespacing by default).
+- Compression introduces CPU overhead.
+
+---
+
+## Roadmap
+
+- [ ] Namespaced cache keys
+- [ ] Stats per bucket
+- [ ] Optional max memory cap per bucket
+- [ ] Built-in fetch/read-or-write DSL
+
+---
+
+## License
+
+MIT License © kiebor81
+
+---
+
+## Contributing
+
+PRs are welcome! To get started:
+
+```bash
+git clone https://github.com/kiebor81/mudis
+cd mudis
+bundle install
+
+```
+
+---
+
+## Contact
+
+For issues, suggestions, or feedback, please open a GitHub issue

data/lib/mudis/version.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+MUDIS_VERSION = "0.1.0"

data/lib/mudis.rb

@@ -0,0 +1,273 @@
+# lib/mudis.rb
+require 'json'
+require 'thread'
+require 'zlib'
+
+# 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
+  # --- Global Configuration and State ---
+
+  @serializer = JSON                            # Default serializer (can be changed to Marshal or Oj)
+  @compress = false                             # Whether to compress values with Zlib
+  @metrics = { hits: 0, misses: 0, evictions: 0 } # Metrics tracking read/write behavior
+  @metrics_mutex = Mutex.new                    # Mutex for synchronizing access to metrics
+  @max_value_bytes = nil                        # Optional size cap per value
+  @stop_expiry = false                          # Signal for stopping expiry thread
+
+  class << self
+    attr_accessor :serializer, :compress, :max_value_bytes
+
+    # Returns a snapshot of metrics (thread-safe)
+    def metrics
+      @metrics_mutex.synchronize { @metrics.dup }
+    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
+    @buckets ||= (ENV['MUDIS_BUCKETS']&.to_i || 32)
+  end
+
+  # --- Internal Structures ---
+
+  @stores = Array.new(buckets) { {} }           # Array of hash buckets for storage
+  @mutexes = Array.new(buckets) { Mutex.new }   # Per-bucket mutexes
+  @lru_heads = Array.new(buckets) { nil }       # Head node for each LRU list
+  @lru_tails = Array.new(buckets) { nil }       # Tail node for each LRU list
+  @lru_nodes = Array.new(buckets) { {} }        # Map of key => LRU node
+  @current_bytes = Array.new(buckets, 0)        # Memory usage per bucket
+  @max_bytes = 1_073_741_824                    # 1 GB global max cache size
+  @threshold_bytes = (@max_bytes * 0.9).to_i     # Eviction threshold at 90%
+  @expiry_thread = nil                          # Background thread for expiry cleanup
+
+  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
+
+    # Computes which bucket a key belongs to
+    def bucket_index(key)
+      key.hash % buckets
+    end
+
+    # Checks if a key exists and is not expired
+    def exists?(key)
+      !!read(key)
+    end
+
+    # Reads and returns the value for a key, updating LRU and metrics
+    def read(key)
+      raw_entry = nil
+      idx = bucket_index(key)
+      mutex = @mutexes[idx]
+
+      mutex.synchronize do
+        raw_entry = @stores[idx][key]
+        if raw_entry && raw_entry[:expires_at] && Time.now > raw_entry[:expires_at]
+          evict_key(idx, key)
+          raw_entry = nil
+        end
+
+        metric(:hits) if raw_entry
+        metric(:misses) unless raw_entry
+      end
+
+      return nil unless raw_entry
+
+      value = decompress_and_deserialize(raw_entry[:value])
+      promote_lru(idx, key)
+      value
+    end
+
+    # Writes a value to the cache with optional expiry and LRU tracking
+    def write(key, value, expires_in: nil)
+      raw = serializer.dump(value)
+      raw = Zlib::Deflate.deflate(raw) if compress
+      size = key.bytesize + raw.bytesize
+      return if max_value_bytes && raw.bytesize > max_value_bytes
+
+      idx = bucket_index(key)
+      mutex = @mutexes[idx]
+      store = @stores[idx]
+
+      mutex.synchronize do
+        evict_key(idx, key) if store[key]
+
+        while @current_bytes[idx] + size > (@threshold_bytes / buckets) && @lru_tails[idx]
+          evict_key(idx, @lru_tails[idx].key)
+          metric(:evictions)
+        end
+
+        store[key] = {
+          value: raw,
+          expires_at: expires_in ? Time.now + expires_in : nil,
+          created_at: Time.now
+        }
+
+        insert_lru(idx, key)
+        @current_bytes[idx] += size
+      end
+    end
+
+    # Atomically updates the value for a key using a block
+    def update(key)
+      idx = bucket_index(key)
+      mutex = @mutexes[idx]
+      store = @stores[idx]
+
+      raw_entry = nil
+      mutex.synchronize do
+        raw_entry = store[key]
+        return nil unless raw_entry
+      end
+
+      value = decompress_and_deserialize(raw_entry[:value])
+      new_value = yield(value)
+      new_raw = serializer.dump(new_value)
+      new_raw = Zlib::Deflate.deflate(new_raw) if compress
+
+      mutex.synchronize do
+        old_size = key.bytesize + raw_entry[:value].bytesize
+        new_size = key.bytesize + new_raw.bytesize
+        store[key][:value] = new_raw
+        @current_bytes[idx] += (new_size - old_size)
+        promote_lru(idx, key)
+      end
+    end
+
+    # Deletes a key from the cache
+    def delete(key)
+      idx = bucket_index(key)
+      mutex = @mutexes[idx]
+
+      mutex.synchronize do
+        evict_key(idx, key)
+      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|
+            if store[key][:expires_at] && now > store[key][:expires_at]
+              evict_key(idx, key)
+            end
+          end
+        end
+      end
+    end
+
+    # Returns an array of all cache keys
+    def all_keys
+      keys = []
+      buckets.times do |idx|
+        mutex = @mutexes[idx]
+        store = @stores[idx]
+        mutex.synchronize { keys.concat(store.keys) }
+      end
+      keys
+    end
+
+    # Returns total memory used across all buckets
+    def current_memory_bytes
+      @current_bytes.sum
+    end
+
+    # Returns configured maximum memory allowed
+    def max_memory_bytes
+      @max_bytes
+    end
+
+    private
+
+    # Decompresses and deserializes a raw value
+    def decompress_and_deserialize(raw)
+      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
+  end
+end
+

data/sig/mudis.rbs

@@ -0,0 +1,28 @@
+# sig/mudis.rbs
+
+class Mudis
+  # Configuration
+  class << self
+    attr_accessor serializer : Object
+    attr_accessor compress : bool
+    attr_accessor max_value_bytes : 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) -> void
+  def self.read: (String) -> untyped?
+  def self.update: (String) { (untyped) -> untyped } -> void
+  def self.delete: (String) -> void
+  def self.exists?: (String) -> bool
+
+  # Introspection & management
+  def self.metrics: () -> Hash[Symbol, Integer]
+  def self.cleanup_expired!: () -> void
+  def self.all_keys: () -> Array[String]
+  def self.current_memory_bytes: () -> Integer
+  def self.max_memory_bytes: () -> Integer
+end

data/spec/mudis_spec.rb

@@ -0,0 +1,120 @@
+# spec/mudis_spec.rb
+require_relative "spec_helper"
+
+RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
+  before(:each) do
+    Mudis.stop_expiry_thread
+    Mudis.instance_variable_set(:@buckets, nil)
+    Mudis.instance_variable_set(:@stores, Array.new(Mudis.buckets) { {} })
+    Mudis.instance_variable_set(:@mutexes, Array.new(Mudis.buckets) { Mutex.new })
+    Mudis.instance_variable_set(:@lru_heads, Array.new(Mudis.buckets) { nil })
+    Mudis.instance_variable_set(:@lru_tails, Array.new(Mudis.buckets) { nil })
+    Mudis.instance_variable_set(:@lru_nodes, Array.new(Mudis.buckets) { {} })
+    Mudis.instance_variable_set(:@current_bytes, Array.new(Mudis.buckets, 0))
+    Mudis.instance_variable_set(:@metrics, { hits: 0, misses: 0, evictions: 0 })
+    Mudis.serializer = JSON
+    Mudis.compress = false
+    Mudis.max_value_bytes = nil
+  end
+
+  describe ".write and .read" do
+    it "writes and reads a value" do
+      Mudis.write("foo", { bar: "baz" })
+      result = Mudis.read("foo")
+      expect(result).to eq({ "bar" => "baz" })
+    end
+
+    it "returns nil for non-existent keys" do
+      expect(Mudis.read("nope")).to be_nil
+    end
+  end
+
+  describe ".exists?" do
+    it "returns true if key exists" do
+      Mudis.write("check", [1, 2, 3])
+      expect(Mudis.exists?("check")).to be true
+    end
+
+    it "returns false if key does not exist" do
+      expect(Mudis.exists?("missing")).to be false
+    end
+  end
+
+  describe ".delete" do
+    it "deletes a key" do
+      Mudis.write("temp", 42)
+      Mudis.delete("temp")
+      expect(Mudis.read("temp")).to be_nil
+    end
+  end
+
+  describe ".update" do
+    it "updates a cached value" do
+      Mudis.write("counter", 5)
+      Mudis.update("counter") { |v| v + 1 }
+      expect(Mudis.read("counter")).to eq(6)
+    end
+  end
+
+  describe "expiry handling" do
+    it "expires values after specified time" do
+      Mudis.write("short_lived", "gone soon", expires_in: 1)
+      sleep 2
+      expect(Mudis.read("short_lived")).to be_nil
+    end
+  end
+
+  describe ".metrics" do
+    it "tracks hits and misses" do
+      Mudis.write("hit_me", "value")
+      Mudis.read("hit_me")   # hit
+      Mudis.read("miss_me")  # miss
+      metrics = Mudis.metrics
+      expect(metrics[:hits]).to eq(1)
+      expect(metrics[:misses]).to eq(1)
+    end
+  end
+
+  describe "LRU eviction" do
+    it "evicts old entries when size limit is reached" do
+      Mudis.stop_expiry_thread
+
+      # Force one bucket
+      Mudis.instance_variable_set(:@buckets, 1)
+      Mudis.instance_variable_set(:@stores, [{}])
+      Mudis.instance_variable_set(:@mutexes, [Mutex.new])
+      Mudis.instance_variable_set(:@lru_heads, [nil])
+      Mudis.instance_variable_set(:@lru_tails, [nil])
+      Mudis.instance_variable_set(:@lru_nodes, [{}])
+      Mudis.instance_variable_set(:@current_bytes, [0])
+
+      # Set very small threshold
+      Mudis.instance_variable_set(:@threshold_bytes, 60)
+      Mudis.max_value_bytes = 100
+
+      big_val1 = "a" * 50
+      big_val2 = "b" * 50
+
+      Mudis.write("a", big_val1)
+      Mudis.write("b", big_val2)
+
+      expect(Mudis.read("a")).to be_nil
+      expect(Mudis.read("b")).not_to be_nil
+    end
+  end
+
+  describe ".all_keys" do
+    it "lists all stored keys" do
+      Mudis.write("k1", 1)
+      Mudis.write("k2", 2)
+      expect(Mudis.all_keys).to include("k1", "k2")
+    end
+  end
+
+  describe ".current_memory_bytes" do
+    it "returns a non-zero byte count after writes" do
+      Mudis.write("size_test", "a" * 100)
+      expect(Mudis.current_memory_bytes).to be > 0
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: mudis
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kiebor81
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-07-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Thread-safe, bucketed, in-process cache for Ruby apps. Drop-in replacement
+  for Kredis in some scenarios.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- sig/mudis.rbs
+files:
+- README.md
+- lib/mudis.rb
+- lib/mudis/version.rb
+- sig/mudis.rbs
+- spec/mudis_spec.rb
+homepage: https://github.com/kiebor81/mudis
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key: 
+specification_version: 4
+summary: A fast in-memory Ruby LRU cache with compression and expiry.
+test_files:
+- spec/mudis_spec.rb