txlemetry-ruby 4.0.0

data/lib/txlemetry/mcp/exceptions.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'txlemetry/exception_capture'
+
+module Txlemetry
+  module MCP
+    # Builds Txlemetry error-tracking properties (`$exception_list` /
+    # `$exception_level`) from anything a tool can fail with, reusing
+    # {Txlemetry::ExceptionCapture} so MCP failures group like every other
+    # exception the Ruby SDK reports.
+    #
+    # @api private
+    module Exceptions
+      GENERIC_MECHANISM = { 'type' => 'generic', 'handled' => true }.freeze
+
+      # Messages the Ruby `mcp` gem wraps around whatever a tool raised.
+      DISPATCH_WRAPPER_TYPE = 'MCP::Server::RequestHandlerError'
+      DISPATCH_WRAPPER_PREFIXES = ['Internal error calling tool', 'Internal error handling'].freeze
+
+      module_function
+
+      # @param error [Exception, String, Hash, Object] exception, message, or an
+      #   `isError` tool result (`{content: [...], isError: true}`)
+      # @return [Hash] `{'$exception_list' => [...], '$exception_level' => 'error'}`
+      def capture_exception(error)
+        return from_message(call_tool_result_message(error)) if call_tool_result?(error)
+        return from_exception(error) if error.is_a?(Exception)
+        return from_message(error) if error.is_a?(String)
+
+        from_message(safe_to_s(error))
+      end
+
+      def from_exception(error)
+        list = Txlemetry::ExceptionCapture.build_exception_list(error) || []
+        original = error.respond_to?(:original_error) ? error.original_error : nil
+        if original.is_a?(Exception) && !chain_includes?(error, original)
+          list.concat(Txlemetry::ExceptionCapture.build_exception_list(original) || [])
+        end
+        list = [message_entry(error.class.to_s, error.message.to_s)] if list.empty?
+        { '$exception_list' => list, '$exception_level' => 'error' }
+      end
+
+      def from_message(message)
+        { '$exception_list' => [message_entry('Error', message)], '$exception_level' => 'error' }
+      end
+
+      def message_entry(type, message)
+        { 'mechanism' => GENERIC_MECHANISM.dup, 'type' => type, 'value' => message }
+      end
+
+      # Whether an `$exception_list` entry is the gem's dispatch wrapper, whose
+      # message says nothing the tool name does not already say.
+      def dispatch_wrapper?(entry)
+        return false unless entry.is_a?(Hash)
+
+        value = entry['value'].to_s
+        entry['type'] == DISPATCH_WRAPPER_TYPE && DISPATCH_WRAPPER_PREFIXES.any? { |p| value.start_with?(p) }
+      end
+
+      # The `$exception_list` entry carrying the actual failure reason, stepping
+      # past consecutive dispatch wrappers.
+      def primary_exception(error)
+        return {} unless error.is_a?(Hash)
+
+        list = error['$exception_list']
+        return {} unless list.is_a?(Array) && !list.empty?
+
+        index = 0
+        index += 1 while index + 1 < list.length && list[index + 1].is_a?(Hash) && dispatch_wrapper?(list[index])
+        list[index].is_a?(Hash) ? list[index] : {}
+      end
+
+      def call_tool_result?(value)
+        return false unless value.is_a?(Hash)
+
+        content = value['content'] || value[:content]
+        (value.key?('isError') || value.key?(:isError)) && content.is_a?(Array)
+      end
+
+      def call_tool_result_message(result)
+        content = result['content'] || result[:content] || []
+        texts = content.filter_map do |part|
+          next unless part.is_a?(Hash)
+
+          type = part['type'] || part[:type]
+          text = part['text'] || part[:text]
+          text if type == 'text' && text.is_a?(String)
+        end
+        joined = texts.join(' ').strip
+        joined.empty? ? 'Unknown error' : joined
+      end
+
+      def chain_includes?(error, target)
+        current = error.cause
+        seen = {}.compare_by_identity
+        while current && !seen.key?(current)
+          return true if current.equal?(target)
+
+          seen[current] = true
+          current = current.cause
+        end
+        false
+      end
+
+      def safe_to_s(value)
+        value.to_s
+      rescue StandardError
+        'Unknown error'
+      end
+    end
+  end
+end

