cache_stache 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d78eea9e2e19c6f95024644eaea2dc942993225c42ca636473e19e46fd6f449
-  data.tar.gz: 6156b5fe4adc1756b1ebf1fe92e413ab16bba3589557e26d17efe3ef2fa18dbf
+  metadata.gz: 3b3e76904376faf81f690f9b8fd24d63c368295e9c133304b3c16bf0f6e48c6d
+  data.tar.gz: 3b23acace11232c359d8d9185946fcb595315ce89e4eacd5b9386de8290e9e71
 SHA512:
-  metadata.gz: b976afa17c53451ea8b6aa57e6d15d88f097f9fd72bc8bd420b91911f06af686f7f7693eee76f9981fd1644b3abd3694c942c6a1e28e764ec97b4148a8062f47
-  data.tar.gz: d31764e21a67a0b2006a59593f1b4757f95a731817d3c8cf0d6af802bef0e7afcbc9e5d0b30f1069d77b6606b60a1f62b6f24315ee9fafb8b77e20a6c71a2ff1
+  metadata.gz: 0ed34798119cada11fbbf64f51a61a291e725288dba4fd4bc82353a1feca9adfbf3f654c1070c7664b3e4397f0d2f48cb6ca504cb4963d2a62d7af639fd68c16
+  data.tar.gz: 49d081eec0e40ae8d2dddb6159aef9b5524d369770d7826981b0e6a2da2c3cae90c50e6ae34ce7b263f76487ea6aa59a51d55a788c2884caa4f7a35108a685ef

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1]
+
+### Fixed
+
+- Fixed Redis calls when `bucket_seconds` or `retention_seconds` are configured with `ActiveSupport::Duration` values
+
+## [0.2.0]
+
+### Changed
+
+- **Breaking:** Replaced `redis_url` config option with `redis`, which accepts a Proc, String URL, or Redis-compatible object
+
+## [0.1.1]
+
+- Fixed Rails dependency to be >=, not ~>
+
+## [0.1.0]
+
+### Added
+
+- Initial release
+- Cache hit/miss rate tracking via Rails instrumentation
+- Redis-backed statistics storage
+- Dashboard UI for viewing cache metrics
+- Keyspace breakdown view
+- Configurable time windows (minute, hour, day)
+- Rake tasks for cache statistics

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nate Berkopec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -63,9 +63,9 @@ All settings go in `config/initializers/cache_stache.rb`:
 
 ```ruby
 CacheStache.configure do |config|
-  # Redis connection for storing cache metrics
-  # Falls back to ENV["REDIS_URL"] if not set
-  config.redis_url = ENV.fetch("CACHE_STACHE_REDIS_URL", ENV["REDIS_URL"])
+  # Redis connection for storing cache metrics.
+  # Can be a String (URL), Proc, or Redis-compatible object.
+  config.redis = ENV.fetch("CACHE_STACHE_REDIS_URL", ENV["REDIS_URL"])
 
   # Time bucket size
   config.bucket_seconds = 5.minutes
@@ -99,7 +99,7 @@ end
 
 | Setting | Default | What it does |
 |---------|---------|--------------|
-| `redis_url` | `ENV["CACHE_STACHE_REDIS_URL"]` or `ENV["REDIS_URL"]` | Redis connection URL |
+| `redis` | `ENV["CACHE_STACHE_REDIS_URL"]` or `ENV["REDIS_URL"]` | Redis connection (String URL, Proc, or Redis object) |
 | `redis_pool_size` | 5 | Size of the Redis connection pool |
 | `bucket_seconds` | 5 minutes | Size of each time bucket |
 | `retention_seconds` | 7 days | How long to keep data |

data/lib/cache_stache/cache_client.rb

@@ -26,7 +26,7 @@ module CacheStache
     def initialize(config = CacheStache.configuration)
       @config = config
       @pool = ConnectionPool.new(size: @config.redis_pool_size) do
-        Redis.new(url: @config.redis_url)
+        @config.build_redis
       end
     end
 
@@ -39,7 +39,7 @@ module CacheStache
           redis.eval(
             INCR_AND_EXPIRE_SCRIPT,
             keys: [key],
-            argv: [@config.retention_seconds, increments.to_json]
+            argv: [retention_seconds, increments.to_json]
           )
         end
       end
@@ -79,16 +79,16 @@ module CacheStache
     def store_config_metadata
       key = "cache_stache:v1:#{@config.rails_env}:config"
       metadata = {
-        bucket_seconds: @config.bucket_seconds,
-        retention_seconds: @config.retention_seconds,
+        bucket_seconds: @config.bucket_seconds.to_i,
+        retention_seconds: retention_seconds,
         updated_at: Time.current.to_i
       }
 
       without_instrumentation do
         @pool.with do |redis|
           # Use SETEX for atomic set-with-expiry (single command)
-          Rails.logger.debug { "CacheStache: Redis SETEX #{key} #{@config.retention_seconds}" }
-          redis.setex(key, @config.retention_seconds, metadata.to_json)
+          Rails.logger.debug { "CacheStache: Redis SETEX #{key} #{retention_seconds}" }
+          redis.setex(key, retention_seconds, metadata.to_json)
         end
       end
     rescue => e
@@ -164,6 +164,10 @@ module CacheStache
       end
     end
 
+    def retention_seconds
+      @config.retention_seconds.to_i
+    end
+
     def bucket_key(timestamp)
       "cache_stache:v1:#{@config.rails_env}:#{timestamp}"
     end

data/lib/cache_stache/configuration.rb

@@ -5,23 +5,53 @@ require "active_support/core_ext/numeric/time"
 
 module CacheStache
   class Configuration
-    attr_accessor :bucket_seconds, :retention_seconds, :sample_rate, :enabled,
-      :redis_url, :redis_pool_size, :use_rack_after_reply, :max_buckets
-    attr_reader :keyspaces
+    DEFAULT_REDIS_OPTIONS = {reconnect_attempts: 0}.freeze
+
+    attr_accessor :sample_rate, :enabled, :redis, :redis_pool_size,
+      :use_rack_after_reply, :max_buckets
+    attr_reader :bucket_seconds, :retention_seconds, :keyspaces
 
     def initialize
-      @bucket_seconds = 5.minutes.to_i
-      @retention_seconds = 7.days.to_i
+      self.bucket_seconds = 5.minutes
+      self.retention_seconds = 7.days
       @sample_rate = 1.0
       @enabled = rails_env != "test"
       @use_rack_after_reply = false
-      @redis_url = ENV.fetch("CACHE_STACHE_REDIS_URL") { ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
+      @redis = ENV.fetch("CACHE_STACHE_REDIS_URL") { ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
       @redis_pool_size = 5
       @max_buckets = 288
       @keyspaces = []
       @keyspace_cache = {}
     end
 
+    # Factory method to create a new Redis instance.
+    #
+    # Handles three options:
+    #
+    #   Option  Class       Result
+    #   :redis  Proc    ->  redis.call
+    #   :redis  String  ->  Redis.new(url: redis)
+    #   :redis  Object  ->  redis (assumed to be a Redis-compatible client)
+    #
+    def bucket_seconds=(value)
+      @bucket_seconds = value.to_i
+    end
+
+    def retention_seconds=(value)
+      @retention_seconds = value.to_i
+    end
+
+    def build_redis
+      case redis
+      when Proc
+        redis.call
+      when String
+        ::Redis.new(DEFAULT_REDIS_OPTIONS.merge(url: redis))
+      else
+        redis
+      end
+    end
+
     def keyspace(name, &block)
       ks = Keyspace.new(name)
       builder = KeyspaceBuilder.new(ks)
@@ -43,8 +73,9 @@ module CacheStache
     def validate!
       raise Error, "bucket_seconds must be positive" unless bucket_seconds.to_i.positive?
       raise Error, "retention_seconds must be positive" unless retention_seconds.to_i.positive?
+      raise Error, "redis must be configured" if redis.nil?
+      raise Error, "redis must be a Proc, String (URL), or Redis-compatible object" unless valid_redis_option?
       raise Error, "redis_pool_size must be positive" unless redis_pool_size.to_i.positive?
-      raise Error, "redis_url must be configured" if redis_url.to_s.strip.empty?
       raise Error, "sample_rate must be between 0 and 1" unless sample_rate&.between?(0, 1)
       raise Error, "max_buckets must be positive" unless max_buckets.to_i.positive?
 
@@ -64,6 +95,12 @@ module CacheStache
 
     private
 
+    def valid_redis_option?
+      return true if redis.is_a?(Proc)
+      return redis.to_s.strip.length > 0 if redis.is_a?(String)
+      true # Assume other objects are Redis-compatible clients
+    end
+
     def key_digest(key)
       # Use last 4 chars of a simple hash as cache key
       Digest::MD5.hexdigest(key.to_s)[-4..]

data/lib/cache_stache/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CacheStache
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

data/lib/generators/cache_stache/templates/cache_stache.rb

@@ -4,9 +4,15 @@
 # This file configures the CacheStache cache hit rate monitoring system.
 
 CacheStache.configure do |config|
-  # Redis connection for storing cache metrics
-  # Falls back to ENV["REDIS_URL"] if not set
-  config.redis_url = ENV.fetch("CACHE_STACHE_REDIS_URL", ENV["REDIS_URL"])
+  # Redis connection for storing cache metrics.
+  # Can be a String (URL), Proc, or Redis-compatible object.
+  #
+  # Examples:
+  #   config.redis = "redis://localhost:6379/0"
+  #   config.redis = -> { Redis.new(url: ENV["REDIS_URL"]) }
+  #   config.redis = ConnectionPool.new { Redis.new }
+  #
+  config.redis = ENV.fetch("CACHE_STACHE_REDIS_URL", ENV["REDIS_URL"])
 
   # Size of time buckets for aggregation (default: 5 minutes)
   config.bucket_seconds = 5.minutes

data/spec/cache_stache_helper.rb

@@ -50,7 +50,7 @@ module CacheStacheTestHelpers
   # Build a test configuration with common defaults
   def build_test_config(keyspaces: {}, **options)
     CacheStache::Configuration.new.tap do |c|
-      c.redis_url = CACHE_STACHE_TEST_REDIS_URL
+      c.redis = CACHE_STACHE_TEST_REDIS_URL
       c.bucket_seconds = options.fetch(:bucket_seconds, 300)
       c.retention_seconds = options.fetch(:retention_seconds, 3600)
       c.sample_rate = options.fetch(:sample_rate, 1.0)
@@ -87,7 +87,7 @@ RSpec.configure do |config|
   config.before do
     # Configure CacheStache to use test Redis
     CacheStache.configure do |c|
-      c.redis_url = CACHE_STACHE_TEST_REDIS_URL
+      c.redis = CACHE_STACHE_TEST_REDIS_URL
       c.redis_pool_size = 1
       c.enabled = true
     end

data/spec/unit/cache_client_spec.rb

@@ -75,6 +75,17 @@ RSpec.describe CacheStache::CacheClient do
       expect(ttl).to be <= config.retention_seconds
     end
 
+    it "increments stats when retention is configured with ActiveSupport::Duration" do
+      duration_config = build_test_config(retention_seconds: 7.days)
+      duration_client = described_class.new(duration_config)
+
+      duration_client.increment_stats(bucket_ts, increments)
+
+      buckets = duration_client.fetch_buckets(bucket_ts - 100, bucket_ts + 100)
+      expect(buckets.size).to eq(1)
+      expect(buckets.first[:stats]["overall:hits"]).to eq(1.0)
+    end
+
     it "handles errors gracefully" do
       # Create client, then make the pool raise errors
       test_client = described_class.new(config)
@@ -168,6 +179,17 @@ RSpec.describe CacheStache::CacheClient do
       expect(metadata["updated_at"]).to be_a(Integer)
     end
 
+    it "stores configuration metadata when durations use ActiveSupport::Duration" do
+      duration_config = build_test_config(bucket_seconds: 5.minutes, retention_seconds: 7.days)
+      duration_client = described_class.new(duration_config)
+
+      duration_client.store_config_metadata
+      metadata = duration_client.fetch_config_metadata
+
+      expect(metadata["bucket_seconds"]).to eq(5.minutes.to_i)
+      expect(metadata["retention_seconds"]).to eq(7.days.to_i)
+    end
+
     it "handles errors gracefully" do
       # Create client, then make the pool raise errors
       test_client = described_class.new(config)

data/spec/unit/configuration_spec.rb

@@ -19,11 +19,52 @@ RSpec.describe CacheStache::Configuration do
     it { expect(config.sample_rate).to eq(1.0) }
     it { expect(config.enabled).to be(true) }
     it { expect(config.use_rack_after_reply).to be(false) }
-    it { expect(config.redis_url).to eq(default_redis_url) }
+    it { expect(config.redis).to eq(default_redis_url) }
     it { expect(config.redis_pool_size).to eq(5) }
     it { expect(config.keyspaces).to eq([]) }
   end
 
+  describe "duration settings" do
+    it "coerces bucket_seconds to integer seconds" do
+      config.bucket_seconds = 5.minutes
+
+      expect(config.bucket_seconds).to eq(300)
+    end
+
+    it "coerces retention_seconds to integer seconds" do
+      config.retention_seconds = 7.days
+
+      expect(config.retention_seconds).to eq(604_800)
+    end
+  end
+
+  describe "#build_redis" do
+    it "calls the proc when redis is a Proc" do
+      redis_instance = instance_double(Redis)
+      config.redis = -> { redis_instance }
+
+      expect(config.build_redis).to eq(redis_instance)
+    end
+
+    it "creates a Redis instance when redis is a String URL" do
+      config.redis = "redis://localhost:6379/1"
+
+      expect(Redis).to receive(:new).with(
+        hash_including(url: "redis://localhost:6379/1")
+      ).and_call_original
+
+      result = config.build_redis
+      expect(result).to be_a(Redis)
+    end
+
+    it "returns the object directly when redis is an Object" do
+      redis_instance = instance_double(Redis)
+      config.redis = redis_instance
+
+      expect(config.build_redis).to eq(redis_instance)
+    end
+  end
+
   describe "#keyspace" do
     it "adds a keyspace with the given name" do
       config.keyspace(:views) do
@@ -135,12 +176,27 @@ RSpec.describe CacheStache::Configuration do
 
   describe "#validate!" do
     before do
-      config.redis_url = "redis://localhost:6379/0"
+      config.redis = "redis://localhost:6379/0"
+    end
+
+    it "requires redis" do
+      config.redis = nil
+      expect { config.validate! }.to raise_error(CacheStache::Error, /redis must be configured/)
     end
 
-    it "requires redis_url" do
-      config.redis_url = nil
-      expect { config.validate! }.to raise_error(CacheStache::Error, /redis_url must be configured/)
+    it "rejects empty string for redis" do
+      config.redis = "   "
+      expect { config.validate! }.to raise_error(CacheStache::Error, /redis must be a Proc, String/)
+    end
+
+    it "accepts a Proc for redis" do
+      config.redis = -> { Redis.new }
+      expect { config.validate! }.not_to raise_error
+    end
+
+    it "accepts an Object for redis" do
+      config.redis = instance_double(Redis)
+      expect { config.validate! }.not_to raise_error
     end
 
     it "requires redis_pool_size to be positive" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cache_stache
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - CacheStache contributors
@@ -155,6 +155,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
 - README.md
 - app/assets/stylesheets/cache_stache/application.css
 - app/assets/stylesheets/cache_stache/pico.css