langfuse-rb 0.8.0 → 0.10.0

data/lib/langfuse/prompt_cache.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require "base64"
 require_relative "stale_while_revalidate"
 
 module Langfuse
@@ -14,9 +15,15 @@ module Langfuse
   #   cache.set("greeting:1", prompt_data)
   #   cache.get("greeting:1") # => prompt_data
   #
+  # rubocop:disable Metrics/ClassLength
   class PromptCache
     include StaleWhileRevalidate
 
+    # Caps the per-name generation map. Without a cap, long-lived processes
+    # that invalidate across many distinct prompts grow it unboundedly; LRU
+    # eviction keeps the working set live and lets cold names go.
+    MAX_NAME_GENERATIONS = 1024
+
     # Cache entry with data and expiration time
     #
     # Supports stale-while-revalidate pattern:
@@ -79,6 +86,9 @@ module Langfuse
       @stale_ttl = stale_ttl
       @logger = logger
       @cache = {}
+      @global_generation = 0
+      @name_generations = {}
+      @name_generation_counter = 0
       @monitor = Monitor.new
       @locks = {} # Track locks for in-memory locking
       initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
@@ -98,24 +108,45 @@ module Langfuse
       end
     end
 
+    # Read a raw cache entry, including stale entries.
+    #
+    # @param key [String] Cache key
+    # @return [CacheEntry, nil] Raw cache entry
+    def entry(key)
+      @monitor.synchronize do
+        @cache[key]
+      end
+    end
+
     # Set a value in the cache
     #
     # @param key [String] Cache key
     # @param value [Object] Value to cache
     # @return [Object] The cached value
-    def set(key, value)
+    def set(key, value, ttl: nil, stale_ttl: nil)
       @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 = fresh_until + stale_ttl
-        @cache[key] = CacheEntry.new(value, fresh_until, stale_until)
+        # TTL math is inlined (not extracted to a helper) to keep this hot path
+        # allocation-free apart from the CacheEntry below.
+        effective_ttl = ttl.nil? ? self.ttl : ttl
+        effective_stale_ttl = stale_ttl.nil? ? self.stale_ttl : stale_ttl
+        fresh_until = Time.now + effective_ttl
+        @cache[key] = CacheEntry.new(value, fresh_until, fresh_until + effective_stale_ttl)
         value
       end
     end
 
+    # Delete one generated storage key.
+    #
+    # @param key [String] Generated storage key
+    # @return [Boolean] true if an entry was removed
+    def delete(key)
+      @monitor.synchronize do
+        !@cache.delete(key).nil?
+      end
+    end
+
     # Clear the entire cache
     #
     # @return [void]
@@ -125,6 +156,65 @@ module Langfuse
       end
     end
 
+    # Logically invalidate every generated storage key.
+    #
+    # @return [Integer] New global generation
+    def clear_logically
+      @monitor.synchronize do
+        @global_generation += 1
+      end
+    end
+
+    # Logically invalidate every cache variant for one prompt name.
+    #
+    # Generations come from a monotonic global counter, not a per-name counter,
+    # so an evicted name re-entering the map can't reuse a generation value
+    # that's still embedded in a stale @cache entry.
+    #
+    # @param name [String] Prompt name
+    # @return [Integer] New name generation
+    def invalidate_name(name)
+      @monitor.synchronize do
+        name_str = name.to_s
+        @name_generations.delete(name_str)
+        @name_generations.shift if @name_generations.size >= MAX_NAME_GENERATIONS
+        @name_generation_counter += 1
+        @name_generations[name_str] = @name_generation_counter
+      end
+    end
+
+    # Build a generated storage key for the current cache generation.
+    #
+    # @param logical_key [String] Stable logical cache identity
+    # @param name [String] Prompt name
+    # @return [String] Generated storage key
+    def storage_key(logical_key, name:)
+      @monitor.synchronize do
+        self.class.storage_key(
+          logical_key,
+          name: name,
+          global_generation: @global_generation,
+          name_generation: @name_generations.fetch(name.to_s, 0)
+        )
+      end
+    end
+
+    # @return [Hash] Prompt cache statistics
+    def stats
+      @monitor.synchronize do
+        counts = count_entries_by_generation
+        {
+          backend: CacheBackend::MEMORY,
+          enabled: true,
+          current_generation_entries: counts.fetch(:current),
+          orphaned_entries: counts.fetch(:orphaned),
+          total_entries: @cache.size,
+          global_generation: @global_generation,
+          unsupported_counts: []
+        }
+      end
+    end
+
     # Remove expired entries from cache
     #
     # @return [Integer] Number of entries removed
@@ -154,6 +244,15 @@ module Langfuse
       end
     end
 
+    # Validate that the memory cache backend is usable.
+    #
+    # @return [Boolean]
+    # rubocop:disable Naming/PredicateMethod
+    def validate!
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
     # Build a cache key from prompt name and options
     #
     # @param name [String] Prompt name
@@ -168,6 +267,18 @@ module Langfuse
       key
     end
 
