mudis 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dc10c0b461aac92e8c559f3e3a97b7654d6c3480c8ba8755fbe10f083945183
-  data.tar.gz: 90292495545e270316d273f525d306c77ca1351e47ac99207d2739352b472f6e
+  metadata.gz: 6a4a27b63d070e4a8e356d6ffed09eda290c7f633ffb3bf7b9008499170b4a55
+  data.tar.gz: 1ccaf9415f6e595272884c926615861975f376d5a52c7109a845dcb4b4480e8d
 SHA512:
-  metadata.gz: 72fcae767bb8d79492b66b76854c65bf30b776caa1a4dd7c1342da6972fe68ca65a54ec56c796a799503681576cf40827d8d85916ea674a9d48c25debc314409
-  data.tar.gz: 2b2886cbdfebb83d63c5093812d898383d33f6b9a6eea60bf3a119c3b72b345d516d7416281cfd18146a2665e4c151bc301dbc7999eca82aea4e8aea495b0759
+  metadata.gz: 2fbcea123de9db1aefcb31e8aea21069bbbdae11300b3a6dd2b73b65c801c6b9dbdc5f60d5d84e001e26059a2e6a2e1e1ef01b61e23261f143cbf0ae3c129e40
+  data.tar.gz: 3344818c66b36d4fbb9c5e5e287a3067ee7a8c6779b2803084b8b7d4001337e073ccd45406665f2e50bc27ef58ac0e4bc9a17168f85fb302e2b0331cbc11ba2c

data/README.md

@@ -21,7 +21,7 @@ There are plenty out there, in various states of maintenance and in many shapes
 
 #### Feature / Function Comparison
 
-| **Feature**                            | **Mudis v0.3.0** | **MemoryStore** (`Rails.cache`) | **FastCache**  | **Zache**     | **EasyCache** | **MiniCache**  |
+| **Feature**                            | **Mudis** | **MemoryStore** (`Rails.cache`) | **FastCache**  | **Zache**     | **EasyCache** | **MiniCache**  |
 | -------------------------------------- | ---------------- | ------------------------------- | -------------- | ------------- | ------------- | -------------- |
 | **LRU eviction strategy**              | ✅ Per-bucket     | ✅ Global                        | ✅ Global       | ❌             | ❌             | ✅ Simplistic   |
 | **TTL expiry support**                 | ✅                | ✅                               | ✅              | ✅             | ✅             | ✅              |
@@ -309,8 +309,9 @@ end
 | `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`|
+| `buckets`      | Number of memory buckets (shards)  | `32` |
 
-To customize the number of buckets, set the `MUDIS_BUCKETS` environment variable.
+Buckets can also be set using a `MUDIS_BUCKETS` environment variable.
 
 When setting `serializer`, be mindful of the below
 

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.4.1"
+MUDIS_VERSION = "0.4.3"

data/lib/mudis.rb

@@ -1,4 +1,4 @@
-# lib/mudis.rb
+# frozen_string_literal: true
 
 require "json"
 require "thread" # rubocop:disable Lint/RedundantRequireStatement
@@ -19,8 +19,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
   @stop_expiry = false                          # Signal for stopping expiry thread
 
   class << self
-    attr_accessor :serializer, :compress, :max_value_bytes, :hard_memory_limit
-    attr_reader :max_bytes
+    attr_accessor :serializer, :compress, :hard_memory_limit
+    attr_reader :max_bytes, :max_value_bytes
 
     # Configures Mudis with a block, allowing customization of settings
     def configure
@@ -35,6 +35,8 @@ class Mudis # rubocop:disable Metrics/ClassLength
 
     # Applies the current configuration to Mudis
     def apply_config!
+      validate_config!
+
       self.serializer = config.serializer
       self.compress = config.compress
       self.max_value_bytes = config.max_value_bytes
@@ -42,6 +44,18 @@ class Mudis # rubocop:disable Metrics/ClassLength
       self.max_bytes = config.max_bytes
     end
 
