mudis 0.4.3 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a4a27b63d070e4a8e356d6ffed09eda290c7f633ffb3bf7b9008499170b4a55
-  data.tar.gz: 1ccaf9415f6e595272884c926615861975f376d5a52c7109a845dcb4b4480e8d
+  metadata.gz: b180000138c976ee0e0c7a7cdc068550c5f33f39f363c63ba6397b84fe8f6cbe
+  data.tar.gz: ee6de323fd9dcc5914ec0fde68da5fff7289e6c830395b9d4be4271d389b2c15
 SHA512:
-  metadata.gz: 2fbcea123de9db1aefcb31e8aea21069bbbdae11300b3a6dd2b73b65c801c6b9dbdc5f60d5d84e001e26059a2e6a2e1e1ef01b61e23261f143cbf0ae3c129e40
-  data.tar.gz: 3344818c66b36d4fbb9c5e5e287a3067ee7a8c6779b2803084b8b7d4001337e073ccd45406665f2e50bc27ef58ac0e4bc9a17168f85fb302e2b0331cbc11ba2c
+  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,11 +305,10 @@ 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`|
-| `buckets`      | Number of memory buckets (shards)  | `32` |
+| `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`|
 
 Buckets can also be set using a `MUDIS_BUCKETS` environment variable.
 
@@ -321,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
@@ -355,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
@@ -380,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.3"
+MUDIS_VERSION = "0.4.4"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.4
 platform: ruby
 authors:
 - kiebor81
@@ -38,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: []
@@ -77,7 +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