cache_stache 0.1.0

data/spec/integration/full_cache_flow_spec.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "../cache_stache_helper"
+
+RSpec.describe "Full Cache Flow" do
+  include ActiveSupport::Testing::TimeHelpers
+
+  include_context "with instrumentation and search"
+
+  after do
+    travel_back if respond_to?(:travel_back)
+  end
+
+  describe "complete workflow" do
+    it "tracks cache operations end-to-end" do
+      # Generate cache misses (first fetch)
+      10.times { |i| Rails.cache.fetch("views/product_#{i}") { "Product #{i}" } }
+
+      # Generate cache hits (repeat fetch)
+      5.times { Rails.cache.fetch("views/product_1") { "Product 1" } }
+
+      # Generate model cache operations
+      3.times { |i| Rails.cache.fetch("community/#{i}") { "Community #{i}" } }
+
+      # Generate operations matching multiple keyspaces
+      Rails.cache.fetch("views/community_search") { "Search results" }
+
+      sleep 0.2 # Allow instrumentation to process
+
+      # Query statistics
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      # Verify overall stats
+      expect(results[:overall][:total_operations]).to be >= 18 # 10 + 5 + 3
+      expect(results[:overall][:hits]).to be >= 5
+      expect(results[:overall][:misses]).to be >= 13
+
+      # Verify view keyspace stats
+      expect(results[:keyspaces][:views][:total_operations]).to be >= 16 # 10 + 5 + 1
+      expect(results[:keyspaces][:views][:hits]).to be >= 5
+
+      # Verify model keyspace stats
+      expect(results[:keyspaces][:models][:total_operations]).to be >= 4 # 3 + 1
+
+      # Verify search keyspace stats
+      expect(results[:keyspaces][:search][:total_operations]).to be >= 1
+    end
+
+    it "calculates accurate hit rates" do
+      # Generate known pattern: 10 misses, 5 hits
+      10.times { |i| Rails.cache.fetch("views/item_#{i}") { "Item #{i}" } }
+      5.times { Rails.cache.fetch("views/item_1") { "Item 1" } }
+
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      # Total operations = 15, hits = 5, misses = 10
+      # Hit rate should be ~33%
+      expect(results[:overall][:total_operations]).to eq(15)
+      expect(results[:overall][:hits]).to eq(5)
+      expect(results[:overall][:misses]).to eq(10)
+      expect(results[:overall][:hit_rate_percent]).to be_within(0.1).of(33.33)
+    end
+
+    it "handles mixed cache operations" do
+      # Mix of reads, writes, and fetches
+      Rails.cache.write("test_1", "value")
+      Rails.cache.read("test_1") # hit
+      Rails.cache.read("nonexistent") # miss
+      Rails.cache.fetch("test_2") { "value" } # miss (write + read)
+      Rails.cache.fetch("test_2") { "value" } # hit
+
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      # Only reads are tracked
+      expect(results[:overall][:total_operations]).to be >= 4
+    end
+
+    it "handles keyspaces with overlapping patterns" do
+      # Key matches both views and search keyspaces
+      Rails.cache.fetch("views/search_page") { "content" }
+
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      # Both keyspaces should record the operation
+      expect(results[:keyspaces][:views][:total_operations]).to eq(1)
+      expect(results[:keyspaces][:search][:total_operations]).to eq(1)
+
+      # Overall should still count it once
+      expect(results[:overall][:total_operations]).to eq(1)
+    end
+  end
+
+  describe "edge cases" do
+    it "handles cache keys with special characters" do
+      special_keys = [
+        "views/product:123",
+        "views/category/sub-category",
+        "views/item.json",
+        "views/search?query=test"
+      ]
+
+      special_keys.each { |key| Rails.cache.fetch(key) { "value" } }
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      expect(results[:keyspaces][:views][:total_operations]).to eq(special_keys.size)
+    end
+
+    it "handles very high operation volumes" do
+      100.times { |i| Rails.cache.fetch("views/item_#{i}") { "value" } }
+      sleep 0.3
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      expect(results[:overall][:total_operations]).to eq(100)
+    end
+
+    it "handles cache operations with nil values" do
+      Rails.cache.write("nil_value", nil)
+      Rails.cache.read("nil_value") # This is a hit
+
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      expect(results[:overall][:hits]).to be >= 1
+    end
+  end
+
+  describe "realistic usage scenarios" do
+    it "simulates a typical request pattern" do
+      # Simulate multiple requests hitting various cache keys
+
+      # Request 1: Homepage (all hits after first)
+      Rails.cache.fetch("views/homepage") { "content" }
+      3.times { Rails.cache.fetch("views/homepage") { "content" } }
+
+      # Request 2: Product listings (some hits, some misses)
+      Rails.cache.fetch("views/products/list") { "list" }
+      Rails.cache.fetch("views/products/list") { "list" }
+
+      # Request 3: Community data (misses)
+      5.times { |i| Rails.cache.fetch("community/#{i}/stats") { "stats" } }
+
+      # Request 4: Search results (misses)
+      Rails.cache.fetch("search/results?q=test") { "results" }
+
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results = query.execute
+
+      # Verify realistic metrics
+      expect(results[:overall][:total_operations]).to be >= 12
+      expect(results[:overall][:hit_rate_percent]).to be > 0
+      expect(results[:overall][:hit_rate_percent]).to be < 100
+
+      # Verify keyspace breakdown
+      expect(results[:keyspaces][:views][:total_operations]).to be >= 6
+      expect(results[:keyspaces][:models][:total_operations]).to be >= 5
+      expect(results[:keyspaces][:search][:total_operations]).to be >= 1
+    end
+
+    it "simulates gradual cache warming" do
+      # First pass: all misses (cold cache)
+      10.times { |i| Rails.cache.fetch("warming_item_#{i}") { "value" } }
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results_after_cold = query.execute
+      cold_misses = results_after_cold[:overall][:misses]
+      expect(cold_misses).to eq(10)
+
+      # Second pass: all hits (warm cache)
+      10.times { |i| Rails.cache.fetch("warming_item_#{i}") { "value" } }
+      sleep 0.2
+
+      query = CacheStache::StatsQuery.new(window: 5.minutes)
+      results_after_warm = query.execute
+
+      # Should now have 10 misses + 10 hits = 20 total, 50% hit rate
+      expect(results_after_warm[:overall][:total_operations]).to eq(20)
+      expect(results_after_warm[:overall][:hits]).to eq(10)
+      expect(results_after_warm[:overall][:misses]).to eq(10)
+      expect(results_after_warm[:overall][:hit_rate_percent]).to eq(50.0)
+    end
+  end
+end

