cache_stache 0.1.0

data/lib/cache_stache/stats_query.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+
+module CacheStache
+  class StatsQuery
+    attr_reader :window, :resolution
+
+    def initialize(window: 1.hour, resolution: nil)
+      @window = window.to_i
+      @resolution = resolution
+      @config = CacheStache.configuration
+      @cache_client = CacheClient.new(@config)
+    end
+
+    def execute
+      to_ts = Time.current.to_i
+      from_ts = to_ts - window
+
+      buckets = @cache_client.fetch_buckets(from_ts, to_ts)
+
+      {
+        overall: calculate_overall_stats(buckets),
+        keyspaces: calculate_keyspace_stats(buckets),
+        buckets: buckets.map { |b| format_bucket(b) },
+        window_seconds: window,
+        bucket_count: buckets.size
+      }
+    end
+
+    private
+
+    def calculate_overall_stats(buckets)
+      total_hits = 0.0
+      total_misses = 0.0
+
+      buckets.each do |bucket|
+        total_hits += bucket[:stats]["overall:hits"].to_f
+        total_misses += bucket[:stats]["overall:misses"].to_f
+      end
+
+      total_ops = total_hits + total_misses
+      hit_rate = total_ops.positive? ? (total_hits / total_ops * 100).round(2) : 0.0
+
+      {
+        hits: total_hits.round,
+        misses: total_misses.round,
+        total_operations: total_ops.round,
+        hit_rate_percent: hit_rate
+      }
+    end
+
+    def calculate_keyspace_stats(buckets)
+      keyspace_data = {}
+
+      @config.keyspaces.each do |keyspace|
+        total_hits = 0.0
+        total_misses = 0.0
+
+        buckets.each do |bucket|
+          total_hits += bucket[:stats]["#{keyspace.name}:hits"].to_f
+          total_misses += bucket[:stats]["#{keyspace.name}:misses"].to_f
+        end
+
+        total_ops = total_hits + total_misses
+        hit_rate = total_ops.positive? ? (total_hits / total_ops * 100).round(2) : 0.0
+
+        keyspace_data[keyspace.name] = {
+          label: keyspace.label,
+          pattern: keyspace.pattern,
+          hits: total_hits.round,
+          misses: total_misses.round,
+          total_operations: total_ops.round,
+          hit_rate_percent: hit_rate
+        }
+      end
+
+      keyspace_data
+    end
+
+    def format_bucket(bucket)
+      {
+        timestamp: bucket[:timestamp],
+        time: Time.at(bucket[:timestamp]).utc,
+        stats: bucket[:stats]
+      }
+    end
+  end
+end

data/lib/cache_stache/version.rb

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

data/lib/cache_stache/web.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "engine"
+
+module CacheStache
+  class Web
+    class << self
+      def call(env)
+        ensure_routes_loaded!
+
+        # Build app only once and cache it
+        unless @app
+          # Capture middlewares outside the Rack::Builder context
+          mw = middlewares
+
+          @app = Rack::Builder.new do
+            mw.each { |middleware, args, block| use(middleware, *args, &block) }
+            run CacheStache::Engine
+          end.to_app
+
+          Rails.logger.info "[CacheStache::Web] Rack app built successfully"
+        end
+
+        @app.call(env)
+      end
+
+      def use(middleware, *args, &block)
+        middlewares << [middleware, args, block]
+      end
+
+      def middlewares
+        @middlewares ||= []
+      end
+
+      def reset_middlewares!
+        @middlewares = []
+        @app = nil
+      end
+
+      def reset_routes!
+        @routes_loaded = false
+        @app = nil
+      end
+
+      private
+
+      def ensure_routes_loaded!
+        return if @routes_loaded
+
+        routes_path = File.expand_path("../../config/routes.rb", __dir__)
+        load_engine_components
+        load routes_path
+        @routes_loaded = true
+      end
+
+      def load_engine_components
+        base_path = File.expand_path("../../app", __dir__)
+
+        Dir["#{base_path}/helpers/**/*.rb"].sort.each do |file|
+          load file
+        end
+
+        Dir["#{base_path}/controllers/**/*.rb"].sort.each do |file|
+          load file
+        end
+      end
+    end
+  end
+end

