langfuse-rb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae64454a24bf090bcaedf13432b8c2c7ecc0c1d986bc5ffdec8ad3f5ada1b2d5
-  data.tar.gz: 05dcbaaa1aa3aa90fcb75d42086a526c60914b3f88ce2fa0049b77d7cafc33cb
+  metadata.gz: 60270020fc35460c5e29381351bbca35f1cdfe8b7dfe05eca43a0fb20dc06b7b
+  data.tar.gz: 4951c9b1546de4c9d00bb3b3be4c5325c8edf4d5bf6f5ecab7d9520ab052451b
 SHA512:
-  metadata.gz: 1b8b91ba6180d4450fef21f59bcca7c06b21c2a5d336e70bf233ca3d2b4d325387f78950ac3ee2c41c4655a0199a4fbd03fdf07164cf224dba7bc2734af1f95c
-  data.tar.gz: 00d0a265e3f41cf6690f740b63c7d61853733b9701e1d1ea0630fe19a6d8b8022d8a1cd26b9eceb62133fe169fde093544d738ba3f258f765cd9ced0e2aecea9
+  metadata.gz: 84fa1fc6ea91bda9ddcaa32dd43cb457439e0e4cdee06e3f3df88aae9c54c5b10abd16cb120f234da28733ba6497c466d0ece7888410d7b2711815e13f3956ef
+  data.tar.gz: 785bd5801a8c6b0ecd7c94f43083bdd6f12463bb918fa5f4a6faee32924a87a5058cf9700b20984fa9e8964cb3070975235771ddfddabca115cb33538020b065

data/CHANGELOG.md

@@ -7,15 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-01-23
+
 ### Added
