mudis 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1586fbcdac3ae237f88954090971beca8be02f3892f36c25363403d2ac80f34f
-  data.tar.gz: b12179ea11d6f51a3049d3eaa4428648fc088ecb6ade607bbe832227ceb64678
+  metadata.gz: 05a589eca123a045badb19d25119bbc9e51c48e6afec22c490615f656c73f65f
+  data.tar.gz: 478553d02b5c62f08d9194355136b0e284c257d47184ba74d79c2d9a26553460
 SHA512:
-  metadata.gz: bff8cda9a3f627f6c94b3f40b737365603ab51fd6edd8e845f058bed517ccfa86a4ad61465fb4b807540525b779586cfbbe77eccd8a16ab59afc69aa2f7cd43a
-  data.tar.gz: 544c25fee1a7346e8c0725ee5e83d5764f3028d76a261666ecdc0d3291c2bccf5a52cf07713d480750cb149e12c52201a2da2a6de0faa8f191ea45b7ba81d47b
+  metadata.gz: bbae5238c153bfc4d29e0efd795c01e6c473fd17a69b28e145dc4fe8ada0faa286fce117cb53a0eaba0df8c67560c08814eb15305fe5bf01e405751b56a6f218
+  data.tar.gz: 1807351fac67cc35c66dc898264807b9542871c2e708baaa2e3fc91bd28b9cda1913257a9083e3115da341b836bd7ce3ca15ef23aae8cf998da4fbc65e6f0e6d

data/README.md

@@ -1,9 +1,13 @@
 ![mudis_signet](design/mudis.png "Mudis")
 
+[![Gem Version](https://badge.fury.io/rb/mudis.svg)](https://rubygems.org/gems/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.
 
+Alternatively, Mudis can be upscaled with higher sharding and resources in a dedicated rails app to provide a Mudis server.
+
 ---
 
 ## Design
@@ -91,7 +95,7 @@ Mudis.delete('user:123')
 
 ## Rails Service Integration
 
-For simplified or transient use in a controller, you can wrap your cache logic in a reusable thin class:
+For simplified or transient use in a controller, you can wrap your cache logic in a reusable thin class (TODO: add more useful abstraction once DSL and namespacing is introduced):
 
 ```ruby
 class MudisService
@@ -126,7 +130,7 @@ end
 Use it like:
 
 ```ruby
-cache = MudisCacheService.new("user:#{current_user.id}")
+cache = MudisService.new("user:#{current_user.id}")
 cache.write({ preferences: "dark" }, expires_in: 3600)
 cache.read # => { "preferences" => "dark" }
 ```
@@ -188,9 +192,8 @@ at_exit { Mudis.stop_expiry_thread }
 
 ## Known Limitations
 
-- Data is **process-local** and **non-persistent**.
-- Not suitable for cross-process or cross-language use.
-- Keys are globally scoped (no namespacing by default).
+- Data is **non-persistent**.
+- Keys are globally scoped (no namespacing by default). Namespaving must be handled by the caller/consumer using scoped keys.
 - Compression introduces CPU overhead.
 
 ---
@@ -200,7 +203,6 @@ at_exit { Mudis.stop_expiry_thread }
 - [ ] Namespaced cache keys
 - [ ] Stats per bucket
 - [ ] Optional max memory cap per bucket
-- [ ] Built-in fetch/read-or-write DSL
 
 ---
 

data/lib/mudis/version.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-MUDIS_VERSION = "0.1.0"
+MUDIS_VERSION = "0.2.0"

data/lib/mudis.rb

@@ -1,11 +1,12 @@
 # lib/mudis.rb
-require 'json'
-require 'thread'
-require 'zlib'
+
+require "json"
+require "thread" # rubocop:disable Lint/RedundantRequireStatement
+require "zlib"
 
 # 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
+class Mudis # rubocop:disable Metrics/ClassLength
   # --- Global Configuration and State ---
 
   @serializer = JSON                            # Default serializer (can be changed to Marshal or Oj)
@@ -27,6 +28,7 @@ class Mudis
   # Node structure for the LRU doubly-linked list
   class LRUNode
     attr_accessor :key, :prev, :next
+
     def initialize(key)
       @key = key
       @prev = nil
@@ -36,7 +38,7 @@ class Mudis
 
   # Number of cache buckets (shards). Default: 32
   def self.buckets
-    @buckets ||= (ENV['MUDIS_BUCKETS']&.to_i || 32)
+    @buckets ||= (ENV["MUDIS_BUCKETS"]&.to_i || 32) # rubocop:disable Style/RedundantParentheses
   end
 
   # --- Internal Structures ---
@@ -48,8 +50,8 @@ class Mudis
   @lru_nodes = Array.new(buckets) { {} }        # Map of key => LRU node
   @current_bytes = Array.new(buckets, 0)        # Memory usage per bucket
   @max_bytes = 1_073_741_824                    # 1 GB global max cache size
-  @threshold_bytes = (@max_bytes * 0.9).to_i     # Eviction threshold at 90%
-  @expiry_thread = nil                          # Background thread for expiry cleanup
+  @threshold_bytes = (@max_bytes * 0.9).to_i # Eviction threshold at 90%
+  @expiry_thread = nil # Background thread for expiry cleanup
 
   class << self
     # Starts a thread that periodically removes expired entries
@@ -60,6 +62,7 @@ class Mudis
       @expiry_thread = Thread.new do
         loop do
           break if @stop_expiry
+
           sleep interval
           cleanup_expired!
         end
@@ -84,7 +87,7 @@ class Mudis
     end
 
     # Reads and returns the value for a key, updating LRU and metrics
-    def read(key)
+    def read(key) # rubocop:disable Metrics/MethodLength
       raw_entry = nil
       idx = bucket_index(key)
       mutex = @mutexes[idx]
@@ -108,7 +111,7 @@ class Mudis
     end
 
     # Writes a value to the cache with optional expiry and LRU tracking
-    def write(key, value, expires_in: nil)
+    def write(key, value, expires_in: nil) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize
       raw = serializer.dump(value)
       raw = Zlib::Deflate.deflate(raw) if compress
       size = key.bytesize + raw.bytesize
@@ -138,7 +141,7 @@ class Mudis
     end
 
     # Atomically updates the value for a key using a block
-    def update(key)
+    def update(key) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
       idx = bucket_index(key)
       mutex = @mutexes[idx]
       store = @stores[idx]
@@ -173,6 +176,59 @@ class Mudis
       end
     end
 
+    # Fetches a value for a key, writing it if not present or expired
+    # The block is executed to generate the value if it doesn't exist
+    # Optionally accepts an expiration time
+    # If force is true, it always fetches and writes the value
+    def fetch(key, expires_in: nil, force: false)
+      unless force
+        cached = read(key)
+        return cached if cached
+      end
+
+      value = yield
+      write(key, value, expires_in: expires_in)
+      value
+    end
+
+    # Clears a specific key from the cache, a semantic synonym for delete
+    # This method is provided for clarity in usage
+    # It behaves the same as delete
+    def clear(key)
+      delete(key)
+    end
+
+    # Replaces the value for a key if it exists, otherwise does nothing
+    # This is useful for updating values without needing to check existence first
+    # It will write the new value and update the expiration if provided
+    # If the key does not exist, it will not create a new entry
+    def replace(key, value, expires_in: nil)
+      return unless exists?(key)
+
+      write(key, value, expires_in: expires_in)
+    end
+
+    # Inspects a key and returns all meta data for it
+    def inspect(key) # rubocop:disable Metrics/MethodLength
+      idx = bucket_index(key)
+      store = @stores[idx]
+      mutex = @mutexes[idx]
+
+      mutex.synchronize do
+        entry = store[key]
+        return nil unless entry
+
+        {
+          key: key,
+          bucket: idx,
+          expires_at: entry[:expires_at],
+          created_at: entry[:created_at],
+          size_bytes: key.bytesize + entry[:value].bytesize,
+          compressed: compress
+        }
+      end
+    end
+
     # Removes expired keys across all buckets
     def cleanup_expired!
       now = Time.now
@@ -180,10 +236,8 @@ class Mudis
         mutex = @mutexes[idx]
         store = @stores[idx]
         mutex.synchronize do
-          store.keys.each do |key|
-            if store[key][:expires_at] && now > store[key][:expires_at]
-              evict_key(idx, key)
-            end
+          store.keys.each do |key| # rubocop:disable Style/HashEachMethods
+            evict_key(idx, key) if store[key][:expires_at] && now > store[key][:expires_at]
           end
         end
       end
@@ -270,4 +324,3 @@ class Mudis
     end
   end
 end
-

data/sig/mudis.rbs

@@ -19,6 +19,17 @@ class Mudis
   def self.delete: (String) -> void
   def self.exists?: (String) -> bool
 
+  # DSL & Helpers
+  def self.fetch: (
+    String,
+    ?expires_in: Integer,
+    ?force: bool
+  ) { () -> untyped } -> untyped
+
+  def self.clear: (String) -> void
+  def self.replace: (String, untyped, ?expires_in: Integer) -> void
+  def self.inspect: (String) -> Hash[Symbol, untyped]?
+
   # Introspection & management
   def self.metrics: () -> Hash[Symbol, Integer]
   def self.cleanup_expired!: () -> void

data/spec/mudis_spec.rb

@@ -1,4 +1,5 @@
-# spec/mudis_spec.rb
+# frozen_string_literal: true
+
 require_relative "spec_helper"
 
 RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
@@ -56,6 +57,63 @@ RSpec.describe Mudis do # rubocop:disable Metrics/BlockLength
     end
   end
 
+  describe ".fetch" do
+    it "returns cached value if exists" do
+      Mudis.write("k", 123)
+      result = Mudis.fetch("k", expires_in: 60) { 999 } # fix: use keyword arg
+      expect(result).to eq(123)
+    end
+
+    it "writes and returns block result if missing" do
+      Mudis.delete("k")
+      result = Mudis.fetch("k", expires_in: 60) { 999 } # fix
+      expect(result).to eq(999)
+      expect(Mudis.read("k")).to eq(999)
+    end
+
+    it "forces overwrite if force: true" do
+      Mudis.write("k", 100)
+      result = Mudis.fetch("k", force: true) { 200 } # fix
+      expect(result).to eq(200)
+    end
+  end
+
+  describe ".clear" do
+    it "removes a key from the cache" do
+      Mudis.write("to_clear", 123)
+      expect(Mudis.read("to_clear")).to eq(123)
+      Mudis.clear("to_clear")
+      expect(Mudis.read("to_clear")).to be_nil
+    end
+  end
+
+  describe ".replace" do
+    it "replaces value only if key exists" do
+      Mudis.write("to_replace", 100)
+      Mudis.replace("to_replace", 200)
+      expect(Mudis.read("to_replace")).to eq(200)
+
+      Mudis.delete("to_replace")
+      Mudis.replace("to_replace", 300)
+      expect(Mudis.read("to_replace")).to be_nil
+    end
+  end
+
+  describe ".inspect" do
+    it "returns metadata for a cached key" do
+      Mudis.write("key1", "abc", expires_in: 60)
+      meta = Mudis.inspect("key1")
+
+      expect(meta).to include(:key, :bucket, :expires_at, :created_at, :size_bytes, :compressed)
+      expect(meta[:key]).to eq("key1")
+      expect(meta[:compressed]).to eq(false)
+    end
+
+    it "returns nil for missing key" do
+      expect(Mudis.inspect("unknown")).to be_nil
+    end
+  end
+
   describe "expiry handling" do
     it "expires values after specified time" do
       Mudis.write("short_lived", "gone soon", expires_in: 1)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mudis
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - kiebor81
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-15 00:00:00.000000000 Z
+date: 2025-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec