langfuse-rb 0.9.0 → 0.10.0

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/rails_cache_adapter.rb

@@ -14,9 +14,12 @@ module Langfuse
   #   adapter.set("greeting:1", prompt_data)
   #   adapter.get("greeting:1") # => prompt_data
   #
+  # rubocop:disable Metrics/ClassLength
   class RailsCacheAdapter
     include StaleWhileRevalidate
 
+    GENERATION_MEMO_TTL_SECONDS = 1.0
+
     # @return [Integer] Time-to-live in seconds
     attr_reader :ttl
 
@@ -51,9 +54,12 @@ module Langfuse
 
       @ttl = ttl
       @namespace = namespace
+      @namespace_prefix = "#{namespace}:"
       @lock_timeout = lock_timeout
       @stale_ttl = stale_ttl
       @logger = logger
+      @generation_memo = {}
+      @generation_memo_mutex = Mutex.new
       initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
     end
 
@@ -65,18 +71,37 @@ module Langfuse
       Rails.cache.read(namespaced_key(key))
     end
 
+    # Read a raw cache entry, including stale entries.
+    #
+    # @param key [String] Cache key
+    # @return [Object, nil] Raw cache entry
+    def entry(key)
+      Rails.cache.read(namespaced_key(key))
+    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)
-      # Calculate expiration: use total_ttl if SWR enabled, otherwise just ttl
-      expires_in = swr_enabled? ? total_ttl : ttl
+    def set(key, value, ttl: nil, stale_ttl: nil)
+      # Total ttl when SWR is enabled, otherwise just ttl. Inlined (not pushed
+      # to a shared helper) to keep this hot write path allocation-free.
+      effective_ttl = ttl.nil? ? self.ttl : ttl
+      effective_stale_ttl = stale_ttl.nil? ? self.stale_ttl : stale_ttl
+      expires_in = swr_enabled? ? effective_ttl + effective_stale_ttl : effective_ttl
       Rails.cache.write(namespaced_key(key), value, expires_in:)
       value
     end
 
+    # Delete one generated storage key.
+    #
+    # @param key [String] Cache key
+    # @return [Boolean] true if an entry was removed
+    def delete(key)
+      Rails.cache.delete(namespaced_key(key))
+    end
+
     # Clear the entire Langfuse cache namespace
     #
     # Note: This uses delete_matched which may not be available on all cache stores.
@@ -86,6 +111,37 @@ module Langfuse
     def clear
       # Delete all keys matching the namespace pattern
       Rails.cache.delete_matched("#{namespace}:*")
+      clear_generation_memo
+    end
+
+    # Logically invalidate every generated storage key.
+    #
+    # @return [Integer] New global generation
+    def clear_logically
+      bump_generation(global_generation_key)
+    end
+
+    # Logically invalidate every cache variant for one prompt name.
+    #
+    # @param name [String] Prompt name
+    # @return [Integer] New name generation
+    def invalidate_name(name)
+      bump_generation(name_generation_key(name))
+    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:)
+      generated = PromptCache.storage_key(
+        logical_key,
+        name: name,
+        global_generation: generation_value(global_generation_key),
+        name_generation: generation_value(name_generation_key(name))
+      )
+      namespaced_key(generated)
     end
 
     # Get current cache size
@@ -98,6 +154,19 @@ module Langfuse
       nil
     end
 
+    # @return [Hash] Prompt cache statistics
+    def stats
+      {
+        backend: CacheBackend::RAILS,
+        enabled: true,
+        current_generation_entries: nil,
+        orphaned_entries: nil,
+        total_entries: nil,
+        global_generation: generation_value(global_generation_key),
+        unsupported_counts: CacheBackend::UNSUPPORTED_COUNT_KEYS
+      }
+    end
+
     # Check if cache is empty
     #
     # Note: Rails.cache doesn't provide an efficient way to check if empty,
@@ -108,6 +177,17 @@ module Langfuse
       false
     end
 
+    # Validate that Rails.cache is available for prompt caching.
+    #
+    # @return [Boolean]
+    # @raise [ConfigurationError] if Rails.cache is not available
+    # rubocop:disable Naming/PredicateMethod
+    def validate!
+      validate_rails_cache!
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
     # Build a cache key from prompt name and options
     #
     # @param name [String] Prompt name
@@ -135,7 +215,7 @@ module Langfuse
     #   cache.fetch_with_lock("greeting:v1") do
     #     api_client.get_prompt("greeting")
     #   end
-    def fetch_with_lock(key)
+    def fetch_with_lock(key, ttl: nil)
       # 1. Check cache first (fast path - no lock needed)
       cached = get(key)
       return cached if cached
@@ -147,7 +227,7 @@ module Langfuse
         begin
           # We got the lock - fetch from source and populate cache
           value = yield
-          set(key, value)
+          set(key, value, ttl: ttl)
           value
         ensure
           # Always release lock, even if block raises
@@ -173,7 +253,7 @@ module Langfuse
     # @param key [String] Cache key
     # @return [Object, nil] Cached value
     def cache_get(key)
