mudis 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1586fbcdac3ae237f88954090971beca8be02f3892f36c25363403d2ac80f34f
-  data.tar.gz: b12179ea11d6f51a3049d3eaa4428648fc088ecb6ade607bbe832227ceb64678
+  metadata.gz: cdff64ca287bd83eaa37c48afbc375e4303b7d3cc8d368b80c1d996d9ad0e3c0
+  data.tar.gz: 20d5d5fbc3afdd79d5a6d826a4a62419d1af60532e4b2515d4d9b2c0956e6174
 SHA512:
-  metadata.gz: bff8cda9a3f627f6c94b3f40b737365603ab51fd6edd8e845f058bed517ccfa86a4ad61465fb4b807540525b779586cfbbe77eccd8a16ab59afc69aa2f7cd43a
-  data.tar.gz: 544c25fee1a7346e8c0725ee5e83d5764f3028d76a261666ecdc0d3291c2bccf5a52cf07713d480750cb149e12c52201a2da2a6de0faa8f191ea45b7ba81d47b
+  metadata.gz: 7de9f04b093e0ae1fadbd7f967fdf843aff8b7d530e766454848ac43afae8bce58228f4d8d3a05349d4d4983c7163b9063a31181de9eb0d30ac0fc3cac7da6b3
+  data.tar.gz: '097252131a51b2dc34db4b8da6dc442ccaa01eb8c49334cfdd658bef9321330f7d8c75037e61abce08ffd6491673d92c75f7438419a964b022c6b53749159936'

data/README.md

@@ -1,9 +1,13 @@
 ![mudis_signet](design/mudis.png "Mudis")
 