data/lib/cache_stache/window_options.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CacheStache
+  module WindowOptions
+    WINDOWS = [
+      {param: "5m", aliases: ["5_minutes"], label: "5 minutes", duration: 5.minutes},
+      {param: "15m", aliases: ["15_minutes"], label: "15 minutes", duration: 15.minutes},
+      {param: "1h", aliases: ["1_hour"], label: "1 hour", duration: 1.hour, default: true},
+      {param: "6h", aliases: ["6_hours"], label: "6 hours", duration: 6.hours},
+      {param: "1d", aliases: ["1_day", "24h"], label: "1 day", duration: 1.day},
+      {param: "1w", aliases: ["1_week", "7d"], label: "1 week", duration: 1.week}
+    ].freeze
+
+    DEFAULT_WINDOW = WINDOWS.find { |w| w[:default] }
+
+    module_function
+
+    def for_select
+      WINDOWS.map { |w| [w[:label], w[:param]] }
+    end
+
+    def find(param)
+      WINDOWS.find { |w| w[:param] == param || w[:aliases].include?(param) } || DEFAULT_WINDOW
+    end
+
+    def label_for(param)
+      find(param)[:label]
+    end
+
+    def duration_for(param)
+      find(param)[:duration]
+    end
+  end
+end

data/lib/cache_stache.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_support/all"
+
+require_relative "cache_stache/version"
+require_relative "cache_stache/window_options"
+require_relative "cache_stache/configuration"
+require_relative "cache_stache/keyspace"
+require_relative "cache_stache/cache_client"
+require_relative "cache_stache/instrumentation"
+require_relative "cache_stache/stats_query"
+require_relative "cache_stache/rack_after_reply_middleware"
+
+module CacheStache
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration.validate!
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require_relative "cache_stache/railtie"
+require_relative "cache_stache/engine"
+require_relative "cache_stache/web"

data/lib/generators/cache_stache/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module CacheStache
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a CacheStache initializer and mounts the dashboard"
+
+      def copy_initializer
+        template "cache_stache.rb", "config/initializers/cache_stache.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/cache_stache/templates/README

@@ -0,0 +1,35 @@
+===============================================================================
+
+CacheStache has been installed!
+
+Next steps:
+
+1. Review and customize config/initializers/cache_stache.rb
+
+2. Mount the dashboard in your routes.rb:
+
+   # config/routes.rb
+   require "cache_stache/web"
+
+   # Optional: Add authentication
+   CacheStache::Web.use Rack::Auth::Basic do |user, pass|
+     ActiveSupport::SecurityUtils.secure_compare(user, ENV["CACHE_STACHE_USER"]) &&
+       ActiveSupport::SecurityUtils.secure_compare(pass, ENV["CACHE_STACHE_PASS"])
+   end
+
+   mount CacheStache::Web, at: "/cache-stache"
+
+3. Set environment variables (if using auth):
+   CACHE_STACHE_USER=admin
+   CACHE_STACHE_PASS=secret
+
+4. Start your Rails server and visit /cache-stache
+
+5. (Optional) Add keyspaces to track specific cache patterns in the initializer
+
+Rake tasks:
+  rake cache_stache:config  # Show current configuration
+  rake cache_stache:stats   # Show current stats
+  rake cache_stache:prune   # Manually prune old data
+
+===============================================================================

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# CacheStache Configuration
+# 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"])
+
+  # Size of time buckets for aggregation (default: 5 minutes)
+  config.bucket_seconds = 5.minutes
+
+  # How long to retain data (default: 7 days)
+  config.retention_seconds = 7.days
+
+  # Sample rate (0.0 to 1.0). Use < 1.0 for high-traffic apps (default: 1.0)
+  config.sample_rate = 1.0
+
+  # Enable/disable instrumentation (default: true)
+  # Set to false in test environment if desired
+  config.enabled = !Rails.env.test?
+
+  # Defer stats increments until after the response is sent, via Rack's
+  # `env["rack.after_reply"]` (supported by Puma and others).
+  # Default: false
+  config.use_rack_after_reply = false
+
+  # Define keyspaces to track specific cache key patterns
+  # Each keyspace uses a regex to match cache keys
+  #
+  # Example:
+  #
+  # config.keyspace :profiles do
+  #   label "Profile Fragments"
+  #   match /^profile:/
+  # end
+  #
+  # config.keyspace :search do
+  #   label "Search Results"
+  #   match %r{/search/}
+  # end
+end

