mudis 0.5.0 → 0.7.0

data/lib/mudis_client.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+require "socket"
+require "json"
+
+class MudisClient
+  SOCKET_PATH = "/tmp/mudis.sock"
+
+  def initialize
+    @mutex = Mutex.new
+  end
+
+  def request(payload)
+    @mutex.synchronize do
+      UNIXSocket.open(SOCKET_PATH) do |sock|
+        sock.puts(JSON.dump(payload))
+        response = sock.gets
+        res = JSON.parse(response, symbolize_names: true)
+        raise res[:error] unless res[:ok]
+        res[:value]
+        
+      end
+
+    rescue Errno::ENOENT
+      warn "[MudisClient] Socket missing; master likely not running MudisServer"
+      nil
+
+    end
+
+  end
+
+  def read(key, namespace: nil)
+    request(cmd: "read", key: key, namespace: namespace)
+  end
+
+  def write(key, value, expires_in: nil, namespace: nil)
+    request(cmd: "write", key: key, value: value, ttl: expires_in, namespace: namespace)
+  end
+
+  def delete(key, namespace: nil)
+    request(cmd: "delete", key: key, namespace: namespace)
+  end
+
+  def exists?(key, namespace: nil)
+    request(cmd: "exists", key: key, namespace: namespace)
+  end
+
+  def fetch(key, expires_in: nil, namespace: nil)
+    val = read(key, namespace: namespace)
+    return val if val
+
+    new_val = yield
+    write(key, new_val, expires_in: expires_in, namespace: namespace)
+    new_val
+  end
+
+  def metrics
+    request(cmd: "metrics")
+  end
+
+  def reset_metrics!
+    request(cmd: "reset_metrics")
+  end
+
+  def reset!
+    request(cmd: "reset")
+  end
+
+end

data/lib/mudis_config.rb

@@ -1,25 +1,25 @@
-# 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,
-                :buckets,
-                :max_ttl,
-                :default_ttl
-
-  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
-    @buckets = nil                            # use nil to signal fallback to ENV or default
-    @max_ttl = nil                            # Max TTL for cache entries (optional)
-    @default_ttl = nil                        # Default TTL for cache entries (optional)
-  end
-end
+# 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,
+                :buckets,
+                :max_ttl,
+                :default_ttl
+
+  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
+    @buckets = nil                            # use nil to signal fallback to ENV or default
+    @max_ttl = nil                            # Max TTL for cache entries (optional)
+    @default_ttl = nil                        # Default TTL for cache entries (optional)
+  end
+end

data/lib/mudis_server.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+require "socket"
+require "json"
+require_relative "mudis"
+
+class MudisServer
+  SOCKET_PATH = "/tmp/mudis.sock"
+
+  def self.start!
+    # Clean up old socket if it exists
+    File.unlink(SOCKET_PATH) if File.exist?(SOCKET_PATH)
+
+    server = UNIXServer.new(SOCKET_PATH)
+    server.listen(128)
+    puts "[MudisServer] Listening on #{SOCKET_PATH}"
+
+    Thread.new do
+      loop do
+        client = server.accept
+        Thread.new(client) do |sock|
+          handle_client(sock)
+        end
+      end
+    end
+  end
+
+  def self.handle_client(sock)
+    request_line = sock.gets
+    return unless request_line
+
+    req = JSON.parse(request_line, symbolize_names: true)
+    cmd  = req[:cmd]
+    key  = req[:key]
+    ns   = req[:namespace]
+    val  = req[:value]
+    ttl  = req[:ttl]
+
+    begin
+      case cmd
+      when "read"
+        result = Mudis.read(key, namespace: ns)
+        sock.puts(JSON.dump({ ok: true, value: result }))
+
+      when "write"
+        Mudis.write(key, val, expires_in: ttl, namespace: ns)
+        sock.puts(JSON.dump({ ok: true }))
+
+      when "delete"
+        Mudis.delete(key, namespace: ns)
+        sock.puts(JSON.dump({ ok: true }))
+
+      when "exists"
+        sock.puts(JSON.dump({ ok: true, value: Mudis.exists?(key, namespace: ns) }))
+
+      when "fetch"
+        result = Mudis.fetch(key, expires_in: ttl, namespace: ns) { req[:fallback] }
+        sock.puts(JSON.dump({ ok: true, value: result }))
+
+      when "metrics"
+        sock.puts(JSON.dump({ ok: true, value: Mudis.metrics }))
+
+      when "reset_metrics"
+        Mudis.reset_metrics!
+        sock.puts(JSON.dump({ ok: true }))
+        
+      when "reset"
+        Mudis.reset!
+        sock.puts(JSON.dump({ ok: true }))
+
+      else
+        sock.puts(JSON.dump({ ok: false, error: "unknown command: #{cmd}" }))
+      end
+    rescue => e
+      sock.puts(JSON.dump({ ok: false, error: e.message }))
+    ensure
+      sock.close
+    end
+  end
+end