+[![Gem Version](https://badge.fury.io/rb/mudis.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/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.
 
+Alternatively, Mudis can be upscaled with higher sharding and resources in a dedicated rails app to provide a Mudis server.
+
 ---
 
 ## Design
@@ -56,6 +60,7 @@ 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
+Mudis.hard_memory_limit = true # enforce hard memory limits
 
 at_exit do
   Mudis.stop_expiry_thread
@@ -95,40 +100,83 @@ For simplified or transient use in a controller, you can wrap your cache logic i
 
 ```ruby
 class MudisService
-  attr_reader :cache_key
+  attr_reader :cache_key, :namespace
 
-  def initialize(cache_key)
+  # Initialize the service with a cache key and optional namespace
+  #
+  # @param cache_key [String] the base key to use
+  # @param namespace [String, nil] optional logical namespace
+  def initialize(cache_key, namespace: nil)
     @cache_key = cache_key
+    @namespace = namespace
   end
 
+  # Write a value to the cache
+  #
+  # @param data [Object] the value to cache
+  # @param expires_in [Integer, nil] optional TTL in seconds
   def write(data, expires_in: nil)
-    Mudis.write(cache_key, data, expires_in: expires_in)
+    Mudis.write(cache_key, data, expires_in: expires_in, namespace: namespace)
   end
 
+  # Read the cached value or return default
+  #
+  # @param default [Object] fallback value if key is not present
   def read(default: nil)
-    Mudis.read(cache_key) || default
+    Mudis.read(cache_key, namespace: namespace) || default
   end
 
+  # Update the cached value using a block
+  #
+  # @yieldparam current [Object] the current value
+  # @yieldreturn [Object] the updated value
   def update
-    Mudis.update(cache_key) { |current| yield(current) }
+    Mudis.update(cache_key, namespace: namespace) { |current| yield(current) }
   end
 
+  # Delete the key from cache
   def delete
-    Mudis.delete(cache_key)
+    Mudis.delete(cache_key, namespace: namespace)
   end
 
+  # Return true if the key exists in cache
   def exists?
-    Mudis.exists?(cache_key)
+    Mudis.exists?(cache_key, namespace: namespace)
+  end
+
+  # Fetch from cache or compute and store it
+  #
+  # @param expires_in [Integer, nil] optional TTL
+  # @param force [Boolean] force recomputation
+  # @yield return value if key is missing
+  def fetch(expires_in: nil, force: false)
+    Mudis.fetch(cache_key, expires_in: expires_in, force: force, namespace: namespace) do
+      yield
+    end
+  end
+
+  # Inspect metadata for the current key
+  #
+  # @return [Hash, nil] metadata including :expires_at, :created_at, :size_bytes, etc.
+  def inspect_meta
+    Mudis.inspect(cache_key, namespace: namespace)
   end
 end
+
 ```
 
 Use it like:
 
 ```ruby
-cache = MudisCacheService.new("user:#{current_user.id}")
-cache.write({ preferences: "dark" }, expires_in: 3600)
-cache.read # => { "preferences" => "dark" }
+cache = MudisService.new("user:42:profile", namespace: "users")
+
+cache.write({ name: "Alice" }, expires_in: 300)
+cache.read                       # => { "name" => "Alice" }
+cache.exists?                    # => true
+
+cache.update { |data| data.merge(age: 30) }
+cache.fetch(expires_in: 60) { expensive_query }
+cache.inspect_meta               # => { key: "users:user:42:profile", ... }
 ```
 
 ---
@@ -139,7 +187,7 @@ Track cache effectiveness and performance:
 
 ```ruby
 Mudis.metrics
-# => { hits: 15, misses: 5, evictions: 3 }
+# => { hits: 15, misses: 5, evictions: 3, rejections: 0 }
 ```
 
 Optionally, return these metrics from a controller for remote analysis and monitoring if using rails.
@@ -171,9 +219,33 @@ end
 | `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|
+| `hard_memory_limit `    | Enfirce hard memory limits on key size and reject if exceeded  | `false`|
 
 To customize the number of buckets, set the `MUDIS_BUCKETS` environment variable.
 
+When setting `serializer`, be mindful of the below
+
+| Serializer | Recommended for                       |
+| ---------- | ------------------------------------- |
+| `Marshal`  | Ruby-only apps, speed-sensitive logic |
+| `JSON`     | Cross-language interoperability       |
+| `Oj`       | API-heavy apps using JSON at scale    |
+
+#### Benchmarks
+
+Based on 100000 iterations
+
+| Serializer     | Iterations | Total Time (s) | Ops/sec |
+|----------------|------------|----------------|---------|
+| oj         | 100000     | 0.1342         | 745320  |
+| marshal        | 100000     | 0.3228         | 309824  |
+| json           | 100000     | 0.9035         | 110682  |
+| oj + zlib    | 100000     | 1.8050         | 55401   |
+| marshal + zlib   | 100000     | 1.8057         | 55381   |
+| json + zlib      | 100000     | 2.7949         | 35780   |
+
+> If opting for OJ, you will need to install the dependncy in your project and configure as needed.
+
 ---
 
 ## Graceful Shutdown
@@ -188,19 +260,14 @@ 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).
+- Data is **non-persistent**.
 - Compression introduces CPU overhead.
 
 ---
 
 ## Roadmap
 
-- [ ] Namespaced cache keys
 - [ ] Stats per bucket
-- [ ] Optional max memory cap per bucket
-- [ ] Built-in fetch/read-or-write DSL
 
 ---
 

data/lib/mudis/version.rb

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

data/lib/mudis.rb

@@ -1,22 +1,23 @@
 # lib/mudis.rb
-require 'json'
-require 'thread'
-require 'zlib'
+
+require "json"
+require "thread" # rubocop:disable Lint/RedundantRequireStatement
+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
+class Mudis # rubocop:disable Metrics/ClassLength
   # --- 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 = { hits: 0, misses: 0, evictions: 0, rejected: 0 } # Metrics tracking read/write behaviour
   @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
+    attr_accessor :serializer, :compress, :max_value_bytes, :hard_memory_limit
 
     # Returns a snapshot of metrics (thread-safe)
     def metrics
@@ -27,6 +28,7 @@ class Mudis
   # Node structure for the LRU doubly-linked list
   class LRUNode
     attr_accessor :key, :prev, :next
+
     def initialize(key)
       @key = key
       @prev = nil
@@ -36,7 +38,7 @@ class Mudis
 
   # Number of cache buckets (shards). Default: 32
   def self.buckets
-    @buckets ||= (ENV['MUDIS_BUCKETS']&.to_i || 32)
+    @buckets ||= (ENV["MUDIS_BUCKETS"]&.to_i || 32) # rubocop:disable Style/RedundantParentheses
   end
 
   # --- Internal Structures ---
@@ -48,8 +50,9 @@ class Mudis
   @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
+  @threshold_bytes = (@max_bytes * 0.9).to_i # Eviction threshold at 90%
+  @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
@@ -60,6 +63,7 @@ class Mudis
       @expiry_thread = Thread.new do
         loop do
           break if @stop_expiry
+
           sleep interval
           cleanup_expired!
         end
@@ -79,12 +83,14 @@ class Mudis
     end
 
     # Checks if a key exists and is not expired
-    def exists?(key)
+    def exists?(key, namespace: nil)
+      key = namespaced_key(key, namespace)
       !!read(key)
     end
 
     # Reads and returns the value for a key, updating LRU and metrics
-    def read(key)
+    def read(key, namespace: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      key = namespaced_key(key, namespace)
       raw_entry = nil
       idx = bucket_index(key)
       mutex = @mutexes[idx]
@@ -108,12 +114,18 @@ class Mudis
     end
 
     # Writes a value to the cache with optional expiry and LRU tracking
-    def write(key, value, expires_in: nil)
+    def write(key, value, expires_in: nil, namespace: nil) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/PerceivedComplexity
+      key = namespaced_key(key, namespace)
       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
 
+      if hard_memory_limit && current_memory_bytes + size > max_memory_bytes
+        metric(:rejected)
+        return
+      end
+
       idx = bucket_index(key)
       mutex = @mutexes[idx]
       store = @stores[idx]
@@ -138,7 +150,8 @@ class Mudis
     end
 
     # Atomically updates the value for a key using a block
-    def update(key)
+    def update(key, namespace: nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      key = namespaced_key(key, namespace)
       idx = bucket_index(key)
       mutex = @mutexes[idx]
       store = @stores[idx]
@@ -164,7 +177,8 @@ class Mudis
     end
 
     # Deletes a key from the cache
-    def delete(key)
+    def delete(key, namespace: nil)
+      key = namespaced_key(key, namespace)
       idx = bucket_index(key)
       mutex = @mutexes[idx]
 
@@ -173,6 +187,61 @@ class Mudis
       end
     end
 
+    # Fetches a value for a key, writing it if not present or expired
+    # The block is executed to generate the value if it doesn't exist
+    # Optionally accepts an expiration time
+    # If force is true, it always fetches and writes the value
+    def fetch(key, expires_in: nil, force: false, namespace: nil)
+      key = namespaced_key(key, namespace)
+      unless force
+        cached = read(key)
+        return cached if cached
+      end
+
+      value = yield
+      write(key, value, expires_in: expires_in)
+      value
+    end
+
+    # Clears a specific key from the cache, a semantic synonym for delete
+    # This method is provided for clarity in usage
+    # It behaves the same as delete
+    def clear(key, namespace: nil)
+      delete(key, namespace: namespace)
+    end
+
+    # Replaces the value for a key if it exists, otherwise does nothing
+    # This is useful for updating values without needing to check existence first
+    # It will write the new value and update the expiration if provided
+    # If the key does not exist, it will not create a new entry
+    def replace(key, value, expires_in: nil, namespace: nil)
+      return unless exists?(key, namespace: namespace)
+
+      write(key, value, expires_in: expires_in, namespace: namespace)
+    end
+
+    # Inspects a key and returns all meta data for it
+    def inspect(key, namespace: nil) # rubocop:disable Metrics/MethodLength
+      key = namespaced_key(key, namespace)
+      idx = bucket_index(key)
+      store = @stores[idx]
+      mutex = @mutexes[idx]
+
+      mutex.synchronize do
+        entry = store[key]
+        return nil unless entry
+
+        {
+          key: key,
+          bucket: idx,
+          expires_at: entry[:expires_at],
+          created_at: entry[:created_at],
+          size_bytes: key.bytesize + entry[:value].bytesize,
+          compressed: compress
+        }
+      end
+    end
+
     # Removes expired keys across all buckets
     def cleanup_expired!
       now = Time.now
@@ -180,10 +249,8 @@ class Mudis
         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
+          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
@@ -210,6 +277,15 @@ class Mudis
       @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
@@ -268,6 +344,11 @@ class Mudis
         @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
   end
 end
-

data/sig/mudis.rbs

@@ -19,6 +19,17 @@ class Mudis
   def self.delete: (String) -> void
   def self.exists?: (String) -> bool
 
+  # DSL & Helpers
+  def self.fetch: (
+    String,
+    ?expires_in: Integer,
+    ?force: bool
+  ) { () -> untyped } -> untyped
+
+  def self.clear: (String) -> void
+  def self.replace: (String, untyped, ?expires_in: Integer) -> void
+  def self.inspect: (String) -> Hash[Symbol, untyped]?
+
   # Introspection & management
   def self.metrics: () -> Hash[Symbol, Integer]
   def self.cleanup_expired!: () -> void

data/spec/mudis_spec.rb

@@ -1,4 +1,5 @@
-# spec/mudis_spec.rb
+# frozen_string_literal: true
+
 require_relative "spec_helper"
 
 RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
@@ -11,7 +12,7 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     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.instance_variable_set(:@metrics, { hits: 0, misses: 0, evictions: 0, rejected: 0 })
     Mudis.serializer = JSON
     Mudis.compress = false
     Mudis.max_value_bytes = nil
@@ -56,6 +57,81 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     end
   end
 
+  describe ".fetch" do
+    it "returns cached value if exists" do
+      Mudis.write("k", 123)
+      result = Mudis.fetch("k", expires_in: 60) { 999 } # fix: use keyword arg
+      expect(result).to eq(123)
+    end
+
+    it "writes and returns block result if missing" do
+      Mudis.delete("k")
+      result = Mudis.fetch("k", expires_in: 60) { 999 } # fix
+      expect(result).to eq(999)
+      expect(Mudis.read("k")).to eq(999)
+    end
+
+    it "forces overwrite if force: true" do
+      Mudis.write("k", 100)
+      result = Mudis.fetch("k", force: true) { 200 } # fix
+      expect(result).to eq(200)
+    end
+  end
+
+  describe ".clear" do
+    it "removes a key from the cache" do
+      Mudis.write("to_clear", 123)
+      expect(Mudis.read("to_clear")).to eq(123)
+      Mudis.clear("to_clear")
+      expect(Mudis.read("to_clear")).to be_nil
+    end
+  end
+
+  describe ".replace" do
+    it "replaces value only if key exists" do
+      Mudis.write("to_replace", 100)
+      Mudis.replace("to_replace", 200)
+      expect(Mudis.read("to_replace")).to eq(200)
+
+      Mudis.delete("to_replace")
+      Mudis.replace("to_replace", 300)
+      expect(Mudis.read("to_replace")).to be_nil
+    end
+  end
+
+  describe ".inspect" do
+    it "returns metadata for a cached key" do
+      Mudis.write("key1", "abc", expires_in: 60)
+      meta = Mudis.inspect("key1")
+
+      expect(meta).to include(:key, :bucket, :expires_at, :created_at, :size_bytes, :compressed)
+      expect(meta[:key]).to eq("key1")
+      expect(meta[:compressed]).to eq(false)
+    end
+
+    it "returns nil for missing key" do
+      expect(Mudis.inspect("unknown")).to be_nil
+    end
+  end
+
+  describe "namespacing" do
+    it "uses thread-local namespace in block" do
+      Mudis.with_namespace("test") do
+        Mudis.write("foo", "bar")
+      end
+      expect(Mudis.read("foo", namespace: "test")).to eq("bar")
+      expect(Mudis.read("foo")).to be_nil
+    end
+
+    it "supports explicit namespace override" do
+      Mudis.write("x", 1, namespace: "alpha")
+      Mudis.write("x", 2, namespace: "beta")
+      expect(Mudis.read("x", namespace: "alpha")).to eq(1)
+      expect(Mudis.read("x", namespace: "beta")).to eq(2)
+      expect(Mudis.read("x")).to be_nil
+    end
+  end
+
   describe "expiry handling" do
     it "expires values after specified time" do
       Mudis.write("short_lived", "gone soon", expires_in: 1)
@@ -75,6 +151,35 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     end
   end
 
+  describe "memory guards" do
+    before do
+      Mudis.stop_expiry_thread
+      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])
+
+      Mudis.max_value_bytes = nil
+      Mudis.instance_variable_set(:@threshold_bytes, 1_000_000) # optional
+      Mudis.hard_memory_limit = true
+      Mudis.instance_variable_set(:@max_bytes, 100) # artificially low
+    end
+
+    it "rejects writes that exceed max memory" do
+      big_value = "a" * 90
+      Mudis.write("a", big_value)
+      expect(Mudis.read("a")).to eq(big_value)
+
+      big_value_2 = "b" * 90 # rubocop:disable Naming/VariableNumber
+      Mudis.write("b", big_value_2)
+      expect(Mudis.read("b")).to be_nil
+      expect(Mudis.metrics[:rejected]).to be > 0
+    end
+  end
+
   describe "LRU eviction" do
     it "evicts old entries when size limit is reached" do
       Mudis.stop_expiry_thread
@@ -87,7 +192,7 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
       Mudis.instance_variable_set(:@lru_tails, [nil])
       Mudis.instance_variable_set(:@lru_nodes, [{}])
       Mudis.instance_variable_set(:@current_bytes, [0])
-
+      Mudis.hard_memory_limit = false
       # Set very small threshold
       Mudis.instance_variable_set(:@threshold_bytes, 60)
       Mudis.max_value_bytes = 100

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - kiebor81
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-15 00:00:00.000000000 Z
+date: 2025-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec