cache_stache 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 601e9576e81fb4405ca36fe64b4a98ffd4d91f4d599fd77c9f96eec3d3547c18
-  data.tar.gz: a726a516a2cfafb77d404df75276fc7ede6f2534f1f43d56dc0209d6bd805f11
+  metadata.gz: d75f242cecde072c5db6fe680a47fcb3b98165a4d12cf46738d64b0c0956c7ef
+  data.tar.gz: 86c3c5b676cb94ea1427cbed332f8fc97b2dac235ce22c031511a8ad1014d8b8
 SHA512:
-  metadata.gz: 902ed8597f65c59c98f5148923246db46fbd5a97a44bda6bf108c589cd647720d37c75ae67b60f840af1abf40872cf7028d2f9905484d9fa7f980fba8cf90645
-  data.tar.gz: 40f535b5e0e95de053886976858cc2bead62cb8b44246a3e4dcd2ce271b7538dafa7ff0f893bee72b364e29b1a2e98524cd67415545f809dfbe8f99b5413b8f5
+  metadata.gz: a4997e8c87c2cb1b974eeac87489b5ad6344adef9dd632d0c1f80429f4aae49edbe76ca4b70557d201a309575f8369a9f361207556c7bb6758630adf6240d174
+  data.tar.gz: 623d1edd5b5a304e7839133d9bc4ae9fc9d8f1d67ec76d893df77c6ff506e6c5322b37c657eac5f42d9cbe617f689def250b4974f150f0a0d668348f00766709

data/README.md

