mudis 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05a589eca123a045badb19d25119bbc9e51c48e6afec22c490615f656c73f65f
-  data.tar.gz: 478553d02b5c62f08d9194355136b0e284c257d47184ba74d79c2d9a26553460
+  metadata.gz: cdff64ca287bd83eaa37c48afbc375e4303b7d3cc8d368b80c1d996d9ad0e3c0
+  data.tar.gz: 20d5d5fbc3afdd79d5a6d826a4a62419d1af60532e4b2515d4d9b2c0956e6174
 SHA512:
-  metadata.gz: bbae5238c153bfc4d29e0efd795c01e6c473fd17a69b28e145dc4fe8ada0faa286fce117cb53a0eaba0df8c67560c08814eb15305fe5bf01e405751b56a6f218
-  data.tar.gz: 1807351fac67cc35c66dc898264807b9542871c2e708baaa2e3fc91bd28b9cda1913257a9083e3115da341b836bd7ce3ca15ef23aae8cf998da4fbc65e6f0e6d
+  metadata.gz: 7de9f04b093e0ae1fadbd7f967fdf843aff8b7d530e766454848ac43afae8bce58228f4d8d3a05349d4d4983c7163b9063a31181de9eb0d30ac0fc3cac7da6b3
+  data.tar.gz: '097252131a51b2dc34db4b8da6dc442ccaa01eb8c49334cfdd658bef9321330f7d8c75037e61abce08ffd6491673d92c75f7438419a964b022c6b53749159936'

data/README.md

@@ -1,6 +1,6 @@
 ![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)](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.
 
@@ -60,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,44 +96,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 +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.
@@ -175,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
@@ -193,16 +261,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
 
 ---
 

data/lib/mudis/version.rb

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

data/lib/mudis.rb

@@ -11,13 +11,13 @@ 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
 
     # Returns a snapshot of metrics (thread-safe)
     def metrics
@@ -52,6 +52,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 +83,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 +114,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 +150,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 +177,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 +191,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 +206,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 +277,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 +344,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

metadata

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