feat(prompt_cache): Add SWR to PromptCache

Author: drborges

lib/langfuse/api_client.rb

@@ -106,9 +106,9 @@ def list_prompts(page: nil, limit: nil)
     # @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)
-
       fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
     end
 
@@ -126,26 +126,19 @@ def fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
         fetch_with_swr_cache(cache_key, name, version, label)
       elsif distributed_cache_available?
         fetch_with_distributed_cache(cache_key, name, version, label)
-      elsif simple_cache_available?
-        fetch_with_simple_cache(cache_key, name, version, label)
       else
-        fetch_prompt_from_api(name, version: version, label: label)
+        fetch_with_simple_cache(cache_key, name, version, label)
       end
     end
 
     # Check if SWR cache is available
     def swr_cache_available?
-      cache&.respond_to?(:fetch_with_stale_while_revalidate)
+      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
-
-    # Check if simple cache is available
-    def simple_cache_available?
-      !cache.nil?
+      cache.respond_to?(:fetch_with_lock)
     end
 
     # Fetch with SWR cache

lib/langfuse/client.rb

@@ -151,17 +151,27 @@ def cache_enabled?
     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
         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.cache_stale_while_revalidate ? config.cache_stale_ttl : nil,
+        refresh_threads: config.cache_refresh_threads,
+        logger: config.logger
+      )
+    end
+
     def create_rails_cache_adapter
       RailsCacheAdapter.new(
         ttl: config.cache_ttl,

lib/langfuse/config.rb

@@ -154,14 +154,9 @@ def validate_swr_config!
         raise ConfigurationError, "cache_stale_ttl must be non-negative"
       end
 
-      if cache_refresh_threads.nil? || cache_refresh_threads <= 0
-        raise ConfigurationError, "cache_refresh_threads must be positive"
-      end
-
-      return unless cache_stale_while_revalidate && cache_backend != :rails
+      return unless cache_refresh_threads.nil? || cache_refresh_threads <= 0
 
-      raise ConfigurationError,
-            "cache_stale_while_revalidate requires cache_backend to be :rails"
+      raise ConfigurationError, "cache_refresh_threads must be positive"
     end
   end
 end

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,6 +15,8 @@ module Langfuse
   #   cache.get("greeting:1") # => prompt_data
   #
   class PromptCache
+    include StaleWhileRevalidate
+
     # Cache entry with data and expiration time
     #
     # Supports stale-while-revalidate pattern:
@@ -50,17 +53,24 @@ def expired?
       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, nil] Stale TTL for SWR (default: nil, disabled)
+    # @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
+      @logger = logger
       @cache = {}
       @monitor = Monitor.new
+      @locks = {} # Track locks for in-memory locking
+      initialize_swr(refresh_threads: refresh_threads) if stale_ttl
     end
 
     # Get a value from the cache
@@ -81,15 +91,16 @@ def get(key)
     #
     # @param key [String] Cache key
     # @param value [Object] Value to cache
+    # @param expires_in [Integer] Optional TTL override (default: uses @ttl)
     # @return [Object] The cached value
-    def set(key, value)
+    def set(key, value, expires_in: ttl)
       @monitor.synchronize do
         # Evict oldest entry if at max size
         evict_oldest if @cache.size >= max_size
 
         now = Time.now
-        fresh_until = now + ttl
-        stale_until = now + ttl
+        fresh_until = now + expires_in
+        stale_until = now + expires_in
         @cache[key] = CacheEntry.new(value, fresh_until, stale_until)
         value
       end
@@ -148,6 +159,62 @@ def self.build_key(name, version: nil, label: nil)
 
     private
 
+    # Implementation of StaleWhileRevalidate abstract methods
+
+    # Get value from cache (SWR interface)
+    #
+    # @param key [String] Cache key
+    # @return [Object, 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 [Object] Value to cache
+    # @param expires_in [Integer] TTL in seconds
+    # @return [Object] The cached value
+    def cache_set(key, value, expires_in: nil)
+      @monitor.synchronize do
+        # Evict oldest entry if at max size
+        evict_oldest if @cache.size >= max_size
+
+        # NOTE: expires_in is accepted for interface compatibility with StaleWhileRevalidate
+        # but not used here since CacheEntry objects manage their own expiration times
+        _ = expires_in
+        @cache[key] = value
+        value
+      end
+    end
+
+    # Acquire a refresh lock using in-memory locking
+    #
+    # @param lock_key [String] Lock key
+    # @return [Boolean] true if lock was acquired, false if already held
+    def acquire_refresh_lock(lock_key)
+      @monitor.synchronize do
+        return false if @locks[lock_key]
+
+        @locks[lock_key] = true
+        true
+      end
+    end
+
+    # Release a refresh lock
+    #
+    # @param lock_key [String] Lock key
+    # @return [void]
+    def release_refresh_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]
@@ -158,5 +225,12 @@ def evict_oldest
       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