mudis 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdaf73fb205686d551ea90a70ffe82e93287c9fcb2e9209e25e626f200c84768
-  data.tar.gz: 778faad72b00b0f2b477df2ec53e107aba064d2cfe4e0a8b53a8d4623521d1ce
+  metadata.gz: a107a0fdb170a8979e0a0a8ae241c6a2bb632f50a314443124b48e82488a72f3
+  data.tar.gz: 438e08ddede26d761cc490d5e83e363142f264b67e67d8c2b5395ef8a7a18ff6
 SHA512:
-  metadata.gz: e860b5e07f84e20481463eb4bf36984e094b2f95c70d1be4c072318b7e089858b7355ca8e44476495354676ce403b4e4e5cf5e796376c1d155bb47bc60e9ea21
-  data.tar.gz: 902113917b4b1a376d850a6a9d2d54994bebdf52c4834680524a43d9407f71343899a07c2b206080d9de9e522d3538b3288e74f065152e3458ee4617fc8eb293
+  metadata.gz: 4e261bbf2112035136d4967fc4064aed07c07918bc5322841e9c70f1761b50b2070265ae6453e5a0447b34dbfb355d5f5fd8f419c8da70808f822441ad780926
+  data.tar.gz: 3a622667d7000e9897ce301f8d40a202a10ba86ab0bb1178ed0b6fe250113b6b68942f1a39348572b8c9d607b852e58026e945aecbb23e3001e05d60fff34348

data/README.md

@@ -46,6 +46,10 @@ There are plenty out there, in various states of maintenance and in many shapes
 
 ## 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")
@@ -89,20 +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
-Mudis.max_bytes = 1_073_741_824 # set maximum cache size
 
 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
+```
 
 ---
 
@@ -127,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
@@ -222,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
-
 ```
 
 ---
@@ -303,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
 
 ---
 
@@ -311,6 +375,8 @@ at_exit { Mudis.stop_expiry_thread }
 
 MIT License © kiebor81
 
+---
+
 ## Contributing
 
 PRs are welcome! To get started:

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.3.1"
+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
@@ -20,11 +22,72 @@ class Mudis # rubocop:disable Metrics/ClassLength
     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

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

@@ -227,4 +227,71 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
       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.1
+  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