mudis 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a43b94197d868d77feb4f2499899faa1c8c38606b166406e7dab9ad4d92b80
-  data.tar.gz: ce0a499a83d0397766624554949e9eefdd3434ccf763e0fc810613bef911dff4
+  metadata.gz: b180000138c976ee0e0c7a7cdc068550c5f33f39f363c63ba6397b84fe8f6cbe
+  data.tar.gz: ee6de323fd9dcc5914ec0fde68da5fff7289e6c830395b9d4be4271d389b2c15
 SHA512:
-  metadata.gz: 66963f1f1a627647fe7504ada52dd27f872fd06a107ca9dd03102271d33bb7d803e15f93a0a29d95679b9fad83c1e28920a95629074db611295be354e675178a
-  data.tar.gz: d0fed0c0df073b86f4433338e32860556467fef209f059ec670e293a938029090d625d8ee59f416fe2e807607eece7e4343943285a1c136d1cb82cace813236b
+  metadata.gz: e7d2c14ca2b2dce8ed23f5fb371fe73456d92d9613e25d75fb645d1a6903259a21dd31dc7e3acca8f4336dc77990d5f33fce9254e3becdbcc59d7c19c526a302
+  data.tar.gz: 6619380f6d7206caec28c0e1f3f5450bb8991817fff6c08d6e7b5ceff2c82edc8a7c7b51b38894e5fb5a09e5f41a0546c50b951d088accfc1dc70a91935d398d

data/README.md

@@ -1,12 +1,12 @@
 ![mudis_signet](design/mudis.png "Mudis")
 
