mudis 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdff64ca287bd83eaa37c48afbc375e4303b7d3cc8d368b80c1d996d9ad0e3c0
-  data.tar.gz: 20d5d5fbc3afdd79d5a6d826a4a62419d1af60532e4b2515d4d9b2c0956e6174
+  metadata.gz: a107a0fdb170a8979e0a0a8ae241c6a2bb632f50a314443124b48e82488a72f3
+  data.tar.gz: 438e08ddede26d761cc490d5e83e363142f264b67e67d8c2b5395ef8a7a18ff6
 SHA512:
-  metadata.gz: 7de9f04b093e0ae1fadbd7f967fdf843aff8b7d530e766454848ac43afae8bce58228f4d8d3a05349d4d4983c7163b9063a31181de9eb0d30ac0fc3cac7da6b3
-  data.tar.gz: '097252131a51b2dc34db4b8da6dc442ccaa01eb8c49334cfdd658bef9321330f7d8c75037e61abce08ffd6491673d92c75f7438419a964b022c6b53749159936'
+  metadata.gz: 4e261bbf2112035136d4967fc4064aed07c07918bc5322841e9c70f1761b50b2070265ae6453e5a0447b34dbfb355d5f5fd8f419c8da70808f822441ad780926
+  data.tar.gz: 3a622667d7000e9897ce301f8d40a202a10ba86ab0bb1178ed0b6fe250113b6b68942f1a39348572b8c9d607b852e58026e945aecbb23e3001e05d60fff34348

data/README.md

@@ -1,17 +1,55 @@
 ![mudis_signet](design/mudis.png "Mudis")
 