data/sig/mudis.rbs

@@ -1,54 +1,56 @@
-class Mudis
-  # Configuration
-  class << self
-    attr_accessor serializer : Object
-    attr_accessor compress : bool
-    attr_accessor hard_memory_limit : bool
-    attr_reader max_bytes : Integer
-    attr_reader max_value_bytes : Integer?
-    attr_accessor max_ttl: Integer?
-    attr_accessor default_ttl: Integer?
-    
-    def configure: () { (config: MudisConfig) -> void } -> void
-    def config: () -> MudisConfig
-    def apply_config!: () -> void
-    def validate_config!: () -> void
-
-    def buckets: () -> Integer
-  end
-
-  # Lifecycle
-  def self.start_expiry_thread: (?interval: Integer) -> void
-  def self.stop_expiry_thread: () -> void
-
-  # Core operations
-  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,
-    ?namespace: String
-  ) { () -> untyped } -> 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, untyped]
-  def self.cleanup_expired!: () -> void
-  def self.all_keys: () -> Array[String]
-  def self.current_memory_bytes: () -> Integer
-  def self.max_memory_bytes: () -> Integer
-  def self.least_touched: (?Integer) -> Array[[String, Integer]]
-
-  # State reset
-  def self.reset!: () -> void
-  def self.reset_metrics!: () -> void
-end
+class Mudis
+  # Configuration
+  class << self
+    attr_accessor serializer : Object
+    attr_accessor compress : bool
+    attr_accessor hard_memory_limit : bool
+    attr_reader max_bytes : Integer
+    attr_reader max_value_bytes : Integer?
+    attr_accessor max_ttl: Integer?
+    attr_accessor default_ttl: Integer?
+    
+    def configure: () { (config: MudisConfig) -> void } -> void
+    def config: () -> MudisConfig
+    def apply_config!: () -> void
+    def validate_config!: () -> void
+
+    def buckets: () -> Integer
+  end
+
+  # Lifecycle
+  def self.start_expiry_thread: (?interval: Integer) -> void
+  def self.stop_expiry_thread: () -> void
+
+  # Core operations
+  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,
+    ?namespace: String
+  ) { () -> untyped } -> 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]?
+  def self.keys: (?namespace: String) -> Array[String]
+  def self.clear_namespace: (?namespace: String) -> void
+
+  # Introspection & management
+  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
+  def self.least_touched: (?Integer) -> Array[[String, Integer]]
+
+  # State reset
+  def self.reset!: () -> void
+  def self.reset_metrics!: () -> void
+end

data/sig/mudis_config.rbs

@@ -1,10 +1,10 @@
-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 max_ttl: Integer?
-  attr_accessor default_ttl: Integer?
-  attr_accessor buckets: Integer?
-end
+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 max_ttl: Integer?
+  attr_accessor default_ttl: Integer?
+  attr_accessor buckets: Integer?
+end