@@ -2,9 +2,9 @@
 
 [![CI](https://github.com/speedshop/cache_stache/actions/workflows/ci.yml/badge.svg)](https://github.com/speedshop/cache_stache/actions/workflows/ci.yml)
 
-CacheStache tracks cache hit rates for Rails apps. It counts how often your cache has data (hits) and how often it does not (misses). You can view these counts on a web page.
+Have you ever had to work with a Redis cache provider which doesn't provide hitrate stats? It's a bummer. Use this gem!
 
-A higher hit rate means your app finds data in the cache more often. This means fewer slow calls to your database or other services. CacheStache helps you see this rate over time and spot problems.
+CacheStache tracks cache hit rates for Rails apps. It counts how often your cache has data (hits) and how often it does not (misses). You can view these counts on a web page.
 
 ## Features
 
@@ -42,7 +42,7 @@ A higher hit rate means your app finds data in the cache more often. This means
 
 4. Restart Rails and go to `/cache-stache`.
 
-### Add a Password (Optional)
+### Add Authentication
 
 You can add a password to the web page:
 
@@ -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,12 +99,12 @@ 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 |
 | `max_buckets` | 288 | Maximum number of buckets to query |
-| `sample_rate` | 1.0 | Not yet active |
+| `sample_rate` | 1.0 | Sample events |
 | `enabled` | true | Turn tracking on or off |
 | `use_rack_after_reply` | false | Wait to write until after response |
 
@@ -126,37 +126,6 @@ end
 
 A cache key can match more than one keyspace.
 
-## Web Page
-
-The web page shows:
-
-- Total hit rate
-- Hit rate for each keyspace
-- Current settings
-- Size of stored data
-
-Time windows: 5m, 15m, 1h (default), 6h, 1d, 1w.
-
-Click a keyspace name to see more detail.
-
-## How It Works
-
-```
-Rails.cache.fetch(...)
-  -> Rails sends an event
-  -> CacheStache counts it
-  -> CacheStache stores the count
-  -> Web page shows the counts
-```
-
-1. **Counting**: CacheStache listens for cache events. It skips its own cache calls.
-
-2. **Buckets**: Times are rounded down to `bucket_seconds`. Each event adds to hit or miss counts.
-
-3. **Storage**: Counts are stored with keys like `cache_stache:v1:production:1234567890`. Each bucket expires after `retention_seconds`.
-
-4. **Reading**: The web page reads all buckets and adds them up.
-
 ## Query Stats in Code
 
 You can get stats from Ruby code:
@@ -171,61 +140,7 @@ results[:overall][:misses]            # => 210
 results[:keyspaces][:profiles][:hit_rate_percent]  # => 92.1
 ```
 
-## Test Data
-
-Make fake data with:
-
-```bash
-rails runner lib/cache_stache/bin/test_day_simulation.rb
-```
-
-This makes 24 hours of fake cache events. Then go to `/cache-stache` to see it.
-
 ## Limits
 
-- The `sample_rate` setting does nothing yet.
 - Only cache reads are tracked. Writes and deletes are not.
-- If you have two cache stores of the same type, their events will be mixed.
-
-## Files
-
-```
-lib/cache_stache/
-├── app/               # Web page views and code
-├── bin/               # Test scripts
-├── config/            # Routes
-├── lib/               # Gem/engine Ruby code
-│   ├── cache_stache.rb
-│   ├── cache_stache/
-│   └── generators/
-├── Gemfile            # Standalone bundler entrypoint
-├── cache_stache.gemspec
-├── Rakefile
-├── spec/              # Tests
-├── tasks/             # Rake tasks
-```
-
-## Running Specs (Standalone)
-
-CacheStache can be tested independently from the host Rails app:
-
-```bash
-cd lib/cache_stache
-bundle install
-bundle exec rspec
-```
-
-From the host app root, you can also run the engine suite without `cd`:
-
-```bash
-BUNDLE_GEMFILE=lib/cache_stache/Gemfile bundle exec rspec --options lib/cache_stache/.rspec lib/cache_stache/spec
-```
-
-## Run Tests
-
-```bash
-cd lib/cache_stache
-bundle exec rspec
-```
-
-Tests are in `lib/cache_stache/spec/`. They do not need Redis.
+- If you have two cache stores of the same type (redis, memcached, etc), their events will be mixed.

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
 

data/lib/cache_stache/configuration.rb

@@ -5,8 +5,10 @@ require "active_support/core_ext/numeric/time"
 
 module CacheStache
   class Configuration
+    DEFAULT_REDIS_OPTIONS = {reconnect_attempts: 0}.freeze
+
     attr_accessor :bucket_seconds, :retention_seconds, :sample_rate, :enabled,
-      :redis_url, :redis_pool_size, :use_rack_after_reply, :max_buckets
+      :redis, :redis_pool_size, :use_rack_after_reply, :max_buckets
     attr_reader :keyspaces
 
     def initialize
@@ -15,13 +17,33 @@ module CacheStache
       @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 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 +65,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 +87,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.0"
+  VERSION = "0.2.0"
 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,11 +50,12 @@ 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)
       c.use_rack_after_reply = options.fetch(:use_rack_after_reply, false)
+      c.enabled = options.fetch(:enabled, true)
 
       keyspaces.each do |name, keyspace_config|
         c.keyspace(name) do
@@ -86,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/configuration_spec.rb

@@ -11,6 +11,7 @@ RSpec.describe CacheStache::Configuration do
     before do
       allow(ENV).to receive(:fetch).and_call_original
       allow(ENV).to receive(:fetch).with("CACHE_STACHE_REDIS_URL").and_return(default_redis_url)
+      allow(ENV).to receive(:fetch).with("RAILS_ENV", "development").and_return("development")
     end
 
     it { expect(config.bucket_seconds).to eq(5.minutes.to_i) }
@@ -18,11 +19,38 @@ 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 "#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
@@ -134,12 +162,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 "rejects empty string for redis" do
+      config.redis = "   "
+      expect { config.validate! }.to raise_error(CacheStache::Error, /redis must be a Proc, String/)
     end
 
-    it "requires redis_url" do
-      config.redis_url = nil
-      expect { config.validate! }.to raise_error(CacheStache::Error, /redis_url must be configured/)
+    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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - CacheStache contributors
@@ -13,14 +13,14 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
 - !ruby/object:Gem::Dependency