feat(config): Allow configuring SWR caches that never expire

Author: drborges

lib/langfuse/config.rb

@@ -75,7 +75,6 @@ class Config
     DEFAULT_CACHE_BACKEND = :memory
     DEFAULT_CACHE_LOCK_TIMEOUT = 10
     DEFAULT_CACHE_STALE_WHILE_REVALIDATE = false
-    DEFAULT_CACHE_STALE_TTL = 300
     DEFAULT_CACHE_REFRESH_THREADS = 5
     DEFAULT_TRACING_ASYNC = true
     DEFAULT_BATCH_SIZE = 50
@@ -96,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 = DEFAULT_CACHE_STALE_TTL
+      @cache_stale_ttl = @cache_ttl # Default to same as cache_ttl (SWR disabled, entries expire not go stale)
       @cache_refresh_threads = DEFAULT_CACHE_REFRESH_THREADS
       @tracing_async = DEFAULT_TRACING_ASYNC
       @batch_size = DEFAULT_BATCH_SIZE
@@ -117,6 +116,7 @@ def validate!
       raise ConfigurationError, "secret_key is required" if secret_key.nil? || secret_key.empty?
       raise ConfigurationError, "base_url cannot be empty" if base_url.nil? || base_url.empty?
       raise ConfigurationError, "timeout must be positive" if timeout.nil? || timeout <= 0
+      raise ConfigurationError, "cache_ttl cannot be Float::INFINITY" if cache_ttl == Float::INFINITY
       raise ConfigurationError, "cache_ttl must be non-negative" if cache_ttl.nil? || cache_ttl.negative?
       raise ConfigurationError, "cache_max_size must be positive" if cache_max_size.nil? || cache_max_size <= 0
 
@@ -150,9 +150,7 @@ def validate_cache_backend!
     end
 
     def validate_swr_config!
-      if cache_stale_ttl.nil? || cache_stale_ttl.negative?
-        raise ConfigurationError, "cache_stale_ttl must be non-negative"
-      end
+      raise ConfigurationError, "cache_stale_ttl must be non-negative" if cache_stale_ttl.negative?
 
       return unless cache_refresh_threads.nil? || cache_refresh_threads <= 0
 

lib/langfuse/prompt_cache.rb

@@ -59,18 +59,18 @@ 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, nil] Stale TTL for SWR (default: nil, disabled)
+    # @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 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)
       @ttl = ttl
       @max_size = max_size
-      @stale_ttl = stale_ttl
+      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl || ttl)
       @logger = logger
       @cache = {}
       @monitor = Monitor.new
       @locks = {} # Track locks for in-memory locking
-      initialize_swr(refresh_threads: refresh_threads) if stale_ttl
+      initialize_swr(refresh_threads: refresh_threads) if @stale_ttl > @ttl
     end
 
     # Get a value from the cache

lib/langfuse/rails_cache_adapter.rb

@@ -24,7 +24,7 @@ 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, nil] Stale TTL for SWR (default: nil, disabled)
+    # @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 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
@@ -35,9 +35,9 @@ def initialize(ttl: 60, namespace: "langfuse", lock_timeout: 10, stale_ttl: nil,
       @ttl = ttl
       @namespace = namespace
       @lock_timeout = lock_timeout
-      @stale_ttl = stale_ttl
+      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl || ttl)
       @logger = logger
-      initialize_swr(refresh_threads: refresh_threads) if stale_ttl
+      initialize_swr(refresh_threads: refresh_threads) if @stale_ttl > @ttl
     end
 
     # Get a value from the cache

lib/langfuse/stale_while_revalidate.rb

@@ -18,11 +18,11 @@ module Langfuse
   #   class MyCache
   #     include Langfuse::StaleWhileRevalidate
   #
-  #     def initialize(ttl: 60, stale_ttl: 30)
+  #     def initialize(ttl: 60, stale_ttl: nil)
   #       @ttl = ttl
-  #       @stale_ttl = stale_ttl
+  #       @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl || ttl)
   #       @logger = Logger.new($stdout)
-  #       initialize_swr if stale_ttl
+  #       initialize_swr
   #     end
   #
   #     def cache_get(key)
@@ -47,6 +47,26 @@ module StaleWhileRevalidate
     # Refresh locks are short-lived to prevent duplicate background refreshes
     REFRESH_LOCK_TIMEOUT = 60
 
+    # Number of seconds in 1000 years (accounting for leap years)
+    THOUSAND_YEARS_IN_SECONDS = (1000 * 365.25 * 24 * 60 * 60).to_i
+
+    # Normalize stale_ttl value
+    #
+    # Converts Float::INFINITY to 1000 years in seconds for practical "never expire"
+    # behavior while keeping the value finite for calculations.
+    #
+    # @param stale_ttl [Integer, Float::INFINITY] Stale TTL value (required, no nil allowed)
+    # @return [Integer] Normalized stale TTL in seconds
+    #
+    # @example
+    #   StaleWhileRevalidate.normalize_stale_ttl(300) # => 300
+    #   StaleWhileRevalidate.normalize_stale_ttl(Float::INFINITY) # => 31557600000
+    def self.normalize_stale_ttl(stale_ttl)
+      return THOUSAND_YEARS_IN_SECONDS if stale_ttl == Float::INFINITY
+
+      stale_ttl
+    end
+
     # Initialize SWR infrastructure
     #
     # Must be called by including class after setting @stale_ttl, @ttl, and @logger.
