refactor(config): Apply better defaults for stale_ttl

Author: drborges

lib/langfuse/client.rb

@@ -166,7 +166,7 @@ def create_memory_cache
       PromptCache.new(
         ttl: config.cache_ttl,
         max_size: config.cache_max_size,
-        stale_ttl: config.cache_stale_while_revalidate ? config.cache_stale_ttl : nil,
+        stale_ttl: config.cache_stale_ttl,
         refresh_threads: config.cache_refresh_threads,
         logger: config.logger
       )
@@ -176,7 +176,7 @@ def create_rails_cache_adapter
       RailsCacheAdapter.new(
         ttl: config.cache_ttl,
         lock_timeout: config.cache_lock_timeout,
-        stale_ttl: config.cache_stale_while_revalidate ? config.cache_stale_ttl : nil,
+        stale_ttl: config.cache_stale_ttl,
         refresh_threads: config.cache_refresh_threads,
         logger: config.logger
       )

lib/langfuse/config.rb

@@ -46,10 +46,10 @@ class Config
     # @return [Integer] Lock timeout in seconds for distributed cache stampede protection
     attr_accessor :cache_lock_timeout
 
-    # @return [Boolean] Enable stale-while-revalidate caching
+    # @return [Boolean] Enable stale-while-revalidate caching (when true, sets cache_stale_ttl to cache_ttl if not customized)
     attr_accessor :cache_stale_while_revalidate
 
-    # @return [Integer] Stale TTL in seconds (grace period for serving stale data)
+    # @return [Integer] Stale TTL in seconds (grace period for serving stale data, default: 0 when SWR disabled, cache_ttl when SWR enabled)
     attr_accessor :cache_stale_ttl
 
     # @return [Integer] Number of background threads for cache refresh
@@ -95,7 +95,7 @@ def initialize
       @cache_backend = DEFAULT_CACHE_BACKEND
       @cache_lock_timeout = DEFAULT_CACHE_LOCK_TIMEOUT
       @cache_stale_while_revalidate = DEFAULT_CACHE_STALE_WHILE_REVALIDATE
-      @cache_stale_ttl = @cache_ttl # Default to same as cache_ttl (SWR disabled, entries expire not go stale)
+      @cache_stale_ttl = 0 # Default to 0 (SWR disabled, entries expire immediately after TTL)
       @cache_refresh_threads = DEFAULT_CACHE_REFRESH_THREADS
       @tracing_async = DEFAULT_TRACING_ASYNC
       @batch_size = DEFAULT_BATCH_SIZE
@@ -104,6 +104,9 @@ def initialize
       @logger = default_logger
 
       yield(self) if block_given?
+
+      # Apply SWR defaults after yield to allow customization
+      apply_swr_defaults!
     end
 
     # Validate the configuration
@@ -150,11 +153,22 @@ def validate_cache_backend!
     end
 
     def validate_swr_config!
-      raise ConfigurationError, "cache_stale_ttl must be non-negative" if cache_stale_ttl.negative?
+      if cache_stale_ttl.nil? || cache_stale_ttl.negative?
+        raise ConfigurationError,
+              "cache_stale_ttl must be non-negative"
+      end
 
       return unless cache_refresh_threads.nil? || cache_refresh_threads <= 0
 
       raise ConfigurationError, "cache_refresh_threads must be positive"
     end
+
+    def apply_swr_defaults!
+      # When SWR is enabled and stale_ttl hasn't been customized (still 0), default to cache_ttl
+      return unless cache_stale_while_revalidate
+      return if cache_stale_ttl != 0 # User has customized it
+
+      @cache_stale_ttl = cache_ttl
+    end
   end
 end

lib/langfuse/prompt_cache.rb

@@ -59,13 +59,13 @@ def expired?
     #
     # @param ttl [Integer] Time-to-live in seconds (default: 60)
     # @param max_size [Integer] Maximum cache size (default: 1000)
-    # @param stale_ttl [Integer, Float::INFINITY, nil] Stale TTL for SWR (default: same as ttl, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
+    # @param stale_ttl [Integer, Float::INFINITY, nil] Stale TTL for SWR (default: 0, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
     # @param refresh_threads [Integer] Number of background refresh threads (default: 5)
     # @param logger [Logger, nil] Logger instance for error reporting (default: nil, creates new logger)
-    def initialize(ttl: 60, max_size: 1000, stale_ttl: nil, refresh_threads: 5, logger: default_logger)
+    def initialize(ttl: 60, max_size: 1000, stale_ttl: 0, refresh_threads: 5, logger: default_logger)
       @ttl = ttl
       @max_size = max_size
-      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl || ttl)
+      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl)
       @logger = logger
       @cache = {}
       @monitor = Monitor.new

lib/langfuse/rails_cache_adapter.rb

@@ -24,18 +24,18 @@ class RailsCacheAdapter
     # @param ttl [Integer] Time-to-live in seconds (default: 60)
     # @param namespace [String] Cache key namespace (default: "langfuse")
     # @param lock_timeout [Integer] Lock timeout in seconds for stampede protection (default: 10)
