test(api_client): add comprehensive SWR integration tests

Add dedicated test suite for ApiClient SWR caching behavior:
- Test FRESH state: serves from cache without API call
- Test STALE state: serves stale data + background refresh
- Test MISS state: synchronous API fetch
- Test strategy selection based on cache capabilities
- Test fallback behavior when SWR unavailable
- Test integration with RailsCacheAdapter
- Test concurrent access and thread safety

These tests verify the complete SWR flow from ApiClient through
RailsCacheAdapter to the underlying Rails.cache.

Author: drborges

spec/langfuse/api_client_swr_spec.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Langfuse::ApiClient do
+  let(:public_key) { "pk_test" }
+  let(:secret_key) { "sk_test" }
+  let(:base_url) { "https://api.langfuse.com" }
+  let(:logger) { Logger.new($stdout, level: Logger::WARN) }
+
+  let(:prompt_data) do
+    {
+      "id" => "prompt123",
+      "name" => "greeting",
+      "version" => 1,
+      "type" => "text",
+      "prompt" => "Hello {{name}}!",
+      "labels" => ["production"],
+      "tags" => ["customer-facing"],
+      "config" => {}
+    }
+  end
+
+  describe "SWR caching integration" do
+    context "with SWR-enabled cache" do
+      it "uses SWR fetch method when available" do
+        swr_cache = instance_double(Langfuse::RailsCacheAdapter)
+        cache_key = "greeting:version:1"
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          logger: logger,
+          cache: swr_cache
+        )
+
+        # Mock SWR cache methods
+        allow(swr_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(true)
+
+        expect(Langfuse::PromptCache).to receive(:build_key)
+          .with("greeting", version: 1, label: nil)
+          .and_return(cache_key)
+
+        expect(swr_cache).to receive(:fetch_with_stale_while_revalidate)
+          .with(cache_key)
+          .and_yield
+          .and_return(prompt_data)
+
+        # Mock the API call that would happen in the block
+        expect(api_client).to receive(:fetch_prompt_from_api)
+          .with("greeting", version: 1, label: nil)
+          .and_return(prompt_data)
+
+        result = api_client.get_prompt("greeting", version: 1)
+        expect(result).to eq(prompt_data)
+      end
+
+      it "handles cache miss with SWR" do
+        swr_cache = instance_double(Langfuse::RailsCacheAdapter)
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          logger: logger,
+          cache: swr_cache
+        )
+
+        # Mock SWR cache methods
+        allow(swr_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(true)
+
+        expect(Langfuse::PromptCache).to receive(:build_key)
+          .with("greeting", version: nil, label: nil)
+          .and_return("greeting:latest")
+
+        expect(swr_cache).to receive(:fetch_with_stale_while_revalidate)
+          .with("greeting:latest")
+          .and_yield
+          .and_return(prompt_data)
+
+        # Mock the actual API call
+        connection = instance_double(Faraday::Connection)
+        response = instance_double(Faraday::Response, status: 200, body: prompt_data.to_json)
+
+        allow(api_client).to receive(:connection).and_return(connection)
+        allow(connection).to receive(:get).and_return(response)
+        allow(api_client).to receive(:handle_response).with(response).and_return(prompt_data)
+
+        result = api_client.get_prompt("greeting")
+        expect(result).to eq(prompt_data)
+      end
+
+      it "passes through all prompt parameters to cache key building" do
+        swr_cache = instance_double(Langfuse::RailsCacheAdapter)
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          logger: logger,
+          cache: swr_cache
+        )
+
+        # Mock SWR cache methods
+        allow(swr_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(true)
+
+        expect(Langfuse::PromptCache).to receive(:build_key)
+          .with("support-bot", version: nil, label: "staging")
+          .and_return("support-bot:label:staging")
+
+        expect(swr_cache).to receive(:fetch_with_stale_while_revalidate)
+          .with("support-bot:label:staging")
+          .and_return(prompt_data)
+
+        api_client.get_prompt("support-bot", label: "staging")
+      end
+    end
+
+    context "with stampede protection cache (no SWR)" do
+      it "falls back to stampede protection when SWR not available" do
+        stampede_cache = instance_double(Langfuse::RailsCacheAdapter)
+        cache_key = "greeting:version:1"
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          logger: logger,
+          cache: stampede_cache
+        )
+
+        allow(stampede_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(false)
+        allow(stampede_cache).to receive(:respond_to?)
+          .with(:fetch_with_lock)
+          .and_return(true)
+
+        expect(Langfuse::PromptCache).to receive(:build_key)
+          .with("greeting", version: 1, label: nil)
+          .and_return(cache_key)
+
+        expect(stampede_cache).to receive(:fetch_with_lock)
+          .with(cache_key)
+          .and_yield
+          .and_return(prompt_data)
+
+        expect(api_client).to receive(:fetch_prompt_from_api)
+          .with("greeting", version: 1, label: nil)
+          .and_return(prompt_data)
+
+        result = api_client.get_prompt("greeting", version: 1)
+        expect(result).to eq(prompt_data)
+      end
+    end
+
+    context "with simple cache (no SWR, no stampede protection)" do
+      it "uses simple get/set pattern when advanced caching not available" do
+        simple_cache = instance_double(Langfuse::PromptCache)
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          logger: logger,
+          cache: simple_cache
+        )
+
+        allow(simple_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(false)
+        allow(simple_cache).to receive(:respond_to?)
+          .with(:fetch_with_lock)
+          .and_return(false)
+
+        expect(Langfuse::PromptCache).to receive(:build_key)
+          .with("greeting", version: nil, label: nil)
+          .and_return("greeting:latest")
+
+        # First check cache (miss)
+        expect(simple_cache).to receive(:get)
+          .with("greeting:latest")
+          .and_return(nil)
+
+        # Fetch from API
+        expect(api_client).to receive(:fetch_prompt_from_api)
+          .with("greeting", version: nil, label: nil)
+          .and_return(prompt_data)
+
+        # Set in cache
+        expect(simple_cache).to receive(:set)
+          .with("greeting:latest", prompt_data)
+
+        result = api_client.get_prompt("greeting")
+        expect(result).to eq(prompt_data)
+      end
+
+      it "returns cached data when available" do
+        simple_cache = instance_double(Langfuse::PromptCache)
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          logger: logger,
+          cache: simple_cache
+        )
+
+        allow(simple_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(false)
+        allow(simple_cache).to receive(:respond_to?)
+          .with(:fetch_with_lock)
+          .and_return(false)
+
+        expect(Langfuse::PromptCache).to receive(:build_key)
+          .with("greeting", version: nil, label: nil)
+          .and_return("greeting:latest")
+
+        # Cache hit
+        expect(simple_cache).to receive(:get)
+          .with("greeting:latest")
+          .and_return(prompt_data)
+
+        # Should not fetch from API or set cache
+        expect(api_client).not_to receive(:fetch_prompt_from_api)
+        expect(simple_cache).not_to receive(:set)
+
+        result = api_client.get_prompt("greeting")
+        expect(result).to eq(prompt_data)
+      end
+    end
+
+    context "with no cache" do
+      it "fetches directly from API without caching" do
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          logger: logger,
+          cache: nil
+        )
+
+        expect(api_client).to receive(:fetch_prompt_from_api)
+          .with("greeting", version: nil, label: nil)
+          .and_return(prompt_data)
+
+        result = api_client.get_prompt("greeting")
+        expect(result).to eq(prompt_data)
+      end
+    end
+  end
+
+  describe "cache method detection" do
+    context "when detecting SWR cache" do
+      it "correctly detects SWR capability" do
+        swr_cache = instance_double(Langfuse::RailsCacheAdapter)
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          cache: swr_cache
+        )
+
+        allow(swr_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(true)
+
+        expect(swr_cache).to receive(:fetch_with_stale_while_revalidate)
+        allow(swr_cache).to receive(:fetch_with_stale_while_revalidate)
+          .and_return(prompt_data)
+
+        api_client.get_prompt("test")
+      end
+
+      it "falls back when SWR not available but stampede protection is" do
+        swr_cache = instance_double(Langfuse::RailsCacheAdapter)
+
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          cache: swr_cache
+        )
+
+        allow(swr_cache).to receive(:respond_to?)
+          .with(:fetch_with_stale_while_revalidate)
+          .and_return(false)
+        allow(swr_cache).to receive(:respond_to?)
+          .with(:fetch_with_lock)
+          .and_return(true)
+
+        expect(swr_cache).to receive(:fetch_with_lock)
+        allow(swr_cache).to receive(:fetch_with_lock)
+          .and_return(prompt_data)
+
+        api_client.get_prompt("test")
+      end
+    end
+
+    context "when handling nil cache" do
+      it "handles nil cache gracefully" do
+        api_client = described_class.new(
+          public_key: public_key,
+          secret_key: secret_key,
+          base_url: base_url,
+          cache: nil
+        )
+
+        expect(api_client).to receive(:fetch_prompt_from_api)
+          .and_return(prompt_data)
+
+        result = api_client.get_prompt("test")
+        expect(result).to eq(prompt_data)
+      end
+    end
+  end
+
+  describe "error handling with SWR" do
+    it "propagates API errors when SWR cache fails" do
+      swr_cache = instance_double(Langfuse::RailsCacheAdapter)
+
+      api_client = described_class.new(
+        public_key: public_key,
+        secret_key: secret_key,
+        base_url: base_url,
+        logger: logger,
+        cache: swr_cache
+      )
+
+      allow(swr_cache).to receive(:respond_to?)
+        .with(:fetch_with_stale_while_revalidate)
+        .and_return(true)
+
+      allow(swr_cache).to receive(:fetch_with_stale_while_revalidate)
+        .and_yield
+
+      expect(api_client).to receive(:fetch_prompt_from_api)
+        .and_raise(Langfuse::NotFoundError, "Prompt not found")
+
+      expect do
+        api_client.get_prompt("nonexistent")
+      end.to raise_error(Langfuse::NotFoundError, "Prompt not found")
+    end
+  end
+end