+    # Build a generated storage key from generation metadata.
+    #
+    # @param logical_key [String] Stable logical cache identity
+    # @param name [String] Prompt name
+    # @param global_generation [Integer] Global cache generation
+    # @param name_generation [Integer] Prompt-name cache generation
+    # @return [String] Generated storage key
+    def self.storage_key(logical_key, name:, global_generation:, name_generation:)
+      encoded_name = Base64.urlsafe_encode64(name.to_s, padding: false)
+      "g#{global_generation}:n#{encoded_name}:#{name_generation}:#{logical_key}"
+    end
+
     private
 
     # Implementation of StaleWhileRevalidate abstract methods
@@ -187,7 +298,7 @@ module Langfuse
     # @param key [String] Cache key
     # @param value [PromptCache::CacheEntry] Value to cache
     # @return [PromptCache::CacheEntry] The cached value
-    def cache_set(key, value)
+    def cache_set(key, value, **_options)
       @monitor.synchronize do
         # Evict oldest entry if at max size
         evict_oldest if @cache.size >= max_size
@@ -230,6 +341,29 @@ module Langfuse
       end
     end
 
+    def count_entries_by_generation
+      @cache.each_key.with_object({ current: 0, orphaned: 0 }) do |key, counts|
+        if current_generation_key?(key)
+          counts[:current] += 1
+        else
+          counts[:orphaned] += 1
+        end
+      end
+    end
+
+    def current_generation_key?(key)
+      parts = key.split(":", 4)
+      return false unless parts.size == 4
+      return false unless parts[0].start_with?("g") && parts[1].start_with?("n")
+
+      global = Integer(parts[0][1..])
+      name = Base64.urlsafe_decode64(parts[1][1..])
+      name_generation = Integer(parts[2])
+      global == @global_generation && name_generation == @name_generations.fetch(name, 0)
+    rescue ArgumentError
+      false
+    end
+
     # In-memory cache helper methods
 
     # Evict the oldest entry from cache
@@ -250,4 +384,5 @@ module Langfuse
       Logger.new($stdout, level: Logger::WARN)
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/langfuse/prompt_cache_events.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Prompt cache event emission for ApiClient.
+  #
+  # Includers must expose:
+  # - `cache_backend_name` — used in {#event_payload} to tag the cache backend
+  # - `logger` — used to warn on observer/notifier failures
+  module PromptCacheEvents
+    # ActiveSupport::Notifications event name used for prompt cache events.
+    PROMPT_CACHE_NOTIFICATION = "prompt_cache.langfuse"
+
+    # Configure prompt cache event dispatch. Wraps the observer once into a
+    # 1-arg callable so the per-event hot path never re-checks arity.
+    #
+    # @param cache_observer [#call, nil] Optional observer
+    # @return [void]
+    def setup_prompt_cache_events(cache_observer:)
+      @cache_observer_callable = wrap_cache_observer(cache_observer)
+      @active_support_notifications = defined?(ActiveSupport::Notifications) ? ActiveSupport::Notifications : nil
+    end
+
+    # Emit a prompt cache event to configured hooks. Accepts an eager payload
+    # hash or a block that builds one. The block is only evaluated when at
+    # least one listener is active, avoiding hash allocations on the hot path.
+    #
+    # @param event [Symbol] Event name
+    # @param payload [Hash, nil] Event payload (omit when passing a block)
+    # @yieldreturn [Hash] Lazily constructed payload
+    # @return [void]
+    def emit_prompt_cache_event(event, payload = nil)
+      observer_callable = @cache_observer_callable
+      as_listening = active_support_listening?
+      return if observer_callable.nil? && !as_listening
+
+      payload ||= block_given? ? yield : {}
+      normalized_payload = payload.merge(event: event.to_sym)
+      notify_cache_observer(normalized_payload) if observer_callable
+      notify_active_support(normalized_payload) if as_listening
+    end
+
+    # Emit a fallback event for a prompt fetch that fell back to caller-provided content.
+    #
+    # @param key [PromptCacheKey] Logical and storage cache key
+    # @param cache_status [Symbol] Cache status to report
+    # @param error [StandardError] The error that triggered the fallback
+    # @return [void]
+    def emit_prompt_fallback_event(key, cache_status:, error:)
+      emit_prompt_cache_event(:fallback) do
+        event_payload(key, cache_status, CacheSource::FALLBACK,
+                      error_class: error.class.name, error_message: error.message)
+      end
+    end
+
+    private
+
+    # @api private
+    def event_payload(key, cache_status, source, extra = {})
+      {
+        name: key.name,
+        version: key.version,
+        label: key.resolved_label,
+        logical_key: key.logical_key,
+        storage_key: key.storage_key,
+        backend: cache_backend_name,
+        cache_status: cache_status,
+        source: source
+      }.merge(extra)
+    end
+
+    # @api private
+    def notify_cache_observer(payload)
+      @cache_observer_callable.call(payload)
+    rescue StandardError => e
+      logger.warn("Langfuse prompt cache observer failed: #{e.class} - #{e.message}")
+    end
+
+    # @api private
+    def active_support_listening?
+      return false unless @active_support_notifications
+
+      notifier = @active_support_notifications.notifier
+      # Defensive: notifier stand-ins (test fakes, AS::Notifications forks,
+      # very old AS versions) may not implement listening?. Assume they're
+      # listening so we still attempt to instrument; notify_active_support
+      # rescues failures.
+      return true unless notifier.respond_to?(:listening?)
+
+      notifier.listening?(PROMPT_CACHE_NOTIFICATION)
+    end
+
+    # @api private
+    def notify_active_support(payload)
+      @active_support_notifications.instrument(PROMPT_CACHE_NOTIFICATION, payload)
+    rescue StandardError => e
+      logger.warn("Langfuse ActiveSupport cache notification failed: #{e.class} - #{e.message}")
+    end
+
+    # @api private
+    def wrap_cache_observer(observer)
+      return nil if observer.nil?
+
+      if observer.method(:call).arity == 1
+        ->(payload) { observer.call(payload) }
+      else
+        ->(payload) { observer.call(payload[:event], payload) }
+      end
+    end
+  end
+end