-      get(key)
+      entry(key)
     end
 
     # Set value in cache (SWR interface)
@@ -181,8 +261,9 @@ module Langfuse
     # @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)
+    def cache_set(key, value, ttl: nil)
+      Rails.cache.write(namespaced_key(key), value, expires_in: ttl || total_ttl)
+      value
     end
 
     # Build lock key with namespace
@@ -248,7 +329,77 @@ module Langfuse
     # @param key [String] Original cache key
     # @return [String] Namespaced cache key
     def namespaced_key(key)
-      "#{namespace}:#{key}"
+      key.start_with?(@namespace_prefix) ? key : "#{@namespace_prefix}#{key}"
+    end
+
+    def global_generation_key
+      namespaced_key("__prompt_cache_generation__:global")
+    end
+
+    def name_generation_key(name)
+      encoded_name = Base64.urlsafe_encode64(name.to_s, padding: false)
+      namespaced_key("__prompt_cache_generation__:name:#{encoded_name}")
+    end
+
+    def generation_value(key)
+      now = monotonic_time
+      memoized = memoized_generation_value(key, now)
+      return memoized unless memoized.nil?
+
+      Rails.cache.read(key).to_i.tap do |value|
+        memoize_generation_value(key, value, now)
+      end
+    end
+
+    def bump_generation(key)
+      incremented = increment_generation(key)
+      if incremented
+        memoize_generation_value(key, incremented.to_i)
+        return incremented
+      end
+
+      new_value = generation_value(key) + 1
+      Rails.cache.write(key, new_value)
+      memoize_generation_value(key, new_value)
+      new_value
+    end
+
+    def increment_generation(key)
+      return unless Rails.cache.respond_to?(:increment)
+
+      Rails.cache.write(key, 0, unless_exist: true)
+      Rails.cache.increment(key, 1)
+    rescue StandardError => e
+      logger.warn("Langfuse prompt cache generation increment failed for key '#{key}': #{e.class} - #{e.message}")
+      nil
+    end
+
+    def memoized_generation_value(key, now)
+      @generation_memo_mutex.synchronize do
+        entry = @generation_memo[key]
+        return nil unless entry
+
+        return entry.fetch(:value) if now < entry.fetch(:expires_at)
+
+        @generation_memo.delete(key)
+        nil
+      end
+    end
+
+    def memoize_generation_value(key, value, now = monotonic_time)
+      @generation_memo_mutex.synchronize do
+        @generation_memo[key] = { value: value, expires_at: now + GENERATION_MEMO_TTL_SECONDS }
+      end
+    end
+
+    def clear_generation_memo
+      @generation_memo_mutex.synchronize do
+        @generation_memo.clear
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     # Validate that Rails.cache is available
@@ -273,4 +424,5 @@ module Langfuse
       end
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/langfuse/stale_while_revalidate.rb

@@ -41,6 +41,7 @@ module Langfuse
   #       # Implementation-specific lock release
   #     end
   #   end
+  # rubocop:disable Metrics/ModuleLength
   module StaleWhileRevalidate
     # Initialize SWR infrastructure
     #
@@ -72,7 +73,7 @@ module Langfuse
     #   cache.fetch_with_stale_while_revalidate("greeting:v1") do
     #     api_client.get_prompt("greeting")
     #   end
-    def fetch_with_stale_while_revalidate(key, &)
+    def fetch_with_stale_while_revalidate(key, ttl: nil, stale_ttl: nil, &)
       raise ConfigurationError, "fetch_with_stale_while_revalidate requires a positive stale_ttl" unless swr_enabled?
 
       entry = cache_get(key)
@@ -84,15 +85,50 @@ module Langfuse
       elsif entry&.stale?
         # REVALIDATE - return stale + refresh in background
         logger.debug("CACHE STALE!")
-        schedule_refresh(key, &)
+        schedule_refresh(key, ttl: ttl, stale_ttl: stale_ttl, &)
         entry.data # Instant response!
       else
         # MISS - must fetch synchronously
         logger.debug("CACHE MISS!")
-        fetch_and_cache(key, &)
+        fetch_and_cache(key, ttl: ttl, stale_ttl: stale_ttl, &)
       end
     end
 
