posthog-ruby 3.28.4 → 3.29.0

data/lib/posthog/flag_evaluation_errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'posthog/unresolved_flag_reason'
+
+module PostHog
+  # InconclusiveMatchError is raised when local evaluation cannot determine a flag's
+  # value. {#reason} says why, as reported by {FeatureFlagEvaluations#unresolved_flags}.
+  class InconclusiveMatchError < StandardError
+    # @return [String] One of the {UnresolvedFlagReason} values.
+    attr_reader :reason
+
+    # @param message [String, nil]
+    # @param reason [String] One of the {UnresolvedFlagReason} values.
+    def initialize(message = nil, reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      super(message)
+      @reason = reason
+    end
+  end
+
+  # RequiresServerEvaluation is raised when feature flag evaluation requires
+  # server-side data that is not available locally (e.g., static cohorts,
+  # experience continuity). This error should propagate immediately to trigger
+  # API fallback, unlike InconclusiveMatchError which allows trying other conditions.
+  class RequiresServerEvaluation < StandardError
+    # @return [String] One of the {UnresolvedFlagReason} values.
+    attr_reader :reason
+
+    # @param message [String, nil]
+    # @param reason [String] One of the {UnresolvedFlagReason} values.
+    def initialize(message = nil, reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      super(message)
+      @reason = reason
+    end
+  end
+end

data/lib/posthog/internal/context.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'posthog/internal/span_context'
+
 module PostHog
   module Internal
     # Internal request/fiber-local context applied to capture calls.
@@ -12,10 +14,12 @@ module PostHog
     # server-side SDK globally stateful per user.
     class Context
       STORAGE_KEY = :posthog_context
+      UNBOUND_OWNER = Object.new.freeze
 
-      attr_reader :distinct_id, :session_id, :properties
+      attr_reader :distinct_id, :session_id, :properties, :owner
 
-      def initialize(distinct_id: nil, session_id: nil, properties: {})
+      def initialize(distinct_id: nil, session_id: nil, properties: {}, owner: UNBOUND_OWNER)
+        @owner = owner
         @distinct_id = distinct_id
         @session_id = session_id
         @properties = properties ? properties.dup : {}
@@ -38,17 +42,18 @@ module PostHog
         end
       end
 
-      def self.with_context(data = nil, fresh: false, **kwargs)
+      def self.with_context(data = nil, fresh: false, owner: UNBOUND_OWNER, enrich_current_span: true, **kwargs)
         previous_context = current
         raise ArgumentError, 'with_context requires a block' unless block_given?
 
-        self.current = resolve(merge_data_and_kwargs(data, kwargs), previous_context, fresh: fresh)
+        self.current = resolve(merge_data_and_kwargs(data, kwargs), previous_context, fresh: fresh, owner: owner)
+        SpanContext.apply_current if enrich_current_span
         yield
       ensure
         self.current = previous_context
       end
 
-      def self.resolve(data, parent, fresh: false)
+      def self.resolve(data, parent, fresh: false, owner: UNBOUND_OWNER)
         data = normalize_data(data)
 
         parent_properties = fresh || parent.nil? ? {} : parent.properties
@@ -61,7 +66,8 @@ module PostHog
         new(
           distinct_id: data[:distinct_id] || (fresh || parent.nil? ? nil : parent.distinct_id),
           session_id: data[:session_id] || (fresh || parent.nil? ? nil : parent.session_id),
-          properties: properties
+          properties: properties,
+          owner: owner.equal?(UNBOUND_OWNER) && parent ? parent.owner : owner
         )
       end
       private_class_method :resolve

data/lib/posthog/internal/span_context.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PostHog
+  module Internal
+    class SpanContext
+      def self.apply(span)
+        context = Context.current
+        return unless context && span&.recording? && span.respond_to?(:attributes)
+
+        return unless context.owner.equal?(Context::UNBOUND_OWNER) || context.owner&.enabled?
+
+        attributes = span.attributes || {}
+        {
+          'posthogDistinctId' => context.distinct_id,
+          'sessionId' => context.session_id
+        }.each do |key, value|
+          next if value.nil? || value == '' || attributes.key?(key)
+
+          span.set_attribute(key, value.is_a?(String) ? value.dup.freeze : value)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def self.apply_current
+        return unless defined?(::OpenTelemetry::Trace)
+
+        apply(::OpenTelemetry::Trace.current_span)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/posthog/mcp/instrumentation.rb

@@ -588,7 +588,9 @@ module PostHog
           'session_id' => (@session.respond_to?(:session_id) ? @session.session_id : nil) || header_session_id,
           'request_id' => @request_id,
           'protocol_version' => protocol_version,
-          'headers' => @headers,
+          # A deep copy, because session and protocol resolution read @headers after
+          # callbacks run, and the values are the Rack env's own Strings.
+          'headers' => @headers.transform_values(&:dup),
           'session' => @session
         }
       end

data/lib/posthog/mcp/request_scope.rb

@@ -17,14 +17,6 @@ module PostHog
       KEY = :posthog_mcp_request_scope
       FIBER_STORAGE = Fiber.respond_to?(:[]) && Fiber.respond_to?(:[]=)
 
-      # Rack `env` keys for the headers the integration reads, by header name.
-      HEADER_ENV_KEYS = {
-        'user-agent' => 'HTTP_USER_AGENT',
-        'x-anthropic-client' => 'HTTP_X_ANTHROPIC_CLIENT',
-        'mcp-session-id' => 'HTTP_MCP_SESSION_ID',
-        'mcp-protocol-version' => 'HTTP_MCP_PROTOCOL_VERSION'
-      }.freeze
-
       module_function
 
       # @return [Hash, nil] `{headers:, transport:, mint:, session_id:}` for the in-flight HTTP request,
@@ -46,20 +38,39 @@ module PostHog
         end
       end
 
-      # @param headers [Hash{String => String}] lowercase header names
-      # @param transport [Symbol] `:http` for the Streamable HTTP transport, `:other`
-      #   for a transport that publishes no headers (stdio, a custom dispatcher)
+      # Rack `env` keys for the two request headers Rack stores without `HTTP_`.
+      UNPREFIXED_HEADER_ENV_KEYS = { 'CONTENT_TYPE' => 'content-type', 'CONTENT_LENGTH' => 'content-length' }.freeze
+      # The request line's protocol, which some servers (WEBrick, Thin) put in `env`.
+      PROTOCOL_ENV_KEY = 'HTTP_VERSION'
+
+      # Every request header, so `identify`, `intent_fallback` and `event_properties`
+      # can read the ones they need (an `authorization` bearer token, an API key)
+      # from `extra['headers']`. The SDK doesn't capture this bag: {Identity} keeps
+      # only scalars from `extra`. {TransportIdentity} still stamps `user-agent` and
+      # `x-anthropic-client`, as before. A callback that returns a raw header value in
+      # identity properties or `event_properties` sends it, unredacted.
+      #
       # @param env [Hash] a Rack `env`
-      # @return [Hash{String => String}] the headers {Instrumentation} reads, lowercase
+      # @return [Hash{String => String}] lowercase header names
       def headers_from_env(env)
         return {} unless env.is_a?(Hash)
 
-        HEADER_ENV_KEYS.each_with_object({}) do |(name, env_key), acc|
-          value = env[env_key]
-          acc[name] = value if value.is_a?(String) && !value.empty?
+        env.each_with_object({}) do |(key, value), acc|
+          name = header_name(key)
+          acc[name] = value if name && value.is_a?(String) && !value.empty?
         end
       end
 
+      def header_name(env_key)
+        return UNPREFIXED_HEADER_ENV_KEYS[env_key] unless env_key.is_a?(String) && env_key.start_with?('HTTP_')
+        return nil if env_key == PROTOCOL_ENV_KEY
+
+        env_key.delete_prefix('HTTP_').downcase.tr('_', '-')
+      end
+
+      # @param headers [Hash{String => String}] lowercase header names
+      # @param transport [Symbol] `:http` for the Streamable HTTP transport, `:other`
+      #   for a transport that publishes no headers (stdio, a custom dispatcher)
       def with(headers:, transport: :http)
         previous = current
         self.current = { headers: headers, transport: transport, mint: nil, session_id: nil }

data/lib/posthog/otel/context_span_processor.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'posthog/internal/context'
+
+module PostHog
+  class ContextSpanProcessor
+    def on_start(span, _parent_context)
+      Internal::SpanContext.apply(span)
+    end
+
+    def on_finish(_span); end
+
+    def force_flush(**_options)
+      0
+    end
+
+    def shutdown(**_options)
+      0
+    end
+  end
+end

data/lib/posthog/unresolved_flag_reason.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PostHog
+  # Why local evaluation left a flag without a value, as reported by
+  # {FeatureFlagEvaluations#unresolved_flags}.
+  #
+  # Reason values:
+  #   EXPERIENCE_CONTINUITY: The flag has experience continuity enabled, which local evaluation never resolves
+  #   UNSUPPORTED_DEFINITION: The flag uses something local evaluation does not support, such as a static
+  #     cohort, an unknown operator, a malformed value, or a missing or circular flag dependency
+  #   UNRESOLVED_DEPENDENCY: A flag this flag depends on has a loaded definition but was unresolved
+  #   MISSING_CONTEXT: The call did not pass a property or group property the flag needs, or passed it in a
+  #     form local evaluation cannot use
+  module UnresolvedFlagReason
+    EXPERIENCE_CONTINUITY = 'experience_continuity'
+    UNSUPPORTED_DEFINITION = 'unsupported_definition'
+    UNRESOLVED_DEPENDENCY = 'unresolved_dependency'
+    MISSING_CONTEXT = 'missing_context'
+  end
+end

data/lib/posthog/utils.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-module PostHog
-  class InconclusiveMatchError < StandardError
-  end
+require 'posthog/flag_evaluation_errors'
 
+module PostHog
   # Utility helpers used internally by the SDK.
   #
   # @api private
@@ -92,7 +91,7 @@ module PostHog
              seconds.abs / 3600, (seconds.abs % 3600) / 60)
     end
 
-    def convert_to_datetime(value)
+    def convert_to_datetime(value, reason:)
       if value.respond_to?(:strftime)
         value
 
@@ -100,10 +99,10 @@ module PostHog
         begin
           DateTime.parse(value)
         rescue ArgumentError
-          raise InconclusiveMatchError, "#{value} is not in a valid date format"
+          raise InconclusiveMatchError.new("#{value} is not in a valid date format", reason: reason)
         end
       else
-        raise InconclusiveMatchError, 'The date provided must be a string or date object'
+        raise InconclusiveMatchError.new('The date provided must be a string or date object', reason: reason)
       end
     end
 

data/lib/posthog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PostHog
-  VERSION = '3.28.4'
+  VERSION = '3.29.0'
 end

data/lib/posthog.rb

@@ -11,6 +11,7 @@ require 'posthog/response'
 require 'posthog/logging'
 require 'posthog/exception_capture'
 require 'posthog/feature_flag_error'
+require 'posthog/unresolved_flag_reason'
 require 'posthog/feature_flag_result'
 require 'posthog/feature_flag_evaluations'
 require 'posthog/flag_definition_cache'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.28.4
+  version: 3.29.0
 platform: ruby
 authors:
 - ''
@@ -46,7 +46,9 @@ files:
 - lib/posthog/feature_flags.rb
 - lib/posthog/field_parser.rb
 - lib/posthog/flag_definition_cache.rb
+- lib/posthog/flag_evaluation_errors.rb
 - lib/posthog/internal/context.rb
+- lib/posthog/internal/span_context.rb
 - lib/posthog/logging.rb
 - lib/posthog/mcp.rb
 - lib/posthog/mcp/README.md
@@ -75,10 +77,12 @@ files:
 - lib/posthog/mcp/truncation.rb
 - lib/posthog/message_batch.rb
 - lib/posthog/noop_worker.rb
+- lib/posthog/otel/context_span_processor.rb
 - lib/posthog/response.rb
 - lib/posthog/send_feature_flags_options.rb
 - lib/posthog/send_worker.rb
 - lib/posthog/transport.rb
+- lib/posthog/unresolved_flag_reason.rb
 - lib/posthog/utils.rb
 - lib/posthog/version.rb
 homepage: https://github.com/PostHog/posthog-ruby