data/lib/txlemetry/mcp/identity.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Txlemetry
+  module MCP
+    # Bounded LRU of session identities, isolated per server.
+    #
+    # @api private
+    class IdentityCache
+      def initialize(max_size = 1000)
+        @cache = {}
+        @max_size = max_size
+        @mutex = Mutex.new
+      end
+
+      def get(session_id)
+        @mutex.synchronize do
+          identity = @cache.delete(session_id)
+          next nil if identity.nil?
+
+          @cache[session_id] = identity
+        end
+      end
+
+      def set(session_id, identity)
+        @mutex.synchronize do
+          @cache.delete(session_id)
+          @cache.shift if @cache.length >= @max_size
+          @cache[session_id] = identity
+        end
+      end
+
+      # Atomically read the cached identity, merge the new one, store it, and
+      # report whether it changed. Keeps concurrent requests for one session
+      # from interleaving their read-merge-write.
+      #
+      # @return [Array(UserIdentity, Boolean)] `[merged, changed]`
+      def merge!(session_id, identity)
+        @mutex.synchronize do
+          previous = @cache.delete(session_id)
+          merged = Identity.merge_identities(previous, identity)
+          changed = !(previous && Identity.identities_equal?(previous, merged))
+          @cache.shift if @cache.length >= @max_size
+          @cache[session_id] = merged
+          [merged, changed]
+        end
+      end
+
+      def has?(session_id)
+        @mutex.synchronize { @cache.key?(session_id) }
+      end
+
+      def size
+        @mutex.synchronize { @cache.length }
+      end
+    end
+
+    # Identity resolution: runs the `identify` option, dedupes against the
+    # per-server cache, and decides when a standalone `$identify` event fires.
+    #
+    # @api private
+    module Identity
+      module_function
+
+      def identities_equal?(first, second)
+        return false if first.distinct_id != second.distinct_id
+        return false if sorted_json(first.groups || {}) != sorted_json(second.groups || {})
+
+        a_props = first.properties || {}
+        b_props = second.properties || {}
+        return false if a_props.keys.map(&:to_s).sort != b_props.keys.map(&:to_s).sort
+
+        a_props.all? do |key, value|
+          other = if b_props.key?(key)
+                    b_props[key]
+                  else
+                    b_props[key.is_a?(Symbol) ? key.to_s : key.to_s.to_sym]
+                  end
+          sorted_json(value) == sorted_json(other)
+        end
+      end
+
+      def merge_identities(previous, nxt)
+        return nxt if previous.nil?
+
+        UserIdentity.new(
+          distinct_id: nxt.distinct_id,
+          properties: (previous.properties || {}).merge(nxt.properties || {}),
+          groups: nxt.groups.nil? ? previous.groups : nxt.groups
+        )
+      end
+
+      # Resolve the optional `identify` callback for one request: the identity the
+      # request's events belong to, plus an `$identify` event to emit only when
+      # that identity has materially changed.
+      #
+      # The actor is handed back rather than left for the caller to read out of
+      # {IdentityCache} later. The cache is keyed by session, and a request's
+      # events are built after its handler returns, so a concurrent request on
+      # the same session would otherwise decide who this one is attributed to.
+      # When resolution yields nothing the cache is read once, here, so whatever
+      # a request is attributed to it is attributed to consistently.
+      #
+      # @return [Array(Hash, UserIdentity), Array(nil, UserIdentity), Array(nil, nil)] `[event, actor]`
+      def identify_for_request(data, session_id, request, extra)
+        identify = data.options.identify
+        return [nil, nil] unless identify
+
+        result = if identify.is_a?(UserIdentity) || identify.is_a?(Hash)
+                   identify
+                 else
+                   Callbacks.call(identify, request,
+                                  extra)
+                 end
+        identity = UserIdentity.coerce(result)
+        unless identity
+          Log.debug(data.options, "Warning: Supplied identify function returned null for session #{session_id}")
+          return [nil, data.identified_sessions.get(session_id)]
+        end
+
+        merged, changed = data.identified_sessions.merge!(session_id, identity)
+        return [nil, merged] unless changed
+
+        Log.debug(data.options, "Identified session #{session_id}")
+        [{
+          'session_id' => session_id,
+          'resource_name' => request_resource_name(request),
+          'event_type' => EventType::IDENTIFY,
+          'parameters' => { 'request' => request, 'extra' => captured_extra(extra) },
+          'timestamp' => Time.now.utc
+        }, merged]
+      rescue StandardError => e
+        Log.debug(data.options, "Error: identify function threw while identifying session #{session_id} - #{e.message}")
+        [nil, data.identified_sessions.get(session_id)]
+      end
+
+      # @return [Hash, nil] the `$identify` event alone; see {identify_for_request}.
+      def handle_identify(data, session_id, request, extra)
+        identify_for_request(data, session_id, request, extra).first
+      end
+
+      def request_resource_name(request)
+        return 'Unknown' unless request.is_a?(Hash)
+
+        params = request[:params] || request['params']
+        return 'Unknown' unless params.is_a?(Hash)
+
+        name = params[:name] || params['name']
+        name.is_a?(String) ? name : 'Unknown'
+      end
+
+      # Only JSON scalars from `extra` are captured; never opaque transport objects.
+      def captured_extra(extra)
+        return nil unless extra.is_a?(Hash)
+
+        extra.select do |_, value|
+          value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+        end
+      end
+
+      def sorted_json(value)
+        JSON.generate(sort_deep(value))
+      rescue StandardError
+        value.to_s
+      end
+
+      def sort_deep(value)
+        case value
+        when Hash then value.map { |k, v| [k.to_s, sort_deep(v)] }.sort_by(&:first).to_h
+        when Array then value.map { |v| sort_deep(v) }
+        when String, Numeric, true, false, nil then value
+        else value.to_s
+        end
+      end
+    end
+
+    # Invokes user callbacks with `(request, extra)`, tolerating 1-arity lambdas.
+    #
+    # @api private
+    module Callbacks
+      module_function
+
+      def call(callable, request, extra)
+        arity = callable.respond_to?(:arity) ? callable.arity : 2
+        case arity
+        when 0 then callable.call
+        when 1 then callable.call(request)
+        else callable.call(request, extra)
+        end
+      end
+    end
+  end
+end