data/lib/langfuse/prompt_fetch_result.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Public metadata returned by prompt fetch operations.
+  class PromptFetchResult
+    # @return [Object] Prompt data or prompt client returned by the fetch
+    attr_reader :prompt
+
+    # @return [String] Stable logical cache identity
+    attr_reader :logical_key
+
+    # @return [String] Generated backend key for the current cache generation
+    attr_reader :storage_key
+
+    # @return [Symbol] Cache status (:hit, :miss, :stale, :refresh, :bypass, :disabled)
+    attr_reader :cache_status
+
+    # @return [Symbol] Source of the returned prompt (:cache, :api, :fallback)
+    attr_reader :source
+
+    # @return [String] Prompt name
+    attr_reader :name
+
+    # @return [Integer, nil] Prompt version
+    attr_reader :version
+
+    # @return [String, nil] Prompt label
+    attr_reader :label
+
+    # @param prompt [Object] Prompt data or prompt client
+    # @param logical_key [String] Stable logical cache identity
+    # @param storage_key [String] Generated backend key
+    # @param cache_status [Symbol] Cache status
+    # @param source [Symbol] Prompt source
+    # @param name [String] Prompt name
+    # @param version [Integer, nil] Prompt version
+    # @param label [String, nil] Prompt label
+    # @return [PromptFetchResult]
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(prompt:, logical_key:, storage_key:, cache_status:, source:, name:, version: nil, label: nil)
+      @prompt = prompt
+      @logical_key = logical_key
+      @storage_key = storage_key
+      @cache_status = cache_status
+      @source = source
+      @name = name
+      @version = version
+      @label = label
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # @return [Boolean] Whether this result used caller-provided fallback content
+    def fallback?
+      source == CacheSource::FALLBACK
+    end
+
+    # @return [Hash] Result metadata as a hash
+    def to_h
+      {
+        logical_key: logical_key,
+        storage_key: storage_key,
+        cache_status: cache_status,
+        source: source,
+        name: name,
+        version: version,
+        label: label,
+        fallback: fallback?
+      }
+    end
+  end
+
+  # Public key inspection result for prompt cache operations.
+  class PromptCacheKey
+    # @return [String] Prompt name
+    attr_reader :name
+
+    # @return [Integer, nil] Prompt version
+    attr_reader :version
+
+    # @return [String, nil] Prompt label
+    attr_reader :label
+
+    # @return [String] Stable logical cache identity
+    attr_reader :logical_key
+
+    # @return [String] Generated backend key for the current cache generation
+    attr_reader :storage_key
+
+    # @param name [String] Prompt name
+    # @param logical_key [String] Stable logical cache identity
+    # @param storage_key [String] Generated backend key
+    # @param version [Integer, nil] Prompt version
+    # @param label [String, nil] Prompt label
+    # @return [PromptCacheKey]
+    def initialize(name:, logical_key:, storage_key:, version: nil, label: nil)
+      @name = name
+      @version = version
+      @label = label
+      @logical_key = logical_key
+      @storage_key = storage_key
+    end
+
+    # Resolve the effective label, defaulting to "production" when neither
+    # an explicit label nor a version was specified.
+    #
+    # @return [String, nil] Effective label
+    def resolved_label
+      label || (version ? nil : "production")
+    end
+
+    # @return [Hash] Cache key data as a hash
+    def to_h
+      {
+        name: name,
+        version: version,
+        label: label,
+        logical_key: logical_key,
+        storage_key: storage_key
+      }
+    end
+  end
+end

data/lib/langfuse/prompt_renderer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "mustache"
+
+module Langfuse
+  # Renders prompt templates with Langfuse SDK-compatible variable semantics.
+  #
+  # @api private
+  class PromptRenderer < Mustache
+    # Langfuse variables are model input, not browser output; JS/Python SDKs substitute raw values.
+    #
+    # @param value [Object] Value to insert into the prompt
+    # @return [String] Raw string representation
+    def escape(value)
+      value.to_s
+    end
+  end
+end