-    # @param stale_ttl [Integer, Float::INFINITY, nil] Stale TTL for SWR (default: same as ttl, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
+    # @param stale_ttl [Integer, Float::INFINITY, nil] Stale TTL for SWR (default: 0, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
     # @param refresh_threads [Integer] Number of background refresh threads (default: 5)
     # @param logger [Logger, nil] Logger instance for error reporting (default: nil, creates new logger)
     # @raise [ConfigurationError] if Rails.cache is not available
-    def initialize(ttl: 60, namespace: "langfuse", lock_timeout: 10, stale_ttl: nil, refresh_threads: 5,
+    def initialize(ttl: 60, namespace: "langfuse", lock_timeout: 10, stale_ttl: 0, refresh_threads: 5,
                    logger: default_logger)
       validate_rails_cache!
 
       @ttl = ttl
       @namespace = namespace
       @lock_timeout = lock_timeout
-      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl || ttl)
+      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl)
       @logger = logger
       initialize_swr(refresh_threads: refresh_threads) if @stale_ttl > @ttl
     end

spec/langfuse/client_spec.rb

@@ -148,9 +148,9 @@ class << self
         client = described_class.new(config_with_rails_cache)
         adapter = client.api_client.cache
 
-        # When SWR disabled, stale_ttl defaults to ttl (no stale period, immediate expiration)
-        expect(adapter.stale_ttl).to eq(120) # Same as cache_ttl
-        expect(adapter.thread_pool).to be_nil # Thread pool not initialized when stale_ttl == ttl
+        # When SWR disabled, stale_ttl defaults to 0 (no stale period, immediate expiration)
+        expect(adapter.stale_ttl).to eq(0)
+        expect(adapter.thread_pool).to be_nil # Thread pool not initialized when stale_ttl <= ttl
       end
     end
 

spec/langfuse/config_spec.rb

@@ -11,7 +11,7 @@
       expect(config.cache_max_size).to eq(1000)
       expect(config.cache_backend).to eq(:memory)
       expect(config.cache_stale_while_revalidate).to be false
-      expect(config.cache_stale_ttl).to eq(60) # Defaults to cache_ttl
+      expect(config.cache_stale_ttl).to eq(0) # Defaults to 0 (SWR disabled)
       expect(config.cache_refresh_threads).to eq(5)
     end
 
@@ -232,6 +232,14 @@
         )
       end
 
+      it "raises ConfigurationError when nil" do
+        config.cache_stale_ttl = nil
+        expect { config.validate! }.to raise_error(
+          Langfuse::ConfigurationError,
+          "cache_stale_ttl must be non-negative"
+        )
+      end
+
       it "allows zero" do
         config.cache_stale_ttl = 0
         expect { config.validate! }.not_to raise_error
@@ -394,9 +402,39 @@
       expect { config.validate! }.not_to raise_error
 
       expect(config.cache_stale_while_revalidate).to be false
-      expect(config.cache_stale_ttl).to eq(60) # Defaults to cache_ttl
+      expect(config.cache_stale_ttl).to eq(0) # Defaults to 0 (SWR disabled)
       expect(config.cache_refresh_threads).to eq(5) # Default
     end
+
+    it "automatically sets stale_ttl to cache_ttl when SWR is enabled without explicit stale_ttl" do
+      config = described_class.new do |c|
+        c.public_key = "pk_test"
+        c.secret_key = "sk_test"
+        c.cache_ttl = 120
+        c.cache_stale_while_revalidate = true
+        # Not setting cache_stale_ttl explicitly
+      end
+
+      expect { config.validate! }.not_to raise_error
+
+      expect(config.cache_stale_while_revalidate).to be true
+      expect(config.cache_stale_ttl).to eq(120) # Auto-defaults to cache_ttl
+    end
+
+    it "allows customizing stale_ttl when SWR is enabled" do
+      config = described_class.new do |c|
+        c.public_key = "pk_test"
+        c.secret_key = "sk_test"
+        c.cache_ttl = 60
+        c.cache_stale_while_revalidate = true
+        c.cache_stale_ttl = 180 # Custom value
+      end
+
+      expect { config.validate! }.not_to raise_error
+
+      expect(config.cache_stale_while_revalidate).to be true
+      expect(config.cache_stale_ttl).to eq(180) # Respects custom value
+    end
   end
 
   describe "constants" do

spec/langfuse/prompt_cache_spec.rb

@@ -84,9 +84,9 @@
         expect(cache.stale_ttl).to eq(Langfuse::StaleWhileRevalidate::THOUSAND_YEARS_IN_SECONDS)
       end
 
-      it "defaults nil to ttl value" do
-        cache = described_class.new(ttl: 60, stale_ttl: nil)
-        expect(cache.stale_ttl).to eq(60)
+      it "defaults to 0 when not specified (SWR disabled)" do
+        cache = described_class.new(ttl: 60)
+        expect(cache.stale_ttl).to eq(0)
       end
     end
   end