-[![Gem Version](https://badge.fury.io/rb/mudis.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/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 | ❌ |
 
 ---
 
 ## Design
 
+#### Internal Structure and Behaviour
+
+![mudis_flow](design/mudis_obj.png "Mudis Internals")
+
 #### Write - Read - Eviction
 
 ![mudis_flow](design/mudis_flow.png "Write - Read - Eviction")
@@ -55,19 +93,34 @@ In your Rails app, create an initializer:
 
 ```ruby
 # config/initializers/mudis.rb
+Mudis.configure do |c|
+  c.serializer = JSON        # or Marshal | Oj
+  c.compress = true          # Compress values using Zlib
+  c.max_value_bytes = 2_000_000  # Reject values > 2MB
+  c.hard_memory_limit = true # enforce hard memory limits
+  c.max_bytes = 1_073_741_824 # set maximum cache size
+end
 
-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
 end
 ```
 
-> If your `lib/` folder isn't eager loaded, explicitly `require 'mudis'` in this file.
+Or with direct setters:
+
+```ruby
+Mudis.serializer = JSON        # or Marshal | Oj
+Mudis.compress = true          # Compress values using Zlib
+Mudis.max_value_bytes = 2_000_000  # Reject values > 2MB
+Mudis.hard_memory_limit = true # enforce hard memory limits
+Mudis.max_bytes = 1_073_741_824 # set maximum cache size
+
+Mudis.start_expiry_thread(interval: 60) # Cleanup every 60s
+
+## set at exit hook
+```
 
 ---
 
@@ -92,6 +145,37 @@ Mudis.update('user:123') { |data| data.merge(age: 30) }
 Mudis.delete('user:123')
 ```
 
+### Developer Utilities
+
+Mudis provides utility methods to help with test environments, console debugging, and dev tool resets.
+
+#### `Mudis.reset!`
+Clears the internal cache state. Including all keys, memory tracking, and metrics. Also stops the expiry thread.
+
+```ruby
+Mudis.write("foo", "bar")
+Mudis.reset!
+Mudis.read("foo") # => nil
+```
+
+- Wipe all buckets (@stores, @lru_nodes, @current_bytes)
+- Reset all metrics (:hits, :misses, :evictions, :rejected)
+- Stop any running background expiry thread
+
+#### `Mudis.reset_metrics!`
+
+Clears only the metric counters and preserves all cached values.
+
+```ruby
+Mudis.write("key", "value")
+Mudis.read("key")    # => "value"
+Mudis.metrics        # => { hits: 1, misses: 0, ... }
+
+Mudis.reset_metrics!
+Mudis.metrics        # => { hits: 0, misses: 0, ... }
+Mudis.read("key")    # => "value" (still cached)
+```
+
 ---
 
 ## Rails Service Integration
@@ -187,25 +271,29 @@ Track cache effectiveness and performance:
 
 ```ruby
 Mudis.metrics
-# => { hits: 15, misses: 5, evictions: 3, rejections: 0 }
+# => {
+#   hits: 15,
+#   misses: 5,
+#   evictions: 3,
+#   rejected: 0,
+#   total_memory: 45678,
+#   buckets: [
+#     { index: 0, keys: 12, memory_bytes: 12345, lru_size: 12 },
+#     ...
+#   ]
+# }
+
 ```
 
-Optionally, return these metrics from a controller for remote analysis and monitoring if using rails.
+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
-    }
+    render json: { mudis: Mudis.metrics }
   end
 
 end
-
 ```
 
 ---
@@ -219,7 +307,8 @@ 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`|
+| `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.
 
@@ -244,7 +333,7 @@ Based on 100000 iterations
 | 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.
+> If opting for OJ, you will need to install the dependency in your project and configure as needed.
 
 ---
 
@@ -267,7 +356,18 @@ at_exit { Mudis.stop_expiry_thread }
 
 ## Roadmap
 
-- [ ] Stats per bucket
+#### API Enhancements
+
+- [ ] bulk_read(keys, namespace:): Batch retrieval of multiple keys with a single method call
+
+#### Safety & Policy Controls
+
+- [ ] max_ttl: Enforce a global upper bound on expires_in to prevent excessively long-lived keys
+- [ ] default_ttl: Provide a fallback TTL when one is not specified
+
+#### Debugging
+
+- [ ] clear_namespace(namespace): Remove all keys in a namespace in one call
 
 ---
 
@@ -293,3 +393,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.3.0"
+MUDIS_VERSION = "0.4.0"

data/lib/mudis.rb

@@ -4,6 +4,8 @@ require "json"
 require "thread" # rubocop:disable Lint/RedundantRequireStatement
 require "zlib"
 
+require_relative "mudis_config"
+
 # 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 # rubocop:disable Metrics/ClassLength
@@ -18,10 +20,77 @@ class Mudis # rubocop:disable Metrics/ClassLength
 
   class << self
     attr_accessor :serializer, :compress, :max_value_bytes, :hard_memory_limit
+    attr_reader :max_bytes
+
+    # Configures Mudis with a block, allowing customization of settings
+    def configure
+      yield(config)
+      apply_config!
+    end
+
+    # Returns the current configuration object
+    def config
+      @config ||= MudisConfig.new
+    end
+
+    # Applies the current configuration to Mudis
+    def apply_config!
+      self.serializer = config.serializer
+      self.compress = config.compress
+      self.max_value_bytes = config.max_value_bytes
+      self.hard_memory_limit = config.hard_memory_limit
+      self.max_bytes = config.max_bytes
+    end
 
     # Returns a snapshot of metrics (thread-safe)
-    def metrics
-      @metrics_mutex.synchronize { @metrics.dup }
+    def metrics # rubocop:disable Metrics/MethodLength
+      @metrics_mutex.synchronize do
+        {
+          hits: @metrics[:hits],
+          misses: @metrics[:misses],
+          evictions: @metrics[:evictions],
+          rejected: @metrics[:rejected],
+          total_memory: current_memory_bytes,
+          buckets: buckets.times.map do |idx|
+            {
+              index: idx,
+              keys: @stores[idx].size,
+              memory_bytes: @current_bytes[idx],
+              lru_size: @lru_nodes[idx].size
+            }
+          end
+        }
+      end
+    end
+
+    # Resets metric counters (thread-safe)
+    def reset_metrics!
+      @metrics_mutex.synchronize do
+        @metrics = { hits: 0, misses: 0, evictions: 0, rejected: 0 }
+      end
+    end
+
+    # Fully resets all internal state (except config)
+    def reset!
+      stop_expiry_thread
+
+      @buckets = nil
+      b = buckets
+
+      @stores        = Array.new(b) { {} }
+      @mutexes       = Array.new(b) { Mutex.new }
+      @lru_heads     = Array.new(b) { nil }
+      @lru_tails     = Array.new(b) { nil }
+      @lru_nodes     = Array.new(b) { {} }
+      @current_bytes = Array.new(b, 0)
+
+      reset_metrics!
+    end
+
+    # Sets the maximum size for a single value in bytes
+    def max_bytes=(value)
+      @max_bytes = value
+      @threshold_bytes = (@max_bytes * 0.9).to_i
     end
   end
 

data/lib/mudis_config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# MudisConfig holds all configuration values for Mudis,
+# and provides defaults that can be overridden via Mudis.configure.
+class MudisConfig
+  attr_accessor :serializer,
+                :compress,
+                :max_value_bytes,
+                :hard_memory_limit,
+                :max_bytes
+
+  def initialize
+    @serializer = JSON                        # Default serialization strategy
+    @compress = false                         # Whether to compress values with Zlib
+    @max_value_bytes = nil                    # Max size per value (optional)
+    @hard_memory_limit = false                # Enforce max_bytes as hard cap
+    @max_bytes = 1_073_741_824                # 1 GB default max cache size
+  end
+end

data/spec/mudis_spec.rb

@@ -216,10 +216,82 @@ 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)
       expect(Mudis.current_memory_bytes).to be > 0
     end
   end
+
+  describe ".metrics" do
+    it "includes per-bucket stats" do
+      Mudis.write("a", "x" * 50)
+      metrics = Mudis.metrics
+
+      expect(metrics).to include(:buckets)
+      expect(metrics[:buckets]).to be_an(Array)
+      expect(metrics[:buckets].first).to include(:index, :keys, :memory_bytes, :lru_size)
+    end
+  end
+
+  describe ".configure" do
+    it "applies configuration settings correctly" do
+      Mudis.configure do |c|
+        c.serializer = JSON
+        c.compress = true
+        c.max_value_bytes = 12_345
+        c.hard_memory_limit = true
+        c.max_bytes = 987_654
+      end
+
+      expect(Mudis.compress).to eq(true)
+      expect(Mudis.max_value_bytes).to eq(12_345)
+      expect(Mudis.hard_memory_limit).to eq(true)
+      expect(Mudis.max_bytes).to eq(987_654)
+    end
+  end
+
+  describe ".reset!" do
+    it "clears all stores, memory, and metrics" do
+      Mudis.write("reset_key", "value")
+      expect(Mudis.read("reset_key")).to eq("value")
+      expect(Mudis.current_memory_bytes).to be > 0
+      expect(Mudis.metrics[:hits]).to be >= 0
+
+      Mudis.reset!
+
+      metrics = Mudis.metrics
+      expect(metrics[:hits]).to eq(0)
+      expect(metrics[:misses]).to eq(0)
+      expect(metrics[:evictions]).to eq(0)
+      expect(metrics[:rejected]).to eq(0)
+      expect(Mudis.current_memory_bytes).to eq(0)
+      expect(Mudis.all_keys).to be_empty
+
+      # Optionally confirm reset_key is now gone
+      expect(Mudis.read("reset_key")).to be_nil
+    end
+  end
+
+  describe ".reset_metrics!" do
+    it "resets only the metrics without clearing cache" do
+      Mudis.write("metrics_key", "value")
+      Mudis.read("metrics_key")  # generates :hits
+      Mudis.read("missing_key")  # generates :misses
+
+      expect(Mudis.metrics[:hits]).to eq(1)
+      expect(Mudis.metrics[:misses]).to eq(1)
+
+      Mudis.reset_metrics!
+
+      expect(Mudis.metrics[:hits]).to eq(0)
+      expect(Mudis.metrics[:misses]).to eq(0)
+      expect(Mudis.read("metrics_key")).to eq("value") # still exists
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - kiebor81
@@ -35,6 +35,7 @@ files:
 - README.md
 - lib/mudis.rb
 - lib/mudis/version.rb
+- lib/mudis_config.rb
 - sig/mudis.rbs
 - spec/mudis_spec.rb
 homepage: https://github.com/kiebor81/mudis