-- Create and update methods for prompts (#36)
+- Stale-while-revalidate (SWR) cache strategy for improved performance (#35)
+
+### Fixed
+- OpenTelemetry Baggage API method signatures for context propagation (#39)
 
+### Changed
+- Relaxed Faraday version constraint for better compatibility with older projects (#37)
 
 ## [0.2.0] - 2025-12-19
 
 ### Added
-- Prompt creation and update methods (`create_prompt`, `update_prompt`)
-- Extended prompt management documentation with create/update examples
+- Prompt creation and update methods (`create_prompt`, `update_prompt`) (#36)
 
 ## [0.1.0] - 2025-12-01
 
@@ -34,5 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/simplepractice/langfuse-rb/releases/tag/v0.1.0

data/README.md

@@ -14,7 +14,7 @@
 
 - 🎯 **Prompt Management** - Centralized prompt versioning with Mustache templating
 - 📊 **LLM Tracing** - Zero-boilerplate observability built on OpenTelemetry
-- ⚡ **Performance** - In-memory or Redis-backed caching with stampede protection
+- ⚡ **Performance** - In-memory or Redis-backed caching with stampede protection, both supporting stale-while-revalidate cache strategy
 - 💬 **Chat & Text Prompts** - First-class support for both formats
 - 🔄 **Automatic Retries** - Built-in exponential backoff for resilient API calls
 - 🛡️ **Fallback Support** - Graceful degradation when API unavailable
@@ -43,6 +43,10 @@ Langfuse.configure do |config|
   config.secret_key = ENV['LANGFUSE_SECRET_KEY']
   # Optional: for self-hosted instances
   config.base_url = ENV.fetch('LANGFUSE_BASE_URL', 'https://cloud.langfuse.com')
+
+  # Optional: Enable stale-while-revalidate for best performance
+  config.cache_backend = :rails  # or :memory
+  config.cache_stale_while_revalidate = true
 end
 ```
 
@@ -110,3 +114,6 @@ We welcome contributions! Please:
 - **[Langfuse Documentation](https://langfuse.com/docs)** - Platform documentation
 - **[API Reference](https://api.reference.langfuse.com)** - REST API reference
 
+## License
+
+[MIT](LICENSE)

data/lib/langfuse/api_client.rb

@@ -21,8 +21,7 @@ module Langfuse
   #     logger: Logger.new($stdout)
   #   )
   #
-  # rubocop:disable Metrics/ClassLength
-  class ApiClient
+  class ApiClient # rubocop:disable Metrics/ClassLength
     attr_reader :public_key, :secret_key, :base_url, :timeout, :logger, :cache
 
     # Initialize a new API client
@@ -107,26 +106,10 @@ module Langfuse
     # @raise [ApiError] for other API errors
     def get_prompt(name, version: nil, label: nil)
       raise ArgumentError, "Cannot specify both version and label" if version && label
+      return fetch_prompt_from_api(name, version: version, label: label) if cache.nil?
 
       cache_key = PromptCache.build_key(name, version: version, label: label)
-
-      # Use distributed lock if cache supports it (Rails.cache backend)
-      if cache.respond_to?(:fetch_with_lock)
-        cache.fetch_with_lock(cache_key) do
-          fetch_prompt_from_api(name, version: version, label: label)
-        end
-      elsif cache
-        # In-memory cache - use simple get/set pattern
-        cached_data = cache.get(cache_key)
-        return cached_data if cached_data
-
-        prompt_data = fetch_prompt_from_api(name, version: version, label: label)
-        cache.set(cache_key, prompt_data)
-        prompt_data
-      else
-        # No cache - fetch directly
-        fetch_prompt_from_api(name, version: version, label: label)
-      end
+      fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
     end
 
     # Create a new prompt (or new version if prompt with same name exists)
@@ -246,8 +229,63 @@ module Langfuse
       raise ApiError, "Batch send failed: #{e.message}"
     end
 
+    def shutdown
+      cache.shutdown if cache.respond_to?(:shutdown)
+    end
+
     private
 
+    # Fetch prompt using the most appropriate caching strategy available
+    #
+    # @param cache_key [String] The cache key for this prompt
+    # @param name [String] The name of the prompt
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label
+    # @return [Hash] The prompt data
+    def fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
+      if swr_cache_available?
+        fetch_with_swr_cache(cache_key, name, version, label)
+      elsif distributed_cache_available?
+        fetch_with_distributed_cache(cache_key, name, version, label)
+      else
+        fetch_with_simple_cache(cache_key, name, version, label)
+      end
+    end
+
+    # Check if SWR cache is available
+    def swr_cache_available?
+      cache.respond_to?(:swr_enabled?) && cache.swr_enabled?
+    end
+
+    # Check if distributed cache is available
+    def distributed_cache_available?
+      cache.respond_to?(:fetch_with_lock)
+    end
+
+    # Fetch with SWR cache
+    def fetch_with_swr_cache(cache_key, name, version, label)
+      cache.fetch_with_stale_while_revalidate(cache_key) do
+        fetch_prompt_from_api(name, version: version, label: label)
+      end
+    end
+
+    # Fetch with distributed cache (Rails.cache with stampede protection)
+    def fetch_with_distributed_cache(cache_key, name, version, label)
+      cache.fetch_with_lock(cache_key) do
+        fetch_prompt_from_api(name, version: version, label: label)
+      end
+    end
+
+    # Fetch with simple cache (in-memory cache)
+    def fetch_with_simple_cache(cache_key, name, version, label)
+      cached_data = cache.get(cache_key)
+      return cached_data if cached_data
+
+      prompt_data = fetch_prompt_from_api(name, version: version, label: label)
+      cache.set(cache_key, prompt_data)
+      prompt_data
+    end
+
     # Fetch a prompt from the API (without caching)
     #
     # @param name [String] The name of the prompt
@@ -408,4 +446,3 @@ module Langfuse
     end
   end
 end
-# rubocop:enable Metrics/ClassLength

data/lib/langfuse/client.rb

@@ -340,9 +340,12 @@ module Langfuse
 
     # Shutdown the client and flush any pending scores
     #
+    # Also shuts down the cache if it supports shutdown (e.g., SWR thread pool).
+    #
     # @return [void]
     def shutdown
       @score_client.shutdown
+      @api_client.shutdown
     end
 
     private
@@ -362,20 +365,37 @@ module Langfuse
     def create_cache
       case config.cache_backend
       when :memory
-        PromptCache.new(
-          ttl: config.cache_ttl,
-          max_size: config.cache_max_size
-        )
+        create_memory_cache
       when :rails
-        RailsCacheAdapter.new(
-          ttl: config.cache_ttl,
-          lock_timeout: config.cache_lock_timeout
-        )
+        create_rails_cache_adapter
       else
         raise ConfigurationError, "Unknown cache backend: #{config.cache_backend}"
       end
     end
 
+    # Create in-memory cache with SWR support if enabled
+    #
+    # @return [PromptCache]
+    def create_memory_cache
+      PromptCache.new(
+        ttl: config.cache_ttl,
+        max_size: config.cache_max_size,
+        stale_ttl: config.normalized_stale_ttl,
+        refresh_threads: config.cache_refresh_threads,
+        logger: config.logger
+      )
+    end
+
+    def create_rails_cache_adapter
+      RailsCacheAdapter.new(
+        ttl: config.cache_ttl,
+        lock_timeout: config.cache_lock_timeout,
+        stale_ttl: config.normalized_stale_ttl,
+        refresh_threads: config.cache_refresh_threads,
+        logger: config.logger
+      )
+    end
+
     # Build the appropriate prompt client based on prompt type
     #
     # @param prompt_data [Hash] The prompt data from API

data/lib/langfuse/config.rb

@@ -46,6 +46,16 @@ module Langfuse
     # @return [Integer] Lock timeout in seconds for distributed cache stampede protection
     attr_accessor :cache_lock_timeout
 
+    # @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, 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
+    attr_accessor :cache_refresh_threads
+
     # @return [Boolean] Use async processing for traces (requires ActiveJob)
     attr_accessor :tracing_async
 
@@ -65,11 +75,16 @@ module Langfuse
     DEFAULT_CACHE_MAX_SIZE = 1000
     DEFAULT_CACHE_BACKEND = :memory
     DEFAULT_CACHE_LOCK_TIMEOUT = 10
+    DEFAULT_CACHE_STALE_WHILE_REVALIDATE = false
+    DEFAULT_CACHE_REFRESH_THREADS = 5
     DEFAULT_TRACING_ASYNC = true
     DEFAULT_BATCH_SIZE = 50
     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
@@ -83,6 +98,9 @@ module Langfuse
       @cache_max_size = DEFAULT_CACHE_MAX_SIZE
       @cache_backend = DEFAULT_CACHE_BACKEND
       @cache_lock_timeout = DEFAULT_CACHE_LOCK_TIMEOUT
+      @cache_stale_while_revalidate = DEFAULT_CACHE_STALE_WHILE_REVALIDATE
+      @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
       @flush_interval = DEFAULT_FLUSH_INTERVAL
@@ -110,10 +128,29 @@ module Langfuse
               "cache_lock_timeout must be positive"
       end
 
+      validate_swr_config!
+
       validate_cache_backend!
     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
@@ -131,5 +168,37 @@ module Langfuse
       raise ConfigurationError,
             "cache_backend must be one of #{valid_backends.inspect}, got #{cache_backend.inspect}"
     end
+
+    def validate_swr_config!
+      validate_swr_stale_ttl!
+      validate_refresh_threads!
+    end
+
+    def validate_swr_stale_ttl!
+      # Check if SWR is enabled but stale_ttl is nil
+      if cache_stale_while_revalidate && cache_stale_ttl.nil?
+        raise ConfigurationError,
+              "cache_stale_ttl cannot be nil when cache_stale_while_revalidate is enabled. " \
+              "Set it to cache_ttl for a logical default, or use :indefinite for never-expiring cache."
+      end
+
+      # Validate that cache_stale_ttl is not nil (unless already caught by SWR check)
+      if cache_stale_ttl.nil?
+        raise ConfigurationError,
+              "cache_stale_ttl must be non-negative or :indefinite"
+      end
+
+      # Validate numeric values are non-negative
+      return unless cache_stale_ttl.is_a?(Integer) && cache_stale_ttl.negative?
+
+      raise ConfigurationError,
+            "cache_stale_ttl must be non-negative or :indefinite"
+    end
+
+    def validate_refresh_threads!
+      return unless cache_refresh_threads.nil? || cache_refresh_threads <= 0
+
+      raise ConfigurationError, "cache_refresh_threads must be positive"
+    end
   end
 end

data/lib/langfuse/prompt_cache.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require_relative "stale_while_revalidate"
 
 module Langfuse
   # Simple in-memory cache for prompt data with TTL
@@ -14,24 +15,63 @@ module Langfuse
   #   cache.get("greeting:1") # => prompt_data
   #
   class PromptCache
+    include StaleWhileRevalidate
+
     # Cache entry with data and expiration time
-    CacheEntry = Struct.new(:data, :expires_at) do
+    #
+    # Supports stale-while-revalidate pattern:
+    # - fresh_until: Time until entry is considered fresh (can be served immediately)
+    # - stale_until: Time until entry is considered stale (serve while revalidating in background)
+    # - After stale_until: Entry is expired (must revalidate synchronously)
+    CacheEntry = Struct.new(:data, :fresh_until, :stale_until) do
+      # Check if the cache entry is still fresh
+      #
+      # @return [Boolean] true if current time is before fresh_until
+      def fresh?
+        Time.now < fresh_until
+      end
+
+      # Check if the cache entry is stale but not expired
+      #
+      # Stale entries can be served immediately while a background
+      # revalidation occurs (stale-while-revalidate pattern)
+      #
+      # @return [Boolean] true if current time is between fresh_until and stale_until
+      def stale?
+        now = Time.now
+        now >= fresh_until && now < stale_until
+      end
+
+      # Check if the cache entry has expired
+      #
+      # Expired entries should not be served and must be revalidated
+      # synchronously before use.
+      #
+      # @return [Boolean] true if current time is at or after stale_until
       def expired?
-        Time.now > expires_at
+        Time.now >= stale_until
       end
     end
 
-    attr_reader :ttl, :max_size
+    attr_reader :ttl, :max_size, :stale_ttl, :logger
 
     # Initialize a new cache
     #
     # @param ttl [Integer] Time-to-live in seconds (default: 60)
     # @param max_size [Integer] Maximum cache size (default: 1000)
-    def initialize(ttl: 60, max_size: 1000)
+    # @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 = stale_ttl
+      @logger = logger
       @cache = {}
       @monitor = Monitor.new
+      @locks = {} # Track locks for in-memory locking
+      initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
     end
 
     # Get a value from the cache
@@ -58,8 +98,10 @@ module Langfuse
         # Evict oldest entry if at max size
         evict_oldest if @cache.size >= max_size
 
-        expires_at = Time.now + ttl
-        @cache[key] = CacheEntry.new(value, expires_at)
+        now = Time.now
+        fresh_until = now + ttl
+        stale_until = fresh_until + stale_ttl
+        @cache[key] = CacheEntry.new(value, fresh_until, stale_until)
         value
       end
     end
@@ -117,15 +159,84 @@ module Langfuse
 
     private
 
+    # Implementation of StaleWhileRevalidate abstract methods
+
+    # Get value from cache (SWR interface)
+    #
+    # @param key [String] Cache key
+    # @return [PromptCache::CacheEntry, nil] Cached value
+    def cache_get(key)
+      @monitor.synchronize do
+        @cache[key]
+      end
+    end
+
+    # Set value in cache (SWR interface)
+    #
+    # @param key [String] Cache key
+    # @param value [PromptCache::CacheEntry] Value to cache
+    # @return [PromptCache::CacheEntry] The cached value
+    def cache_set(key, value)
+      @monitor.synchronize do
+        # Evict oldest entry if at max size
+        evict_oldest if @cache.size >= max_size
+
+        @cache[key] = value
+        value
+      end
+    end
+
+    # Acquire a lock using in-memory locking
+    #
+    # Prevents duplicate background refreshes from different threads within
+    # the same process. This is NOT distributed locking - it only works
+    # within a single process. For distributed locking, use RailsCacheAdapter.
+    #
+    # **MEMORY LEAK WARNING**: Locks are stored in a hash and only deleted on
+    # release_lock. If a refresh thread crashes or is killed externally (e.g., Thread#kill)
+    # between acquire_lock and release_lock, the lock persists forever. Unlike Redis locks
+    # which have TTL expiration, in-memory locks have no timeout. For production use with
+    # SWR, prefer RailsCacheAdapter to avoid lock accumulation and potential memory exhaustion.
+    #
+    # @param lock_key [String] Lock key
+    # @return [Boolean] true if lock was acquired, false if already held
+    def acquire_lock(lock_key)
+      @monitor.synchronize do
+        return false if @locks[lock_key]
+
+        @locks[lock_key] = true
+        true
+      end
+    end
+
+    # Release a lock
+    #
+    # @param lock_key [String] Lock key
+    # @return [void]
+    def release_lock(lock_key)
+      @monitor.synchronize do
+        @locks.delete(lock_key)
+      end
+    end
+
+    # In-memory cache helper methods
+
     # Evict the oldest entry from cache
     #
     # @return [void]
     def evict_oldest
       return if @cache.empty?
 
-      # Find entry with earliest expiration
-      oldest_key = @cache.min_by { |_key, entry| entry.expires_at }&.first
+      # Find entry with earliest expiration (using stale_until as expiration time)
+      oldest_key = @cache.min_by { |_key, entry| entry.stale_until }&.first
       @cache.delete(oldest_key) if oldest_key
     end
+
+    # Create a default logger
+    #
+    # @return [Logger]
+    def default_logger
+      Logger.new($stdout, level: Logger::WARN)
+    end
   end
 end

data/lib/langfuse/propagation.rb

@@ -364,7 +364,6 @@ module Langfuse
     def self._get_span_key_from_baggage_key(baggage_key)
       return nil unless baggage_key.start_with?(BAGGAGE_PREFIX)
 
-      # Remove prefix
       suffix = baggage_key[BAGGAGE_PREFIX.length..]
 
       # Handle metadata keys (format: langfuse_metadata_{key_name})
@@ -373,17 +372,7 @@ module Langfuse
         return "#{OtelAttributes::TRACE_METADATA}.#{metadata_key}"
       end
 
-      # Map standard keys
-      case suffix
-      when "user_id"
-        _get_propagated_span_key("user_id")
-      when "session_id"
-        _get_propagated_span_key("session_id")
-      when "version"
-        _get_propagated_span_key("version")
-      when "tags"
-        _get_propagated_span_key("tags")
-      end
+      SPAN_KEY_MAP[suffix]
     end
 
     # Check if baggage API is available
@@ -404,7 +393,7 @@ module Langfuse
     def self._extract_baggage_attributes(context)
       return {} unless baggage_available?
 
-      baggage = OpenTelemetry::Baggage.value(context: context)
+      baggage = OpenTelemetry::Baggage.values(context: context)
       return {} unless baggage.is_a?(Hash)
 
       attributes = {}
@@ -453,12 +442,12 @@ module Langfuse
       if key == "metadata" && value.is_a?(Hash)
         value.each do |k, v|
           entry_key = "#{baggage_key}_#{k}"
-          context = OpenTelemetry::Baggage.set_value(context: context, key: entry_key, value: v.to_s)
+          context = OpenTelemetry::Baggage.set_value(entry_key, v.to_s, context: context)
         end
       elsif key == "tags" && value.is_a?(Array)
-        context = OpenTelemetry::Baggage.set_value(context: context, key: baggage_key, value: value.join(","))
+        context = OpenTelemetry::Baggage.set_value(baggage_key, value.join(","), context: context)
       else
-        context = OpenTelemetry::Baggage.set_value(context: context, key: baggage_key, value: value.to_s)
+        context = OpenTelemetry::Baggage.set_value(baggage_key, value.to_s, context: context)
       end
       context
     rescue StandardError => e

data/lib/langfuse/rails_cache_adapter.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "prompt_cache"
+require_relative "stale_while_revalidate"
+
 module Langfuse
   # Rails.cache adapter for distributed caching with Redis
   #
@@ -12,20 +15,30 @@ module Langfuse
   #   adapter.get("greeting:1") # => prompt_data
   #
   class RailsCacheAdapter
-    attr_reader :ttl, :namespace, :lock_timeout
+    include StaleWhileRevalidate
+
+    attr_reader :ttl, :namespace, :lock_timeout, :stale_ttl, :thread_pool, :logger
 
     # Initialize a new Rails.cache adapter
     #
     # @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] 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
-    def initialize(ttl: 60, namespace: "langfuse", lock_timeout: 10)
+    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 = stale_ttl
+      @logger = logger
+      initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
     end
 
     # Get a value from the cache
@@ -42,14 +55,57 @@ module Langfuse
     # @param value [Object] Value to cache
     # @return [Object] The cached value
     def set(key, value)
-      Rails.cache.write(namespaced_key(key), value, expires_in: ttl)
+      # Calculate expiration: use total_ttl if SWR enabled, otherwise just ttl
+      expires_in = swr_enabled? ? total_ttl : ttl
+      Rails.cache.write(namespaced_key(key), value, expires_in:)
       value
     end
 
-    # Fetch a value from cache with distributed lock for stampede protection
+    # Clear the entire Langfuse cache namespace
+    #
+    # Note: This uses delete_matched which may not be available on all cache stores.
+    # Works with Redis, Memcached, and memory stores. File store support varies.
+    #
+    # @return [void]
+    def clear
+      # Delete all keys matching the namespace pattern
+      Rails.cache.delete_matched("#{namespace}:*")
+    end
+
+    # Get current cache size
+    #
+    # Note: Rails.cache doesn't provide a size method, so we return nil
+    # to indicate this operation is not supported.
+    #
+    # @return [nil]
+    def size
+      nil
+    end
+
+    # Check if cache is empty
+    #
+    # Note: Rails.cache doesn't provide an efficient way to check if empty,
+    # so we return false to indicate this operation is not supported.
+    #
+    # @return [Boolean] Always returns false (unsupported operation)
+    def empty?
+      false
+    end
+
+    # Build a cache key from prompt name and options
+    #
+    # @param name [String] Prompt name
+    # @param version [Integer, nil] Optional version
+    # @param label [String, nil] Optional label
+    # @return [String] Cache key
+    def self.build_key(name, version: nil, label: nil)
+      PromptCache.build_key(name, version: version, label: label)
+    end
+
+    # Fetch a value from cache with lock for stampede protection
     #
     # This method prevents cache stampedes (thundering herd) by ensuring only one
-    # process fetches from the source when the cache is empty. Other processes wait
+    # process/thread fetches from the source when the cache is empty. Others wait
     # for the first one to populate the cache.
     #
     # Uses exponential backoff: 50ms, 100ms, 200ms (3 retries max, ~350ms total).
@@ -60,7 +116,7 @@ module Langfuse
     # @return [Object] Cached or freshly fetched value
     #
     # @example
-    #   adapter.fetch_with_lock("greeting:v1") do
+    #   cache.fetch_with_lock("greeting:v1") do
     #     api_client.get_prompt("greeting")
     #   end
     def fetch_with_lock(key)
@@ -68,8 +124,8 @@ module Langfuse
       cached = get(key)
       return cached if cached
 
-      # 2. Cache miss - try to acquire distributed lock
-      lock_key = "#{namespaced_key(key)}:lock"
+      # 2. Cache miss - try to acquire lock
+      lock_key = build_lock_key(key)
 
       if acquire_lock(lock_key)
         begin
@@ -92,74 +148,57 @@ module Langfuse
       end
     end
 
-    # Clear the entire Langfuse cache namespace
-    #
-    # Note: This uses delete_matched which may not be available on all cache stores.
-    # Works with Redis, Memcached, and memory stores. File store support varies.
-    #
-    # @return [void]
-    def clear
-      # Delete all keys matching the namespace pattern
-      Rails.cache.delete_matched("#{namespace}:*")
-    end
+    private
 
-    # Get current cache size
-    #
-    # Note: Rails.cache doesn't provide a size method, so we return nil
-    # to indicate this operation is not supported.
-    #
-    # @return [nil]
-    def size
-      nil
-    end
+    # Implementation of StaleWhileRevalidate abstract methods
 
-    # Check if cache is empty
-    #
-    # Note: Rails.cache doesn't provide an efficient way to check if empty,
-    # so we return false to indicate this operation is not supported.
+    # Get value from cache (SWR interface)
     #
-    # @return [Boolean] Always returns false (unsupported operation)
-    def empty?
-      false
+    # @param key [String] Cache key
+    # @return [Object, nil] Cached value
+    def cache_get(key)
+      get(key)
     end
 
-    # Build a cache key from prompt name and options
+    # Set value in cache (SWR interface)
     #
-    # @param name [String] Prompt name
-    # @param version [Integer, nil] Optional version
-    # @param label [String, nil] Optional label
-    # @return [String] Cache key
-    def self.build_key(name, version: nil, label: nil)
-      PromptCache.build_key(name, version: version, label: label)
+    # @param key [String] Cache key
+    # @param value [Object] Value to cache (expects CacheEntry)
+    # @return [Object] The cached value
+    def cache_set(key, value)
+      set(key, value)
     end
 
-    private
-
-    # Add namespace prefix to cache key
+    # Build lock key with namespace
     #
-    # @param key [String] Original cache key
-    # @return [String] Namespaced cache key
-    def namespaced_key(key)
-      "#{namespace}:#{key}"
+    # Used for both fetch operations (stampede protection) and refresh operations
+    # (preventing duplicate background refreshes).
+    #
+    # @param key [String] Cache key
+    # @return [String] Namespaced lock key
+    def build_lock_key(key)
+      "#{namespaced_key(key)}:lock"
     end
 
-    # Acquire a distributed lock using Rails.cache
+    # Acquire a lock using Rails.cache
     #
-    # Uses atomic "write if not exists" operation to ensure only one process
-    # can acquire the lock.
+    # Used for both fetch operations and refresh operations.
+    # Uses the configured lock_timeout for all locking scenarios.
     #
     # @param lock_key [String] Full lock key (already namespaced)
-    # @return [Boolean] true if lock was acquired, false if already held by another process
+    # @return [Boolean] true if lock was acquired, false if already held
     def acquire_lock(lock_key)
       Rails.cache.write(
         lock_key,
         true,
         unless_exist: true, # Atomic: only write if key doesn't exist
-        expires_in: lock_timeout # Auto-expire to prevent deadlocks
+        expires_in: lock_timeout # Use configured lock timeout
       )
     end
 
-    # Release a distributed lock
+    # Release a lock
+    #
+    # Used for both fetch and refresh operations.
     #
     # @param lock_key [String] Full lock key (already namespaced)
     # @return [void]
@@ -172,7 +211,7 @@ module Langfuse
     # Uses exponential backoff: 50ms, 100ms, 200ms (3 retries, ~350ms total).
     # This gives the lock holder time to fetch and populate the cache.
     #
-    # @param key [String] Cache key (not namespaced)
+    # @param key [String] Cache key
     # @return [Object, nil] Cached value if found, nil if still empty after waiting
     def wait_for_cache(key)
       intervals = [0.05, 0.1, 0.2] # 50ms, 100ms, 200ms (exponential backoff)
@@ -186,6 +225,16 @@ module Langfuse
       nil # Cache still empty after all retries
     end
 
+    # Rails.cache-specific helper methods
+
+    # Add namespace prefix to cache key
+    #
+    # @param key [String] Original cache key
+    # @return [String] Namespaced cache key
+    def namespaced_key(key)
+      "#{namespace}:#{key}"
+    end
+
     # Validate that Rails.cache is available
     #
     # @raise [ConfigurationError] if Rails.cache is not available
@@ -196,5 +245,16 @@ module Langfuse
       raise ConfigurationError,
             "Rails.cache is not available. Rails cache backend requires Rails with a configured cache store."
     end
+
+    # Create a default logger
+    #
+    # @return [Logger]
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        Logger.new($stdout, level: Logger::WARN)
+      end
+    end
   end
 end

data/lib/langfuse/stale_while_revalidate.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Langfuse
+  # Stale-While-Revalidate caching pattern module
+  #
+  # Provides SWR functionality for cache implementations. When included,
+  # allows serving stale data immediately while refreshing in the background.
+  #
+  # Including classes must implement:
+  # - cache_get(key) - Read from cache
+  # - cache_set(key, value) - Write to cache
+  # - acquire_lock(lock_key) - Acquire lock for background refresh
+  # - release_lock(lock_key) - Release refresh lock
+  #
+  # @example
+  #   class MyCache
+  #     include Langfuse::StaleWhileRevalidate
+  #
+  #     def initialize(ttl: 60, stale_ttl: 0)
+  #       @ttl = ttl
+  #       @stale_ttl = stale_ttl
+  #       @logger = Logger.new($stdout)
+  #       initialize_swr if stale_ttl.positive?
+  #     end
+  #
+  #     def cache_get(key)
+  #       @storage[key]
+  #     end
+  #
+  #     def cache_set(key, value)
+  #       @storage[key] = value
+  #     end
+  #
+  #     def acquire_lock(lock_key)
+  #       # Implementation-specific lock acquisition
+  #     end
+  #
+  #     def release_lock(lock_key)
+  #       # Implementation-specific lock release
+  #     end
+  #   end
+  module StaleWhileRevalidate
+    # Initialize SWR infrastructure
+    #
+    # Must be called by including class after setting @stale_ttl, @ttl, and @logger.
+    # Typically called in the class's initialize method when stale_ttl is provided.
+    #
+    # @param refresh_threads [Integer] Number of background refresh threads (default: 5)
+    # @return [void]
+    def initialize_swr(refresh_threads: 5)
+      @thread_pool = initialize_thread_pool(refresh_threads)
+    end
+
+    # Fetch a value from cache with Stale-While-Revalidate support
+    #
+    # This method implements SWR caching: serves stale data immediately while
+    # refreshing in the background. Requires SWR to be enabled (stale_ttl must be positive).
+    #
+    # Three cache states:
+    # - FRESH: Return immediately, no action needed
+    # - STALE: Return stale data + trigger background refresh
+    # - EXPIRED: Must fetch fresh data synchronously
+    #
+    # @param key [String] Cache key
+    # @yield Block to execute to fetch fresh data
+    # @return [Object] Cached, stale, or freshly fetched value
+    # @raise [ConfigurationError] if SWR is not enabled (stale_ttl is not positive)
+    #
+    # @example
+    #   cache.fetch_with_stale_while_revalidate("greeting:v1") do
+    #     api_client.get_prompt("greeting")
+    #   end
+    def fetch_with_stale_while_revalidate(key, &)
+      raise ConfigurationError, "fetch_with_stale_while_revalidate requires a positive stale_ttl" unless swr_enabled?
+
+      entry = cache_get(key)
+
+      if entry&.fresh?
+        # FRESH - return immediately
+        logger.debug("CACHE HIT!")
+        entry.data
+      elsif entry&.stale?
+        # REVALIDATE - return stale + refresh in background
+        logger.debug("CACHE STALE!")
+        schedule_refresh(key, &)
+        entry.data # Instant response!
+      else
+        # MISS - must fetch synchronously
+        logger.debug("CACHE MISS!")
+        fetch_and_cache(key, &)
+      end
+    end
+
+    # Check if SWR is enabled
+    #
+    # 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 positive
+    def swr_enabled?
+      stale_ttl.positive?
+    end
+
+    # Shutdown the cache refresh thread pool gracefully
+    #
+    # @return [void]
+    def shutdown
+      return unless @thread_pool
+
+      @thread_pool.shutdown
+      @thread_pool.wait_for_termination(5) # Wait up to 5 seconds
+    end
+
+    private
+
+    # Initialize thread pool for background refresh operations
+    #
+    # @param refresh_threads [Integer] Maximum number of refresh threads
+    # @return [Concurrent::CachedThreadPool]
+    def initialize_thread_pool(refresh_threads)
+      Concurrent::CachedThreadPool.new(
+        max_threads: refresh_threads,
+        min_threads: 0,
+        max_queue: 50,
+        fallback_policy: :discard
+      )
+    end
+
+    # Schedule a background refresh for a cache key
+    #
+    # Prevents duplicate refreshes by using a fetch lock. If another process/thread
+    # is already refreshing this key, this method returns immediately.
+    #
+    # Errors during refresh are caught and logged to prevent thread crashes.
+    #
+    # @param key [String] Cache key
+    # @yield Block to execute to fetch fresh data
+    # @return [void]
+    def schedule_refresh(key, &block)
+      # Prevent duplicate refreshes
+      lock_key = build_lock_key(key)
+      return unless acquire_lock(lock_key)
+
+      @thread_pool.post do
+        value = yield block
+        set_cache_entry(key, value)
+      rescue StandardError => e
+        logger.error("Langfuse cache refresh failed for key '#{key}': #{e.class} - #{e.message}")
+      ensure
+        release_lock(lock_key)
+      end
+    end
+
+    # Fetch data and cache it with SWR metadata
+    #
+    # @param key [String] Cache key
+    # @yield Block to execute to fetch fresh data
+    # @return [Object] Freshly fetched value
+    def fetch_and_cache(key, &block)
+      value = yield block
+      set_cache_entry(key, value)
+    end
+
+    # Set value in cache with SWR metadata (CacheEntry)
+    #
+    # @param key [String] Cache key
+    # @param value [Object] Value to cache
+    # @return [Object] The cached value
+    def set_cache_entry(key, value)
+      now = Time.now
+      fresh_until = now + ttl
+      stale_until = fresh_until + stale_ttl
+      entry = PromptCache::CacheEntry.new(value, fresh_until, stale_until)
+
+      cache_set(key, entry)
+
+      value
+    end
+
+    # Build a lock key for fetch operations
+    #
+    # Can be overridden by including class if custom key format is needed.
+    #
+    # @param key [String] Cache key
+    # @return [String] Lock key
+    def build_lock_key(key)
+      "#{key}:lock"
+    end
+
+    # Calculate total TTL (fresh + stale)
+    #
+    # @return [Integer] Total TTL in seconds
+    def total_ttl
+      ttl + stale_ttl
+    end
+
+    # Abstract methods that must be implemented by including class
+
+    # Get a value from cache
+    #
+    # @param key [String] Cache key
+    # @return [Object, nil] Cached value or nil
+    # @raise [NotImplementedError] if not implemented by including class
+    def cache_get(_key)
+      raise NotImplementedError, "#{self.class} must implement #cache_get"
+    end
+
+    # Set a value in cache
+    #
+    # @param key [String] Cache key
+    # @param value [Object] Value to cache
+    # @return [Object] The cached value
+    # @raise [NotImplementedError] if not implemented by including class
+    def cache_set(_key, _value)
+      raise NotImplementedError, "#{self.class} must implement #cache_set"
+    end
+
+    # Acquire a lock
+    #
+    # @param lock_key [String] Lock key
+    # @return [Boolean] true if lock was acquired
+    # @raise [NotImplementedError] if not implemented by including class
+    def acquire_lock(_lock_key)
+      raise NotImplementedError, "#{self.class} must implement #acquire_lock"
+    end
+
+    # Release a lock
+    #
+    # @param lock_key [String] Lock key
+    # @return [void]
+    # @raise [NotImplementedError] if not implemented by including class
+    def release_lock(_lock_key)
+      raise NotImplementedError, "#{self.class} must implement #release_lock"
+    end
+
+    # Get TTL value
+    #
+    # @return [Integer] TTL in seconds
+    # @raise [NotImplementedError] if not implemented by including class
+    def ttl
+      @ttl || raise(NotImplementedError, "#{self.class} must provide @ttl")
+    end
+
+    # Get stale TTL value
+    #
+    # @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")
+    end
+
+    # Get logger instance
+    #
+    # @return [Logger] Logger instance
+    # @raise [NotImplementedError] if not implemented by including class
+    def logger
+      @logger || raise(NotImplementedError, "#{self.class} must provide @logger")
+    end
+  end
+end

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - SimplePractice
@@ -13,30 +13,42 @@ dependencies:
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: mustache
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +63,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
   requirement: !ruby/object:Gem::Requirement
@@ -146,6 +172,7 @@ files:
 - lib/langfuse/rails_cache_adapter.rb
 - lib/langfuse/score_client.rb
 - lib/langfuse/span_processor.rb
+- lib/langfuse/stale_while_revalidate.rb
 - lib/langfuse/text_prompt_client.rb
 - lib/langfuse/types.rb
 - lib/langfuse/version.rb
@@ -171,7 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Ruby SDK for Langfuse - LLM observability and prompt management
 test_files: []