+    # Validates the current configuration, raising errors for invalid settings
+    def validate_config! # rubocop:disable Metrics/AbcSize
+      if config.max_value_bytes && config.max_value_bytes > config.max_bytes
+        raise ArgumentError,
+              "max_value_bytes cannot exceed max_bytes"
+      end
+
+      raise ArgumentError, "max_value_bytes must be > 0" if config.max_value_bytes && config.max_value_bytes <= 0
+
+      raise ArgumentError, "buckets must be > 0" if config.buckets && config.buckets <= 0
+    end
+
     # Returns a snapshot of metrics (thread-safe)
     def metrics # rubocop:disable Metrics/MethodLength
       @metrics_mutex.synchronize do
@@ -89,9 +103,18 @@ class Mudis # rubocop:disable Metrics/ClassLength
 
     # Sets the maximum size for a single value in bytes
     def max_bytes=(value)
+      raise ArgumentError, "max_bytes must be > 0" if value.to_i <= 0
+
       @max_bytes = value
       @threshold_bytes = (@max_bytes * 0.9).to_i
     end
+
+    # Sets the maximum size for a single value in bytes, raising an error if invalid
+    def max_value_bytes=(value)
+      raise ArgumentError, "max_value_bytes must be > 0" if value && value.to_i <= 0
+
+      @max_value_bytes = value
+    end
   end
 
   # Node structure for the LRU doubly-linked list
@@ -107,7 +130,12 @@ class Mudis # rubocop:disable Metrics/ClassLength
 
   # Number of cache buckets (shards). Default: 32
   def self.buckets
-    @buckets ||= (ENV["MUDIS_BUCKETS"]&.to_i || 32) # rubocop:disable Style/RedundantParentheses
+    return @buckets if @buckets
+
+    val = config.buckets || ENV["MUDIS_BUCKETS"]&.to_i || 32
+    raise ArgumentError, "bucket count must be > 0" if val <= 0
+
+    @buckets = val
   end
 
   # --- Internal Structures ---

data/lib/mudis_config.rb

@@ -7,7 +7,8 @@ class MudisConfig
                 :compress,
                 :max_value_bytes,
                 :hard_memory_limit,
-                :max_bytes
+                :max_bytes,
+                :buckets
 
   def initialize
     @serializer = JSON                        # Default serialization strategy
@@ -15,5 +16,6 @@ class MudisConfig
     @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
+    @buckets = nil                            # use nil to signal fallback to ENV or default
   end
 end

data/sig/mudis.rbs

@@ -1,11 +1,17 @@
-# sig/mudis.rbs
-
 class Mudis
   # Configuration
   class << self
     attr_accessor serializer : Object
     attr_accessor compress : bool
-    attr_accessor max_value_bytes : Integer?
+    attr_accessor hard_memory_limit : bool
+    attr_reader max_bytes : Integer
+    attr_reader max_value_bytes : Integer?
+
+    def configure: () { (config: MudisConfig) -> void } -> void
+    def config: () -> MudisConfig
+    def apply_config!: () -> void
+
+    def buckets: () -> Integer
   end
 
   # Lifecycle
@@ -13,27 +19,32 @@ class Mudis
   def self.stop_expiry_thread: () -> void
 
   # Core operations
-  def self.write: (String, untyped, ?expires_in: Integer) -> void
-  def self.read: (String) -> untyped?
-  def self.update: (String) { (untyped) -> untyped } -> void
-  def self.delete: (String) -> void
-  def self.exists?: (String) -> bool
+  def self.write: (String, untyped, ?expires_in: Integer, ?namespace: String) -> void
+  def self.read: (String, ?namespace: String) -> untyped?
+  def self.update: (String, ?namespace: String) { (untyped) -> untyped } -> void
+  def self.delete: (String, ?namespace: String) -> void
+  def self.exists?: (String, ?namespace: String) -> bool
 
   # DSL & Helpers
   def self.fetch: (
     String,
     ?expires_in: Integer,
-    ?force: bool
+    ?force: bool,
+    ?namespace: String
   ) { () -> untyped } -> untyped
 
-  def self.clear: (String) -> void
-  def self.replace: (String, untyped, ?expires_in: Integer) -> void
-  def self.inspect: (String) -> Hash[Symbol, untyped]?
+  def self.clear: (String, ?namespace: String) -> void
+  def self.replace: (String, untyped, ?expires_in: Integer, ?namespace: String) -> void
+  def self.inspect: (String, ?namespace: String) -> Hash[Symbol, untyped]?
 
   # Introspection & management
-  def self.metrics: () -> Hash[Symbol, Integer]
+  def self.metrics: () -> Hash[Symbol, untyped]
   def self.cleanup_expired!: () -> void
   def self.all_keys: () -> Array[String]
   def self.current_memory_bytes: () -> Integer
   def self.max_memory_bytes: () -> Integer
+
+  # State reset
+  def self.reset!: () -> void
+  def self.reset_metrics!: () -> void
 end

data/sig/mudis_config.rbs

@@ -0,0 +1,8 @@
+class MudisConfig
+  attr_accessor serializer : Object
+  attr_accessor compress : bool
+  attr_accessor max_value_bytes : Integer?
+  attr_accessor hard_memory_limit : bool
+  attr_accessor max_bytes : Integer
+  attr_accessor buckets : Integer?
+end

data/spec/guardrails_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "climate_control"
+
+RSpec.describe "Mudis Configuration Guardrails" do # rubocop:disable Metrics/BlockLength
+  after { Mudis.reset! }
+
+  describe "bucket configuration" do
+    it "defaults to 32 buckets if ENV is nil" do
+      Mudis.instance_variable_set(:@buckets, nil) # force recomputation
+      ClimateControl.modify(MUDIS_BUCKETS: nil) do
+        expect(Mudis.send(:buckets)).to eq(32)
+      end
+    end
+
+    it "raises if MUDIS_BUCKETS is 0 or less" do
+      expect do
+        Mudis.instance_variable_set(:@buckets, nil) # force recomputation
+        ClimateControl.modify(MUDIS_BUCKETS: "0") { Mudis.send(:buckets) }
+      end.to raise_error(ArgumentError, /bucket count must be > 0/)
+
+      expect do
+        Mudis.instance_variable_set(:@buckets, nil) # force recomputation
+        ClimateControl.modify(MUDIS_BUCKETS: "-5") { Mudis.send(:buckets) }
+      end.to raise_error(ArgumentError, /bucket count must be > 0/)
+    end
+  end
+
+  describe "memory configuration" do
+    it "raises if max_bytes is set to 0 or less" do
+      expect do
+        Mudis.max_bytes = 0
+      end.to raise_error(ArgumentError, /max_bytes must be > 0/)
+
+      expect do
+        Mudis.max_bytes = -1
+      end.to raise_error(ArgumentError, /max_bytes must be > 0/)
+    end
+
+    it "raises if max_value_bytes is 0 or less via config" do
+      expect do
+        Mudis.configure do |c|
+          c.max_value_bytes = 0
+        end
+      end.to raise_error(ArgumentError, /max_value_bytes must be > 0/)
+    end
+
+    it "raises if max_value_bytes exceeds max_bytes" do
+      expect do
+        Mudis.configure do |c|
+          c.max_bytes = 1_000_000
+          c.max_value_bytes = 2_000_000
+        end
+      end.to raise_error(ArgumentError, /max_value_bytes cannot exceed max_bytes/)
+    end
+  end
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - kiebor81
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-16 00:00:00.000000000 Z
+date: 2025-07-17 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: climate_control
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -31,12 +45,15 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - sig/mudis.rbs
+- sig/mudis_config.rbs
 files:
 - README.md
 - lib/mudis.rb
 - lib/mudis/version.rb
 - lib/mudis_config.rb
 - sig/mudis.rbs
+- sig/mudis_config.rbs
+- spec/guardrails_spec.rb
 - spec/mudis_spec.rb
 homepage: https://github.com/kiebor81/mudis
 licenses:
@@ -62,4 +79,5 @@ signing_key:
 specification_version: 4
 summary: A fast in-memory Ruby LRU cache with compression and expiry.
 test_files:
+- spec/guardrails_spec.rb
 - spec/mudis_spec.rb