-[![Gem Version](https://badge.fury.io/rb/mudis.svg?icon=si%3Arubygems&refresh=1)](https://badge.fury.io/rb/mudis)
+[![Gem Version](https://badge.fury.io/rb/mudis.svg?icon=si%3Arubygems&refresh=1&cachebust=0)](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/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](#create-a-mudis-server).
 
 ### Why another Caching Gem?
 
@@ -305,12 +305,12 @@ end
 | `Mudis.serializer`       | JSON, Marshal, or Oj                        | `JSON`             |
 | `Mudis.compress`         | Enable Zlib compression                     | `false`            |
 | `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`|
+| `Mudis.buckets`          | Number of cache shards        | `32`               |
+| `Mudis.start_expiry_thread`    | Background TTL cleanup loop (every N sec)   | Disabled by default|
+| `Mudis.hard_memory_limit`    | Enforce hard memory limits on key size and reject if exceeded  | `false`|
+| `Mudis.max_bytes`    | Maximum allowed cache size  | `1GB`|
 
-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
 
@@ -320,21 +320,69 @@ When setting `serializer`, be mindful of the below
 | `JSON`     | Cross-language interoperability       |
 | `Oj`       | API-heavy apps using JSON at scale    |
 
-#### Benchmarks
+---
+
+## Benchmarks
+
+#### Serializer(s)
 
-Based on 100000 iterations
+_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   |
+| Serializer     | Total Time (s) | Ops/sec |
+|----------------|------------|----------------|
+| oj         | 0.1342         | 745320  |
+| marshal        | 0.3228         | 309824  |
+| json           | 0.9035         | 110682  |
+| oj + zlib    | 1.8050         | 55401   |
+| marshal + zlib   | 1.8057         | 55381   |
+| json + zlib      | 2.7949         | 35780   |
 
 > If opting for OJ, you will need to install the dependency in your project and configure as needed.
 
+#### Mudis vs Rails.cache
+
+Mudis is marginally slower than `Rails.cache` by design; it trades raw speed for control, observability, and safety.
+
+_10000 iterations of 1MB, Marshal (to match MemoryStore default), compression ON_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta     |
+| --------- | ------------- | ----------- | --------- |
+| Write     | 2.139 ms/op   | 2.417 ms/op | +0.278 ms |
+| Read      | 0.007 ms/op   | 0.810 ms/op | +0.803 ms |
+
+> For context: a typical database query or HTTP call takes 10–50ms. A difference of less than 1ms per operation is negligible for most apps.
+
+###### **Why this overhead exists**
+
+Mudis includes features that MemoryStore doesn’t:
+
+| Feature            | Mudis                  | Rails.cache (MemoryStore)   |
+| ------------------ | ---------------------- | --------------------------- |
+| Per-key TTL expiry | ✅    | ⚠️ on access |
+| True LRU eviction  | ✅     | ❌          |
+| Hard memory limits | ✅                   | ❌         |
+| Value compression  | ✅     | ❌             |
+| Thread safety      | ✅ Bucket-level mutexes | ✅ Global mutex              |
+| Observability      | ✅         | ❌           |
+| Namespacing        | ✅           | ❌ Manual scoping        |
+
+It will be down to the developer to decide if a fraction of a millisecond is worth
+
+- Predictable eviction
+- Configurable expiry
+- Memory protection
+- Namespace scoping
+- Real-time metrics for hits, misses, evictions, memory usage
+
+_10000 iterations of 1MB, Marshal (to match MemoryStore default), compression OFF (to match MemoryStore default)_
+
+| Operation | `Rails.cache` | `Mudis`     | Delta         |
+| --------- | ------------- | ----------- | ------------- |
+| Write     | 2.342 ms/op   | 0.501 ms/op | **−1.841 ms** |
+| Read      | 0.007 ms/op   | 0.011 ms/op | +0.004 ms     |
+
+With compression disabled, Mudis writes significanty faster and reads are virtually identical. Optimisation and configuration of Mudis will be determined by your individual needs.
+
 ---
 
 ## Graceful Shutdown
@@ -354,6 +402,115 @@ at_exit { Mudis.stop_expiry_thread }
 
 ---
 
+## Create a Mudis Server
+
+### Minimal Setup
+
+- Create a new Rails API app:
+
+```bash
+rails new mudis-server --api
+cd mudis-server
+```
+
+- Add mudis to your Gemfile
+- Create Initializer: `config/initializers/mudis.rb`
+- Define routes
+
+```ruby
+Rails.application.routes.draw do
+  get "/cache/:key", to: "cache#show"
+  post "/cache/:key", to: "cache#write"
+  delete "/cache/:key", to: "cache#delete"
+  get "/metrics", to: "cache#metrics"
+end
+```
+
+- Create a `cache_controller` (with optional per caller/consumer namespace)
+
+```ruby
+class CacheController < ApplicationController
+
+  def show
+    key = params[:key]
+    ns  = params[:namespace]
+
+    value = Mudis.read(key, namespace: ns)
+    if value.nil?
+      render json: { error: "not found" }, status: :not_found
+    else
+      render json: { value: value }
+    end
+  end
+
+  def write
+    key = params[:key]
+    ns  = params[:namespace]
+    val = params[:value]
+    ttl = params[:expires_in]&.to_i
+
+    Mudis.write(key, val, expires_in: ttl, namespace: ns)
+    render json: { status: "written", key: key }
+  end
+
+  def delete
+    key = params[:key]
+    ns  = params[:namespace]
+
+    Mudis.delete(key, namespace: ns)
+    render json: { status: "deleted" }
+  end
+
+  def metrics
+    render json: Mudis.metrics
+  end
+end
+```
+
+- Test it
+
+```bash
+curl http://localhost:3000/cache/foo
+curl -X POST http://localhost:3000/cache/foo -d 'value=bar&expires_in=60'
+curl http://localhost:3000/metrics
+
+# Write with namespace
+curl -X POST "http://localhost:3000/cache/foo?namespace=orders" \
+     -d "value=123&expires_in=60"
+
+# Read from namespace
+curl "http://localhost:3000/cache/foo?namespace=orders"
+
+# Delete from namespace
+curl -X DELETE "http://localhost:3000/cache/foo?namespace=orders"
+
+```
+
+---
+
+## Project Philosophy
+
+Mudis is intended to be a minimal, thread-safe, in-memory cache designed specifically for Ruby applications. It focuses on:
+
+- In-process caching
+- Fine-grained memory and namespace control
+- Observability and testing friendliness
+- Minimal external dependencies
+- Configurability without complexity
+
+The primary use cases are:
+
+- Per-service application caches
+- Short-lived local caching inside background jobs or API layers
+
+Mudis is not intended to be a general-purpose, distributed caching platform. You are, however, welcome to build on top of Mudis if you want its functionality in such projects. E.g.,
+
+- mudis-server – expose Mudis via HTTP, web sockets, hooks, etc
+- mudis-broker – distributed key routing layer for coordinating multiple Mudis nodes
+- mudis-activejob-store – adapter for using Mudis in job queues or retry buffers
+
+---
+
 ## Roadmap
 
 #### API Enhancements
@@ -379,14 +536,7 @@ MIT License © kiebor81
 
 ## Contributing
 
-PRs are welcome! To get started:
-
-```bash
-git clone https://github.com/kiebor81/mudis
-cd mudis
-bundle install
-
-```
+See [contributor's guide](CONTRIBUTING.md)
 
 ---
 

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.4.2"
+MUDIS_VERSION = "0.4.4"

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

@@ -3,14 +3,15 @@ class Mudis
   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
-    def max_bytes=: (Integer) -> void
+    attr_reader max_value_bytes : Integer?
 
     def configure: () { (config: MudisConfig) -> void } -> void
     def config: () -> MudisConfig
     def apply_config!: () -> void
+
+    def buckets: () -> Integer
   end
 
   # Lifecycle

data/sig/mudis_config.rbs

@@ -4,4 +4,5 @@ class MudisConfig
   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.2
+  version: 0.4.4
 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
@@ -24,8 +38,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
-description: Thread-safe, bucketed, in-process cache for Ruby apps. Drop-in replacement
-  for Kredis in some scenarios.
+description: Mudis is a fast, thread-safe, in-memory, sharded LRU 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.
 email: 
 executables: []
 extensions: []
@@ -39,6 +54,7 @@ files:
 - 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,6 +78,8 @@ requirements: []
 rubygems_version: 3.5.17
 signing_key: 
 specification_version: 4
-summary: A fast in-memory Ruby LRU cache with compression and expiry.
+summary: A fast in-memory, thread-safe and high performance Ruby LRU cache with compression
+  and auto-expiry.
 test_files:
+- spec/guardrails_spec.rb
 - spec/mudis_spec.rb