data/lib/txlemetry/mcp/ids.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Txlemetry
+  module MCP
+    # Id generation: `evt_<uuidv7>` / `ses_<uuidv7>` and the deterministic FNV-1a
+    # derivation used for session ids that must agree across servers and restarts.
+    #
+    # @api private
+    module Ids
+      module_function
+
+      # RFC 9562 UUIDv7 (time-ordered), implemented inline so Ruby 3.0/3.1 work too.
+      #
+      # @return [String] lowercase, hyphenated uuid
+      def uuid_v7
+        unix_ts_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) & ((1 << 48) - 1)
+        rand_a = SecureRandom.random_number(1 << 12)
+        rand_b = SecureRandom.random_number(1 << 62)
+
+        value = unix_ts_ms << 80
+        value |= 0x7 << 76
+        value |= rand_a << 64
+        value |= 0b10 << 62
+        value |= rand_b
+
+        hex = format('%032x', value)
+        "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+      end
+
+      # @param prefix [String] `'evt'` or `'ses'`
+      def new_prefixed_id(prefix)
+        "#{prefix}_#{uuid_v7}"
+      end
+
+      # Deterministic id derived from an arbitrary string. FNV-1a 64-bit mixed
+      # twice to fill 32 hex chars. Not cryptographic; only stable and low-collision.
+      #
+      # Iterates code points; session/conversation ids are ASCII in practice.
+      def deterministic_prefixed_id(prefix, value)
+        "#{prefix}_#{fnv1a_hex(value)}#{fnv1a_hex("#{value}::salt")}"
+      end
+
+      def fnv1a_hex(value)
+        h1 = 0x84222325
+        h2 = 0xcbf29ce4
+        value.to_s.each_codepoint do |c|
+          h1 = ((h1 ^ c) * 0x000001b3) & 0xffffffff
+          h2 = ((h2 ^ c) * 0x00000193) & 0xffffffff
+        end
+        format('%<h1>08x%<h2>08x', h1: h1, h2: h2)
+      end
+    end
+  end
+end