data/spec/eviction_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Mudis LRU Eviction" do
+  before do
+    Mudis.reset!
+    Mudis.stop_expiry_thread
+
+    Mudis.instance_variable_set(:@buckets, 1)
+    Mudis.instance_variable_set(:@stores, [{}])
+    Mudis.instance_variable_set(:@mutexes, [Mutex.new])
+    Mudis.instance_variable_set(:@lru_heads, [nil])
+    Mudis.instance_variable_set(:@lru_tails, [nil])
+    Mudis.instance_variable_set(:@lru_nodes, [{}])
+    Mudis.instance_variable_set(:@current_bytes, [0])
+    Mudis.hard_memory_limit = false
+    Mudis.instance_variable_set(:@threshold_bytes, 60)
+    Mudis.max_value_bytes = 100
+  end
+
+  it "evicts old entries when size limit is reached" do
+    Mudis.write("a", "a" * 50)
+    Mudis.write("b", "b" * 50)
+
+    expect(Mudis.read("a")).to be_nil
+    expect(Mudis.read("b")).not_to be_nil
+  end
+end

data/spec/guardrails_spec.rb

@@ -1,138 +1,138 @@
-# frozen_string_literal: true
-
-require "spec_helper"
-require "climate_control"
-
-RSpec.describe "Mudis TTL Guardrail" do # rubocop:disable Metrics/BlockLength
-  before do
-    Mudis.reset!
-    Mudis.configure do |c|
-      c.max_ttl = 60 # 60 seconds max
-    end
-  end
-
-  describe "default_ttl configuration" do # rubocop:disable Metrics/BlockLength
-    before do
-      Mudis.reset!
-      Mudis.configure do |c|
-        c.default_ttl = 60
-      end
-    end
-
-    it "applies default_ttl when expires_in is nil" do
-      Mudis.write("foo", "bar") # no explicit expires_in
-      meta = Mudis.inspect("foo")
-      expect(meta[:expires_at]).not_to be_nil
-      expect(meta[:expires_at]).to be_within(5).of(Time.now + 60)
-    end
-
-    it "respects expires_in if explicitly given" do
-      Mudis.write("short_lived", "bar", expires_in: 10)
-      meta = Mudis.inspect("short_lived")
-      expect(meta[:expires_at]).not_to be_nil
-      expect(meta[:expires_at]).to be_within(5).of(Time.now + 10)
-    end
-
-    it "applies max_ttl over default_ttl if both are set" do
-      Mudis.configure do |c|
-        c.default_ttl = 120
-        c.max_ttl = 30
-      end
-
-      Mudis.write("capped", "baz") # no explicit expires_in
-      meta = Mudis.inspect("capped")
-      expect(meta[:expires_at]).not_to be_nil
-      expect(meta[:expires_at]).to be_within(5).of(Time.now + 30)
-    end
-
-    it "stores forever if default_ttl and expires_in are nil" do
-      Mudis.configure do |c|
-        c.default_ttl = nil
-      end
-
-      Mudis.write("forever", "ever")
-      meta = Mudis.inspect("forever")
-      expect(meta[:expires_at]).to be_nil
-    end
-  end
-
-  it "clamps expires_in to max_ttl if it exceeds max_ttl" do
-    Mudis.write("foo", "bar", expires_in: 300) # user requests 5 minutes
-
-    metadata = Mudis.inspect("foo")
-    ttl = metadata[:expires_at] - metadata[:created_at]
-
-    expect(ttl).to be <= 60
-    expect(ttl).to be > 0
-  end
-
-  it "respects expires_in if below max_ttl" do
-    Mudis.write("bar", "baz", expires_in: 30) # under the max_ttl
-
-    metadata = Mudis.inspect("bar")
-    ttl = metadata[:expires_at] - metadata[:created_at]
-
-    expect(ttl).to be_within(1).of(30)
-  end
-
-  it "allows nil expires_in (no expiry) if not required" do
-    Mudis.write("baz", "no expiry")
-
-    metadata = Mudis.inspect("baz")
-    expect(metadata[:expires_at]).to be_nil
-  end
-end
-
-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
+# frozen_string_literal: true
+
+require "spec_helper"
+require "climate_control"
+
+RSpec.describe "Mudis TTL Guardrail" do # rubocop:disable Metrics/BlockLength
+  before do
+    Mudis.reset!
+    Mudis.configure do |c|
+      c.max_ttl = 60 # 60 seconds max
+    end
+  end
+
+  describe "default_ttl configuration" do # rubocop:disable Metrics/BlockLength
+    before do
+      Mudis.reset!
+      Mudis.configure do |c|
+        c.default_ttl = 60
+      end
+    end
+
+    it "applies default_ttl when expires_in is nil" do
+      Mudis.write("foo", "bar") # no explicit expires_in
+      meta = Mudis.inspect("foo")
+      expect(meta[:expires_at]).not_to be_nil
+      expect(meta[:expires_at]).to be_within(5).of(Time.now + 60)
+    end
+
+    it "respects expires_in if explicitly given" do
+      Mudis.write("short_lived", "bar", expires_in: 10)
+      meta = Mudis.inspect("short_lived")
+      expect(meta[:expires_at]).not_to be_nil
+      expect(meta[:expires_at]).to be_within(5).of(Time.now + 10)
+    end
+
+    it "applies max_ttl over default_ttl if both are set" do
+      Mudis.configure do |c|
+        c.default_ttl = 120
+        c.max_ttl = 30
+      end
+
+      Mudis.write("capped", "baz") # no explicit expires_in
+      meta = Mudis.inspect("capped")
+      expect(meta[:expires_at]).not_to be_nil
+      expect(meta[:expires_at]).to be_within(5).of(Time.now + 30)
+    end
+
+    it "stores forever if default_ttl and expires_in are nil" do
+      Mudis.configure do |c|
+        c.default_ttl = nil
+      end
+
+      Mudis.write("forever", "ever")
+      meta = Mudis.inspect("forever")
+      expect(meta[:expires_at]).to be_nil
+    end
+  end
+
+  it "clamps expires_in to max_ttl if it exceeds max_ttl" do
+    Mudis.write("foo", "bar", expires_in: 300) # user requests 5 minutes
+
+    metadata = Mudis.inspect("foo")
+    ttl = metadata[:expires_at] - metadata[:created_at]
+
+    expect(ttl).to be <= 60
+    expect(ttl).to be > 0
+  end
+
+  it "respects expires_in if below max_ttl" do
+    Mudis.write("bar", "baz", expires_in: 30) # under the max_ttl
+
+    metadata = Mudis.inspect("bar")
+    ttl = metadata[:expires_at] - metadata[:created_at]
+
+    expect(ttl).to be_within(1).of(30)
+  end
+
+  it "allows nil expires_in (no expiry) if not required" do
+    Mudis.write("baz", "no expiry")
+
+    metadata = Mudis.inspect("baz")
+    expect(metadata[:expires_at]).to be_nil
+  end
+end
+
+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

