cache_stache 0.1.0

data/spec/unit/cache_client_spec.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require_relative "../cache_stache_helper"
+require "json"
+
+RSpec.describe CacheStache::CacheClient do
+  subject(:client) { described_class.new(config) }
+
+  let(:config) { build_test_config }
+
+  describe "#initialize" do
+    it "uses the provided configuration" do
+      expect(client.instance_variable_get(:@config)).to eq(config)
+    end
+
+    it "uses the default configuration when none provided" do
+      allow(CacheStache).to receive(:configuration).and_return(config)
+      default_client = described_class.new
+      expect(default_client.instance_variable_get(:@config)).to eq(config)
+    end
+
+    it "creates a Redis connection pool" do
+      expect(client.instance_variable_get(:@pool)).to be_a(ConnectionPool)
+    end
+  end
+
+  describe "#increment_stats" do
+    # Use aligned timestamp (1_700_000_000 / 300 * 300 = 1_699_999_800)
+    let(:bucket_ts) { (1_700_000_000 / 300) * 300 }
+    let(:increments) do
+      {
+        "overall:hits" => 1,
+        "overall:misses" => 0,
+        "views:hits" => 1,
+        "views:misses" => 0
+      }
+    end
+
+    it "increments stats for a bucket" do
+      client.increment_stats(bucket_ts, increments)
+
+      buckets = 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)
+      expect(buckets.first[:stats]["overall:misses"]).to eq(0.0)
+      expect(buckets.first[:stats]["views:hits"]).to eq(1.0)
+      expect(buckets.first[:stats]["views:misses"]).to eq(0.0)
+    end
+
+    it "accumulates stats across multiple calls" do
+      client.increment_stats(bucket_ts, increments)
+      client.increment_stats(bucket_ts, increments)
+
+      buckets = client.fetch_buckets(bucket_ts - 100, bucket_ts + 100)
+      expect(buckets.first[:stats]["overall:hits"]).to eq(2.0)
+      expect(buckets.first[:stats]["views:hits"]).to eq(2.0)
+    end
+
+    it "handles mixed hit and miss increments" do
+      client.increment_stats(bucket_ts, {"overall:hits" => 1, "overall:misses" => 0})
+      client.increment_stats(bucket_ts, {"overall:hits" => 0, "overall:misses" => 1})
+
+      buckets = client.fetch_buckets(bucket_ts - 100, bucket_ts + 100)
+      expect(buckets.first[:stats]["overall:hits"]).to eq(1.0)
+      expect(buckets.first[:stats]["overall:misses"]).to eq(1.0)
+    end
+
+    it "sets expiry on the bucket" do
+      client.increment_stats(bucket_ts, increments)
+
+      key = "cache_stache:v1:test:#{bucket_ts}"
+      ttl = cache_stache_redis.ttl(key)
+
+      expect(ttl).to be > 0
+      expect(ttl).to be <= config.retention_seconds
+    end
+
+    it "handles errors gracefully" do
+      # Create client, then make the pool raise errors
+      test_client = described_class.new(config)
+      pool = test_client.instance_variable_get(:@pool)
+      allow(pool).to receive(:with).and_raise(StandardError, "Redis error")
+      allow(Rails.logger).to receive(:error)
+
+      expect { test_client.increment_stats(bucket_ts, increments) }.not_to raise_error
+      expect(Rails.logger).to have_received(:error).with(/Failed to increment stats/)
+    end
+  end
+
+  describe "#fetch_buckets" do
+    # Use a timestamp that aligns to 300-second bucket boundaries
+    let(:base_ts) { (1_700_000_000 / 300) * 300 } # 1_699_999_800
+
+    before do
+      # Create some test buckets
+      client.increment_stats(base_ts, {"overall:hits" => 5, "overall:misses" => 2})
+      client.increment_stats(base_ts + 300, {"overall:hits" => 3, "overall:misses" => 1})
+      client.increment_stats(base_ts + 600, {"overall:hits" => 8, "overall:misses" => 4})
+    end
+
+    it "fetches buckets in time range" do
+      from_ts = base_ts
+      to_ts = base_ts + 700
+
+      buckets = client.fetch_buckets(from_ts, to_ts)
+
+      expect(buckets.size).to eq(3)
+      expect(buckets[0][:timestamp]).to eq(base_ts)
+      expect(buckets[1][:timestamp]).to eq(base_ts + 300)
+      expect(buckets[2][:timestamp]).to eq(base_ts + 600)
+    end
+
+    it "returns bucket stats as floats" do
+      buckets = client.fetch_buckets(base_ts, base_ts + 100)
+
+      expect(buckets[0][:stats]["overall:hits"]).to eq(5.0)
+      expect(buckets[0][:stats]["overall:misses"]).to eq(2.0)
+    end
+
+    it "excludes empty buckets" do
+      buckets = client.fetch_buckets(base_ts + 900, base_ts + 1200)
+      expect(buckets).to be_empty
+    end
+
+    it "aligns timestamps to bucket boundaries" do
+      buckets = client.fetch_buckets(base_ts + 50, base_ts + 550)
+
+      expect(buckets.map { |b| b[:timestamp] }).to eq([base_ts, base_ts + 300])
+    end
+
+    it "handles errors gracefully" do
+      # Create client, then make the pool raise errors
+      test_client = described_class.new(config)
+      pool = test_client.instance_variable_get(:@pool)
+      allow(pool).to receive(:with).and_raise(StandardError, "Redis error")
+      allow(Rails.logger).to receive(:error)
+
+      buckets = test_client.fetch_buckets(base_ts, base_ts + 300)
+      expect(buckets).to eq([])
+      expect(Rails.logger).to have_received(:error).with(/Failed to fetch buckets/)
+    end
+
+    it "reflects single-field increments" do
+      # Use a timestamp aligned to bucket boundary
+      ts = base_ts + 900
+
+      # Increment a single field
+      client.increment_stats(ts, {"overall:hits" => 1})
+
+      # Fetch the bucket containing this increment
+      buckets = client.fetch_buckets(ts, ts + 100)
+
+      # Verify the increment is visible
+      expect(buckets.size).to eq(1)
+      expect(buckets[0][:timestamp]).to eq(ts)
+      expect(buckets[0][:stats]["overall:hits"]).to eq(1.0)
+    end
+  end
+
+  describe "#store_config_metadata" do
+    it "stores configuration metadata in Redis" do
+      client.store_config_metadata
+
+      metadata = client.fetch_config_metadata
+
+      expect(metadata["bucket_seconds"]).to eq(300)
+      expect(metadata["retention_seconds"]).to eq(3600)
+      expect(metadata["updated_at"]).to be_a(Integer)
+    end
+
+    it "handles errors gracefully" do
+      # Create client, then make the pool raise errors
+      test_client = described_class.new(config)
+      pool = test_client.instance_variable_get(:@pool)
+      allow(pool).to receive(:with).and_raise(StandardError, "Redis error")
+      allow(Rails.logger).to receive(:error)
+
+      expect { test_client.store_config_metadata }.not_to raise_error
+      expect(Rails.logger).to have_received(:error).with(/Failed to store config metadata/)
+    end
+  end
+
+  describe "#fetch_config_metadata" do
+    it "retrieves stored metadata" do
+      client.store_config_metadata
+      metadata = client.fetch_config_metadata
+
+      expect(metadata["bucket_seconds"]).to eq(300)
+      expect(metadata["retention_seconds"]).to eq(3600)
+    end
+
+    it "returns nil when metadata doesn't exist" do
+      metadata = client.fetch_config_metadata
+      expect(metadata).to be_nil
+    end
+
+    it "handles errors gracefully" do
+      # Create client, then make the pool raise errors
+      test_client = described_class.new(config)
+      pool = test_client.instance_variable_get(:@pool)
+      allow(pool).to receive(:with).and_raise(StandardError, "Redis error")
+      allow(Rails.logger).to receive(:error)
+
+      metadata = test_client.fetch_config_metadata
+      expect(metadata).to be_nil
+      expect(Rails.logger).to have_received(:error).with(/Failed to fetch config metadata/)
+    end
+  end
+
+  describe "#estimate_storage_size" do
+    before do
+      config.keyspace(:views) { match(/^views\//) }
+      config.keyspace(:models) { match(/model/) }
+    end
+
+    it "calculates estimated storage size" do
+      estimate = client.estimate_storage_size
+
+      expect(estimate[:max_buckets]).to be > 0
+      expect(estimate[:fields_per_bucket]).to eq(6) # 2 overall + 2*2 keyspaces
+      expect(estimate[:bytes_per_bucket]).to be > 0
+      expect(estimate[:total_bytes]).to be > 0
+      expect(estimate[:human_size]).to be_a(String)
+    end
+
+    it "formats bytes correctly" do
+      expect(client.send(:format_bytes, 500)).to eq("500 B")
+      expect(client.send(:format_bytes, 2048)).to eq("2.0 KB")
+      expect(client.send(:format_bytes, 2_097_152)).to eq("2.0 MB")
+      expect(client.send(:format_bytes, 2_147_483_648)).to eq("2.0 GB")
+    end
+
+    it "handles errors gracefully" do
+      allow(config).to receive(:retention_seconds).and_raise(StandardError, "Config error")
+      expect(Rails.logger).to receive(:error).with(/Failed to estimate storage size/)
+
+      estimate = client.estimate_storage_size
+      expect(estimate[:total_bytes]).to eq(0)
+      expect(estimate[:human_size]).to eq("Unknown")
+    end
+  end
+
+  describe "private methods" do
+    describe "#bucket_key" do
+      it "generates correct bucket key format" do
+        key = client.send(:bucket_key, 1_700_000_000)
+        expect(key).to eq("cache_stache:v1:test:1700000000")
+      end
+    end
+
+    describe "#align_to_bucket" do
+      it "aligns timestamp to bucket boundary" do
+        aligned = client.send(:align_to_bucket, 1_700_000_123)
+        expect(aligned).to eq(1_700_000_100) # 123 aligned to 300s bucket
+      end
+    end
+
+    describe "#extract_timestamp_from_key" do
+      it "extracts timestamp from key" do
+        ts = client.send(:extract_timestamp_from_key, "cache_stache:v1:test:1700000000")
+        expect(ts).to eq(1_700_000_000)
+      end
+    end
+
+    describe "#bucket_keys_in_range" do
+      it "generates all bucket keys in range" do
+        # Use aligned timestamps (1_699_999_800 is divisible by 300)
+        aligned_base = (1_700_000_000 / 300) * 300
+        keys = client.send(:bucket_keys_in_range, aligned_base, aligned_base + 700)
+        expect(keys).to eq([
+          "cache_stache:v1:test:#{aligned_base}",
+          "cache_stache:v1:test:#{aligned_base + 300}",
+          "cache_stache:v1:test:#{aligned_base + 600}"
+        ])
+      end
+    end
+  end
+end

data/spec/unit/configuration_spec.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "../cache_stache_helper"
+
+RSpec.describe CacheStache::Configuration do
+  subject(:config) { described_class.new }
+
+  describe "#initialize" do
+    let(:default_redis_url) { "redis://cache-stache.test/0" }
+
+    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)
+    end
+
+    it { expect(config.bucket_seconds).to eq(5.minutes.to_i) }
+    it { expect(config.retention_seconds).to eq(7.days.to_i) }
+    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_pool_size).to eq(5) }
+    it { expect(config.keyspaces).to eq([]) }
+  end
+
+  describe "#keyspace" do
+    it "adds a keyspace with the given name" do
+      config.keyspace(:views) do
+        label "View Fragments"
+        match(/^views\//)
+      end
+
+      expect(config.keyspaces.size).to eq(1)
+      expect(config.keyspaces.first.name).to eq(:views)
+      expect(config.keyspaces.first.label).to eq("View Fragments")
+    end
+
+    it "uses humanized name as default label" do
+      config.keyspace(:search_results) do
+        match(/search/)
+      end
+
+      expect(config.keyspaces.first.label).to eq("Search results")
+    end
+
+    it "validates the keyspace requires a pattern" do
+      expect do
+        config.keyspace(:invalid) do
+          label "Invalid"
+          # No match pattern
+        end
+      end.to raise_error(CacheStache::Error, /requires a match pattern/)
+    end
+
+    it "validates the pattern must be a Regexp" do
+      expect do
+        config.keyspace(:invalid) do
+          match "not a regex"
+        end
+      end.to raise_error(CacheStache::Error, /requires a Regexp argument/)
+    end
+
+    it "raises error for duplicate keyspace names" do
+      config.keyspace(:views) do
+        match(/^views\//)
+      end
+
+      expect do
+        config.keyspace(:views) do
+          match(/view/)
+        end
+      end.to raise_error(CacheStache::Error, /already defined/)
+    end
+
+    it "accepts a block without a label" do
+      config.keyspace(:test) do
+        match(/test/)
+      end
+
+      expect(config.keyspaces.first.label).to eq("Test")
+    end
+
+    it "stores the pattern on the keyspace" do
+      config.keyspace(:views) do
+        match(/^views\//)
+      end
+
+      expect(config.keyspaces.first.pattern).to eq(/^views\//)
+    end
+  end
+
+  describe "#matching_keyspaces" do
+    before do
+      config.keyspace(:views) do
+        match(/^views\//)
+      end
+
+      config.keyspace(:models) do
+        match(/community/)
+      end
+
+      config.keyspace(:search) do
+        match(/search/)
+      end
+    end
+
+    it "returns keyspaces matching the key" do
+      matches = config.matching_keyspaces("views/product_123")
+      expect(matches.map(&:name)).to eq([:views])
+    end
+
+    it "returns multiple keyspaces when key matches multiple patterns" do
+      matches = config.matching_keyspaces("views/community_search")
+      expect(matches.map(&:name)).to contain_exactly(:views, :models, :search)
+    end
+
+    it "returns empty array when no keyspaces match" do
+      matches = config.matching_keyspaces("unmatched_key")
+      expect(matches).to eq([])
+    end
+
+    it "caches results for the same key" do
+      # First call
+      config.matching_keyspaces("views/test")
+
+      # Modify keyspace to prove caching
+      config.keyspaces.first.instance_variable_set(:@pattern, /never_match/)
+
+      # Should still return cached result
+      matches = config.matching_keyspaces("views/test")
+      expect(matches.map(&:name)).to eq([:views])
+    end
+  end
+
+  describe "#validate!" do
+    before do
+      config.redis_url = "redis://localhost:6379/0"
+    end
+
+    it "requires redis_url" do
+      config.redis_url = nil
+      expect { config.validate! }.to raise_error(CacheStache::Error, /redis_url must be configured/)
+    end
+
+    it "requires redis_pool_size to be positive" do
+      config.redis_pool_size = 0
+      expect { config.validate! }.to raise_error(CacheStache::Error, /redis_pool_size must be positive/)
+    end
+
+    it "validates bucket_seconds is positive" do
+      config.bucket_seconds = 0
+      expect { config.validate! }.to raise_error(CacheStache::Error, /bucket_seconds must be positive/)
+    end
+
+    it "validates retention_seconds is positive" do
+      config.retention_seconds = -1
+      expect { config.validate! }.to raise_error(CacheStache::Error, /retention_seconds must be positive/)
+    end
+
+    it "validates sample_rate is between 0 and 1" do
+      config.sample_rate = 1.5
+      expect { config.validate! }.to raise_error(CacheStache::Error, /sample_rate must be between 0 and 1/)
+    end
+
+    it "validates all keyspaces" do
+      # Create a keyspace with a valid pattern first
+      config.keyspace(:invalid) do
+        match(/test/)
+      end
+
+      # Then corrupt it by setting pattern to nil
+      config.instance_variable_get(:@keyspaces).last.instance_variable_set(:@pattern, nil)
+
+      expect { config.validate! }.to raise_error(CacheStache::Error, /requires a match pattern/)
+    end
+
+    it "warns when retention doesn't divide evenly by bucket size" do
+      config.bucket_seconds = 7.minutes.to_i
+      config.retention_seconds = 1.hour.to_i
+
+      expect(Rails.logger).to receive(:warn).with(/does not divide evenly/)
+      config.validate!
+    end
+
+    it "passes validation with valid configuration" do
+      config.keyspace(:views) do
+        match(/^views\//)
+      end
+
+      expect { config.validate! }.not_to raise_error
+    end
+  end
+
+  describe "#rails_env" do
+    it "returns RAILS_ENV when set" do
+      allow(ENV).to receive(:fetch).and_call_original
+      allow(ENV).to receive(:fetch).with("CACHE_STACHE_REDIS_URL").and_return("redis://cache-stache.test/0")
+      allow(ENV).to receive(:fetch).with("RAILS_ENV", "development").and_return("production")
+      expect(config.rails_env).to eq("production")
+    end
+
+    it "defaults to development when RAILS_ENV is not set" do
+      allow(ENV).to receive(:fetch).and_call_original
+      allow(ENV).to receive(:fetch).with("CACHE_STACHE_REDIS_URL").and_return("redis://cache-stache.test/0")
+      allow(ENV).to receive(:fetch).with("RAILS_ENV", "development").and_return("development")
+      expect(config.rails_env).to eq("development")
+    end
+  end
+end

data/spec/unit/keyspace_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../cache_stache_helper"
+
+RSpec.describe CacheStache::Keyspace do
+  subject(:keyspace) { described_class.new(:views) }
+
+  describe "#initialize" do
+    it { expect(keyspace.name).to eq(:views) }
+    it { expect(keyspace.label).to eq("Views") }
+    it { expect(keyspace.pattern).to be_nil }
+  end
+
+  describe "#match?" do
+    context "with a valid pattern" do
+      before do
+        keyspace.pattern = /^views\//
+      end
+
+      it "returns true when key matches" do
+        expect(keyspace.match?("views/product_123")).to be(true)
+      end
+
+      it "returns false when key doesn't match" do
+        expect(keyspace.match?("community/456")).to be(false)
+      end
+    end
+
+    context "without a pattern" do
+      it "returns false" do
+        expect(keyspace.match?("any_key")).to be(false)
+      end
+    end
+
+    context "with various regex patterns" do
+      it "handles start anchor" do
+        keyspace.pattern = /^views\/\w+_\d+$/
+        expect(keyspace.match?("views/product_123")).to be(true)
+        expect(keyspace.match?("views/invalid")).to be(false)
+      end
+
+      it "handles partial matching" do
+        keyspace.pattern = /search/
+        expect(keyspace.match?("pages/search/results")).to be(true)
+        expect(keyspace.match?("pages/home")).to be(false)
+      end
+
+      it "handles alternation" do
+        keyspace.pattern = %r{/(community|unit|lease)/}
+        expect(keyspace.match?("models/community/123")).to be(true)
+        expect(keyspace.match?("models/unit/456")).to be(true)
+        expect(keyspace.match?("models/account/789")).to be(false)
+      end
+    end
+  end
+
+  describe "#validate!" do
+    it "raises error when pattern is not set" do
+      expect do
+        keyspace.validate!
+      end.to raise_error(CacheStache::Error, /Keyspace views requires a match pattern/)
+    end
+
+    it "raises error when pattern is not a Regexp" do
+      keyspace.pattern = "not a regex"
+      expect do
+        keyspace.validate!
+      end.to raise_error(CacheStache::Error, /match pattern must be a Regexp/)
+    end
+
+    it "passes validation when pattern is a valid Regexp" do
+      keyspace.pattern = /test/
+      expect { keyspace.validate! }.not_to raise_error
+    end
+  end
+
+  describe "label humanization" do
+    it "humanizes snake_case names" do
+      ks = described_class.new(:search_results)
+      expect(ks.label).to eq("Search results")
+    end
+
+    it "humanizes single word names" do
+      ks = described_class.new(:profiles)
+      expect(ks.label).to eq("Profiles")
+    end
+
+    it "can be overridden" do
+      keyspace.label = "Custom Label"
+      expect(keyspace.label).to eq("Custom Label")
+    end
+  end
+end