data/spec/cache_stache_helper.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+require "json"
+
+# Initialize the Rails app (spec_helper loads it but doesn't initialize)
+CacheStacheDummy::Application.initialize! unless CacheStacheDummy::Application.initialized?
+
+# Load RSpec Rails integration (controller specs, etc.)
+require "rspec/rails"
+
+# Ensure the engine is loaded after Rails is initialized
+require "cache_stache/engine"
+load CacheStache::Engine.root.join("config/routes.rb")
+
+# Test Redis configuration - uses database 15 to isolate from other Redis usage
+CACHE_STACHE_TEST_REDIS_URL = ENV.fetch("CACHE_STACHE_TEST_REDIS_URL", "redis://localhost:6379/15")
+
+module CacheStacheTestHelpers
+  # Helper to get the test Redis connection directly
+  def cache_stache_redis
+    @_cache_stache_redis ||= Redis.new(url: CACHE_STACHE_TEST_REDIS_URL)
+  end
+
+  # Helper to get the current bucket key
+  def current_bucket_key(bucket_seconds: 300)
+    bucket_ts = (Time.current.to_i / bucket_seconds) * bucket_seconds
+    "cache_stache:v1:test:#{bucket_ts}"
+  end
+
+  # Helper to get stats from current bucket
+  def current_bucket_stats(bucket_seconds: 300)
+    cache_stache_redis.hgetall(current_bucket_key(bucket_seconds: bucket_seconds))
+  end
+
+  # Helper to clear all CacheStache notification listeners
+  def clear_cache_stache_listeners
+    ActiveSupport::Notifications.notifier.listeners_for("cache_read.active_support").each do |listener|
+      ActiveSupport::Notifications.unsubscribe(listener)
+    end
+  end
+
+  # Helper to flush CacheStache keys from Redis
+  def flush_cache_stache_redis
+    redis = Redis.new(url: CACHE_STACHE_TEST_REDIS_URL)
+    redis.scan_each(match: "cache_stache:*") { |key| redis.del(key) }
+    redis.close
+  end
+
+  # 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.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)
+
+      keyspaces.each do |name, keyspace_config|
+        c.keyspace(name) do
+          label keyspace_config[:label] if keyspace_config[:label]
+          match keyspace_config[:match]
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include CacheStacheTestHelpers
+
+  config.before(:suite) do
+    # Verify Redis is available before running tests
+    redis = Redis.new(url: CACHE_STACHE_TEST_REDIS_URL)
+    begin
+      redis.ping
+    rescue Redis::CannotConnectError => e
+      abort "CacheStache tests require a running Redis server. " \
+            "Please start Redis and try again.\n" \
+            "Connection error: #{e.message}"
+    ensure
+      redis.close
+    end
+  end
+
+  config.before do
+    # Configure CacheStache to use test Redis
+    CacheStache.configure do |c|
+      c.redis_url = CACHE_STACHE_TEST_REDIS_URL
+      c.redis_pool_size = 1
+      c.enabled = true
+    end
+
+    # Create a fresh cache client for each test
+    cache_client = CacheStache::CacheClient.new(CacheStache.configuration)
+    Thread.current[:cache_stache_test_client] = cache_client
+
+    flush_cache_stache_redis
+    Rails.cache.clear
+    clear_cache_stache_listeners
+    CacheStache::Instrumentation.reset!
+  end
+
+  config.after do
+    Thread.current[:cache_stache_test_client] = nil
+    Rails.cache.clear
+
+    if defined?(@_cache_stache_redis) && @_cache_stache_redis
+      @_cache_stache_redis.close
+      @_cache_stache_redis = nil
+    end
+  end
+end
+
+# Shared context for tests that need instrumentation installed
+RSpec.shared_context "with 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)
+    CacheStache::Instrumentation.install!
+  end
+end
+
+# Shared context for tests that need instrumentation with search keyspace
+RSpec.shared_context "with instrumentation and search" do
+  let(:config) do
+    build_test_config(
+      keyspaces: {
+        views: {label: "View Fragments", match: /^views\//},
+        models: {label: "Model Cache", match: /community/},
+        search: {label: "Search Results", match: /search/}
+      }
+    )
+  end
+
+  before do
+    allow(CacheStache).to receive(:configuration).and_return(config)
+    CacheStache::Instrumentation.install!
+  end
+end

data/spec/dummy_app/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/spec/dummy_app/app/assets/config/manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets .css

data/spec/dummy_app/config/application.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "boot"
+
+require "pathname"
+require "logger"
+require "rails"
+require "rails/engine"
+require "active_support/all"
+require "action_dispatch/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+require "sprockets/railtie"
+
+require "cache_stache"
+require "cache_stache/web"
+require "cache_stache/engine"
+require "cache_stache/railtie"
+
+module CacheStacheDummy
+  class Application < Rails::Application
+    config.load_defaults Rails::VERSION::STRING.to_f
+    config.root = Pathname.new(File.expand_path("..", __dir__))
+
+    config.eager_load = false
+    config.cache_store = :memory_store
+    config.logger = Logger.new(nil)
+    config.active_support.deprecation = :log
+    config.secret_key_base = "cache-stache-test"
+  end
+end

data/spec/dummy_app/config/boot.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/setup"

data/spec/dummy_app/config/environment.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "application"
+
+CacheStacheDummy::Application.initialize!

data/spec/dummy_app/config/routes.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "cache_stache/web"
+
+Rails.application.routes.draw do
+  mount CacheStache::Web => "/cache-stache"
+end

data/spec/integration/dashboard_controller_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "../cache_stache_helper"
+
+RSpec.describe CacheStache::DashboardController, type: :controller do
+  routes { CacheStache::Engine.routes }
+
+  let(:config) do
+    CacheStache::Configuration.new.tap do |c|
+      c.bucket_seconds = 300
+      c.retention_seconds = 3600
+
+      c.keyspace(:views) do
+        label "View Fragments"
+        match(/^views\//)
+      end
+
+      c.keyspace(:models) do
+        label "Model Cache"
+        match(/community/)
+      end
+    end
+  end
+
+  before do
+    allow(CacheStache).to receive(:configuration).and_return(config)
+    Rails.cache.clear
+  end
+
+  describe "GET #index" do
+    it "renders successfully" do
+      get :index
+      expect(response).to be_successful
+    end
+
+    context "with custom window parameter" do
+      it "accepts 5 minutes window" do
+        get :index, params: {window: "5m"}
+        expect(response).to be_successful
+      end
+
+      it "accepts 15 minutes window" do
+        get :index, params: {window: "15m"}
+        expect(response).to be_successful
+      end
+
+      it "accepts 1 hour window" do
+        get :index, params: {window: "1h"}
+        expect(response).to be_successful
+      end
+
+      it "accepts 6 hours window" do
+        get :index, params: {window: "6h"}
+        expect(response).to be_successful
+      end
+
+      it "accepts 1 day window" do
+        get :index, params: {window: "1d"}
+        expect(response).to be_successful
+      end
+
+      it "accepts 1 week window" do
+        get :index, params: {window: "1w"}
+        expect(response).to be_successful
+      end
+
+      it "defaults to 1 hour for invalid window" do
+        get :index, params: {window: "invalid"}
+        expect(response).to be_successful
+      end
+    end
+  end
+
+  describe "GET #keyspace" do
+    it "renders successfully for valid keyspace" do
+      get :keyspace, params: {name: "views"}
+      expect(response).to be_successful
+    end
+
+    context "with custom window parameter" do
+      it "respects window parameter" do
+        get :keyspace, params: {name: "views", window: "6h"}
+        expect(response).to be_successful
+      end
+    end
+
+    context "with invalid keyspace" do
+      it "returns 404" do
+        get :keyspace, params: {name: "nonexistent"}
+        expect(response).to have_http_status(:not_found)
+      end
+    end
+  end
+end