data/spec/integration/instrumentation_spec.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require_relative "../cache_stache_helper"
+
+RSpec.describe CacheStache::Instrumentation do
+  let(:config) do
+    build_test_config(
+      keyspaces: {
+        views: {label: "View Fragments", match: /^views\//},
+        models: {label: "Model Cache", match: /community/}
+      }
+    )
+  end
+
+  before do
+    allow(CacheStache).to receive(:configuration).and_return(config)
+  end
+
+  describe ".install!" do
+    it "installs instrumentation when enabled" do
+      expect(Rails.logger).to receive(:info).with(/Instrumentation installed/)
+      described_class.install!
+
+      expect(described_class.instance_variable_get(:@installed)).to be(true)
+    end
+
+    it "does not install when disabled" do
+      config.enabled = false
+      described_class.install!
+
+      expect(described_class.instance_variable_get(:@installed)).to be_falsey
+    end
+
+    it "does not install twice" do
+      described_class.install!
+      expect(Rails.logger).not_to receive(:info)
+      described_class.install!
+    end
+
+    it "subscribes to cache_read.active_support" do
+      described_class.install!
+
+      listeners = ActiveSupport::Notifications.notifier.listeners_for("cache_read.active_support")
+      expect(listeners).not_to be_empty
+    end
+
+    it "creates a cache client" do
+      described_class.install!
+      cache_client = described_class.instance_variable_get(:@cache_client)
+
+      expect(cache_client).to be_a(CacheStache::CacheClient)
+    end
+
+    it "stores config metadata" do
+      described_class.install!
+
+      raw_metadata = cache_stache_redis.get("cache_stache:v1:test:config")
+      metadata = raw_metadata ? JSON.parse(raw_metadata) : nil
+      expect(metadata).not_to be_nil
+      expect(metadata["bucket_seconds"]).to eq(300)
+    end
+
+    it "captures the monitored store class name" do
+      described_class.install!
+
+      expect(described_class.monitored_store_class).to eq(Rails.cache.class.name)
+    end
+  end
+
+  describe ".call" do
+    before do
+      described_class.install!
+    end
+
+    it "records cache hits" do
+      Rails.cache.write("test_key", "value")
+      Rails.cache.read("test_key")
+
+      sleep 0.1
+
+      expect(current_bucket_stats["overall:hits"].to_f).to be >= 1
+    end
+
+    it "records cache misses" do
+      Rails.cache.read("nonexistent_key")
+
+      sleep 0.1
+
+      expect(current_bucket_stats["overall:misses"].to_f).to be >= 1
+    end
+
+    it "records keyspace hits when key matches" do
+      Rails.cache.write("views/product_123", "value")
+      Rails.cache.read("views/product_123")
+
+      sleep 0.1
+
+      expect(current_bucket_stats["views:hits"].to_f).to be >= 1
+    end
+
+    it "records keyspace misses when key matches" do
+      Rails.cache.read("views/nonexistent")
+
+      sleep 0.1
+
+      expect(current_bucket_stats["views:misses"].to_f).to be >= 1
+    end
+
+    it "records multiple keyspaces when key matches multiple patterns" do
+      Rails.cache.write("views/community_123", "value")
+      Rails.cache.read("views/community_123")
+
+      sleep 0.1
+
+      stats = current_bucket_stats
+      expect(stats["views:hits"].to_f).to be >= 1
+      expect(stats["models:hits"].to_f).to be >= 1
+    end
+
+    it "ignores cache_stache keys to prevent recursion" do
+      Rails.cache.read("cache_stache:v1:test:12345")
+
+      sleep 0.1
+
+      stats = Rails.cache.read(current_bucket_key)
+
+      # Should not record the cache_stache key read
+      expect(stats).to be_nil
+    end
+
+    it "handles payloads with :key field" do
+      payload = {key: "test_key", hit: true, store: Rails.cache.class.name}
+      described_class.call(nil, nil, nil, nil, payload)
+
+      sleep 0.1
+
+      expect(current_bucket_stats["overall:hits"].to_f).to be >= 1
+    end
+
+    it "handles payloads with :name field" do
+      payload = {name: "test_key", hit: false, store: Rails.cache.class.name}
+      described_class.call(nil, nil, nil, nil, payload)
+
+      sleep 0.1
+
+      expect(current_bucket_stats["overall:misses"].to_f).to be >= 1
+    end
+
+    it "ignores payloads without key or name" do
+      payload = {hit: true, store: Rails.cache.class.name}
+      expect { described_class.call(nil, nil, nil, nil, payload) }.not_to raise_error
+
+      stats = Rails.cache.read(current_bucket_key)
+
+      expect(stats).to be_nil
+    end
+
+    it "ignores payloads from different store classes" do
+      payload = {key: "test_key", hit: true, store: "ActiveSupport::Cache::MemoryStore"}
+      # Only ignore if Rails.cache is not a MemoryStore
+      if Rails.cache.class.name != "ActiveSupport::Cache::MemoryStore"
+        described_class.call(nil, nil, nil, nil, payload)
+
+        sleep 0.1
+
+        stats = Rails.cache.read(current_bucket_key)
+
+        expect(stats).to be_nil
+      end
+    end
+
+    it "handles errors gracefully" do
+      allow_any_instance_of(CacheStache::CacheClient).to receive(:increment_stats).and_raise(StandardError, "Test error")
+      allow(Rails.logger).to receive(:error)
+
+      payload = {key: "test_key", hit: true, store: Rails.cache.class.name}
+      expect { described_class.call(nil, nil, nil, nil, payload) }.not_to raise_error
+      expect(Rails.logger).to have_received(:error).with(/instrumentation error/)
+    end
+
+    it "logs error backtraces" do
+      allow_any_instance_of(CacheStache::CacheClient).to receive(:increment_stats).and_raise(StandardError, "Test error")
+      allow(Rails.logger).to receive(:error)
+
+      payload = {key: "test_key", hit: true, store: Rails.cache.class.name}
+      described_class.call(nil, nil, nil, nil, payload)
+
+      # Should log both the error message and the backtrace
+      expect(Rails.logger).to have_received(:error).twice
+    end
+  end
+
+  describe "bucket alignment" do
+    before do
+      described_class.install!
+    end
+
+    it "assigns operations to correct time buckets" do
+      Rails.cache.read("test_bucket_alignment") # miss
+
+      expect(current_bucket_stats["overall:misses"].to_f).to be >= 1
+    end
+
+    it "groups operations within the same bucket" do
+      Rails.cache.read("test_bucket_1") # miss
+      Rails.cache.read("test_bucket_2") # miss
+      Rails.cache.read("test_bucket_3") # miss
+
+      expect(current_bucket_stats["overall:misses"].to_f).to be >= 3
+    end
+  end
+
+  describe "sample_rate" do
+    it "reduces event volume when sample_rate is lower than 1.0" do
+      config.sample_rate = 0.5
+      described_class.install!
+
+      200.times { |i| Rails.cache.read("sample_test_#{i}") }
+
+      sleep 0.1
+
+      recorded_count = (current_bucket_stats["overall:misses"] || 0).to_f
+
+      expect(recorded_count).to be >= 80
+      expect(recorded_count).to be <= 120
+      expect(recorded_count).to be < 200
+    end
+
+    it "records all events when sample_rate is 1.0" do
+      config.sample_rate = 1.0
+      described_class.install!
+
+      50.times { |i| Rails.cache.read("full_sample_test_#{i}") }
+
+      sleep 0.1
+
+      recorded_count = (current_bucket_stats["overall:misses"] || 0).to_f
+
+      expect(recorded_count).to eq(50)
+    end
+
+    it "applies sampling consistently across keyspaces" do
+      config.sample_rate = 0.5
+      described_class.install!
+
+      200.times { |i| Rails.cache.read("views/sample_test_#{i}") }
+
+      sleep 0.1
+
+      stats = current_bucket_stats
+      overall_count = (stats["overall:misses"] || 0).to_f
+      keyspace_count = (stats["views:misses"] || 0).to_f
+
+      expect(overall_count).to be >= 80
+      expect(overall_count).to be <= 120
+      expect(keyspace_count).to eq(overall_count)
+    end
+  end
+end

data/spec/integration/rack_after_reply_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rack/mock"
+require "active_support/testing/time_helpers"
+require_relative "../cache_stache_helper"
+
+RSpec.describe "CacheStache rack.after_reply" do
+  include ActiveSupport::Testing::TimeHelpers
+
+  let(:config) { build_test_config(use_rack_after_reply: true) }
+
+  before do
+    allow(CacheStache).to receive(:configuration).and_return(config)
+    CacheStache::Instrumentation.install!
+  end
+
+  after do
+    travel_back if respond_to?(:travel_back)
+  end
+
+  it "records cache stats via a single after_reply proc" do
+    travel_to Time.utc(2020, 1, 1, 0, 0, 0) do
+      inner = lambda do |_env|
+        Rails.cache.write("test_key", "value")
+        Rails.cache.read("test_key") # hit
+        Rails.cache.read("missing_key") # miss
+        [200, {"Content-Type" => "text/plain"}, ["ok"]]
+      end
+
+      app = CacheStache::RackAfterReplyMiddleware.new(inner)
+
+      env = Rack::MockRequest.env_for("/", "rack.after_reply" => [])
+      status, = app.call(env)
+      expect(status).to eq(200)
+
+      expect(env["rack.after_reply"].size).to eq(1)
+
+      expect(cache_stache_redis.hgetall(current_bucket_key)).to be_empty
+
+      env["rack.after_reply"].each(&:call)
+
+      stats = current_bucket_stats
+      expect(stats["overall:hits"].to_f).to be >= 1
+      expect(stats["overall:misses"].to_f).to be >= 1
+    end
+  end
+end

data/spec/integration/rake_tasks_spec.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../spec_helper"
+
+RSpec.describe "CacheStache rake tasks" do
+  it "loads without error and registers tasks" do
+    # Run `rake -P` from the dummy app to verify the railtie loads tasks correctly.
+    # If the railtie's rake task path is wrong, this will fail with LoadError.
+    dummy_app_path = File.expand_path("../dummy_app", __dir__)
+    output = `cd #{dummy_app_path} && bundle exec rake -P 2>&1`
+
+    expect($?.success?).to be(true), "rake -P failed:\n#{output}"
+    expect(output).to include("cache_stache:config")
+    expect(output).to include("cache_stache:prune")
+    expect(output).to include("cache_stache:stats")
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Only run SimpleCov when running CacheStache specs in isolation
+# (not when loaded as part of the main app's test suite)
+if ENV["CACHE_STACHE_COVERAGE"] || !defined?(Rails)
+  require "simplecov"
+
+  SimpleCov.start do
+    enable_coverage :branch
+    command_name "CacheStache"
+
+    # The project root for CacheStache is the lib/cache_stache directory
+    cache_stache_root = File.expand_path("..", __dir__)
+    root cache_stache_root
+    coverage_dir File.join(cache_stache_root, "coverage")
+
+    # Only track files within lib/cache_stache
+    add_filter do |source_file|
+      !source_file.filename.start_with?(cache_stache_root)
+    end
+
+    add_filter "/spec/"
+    add_filter "/bin/"
+    add_filter "/tasks/"
+    add_filter "/generators/"
+
+    add_group "Core", ["cache_stache.rb", "configuration.rb", "keyspace.rb"]
+    add_group "Storage", ["cache_client.rb"]
+    add_group "Instrumentation", ["instrumentation.rb"]
+    add_group "Query", ["stats_query.rb"]
+    add_group "Web", ["engine.rb", "railtie.rb", "web.rb", "app/"]
+
+    # Coverage thresholds disabled for now - just tracking coverage
+    # minimum_coverage line: 80, branch: 60
+    # minimum_coverage_by_file line: 50, branch: 30
+  end
+end
+
+require "bundler/setup"
+
+# Set up Rails environment and load the dummy app (which loads CacheStache)
+ENV["RAILS_ENV"] ||= "test"
+require_relative "dummy_app/config/application"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  # Use consistent ordering for tests
+  config.order = :random
+  Kernel.srand config.seed
+
+  # Clear configuration before each test
+  config.before do
+    CacheStache.instance_variable_set(:@configuration, nil)
+  end
+end