data/spec/memory_guard_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Mudis Memory Guardrails" do
+  before do
+    Mudis.reset!
+    Mudis.stop_expiry_thread
+    Mudis.instance_variable_set(:@buckets, 1)
+    Mudis.instance_variable_set(:@stores, [{}])
+    Mudis.instance_variable_set(:@mutexes, [Mutex.new])
+    Mudis.instance_variable_set(:@lru_heads, [nil])
+    Mudis.instance_variable_set(:@lru_tails, [nil])
+    Mudis.instance_variable_set(:@lru_nodes, [{}])
+    Mudis.instance_variable_set(:@current_bytes, [0])
+
+    Mudis.max_value_bytes = nil
+    Mudis.instance_variable_set(:@threshold_bytes, 1_000_000)
+    Mudis.hard_memory_limit = true
+    Mudis.instance_variable_set(:@max_bytes, 100)
+  end
+
+  it "rejects writes that exceed max memory" do
+    big_value = "a" * 90
+    Mudis.write("a", big_value)
+    expect(Mudis.read("a")).to eq(big_value)
+
+    big_value2 = "b" * 90
+    Mudis.write("b", big_value2)
+    expect(Mudis.read("b")).to be_nil
+    expect(Mudis.metrics[:rejected]).to be > 0
+  end
+end