mudis 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05a589eca123a045badb19d25119bbc9e51c48e6afec22c490615f656c73f65f
-  data.tar.gz: 478553d02b5c62f08d9194355136b0e284c257d47184ba74d79c2d9a26553460
+  metadata.gz: bdaf73fb205686d551ea90a70ffe82e93287c9fcb2e9209e25e626f200c84768
+  data.tar.gz: 778faad72b00b0f2b477df2ec53e107aba064d2cfe4e0a8b53a8d4623521d1ce
 SHA512:
-  metadata.gz: bbae5238c153bfc4d29e0efd795c01e6c473fd17a69b28e145dc4fe8ada0faa286fce117cb53a0eaba0df8c67560c08814eb15305fe5bf01e405751b56a6f218
-  data.tar.gz: 1807351fac67cc35c66dc898264807b9542871c2e708baaa2e3fc91bd28b9cda1913257a9083e3115da341b836bd7ce3ca15ef23aae8cf998da4fbc65e6f0e6d
+  metadata.gz: e860b5e07f84e20481463eb4bf36984e094b2f95c70d1be4c072318b7e089858b7355ca8e44476495354676ce403b4e4e5cf5e796376c1d155bb47bc60e9ea21
+  data.tar.gz: 902113917b4b1a376d850a6a9d2d54994bebdf52c4834680524a43d9407f71343899a07c2b206080d9de9e522d3538b3288e74f065152e3458ee4617fc8eb293

data/README.md

@@ -1,12 +1,46 @@
 ![mudis_signet](design/mudis.png "Mudis")
 
