refactor(config): Use :indefinite symbol instead of Float::INFINITY for cache_stale_ttl

Improves API ergonomics by replacing Float::INFINITY with a more Ruby-idiomatic
:indefinite symbol for never-expiring cache configuration.

Rationale:
- :indefinite is more readable and Ruby-idiomatic than Float::INFINITY
- Symbols are the conventional way to represent special values in Ruby config
- Makes intent clearer in configuration code
- Aligns with Ruby community conventions (e.g., Rails cache :expires_in)

Changes:
- Renamed THOUSAND_YEARS_IN_SECONDS constant to INDEFINITE_SECONDS
- Updated constant comment to clarify intent ("indefinite cache duration")
- Changed normalize_stale_ttl from class method to instance method (normalized_stale_ttl)
- Instance method reads from cache_stale_ttl and returns normalized value on-demand
- Removed normalization from Config#initialize (now done lazily via method)
- Updated create_memory_cache to use config.normalized_stale_ttl
- Updated create_rails_cache_adapter to use config.normalized_stale_ttl
- Updated validate_swr_config! to handle :indefinite symbol properly
- Updated validation error message: "must be non-negative or :indefinite"

Documentation Updates:
- docs/CACHING.md: Changed Float::INFINITY to :indefinite in examples
- docs/CONFIGURATION.md: Changed Float::INFINITY to :indefinite in examples
- lib/langfuse/config.rb: Updated attr_accessor doc to mention :indefinite
- lib/langfuse/prompt_cache.rb: Updated comment to reflect :indefinite normalization

Test Coverage:
- Updated all tests to use :indefinite instead of Float::INFINITY
- Updated all tests to use INDEFINITE_SECONDS instead of THOUSAND_YEARS_IN_SECONDS
- Updated test expectations for new validation error message
- All 797 examples passing, 96.86% coverage maintained

Benefits:
- More intuitive API for developers (config.cache_stale_ttl = :indefinite)
- Clearer intent in configuration code
- Normalization happens on-demand via instance method
- Original config value preserved (not mutated during initialization)
- Better alignment with Ruby conventions and best practices

Author: drborges

docs/CACHING.md

@@ -198,10 +198,12 @@ Langfuse.configure do |config|
   config.cache_backend = :memory
   config.cache_ttl = 300  # Still refreshes every 5 minutes
   config.cache_stale_while_revalidate = true
-  config.cache_stale_ttl = Float::INFINITY  # Never expire (serve stale forever)
+  config.cache_stale_ttl = :indefinite  # Never expire (normalized to 1000 years internally)
 end
 ```
 
+**Note:** `:indefinite` is automatically normalized to 1000 years (31,536,000,000 seconds) during configuration initialization. This provides a practical "never expire" behavior while keeping the value finite for calculations.
+
 ### Cache States
 
 SWR introduces three cache states instead of two:

docs/CONFIGURATION.md

@@ -144,13 +144,14 @@ See [CACHING.md](CACHING.md#stale-while-revalidate-swr) for detailed usage.
 
 #### `cache_stale_ttl`
 
-- **Type:** Integer (seconds) or `Float::INFINITY`
+- **Type:** Integer (seconds) or `:indefinite` Symbol
 - **Default:** `0` (SWR disabled)
 - **Description:** Grace period for serving stale data during background refresh
+- **Note:** `:indefinite` is automatically normalized to 1000 years (31,536,000,000 seconds) during config initialization
 
 ```ruby
 config.cache_stale_ttl = 300  # Serve stale data for up to 5 minutes