+    # Schedule a cache refresh without performing a read.
+    #
+    # @param key [String] Cache key
+    # @param ttl [Integer, nil] Optional fresh TTL override
+    # @param stale_ttl [Integer, nil] Optional stale TTL override
+    # @param on_success [#call, nil] Callback invoked after a successful write
+    # @param on_failure [#call, nil] Callback invoked when refresh raises
+    # @yield Block to execute to fetch fresh data
+    # @return [Boolean] true if a refresh was scheduled
+    def refresh_async(key, ttl: nil, stale_ttl: nil, on_success: nil, on_failure: nil, &)
+      raise ConfigurationError, "refresh_async requires a positive stale_ttl" unless swr_enabled?
+
+      schedule_refresh(
+        key,
+        ttl: ttl,
+        stale_ttl: stale_ttl,
+        on_success: on_success,
+        on_failure: on_failure,
+        &
+      )
+    end
+
+    # Write a value with stale-while-revalidate metadata.
+    #
+    # @param key [String] Cache key
+    # @param value [Object] Value to cache
+    # @param ttl [Integer, nil] Optional fresh TTL override
+    # @param stale_ttl [Integer, nil] Optional stale TTL override
+    # @return [Object] The cached value
+    def write_with_stale_while_revalidate(key, value, ttl: nil, stale_ttl: nil)
+      raise ConfigurationError, "write_with_stale_while_revalidate requires a positive stale_ttl" unless swr_enabled?
+
+      set_cache_entry(key, value, ttl: ttl, stale_ttl: stale_ttl)
+    end
+
     # Check if SWR is enabled
     #
     # SWR is enabled when stale_ttl is positive, meaning there's a grace period
@@ -138,29 +174,35 @@ module Langfuse
     # @param key [String] Cache key
     # @yield Block to execute to fetch fresh data
     # @return [void]
-    def schedule_refresh(key, &block)
+    # rubocop:disable Naming/PredicateMethod
+    def schedule_refresh(key, ttl: nil, stale_ttl: nil, on_success: nil, on_failure: nil, &block)
       # Prevent duplicate refreshes
       lock_key = build_lock_key(key)
-      return unless acquire_lock(lock_key)
+      return false unless acquire_lock(lock_key)
 
       @thread_pool.post do
-        value = yield block
-        set_cache_entry(key, value)
+        value = block.call
+        set_cache_entry(key, value, ttl: ttl, stale_ttl: stale_ttl)
+        on_success&.call(value)
       rescue StandardError => e
+        on_failure&.call(e)
         logger.error("Langfuse cache refresh failed for key '#{key}': #{e.class} - #{e.message}")
       ensure
         release_lock(lock_key)
       end
+
+      true
     end
+    # rubocop:enable Naming/PredicateMethod
 
     # 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)
+    def fetch_and_cache(key, ttl: nil, stale_ttl: nil, &block)
+      value = block.call
+      set_cache_entry(key, value, ttl: ttl, stale_ttl: stale_ttl)
     end
 
     # Set value in cache with SWR metadata (CacheEntry)
@@ -168,14 +210,14 @@ module Langfuse
     # @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)
-
+    def set_cache_entry(key, value, ttl: nil, stale_ttl: nil)
+      # TTL math is inlined (not extracted to a helper) to keep this hot write
+      # 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
+      entry = PromptCache::CacheEntry.new(value, fresh_until, fresh_until + effective_stale_ttl)
+      cache_set(key, entry, ttl: effective_ttl + effective_stale_ttl)
       value
     end
 
@@ -213,7 +255,7 @@ module Langfuse
     # @param value [Object] Value to cache
     # @return [Object] The cached value
     # @raise [NotImplementedError] if not implemented by including class
-    def cache_set(_key, _value)
+    def cache_set(_key, _value, ttl: nil)
       raise NotImplementedError, "#{self.class} must implement #cache_set"
     end
 
@@ -259,4 +301,5 @@ module Langfuse
       @logger || raise(NotImplementedError, "#{self.class} must provide @logger")
     end
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/langfuse/version.rb

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

data/lib/langfuse.rb

@@ -40,9 +40,12 @@ module Langfuse
 end
 
 require_relative "langfuse/config"
+require_relative "langfuse/cache_constants"
 require_relative "langfuse/prompt_cache"
+require_relative "langfuse/prompt_fetch_result"
 require_relative "langfuse/rails_cache_adapter"
 require_relative "langfuse/cache_warmer"
+require_relative "langfuse/prompt_cache_events"
 require_relative "langfuse/api_client"
 require_relative "langfuse/span_filter"
 require_relative "langfuse/sampling"

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - SimplePractice
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -160,6 +161,7 @@ files:
 - README.md
 - lib/langfuse.rb
 - lib/langfuse/api_client.rb
+- lib/langfuse/cache_constants.rb
 - lib/langfuse/cache_warmer.rb
 - lib/langfuse/chat_prompt_client.rb
 - lib/langfuse/client.rb
@@ -176,6 +178,8 @@ files:
 - lib/langfuse/otel_attributes.rb
 - lib/langfuse/otel_setup.rb
 - lib/langfuse/prompt_cache.rb
+- lib/langfuse/prompt_cache_events.rb
+- lib/langfuse/prompt_fetch_result.rb
 - lib/langfuse/prompt_renderer.rb
 - lib/langfuse/propagation.rb
 - lib/langfuse/rails_cache_adapter.rb
@@ -198,6 +202,7 @@ metadata:
   source_code_uri: https://github.com/simplepractice/langfuse-rb
   changelog_uri: https://github.com/simplepractice/langfuse-rb/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -212,7 +217,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: Ruby SDK for Langfuse - LLM observability and prompt management
 test_files: []