-[![Gem Version](https://badge.fury.io/rb/mudis.svg)](https://rubygems.org/gems/mudis)
+[![Gem Version](https://badge.fury.io/rb/mudis.svg?icon=si%3Arubygems&refresh=1)](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.
+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.
+Alternatively, Mudis can be upscaled with higher sharding and resources in a dedicated Rails app to provide a Mudis server.
+
+### Why another Caching Gem?
+
+There are plenty out there, in various states of maintenance and in many shapes and sizes. So why on earth do we need another? I needed a drop-in replacement for Kredis, and the reason I was interested in using Kredis was for the simplified API and keyed management it gave me in extension to Redis. But what I didn't really need was Redis. I needed an observable, fast, simple, easy to use, flexible and highly configurable, thread-safe and high performant caching system which didn't require too many dependencies or standing up additional services. So, Mudis was born. In its most rudimentary state it was extremely useful in my project, which was an API gateway connecting into mutliple micro-services and a wide selection of APIs. The majority of the data was cold and produced by repeat expensive queries across several domains. Mudis allowed for me to minimize the footprint of the gateway, and improve end user experience, and increase performance. So, yeah, there's a lot of these gems out there, but none which really met all my needs. I decided to provide Mudis for anyone else. If you use it, I'd be interested to know how and whether you got any benefit.
+
+#### Similar Gems
+
+- [FastCache](https://github.com/swoop-inc/fast_cache)
+- [EasyCache](https://github.com/malvads/easycache)
+- [MiniCache](https://github.com/derrickreimer/mini_cache)
+- [Zache](https://github.com/yegor256/zache)
+
+#### Feature / Function Comparison
+
+| **Feature**                            | **Mudis v0.3.0** | **MemoryStore** (`Rails.cache`) | **FastCache**  | **Zache**     | **EasyCache** | **MiniCache**  |
+| -------------------------------------- | ---------------- | ------------------------------- | -------------- | ------------- | ------------- | -------------- |
+| **LRU eviction strategy**              | ✅ Per-bucket     | ✅ Global                        | ✅ Global       | ❌             | ❌             | ✅ Simplistic   |
+| **TTL expiry support**                 | ✅                | ✅                               | ✅              | ✅             | ✅             | ✅              |
+| **Background expiry cleanup thread**   | ✅                | ❌ (only on access)              | ❌              | ✅            | ❌             | ❌              |
+| **Thread safety**                      | ✅ Bucketed       | ⚠️ Global lock                  | ✅ Fine-grained | ✅    | ⚠️     | ⚠️      |
+| **Sharding (buckets)**                 | ✅                | ❌                               | ✅              | ❌             | ❌             | ❌              |
+| **Custom serializers**                 | ✅                | ✅                               | ❌              | ❌             | ❌             | ❌              |
+| **Compression (Zlib)**                 | ✅                | ✅                               | ❌              | ❌             | ❌             | ❌              |
+| **Hard memory cap**                    | ✅                | ❌                               | ❌              | ❌             | ❌             | ❌              |
+| **Max value size enforcement**         | ✅                | ❌                               | ❌              | ❌             | ❌             | ❌              |
+| **Metrics (hits, misses, evictions)**  | ✅                | ⚠️ Partial                      | ❌              | ❌             | ❌             | ❌              |
+| **Fetch/update pattern**               | ✅ Full           | ✅ Standard                      | ⚠️ Partial     | ✅ Basic       | ✅ Basic       | ✅ Basic        |
+| **Namespacing**                        | ✅                | ✅                               | ❌              | ❌             | ❌             | ❌              |
+| **Replace (if exists)**                | ✅                | ✅                               | ❌              | ❌             | ❌             | ❌              |
+| **Clear/delete method**                | ✅                | ✅                               | ✅              | ✅             | ✅             | ✅              |
+| **Key inspection with metadata**       | ✅                | ❌                               | ❌              | ❌             | ❌             | ❌              |
+| **Concurrency model**                  | ✅                | ❌                               | ✅              | ❌             | ❌             | ❌              |
+| **Maintenance level**                  | ✅                | ✅                               | ✅              | ⚠️            | ⚠️            | ⚠️             |
+| **Suitable for APIs or microservices** | ✅                | ⚠️ Limited                      | ✅              | ⚠️ Small apps | ⚠️ Small apps | ❌ |
 
 ---
 
@@ -60,6 +94,8 @@ 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
+Mudis.max_bytes = 1_073_741_824 # set maximum cache size
 
 at_exit do
   Mudis.stop_expiry_thread
@@ -95,44 +131,87 @@ 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 (TODO: add more useful abstraction once DSL and namespacing is introduced):
+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
+  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 = MudisService.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", ... }
 ```
 
 ---
@@ -143,7 +222,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.
@@ -175,9 +254,34 @@ 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`    | Enforce hard memory limits on key size and reject if exceeded  | `false`|
+| `max_bytes`    | Maximum allowed cache size  | `1GB`|
 
 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 dependency in your project and configure as needed.
+
 ---
 
 ## Graceful Shutdown
@@ -193,16 +297,13 @@ at_exit { Mudis.stop_expiry_thread }
 ## Known Limitations
 
 - Data is **non-persistent**.
-- Keys are globally scoped (no namespacing by default). Namespaving must be handled by the caller/consumer using scoped keys.
 - Compression introduces CPU overhead.
 
 ---
 
 ## Roadmap
 
-- [ ] Namespaced cache keys
 - [ ] Stats per bucket
-- [ ] Optional max memory cap per bucket
 
 ---
 
@@ -210,8 +311,6 @@ at_exit { Mudis.stop_expiry_thread }
 
 MIT License © kiebor81
 
----
-
 ## Contributing
 
 PRs are welcome! To get started:
@@ -228,3 +327,5 @@ bundle install
 ## Contact
 
 For issues, suggestions, or feedback, please open a GitHub issue
+
+---

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.2.0"
+MUDIS_VERSION = "0.3.1"

data/lib/mudis.rb

@@ -11,18 +11,24 @@ class Mudis # rubocop:disable Metrics/ClassLength
 
   @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
+    attr_reader :max_bytes
 
     # Returns a snapshot of metrics (thread-safe)
     def metrics
       @metrics_mutex.synchronize { @metrics.dup }
     end
+
+    def max_bytes=(value)
+      @max_bytes = value
+      @threshold_bytes = (@max_bytes * 0.9).to_i
+    end
   end
 
   # Node structure for the LRU doubly-linked list
@@ -52,6 +58,7 @@ class Mudis # rubocop:disable Metrics/ClassLength
   @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
+  @hard_memory_limit = false # Whether to enforce hard memory cap
 
   class << self
     # Starts a thread that periodically removes expired entries
@@ -82,12 +89,14 @@ class Mudis # rubocop:disable Metrics/ClassLength
     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) # rubocop:disable Metrics/MethodLength
+    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]
@@ -111,12 +120,18 @@ class Mudis # rubocop:disable Metrics/ClassLength
     end
 
     # Writes a value to the cache with optional expiry and LRU tracking
-    def write(key, value, expires_in: nil) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize
+    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]
@@ -141,7 +156,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
     end
 
     # Atomically updates the value for a key using a block
-    def update(key) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+    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]
@@ -167,7 +183,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
     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]
 
@@ -180,7 +197,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
     # 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)
+    def fetch(key, expires_in: nil, force: false, namespace: nil)
+      key = namespaced_key(key, namespace)
       unless force
         cached = read(key)
         return cached if cached
@@ -194,22 +212,23 @@ class Mudis # rubocop:disable Metrics/ClassLength
     # 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)
-      delete(key)
+    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)
-      return unless exists?(key)
+    def replace(key, value, expires_in: nil, namespace: nil)
+      return unless exists?(key, namespace: namespace)
 
-      write(key, value, expires_in: expires_in)
+      write(key, value, expires_in: expires_in, namespace: namespace)
     end
 
     # Inspects a key and returns all meta data for it
-    def inspect(key) # rubocop:disable Metrics/MethodLength
+    def inspect(key, namespace: nil) # rubocop:disable Metrics/MethodLength
+      key = namespaced_key(key, namespace)
       idx = bucket_index(key)
       store = @stores[idx]
       mutex = @mutexes[idx]
@@ -264,6 +283,15 @@ class Mudis # rubocop:disable Metrics/ClassLength
       @max_bytes
     end
 
+    # Executes a block with a specific namespace, restoring the old namespace afterwards
+    def with_namespace(namespace)
+      old_ns = Thread.current[:mudis_namespace]
+      Thread.current[:mudis_namespace] = namespace
+      yield
+    ensure
+      Thread.current[:mudis_namespace] = old_ns
+    end
+
     private
 
     # Decompresses and deserializes a raw value
@@ -322,5 +350,11 @@ class Mudis # rubocop:disable Metrics/ClassLength
         @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/spec/mudis_spec.rb

@@ -12,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
@@ -114,6 +114,24 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     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)
@@ -133,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
@@ -145,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
@@ -169,6 +216,11 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     end
   end
 
+  it "respects max_bytes when updated externally" do
+    Mudis.max_bytes = 100
+    expect(Mudis.send(:max_bytes)).to eq(100)
+  end
+
   describe ".current_memory_bytes" do
     it "returns a non-zero byte count after writes" do
       Mudis.write("size_test", "a" * 100)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - kiebor81