-config.cache_stale_ttl = Float::INFINITY  # Never expire (1000 years)
+config.cache_stale_ttl = :indefinite  # Never expire (normalized to 1000 years internally)
 ```
 
 **How it works:**
@@ -163,7 +164,7 @@ config.cache_stale_ttl = Float::INFINITY  # Never expire (1000 years)
 
 - Same as `cache_ttl` (default when SWR enabled): Balanced freshness/latency
 - `2x cache_ttl`: More tolerance for API slowdowns
-- `Float::INFINITY`: Maximum performance, eventual consistency, high availability
+- `:indefinite`: Maximum performance, eventual consistency, high availability
 
 **Auto-configuration:**
 When `cache_stale_while_revalidate = true` and `cache_stale_ttl` is not set (still `0`), it automatically defaults to `cache_ttl`.

lib/langfuse/client.rb

@@ -292,7 +292,7 @@ def create_memory_cache
       PromptCache.new(
         ttl: config.cache_ttl,
         max_size: config.cache_max_size,
-        stale_ttl: config.cache_stale_ttl,
+        stale_ttl: config.normalized_stale_ttl,
         refresh_threads: config.cache_refresh_threads,
         logger: config.logger
       )
@@ -302,7 +302,7 @@ def create_rails_cache_adapter
       RailsCacheAdapter.new(
         ttl: config.cache_ttl,
         lock_timeout: config.cache_lock_timeout,
-        stale_ttl: config.cache_stale_ttl,
+        stale_ttl: config.normalized_stale_ttl,
         refresh_threads: config.cache_refresh_threads,
         logger: config.logger
       )

lib/langfuse/config.rb

@@ -49,7 +49,8 @@ class Config
     # @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, default: 0 when SWR disabled, cache_ttl when SWR enabled)
+    # @return [Integer, Symbol] Stale TTL in seconds (grace period for serving stale data, default: 0 when SWR disabled, cache_ttl when SWR enabled)
+    #   Accepts :indefinite which is automatically normalized to 1000 years (31,536,000,000 seconds) for practical "never expire" behavior.
     attr_accessor :cache_stale_ttl
 
     # @return [Integer] Number of background threads for cache refresh
@@ -81,6 +82,9 @@ class Config
     DEFAULT_FLUSH_INTERVAL = 10
     DEFAULT_JOB_QUEUE = :default
 
+    # Number of seconds representing indefinite cache duration (~1000 years)
+    INDEFINITE_SECONDS = 1000 * 365 * 24 * 60 * 60
+
     # Initialize a new Config object
     #
     # @yield [config] Optional block for configuration
@@ -119,7 +123,6 @@ 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
 
@@ -134,6 +137,23 @@ def validate!
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+    # Normalize stale_ttl value
+    #
+    # Converts :indefinite to 1000 years in seconds for practical "never expire"
+    # behavior while keeping the value finite for calculations.
+    #
+    # @return [Integer] Normalized stale TTL in seconds
+    #
+    # @example
+    #   config.cache_stale_ttl = 300
+    #   config.normalized_stale_ttl # => 300
+    #
+    #   config.cache_stale_ttl = :indefinite
+    #   config.normalized_stale_ttl # => 31536000000
+    def normalized_stale_ttl
+      cache_stale_ttl == :indefinite ? INDEFINITE_SECONDS : cache_stale_ttl
+    end
+
     private
 
     def default_logger
@@ -153,9 +173,10 @@ def validate_cache_backend!
     end
 
     def validate_swr_config!
-      if cache_stale_ttl.nil? || cache_stale_ttl.negative?
+      # Allow :indefinite symbol, but validate numeric values
+      if cache_stale_ttl.nil? || (cache_stale_ttl.is_a?(Integer) && cache_stale_ttl.negative?)
         raise ConfigurationError,
-              "cache_stale_ttl must be non-negative"
+              "cache_stale_ttl must be non-negative or :indefinite"
       end
 
       return unless cache_refresh_threads.nil? || cache_refresh_threads <= 0

lib/langfuse/prompt_cache.rb

@@ -59,13 +59,14 @@ 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: 0, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
+    # @param stale_ttl [Integer] Stale TTL for SWR in seconds (default: 0, SWR disabled).
+    #   Note: :indefinite is normalized to 1000 years by Config before being passed here.
     # @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: 0, refresh_threads: 5, logger: default_logger)
       @ttl = ttl
       @max_size = max_size
-      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl)
+      @stale_ttl = stale_ttl
       @logger = logger
       @cache = {}
       @monitor = Monitor.new

lib/langfuse/rails_cache_adapter.rb

@@ -24,7 +24,8 @@ 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: 0, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
+    # @param stale_ttl [Integer] Stale TTL for SWR in seconds (default: 0, SWR disabled).
+    #   Note: :indefinite is normalized to 1000 years by Config before being passed here.
     # @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,7 +36,7 @@ def initialize(ttl: 60, namespace: "langfuse", lock_timeout: 10, stale_ttl: 0, r
       @ttl = ttl
       @namespace = namespace
       @lock_timeout = lock_timeout
-      @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl)
+      @stale_ttl = stale_ttl
       @logger = logger
       initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
     end

lib/langfuse/stale_while_revalidate.rb

@@ -18,11 +18,11 @@ module Langfuse
   #   class MyCache
   #     include Langfuse::StaleWhileRevalidate
   #
-  #     def initialize(ttl: 60, stale_ttl: nil)
+  #     def initialize(ttl: 60, stale_ttl: 0)
   #       @ttl = ttl
-  #       @stale_ttl = StaleWhileRevalidate.normalize_stale_ttl(stale_ttl || ttl)
+  #       @stale_ttl = stale_ttl
   #       @logger = Logger.new($stdout)
-  #       initialize_swr
+  #       initialize_swr if stale_ttl.positive?
   #     end
   #
   #     def cache_get(key)
@@ -42,26 +42,6 @@ module Langfuse
   #     end
   #   end
   module StaleWhileRevalidate
-    # 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.
@@ -115,10 +95,10 @@ def fetch_with_stale_while_revalidate(key, &)
 
     # Check if SWR is enabled
     #
-    # SWR is enabled when stale_ttl > ttl, meaning there's a grace period
+    # SWR is enabled when stale_ttl is positive, 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
+    # @return [Boolean] true if stale_ttl is positive
     def swr_enabled?
       stale_ttl.positive?
     end

spec/langfuse/client_spec.rb

@@ -171,6 +171,44 @@ class << self
         end.to raise_error(Langfuse::ConfigurationError, /cache_backend must be one of/)
       end
     end
+
+    context "with :indefinite stale_ttl" do
+      it "normalizes :indefinite to INDEFINITE_SECONDS via normalized_stale_ttl method" do
+        config = Langfuse::Config.new do |c|
+          c.public_key = "pk_test_123"
+          c.secret_key = "sk_test_456"
+          c.cache_stale_ttl = :indefinite
+        end
+
+        expect(config.normalized_stale_ttl).to eq(Langfuse::Config::INDEFINITE_SECONDS)
+      end
+
+      it "passes normalized stale_ttl to cache instances" do
+        config = Langfuse::Config.new do |c|
+          c.public_key = "pk_test_123"
+          c.secret_key = "sk_test_456"
+          c.cache_ttl = 60
+          c.cache_stale_ttl = :indefinite
+        end
+
+        client = described_class.new(config)
+        cache = client.api_client.cache
+
+        expect(cache.stale_ttl).to eq(Langfuse::Config::INDEFINITE_SECONDS)
+      end
+
+      it "normalizes :indefinite when set via cache_stale_while_revalidate" do
+        config = Langfuse::Config.new do |c|
+          c.public_key = "pk_test_123"
+          c.secret_key = "sk_test_456"
+          c.cache_ttl = 60
+          c.cache_stale_while_revalidate = true
+          c.cache_stale_ttl = :indefinite
+        end
+
+        expect(config.normalized_stale_ttl).to eq(Langfuse::Config::INDEFINITE_SECONDS)
+      end
+    end
   end
 
   describe "#get_prompt" do

spec/langfuse/config_spec.rb

@@ -158,14 +158,6 @@
         )
       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
@@ -228,15 +220,15 @@
         config.cache_stale_ttl = -1
         expect { config.validate! }.to raise_error(
           Langfuse::ConfigurationError,
-          "cache_stale_ttl must be non-negative"
+          "cache_stale_ttl must be non-negative or :indefinite"
         )
       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"
+          "cache_stale_ttl must be non-negative or :indefinite"
         )
       end
 
@@ -249,6 +241,11 @@
         config.cache_stale_ttl = 300
         expect { config.validate! }.not_to raise_error
       end
+
+      it "allows :indefinite symbol" do
+        config.cache_stale_ttl = :indefinite
+        expect { config.validate! }.not_to raise_error
+      end
     end
 
     context "when cache_refresh_threads is invalid" do
@@ -363,6 +360,11 @@
       expect(config.cache_stale_ttl).to eq(600)
     end
 
+    it "allows setting cache_stale_ttl to :indefinite" do
+      config.cache_stale_ttl = :indefinite
+      expect(config.cache_stale_ttl).to eq(:indefinite)
+    end
+
     it "allows setting cache_refresh_threads" do
       config.cache_refresh_threads = 10
       expect(config.cache_refresh_threads).to eq(10)
@@ -443,4 +445,47 @@
       expect(Langfuse::Config::DEFAULT_CACHE_REFRESH_THREADS).to eq(5)
     end
   end
+
+  describe "#normalized_stale_ttl" do
+    let(:config) do
+      described_class.new do |c|
+        c.public_key = "pk_test"
+        c.secret_key = "sk_test"
+      end
+    end
+
+    it "returns the numeric value unchanged for regular TTL" do
+      config.cache_stale_ttl = 300
+      expect(config.normalized_stale_ttl).to eq(300)
+    end
+
+    it "returns 0 for zero TTL" do
+      config.cache_stale_ttl = 0
+      expect(config.normalized_stale_ttl).to eq(0)
+    end
+
+    it "returns INDEFINITE_SECONDS when cache_stale_ttl is :indefinite" do
+      config.cache_stale_ttl = :indefinite
+      expect(config.normalized_stale_ttl).to eq(Langfuse::Config::INDEFINITE_SECONDS)
+    end
+
+    it "does not mutate the original cache_stale_ttl value" do
+      config.cache_stale_ttl = :indefinite
+      config.normalized_stale_ttl # Call normalization
+      expect(config.cache_stale_ttl).to eq(:indefinite) # Original value preserved
+    end
+
+    it "works with SWR auto-configuration" do
+      config_swr = 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
+        c.cache_stale_ttl = :indefinite
+      end
+
+      expect(config_swr.cache_stale_ttl).to eq(:indefinite)
+      expect(config_swr.normalized_stale_ttl).to eq(Langfuse::Config::INDEFINITE_SECONDS)
+    end
+  end
 end

spec/langfuse/prompt_cache_spec.rb

@@ -79,11 +79,6 @@
         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 to 0 when not specified (SWR disabled)" do
         cache = described_class.new(ttl: 60)
         expect(cache.stale_ttl).to eq(0)