@@ -145,9 +165,12 @@ def fetch_with_lock(key)
 
     # Check if SWR is enabled
     #
-    # @return [Boolean] true if stale_ttl is configured
+    # SWR is enabled when stale_ttl > ttl, meaning there's a grace period
+    # where stale data can be served while revalidating in the background.
+    #
+    # @return [Boolean] true if stale_ttl is greater than ttl
     def swr_enabled?
-      !stale_ttl.nil? && stale_ttl.positive?
+      stale_ttl > ttl
     end
 
     # Shutdown the cache refresh thread pool gracefully
@@ -358,7 +381,7 @@ def ttl
 
     # Get stale TTL value
     #
-    # @return [Integer, nil] Stale TTL in seconds, or nil if disabled
+    # @return [Integer] Stale TTL in seconds
     # @raise [NotImplementedError] if not implemented by including class
     def stale_ttl
       @stale_ttl || raise(NotImplementedError, "#{self.class} must provide @stale_ttl")

spec/langfuse/client_spec.rb

@@ -148,8 +148,9 @@ class << self
         client = described_class.new(config_with_rails_cache)
         adapter = client.api_client.cache
 
-        expect(adapter.stale_ttl).to be_nil
-        expect(adapter.thread_pool).to be_nil
+        # 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
       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(300)
+      expect(config.cache_stale_ttl).to eq(60) # Defaults to cache_ttl
       expect(config.cache_refresh_threads).to eq(5)
     end
 
@@ -158,10 +158,23 @@
         )
       end
 
+      it "raises ConfigurationError when Float::INFINITY" do
+        config.cache_ttl = Float::INFINITY
+        expect { config.validate! }.to raise_error(
+          Langfuse::ConfigurationError,
+          "cache_ttl cannot be Float::INFINITY"
+        )
+      end
+
       it "allows zero (disabled cache)" do
         config.cache_ttl = 0
         expect { config.validate! }.not_to raise_error
       end
+
+      it "allows positive values" do
+        config.cache_ttl = 300
+        expect { config.validate! }.not_to raise_error
+      end
     end
 
     context "when cache_max_size is invalid" do
@@ -211,14 +224,6 @@
     end
 
     context "when cache_stale_ttl is invalid" do
-      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 "raises ConfigurationError when negative" do
         config.cache_stale_ttl = -1
         expect { config.validate! }.to raise_error(
@@ -389,15 +394,14 @@
       expect { config.validate! }.not_to raise_error
 
       expect(config.cache_stale_while_revalidate).to be false
-      expect(config.cache_stale_ttl).to eq(300) # Default
+      expect(config.cache_stale_ttl).to eq(60) # Defaults to cache_ttl
       expect(config.cache_refresh_threads).to eq(5) # Default
     end
   end
 
   describe "constants" do
     it "defines correct SWR default values" do
       expect(Langfuse::Config::DEFAULT_CACHE_STALE_WHILE_REVALIDATE).to be false
-      expect(Langfuse::Config::DEFAULT_CACHE_STALE_TTL).to eq(300)
       expect(Langfuse::Config::DEFAULT_CACHE_REFRESH_THREADS).to eq(5)
     end
   end

spec/langfuse/prompt_cache_spec.rb

@@ -72,6 +72,23 @@
       cache = described_class.new(max_size: 500)
       expect(cache.max_size).to eq(500)
     end
+
+    context "with stale_ttl" do
+      it "sets custom stale_ttl" do
+        cache = described_class.new(stale_ttl: 300)
+        expect(cache.stale_ttl).to eq(300)
+      end
+
+      it "converts Float::INFINITY to 1000 years in seconds" do
+        cache = described_class.new(stale_ttl: Float::INFINITY)
+        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)
+      end
+    end
   end
 
   describe "#get and #set" do

spec/langfuse/rails_cache_adapter_spec.rb

@@ -46,6 +46,11 @@ class << self
           expect(adapter.stale_ttl).to eq(300)
         end
 
+        it "converts Float::INFINITY to 1000 years in seconds" do
+          adapter = described_class.new(stale_ttl: Float::INFINITY)
+          expect(adapter.stale_ttl).to eq(Langfuse::StaleWhileRevalidate::THOUSAND_YEARS_IN_SECONDS)
+        end
+
         it "initializes thread pool with default refresh_threads (5)" do
           expect(Concurrent::CachedThreadPool).to receive(:new)
             .with(