e11y 0.2.0 → 1.0.0

data/lib/e11y/slo/tracker.rb

@@ -17,7 +17,7 @@ module E11y
     #
     # @example Enable SLO tracking
     #   E11y.configure do |config|
-    #     config.slo_tracking.enabled = true
+    #     config.slo_tracking_enabled = true
     #   end
     #
     # @example Track HTTP request
@@ -28,10 +28,31 @@ module E11y
     #     duration_ms: 42.5
     #   )
     #
-    # @note C11 Resolution (Sampling Correction): Not yet implemented.
-    #   Requires Phase 2.8 (Stratified Sampling) for accurate SLO with sampling.
+    # @note C11 Resolution: Event-driven SLO (EventSlo middleware) applies stratified
+    #   sampling correction via E11y::Sampling.stratified_tracker. HTTP/job SLO
+    #   are tracked directly (no sampling) and need no correction.
     module Tracker
+      # In-memory store for tracked request data (per endpoint).
+      # @api private Intended for test assertions only; not part of public API.
+      @_store = {}
+
       class << self
+        # Return a snapshot of all tracked endpoints and their request counts.
+        # @api private Intended for test assertions only.
+        #
+        # @return [Hash] Map of "controller#action" => { requests: Integer }
+        def status
+          @_store.dup
+        end
+
+        # Reset the in-memory store (useful for testing and per-request isolation).
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @_store = {}
+        end
+
         # Track HTTP request for SLO metrics.
         #
         # @param controller [String] Controller name
@@ -58,6 +79,12 @@ module E11y
             labels.except(:status),
             buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
           )
+
+          # Store in-memory for status reporting
+          key = "#{controller}##{action}"
+          @_store ||= {}
+          @_store[key] ||= { requests: 0 }
+          @_store[key][:requests] += 1
         end
 
         # Track background job for SLO metrics.
@@ -94,7 +121,7 @@ module E11y
         #
         # @return [Boolean] true if enabled
         def enabled?
-          E11y.config.respond_to?(:slo_tracking) && E11y.config.slo_tracking&.enabled
+          E11y.config.respond_to?(:slo_tracking_enabled) && E11y.config.slo_tracking_enabled
         end
 
         # Normalize HTTP status code to category (2xx, 3xx, 4xx, 5xx).

data/lib/e11y/testing/have_tracked_event_matcher.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module E11y
+  module Testing
+    # RSpec matcher for asserting that an event was tracked during block execution.
+    #
+    # @example Basic usage
+    #   expect { OrdersController.create }.to have_tracked_event(Events::OrderCreated)
+    #
+    # @example With payload
+    #   expect { action }.to have_tracked_event(Events::OrderPaid).with(order_id: 123)
+    #
+    # @example With count
+    #   expect { action }.to have_tracked_event(Events::OrderPaid).once
+    # rubocop:disable Metrics/ClassLength
+    class HaveTrackedEventMatcher
+      def initialize(event_class_or_pattern)
+        @event_class_or_pattern = event_class_or_pattern
+        @payload_matchers = {}
+        @severity_matcher = nil
+        @count_matcher = nil
+        @trace_id_matcher = nil
+      end
+
+      def with(payload_hash)
+        @payload_matchers = payload_hash
+        self
+      end
+
+      def with_severity(severity)
+        @severity_matcher = severity
+        self
+      end
+
+      def exactly(count)
+        @count_matcher = count
+        self
+      end
+
+      def at_least(count)
+        @count_matcher = [:at_least, count]
+        self
+      end
+
+      def at_most(count)
+        @count_matcher = [:at_most, count]
+        self
+      end
+
+      def once
+        exactly(1)
+      end
+
+      def twice
+        exactly(2)
+      end
+
+      def with_trace_id(trace_id)
+        @trace_id_matcher = trace_id
+        self
+      end
+
+      def matches?(actual = nil)
+        actual.call if actual.respond_to?(:call) # Execute block before checking events
+        @events = find_matching_events
+        return false if @events.empty?
+        return false unless count_matches?
+        return false unless payload_matches?
+        return false unless severity_matches?
+        return false unless trace_id_matches?
+
+        true
+      end
+
+      def failure_message
+        if @events.empty?
+          no_events_message
+        elsif !count_matches?
+          count_mismatch_message
+        elsif !payload_matches?
+          payload_mismatch_message
+        elsif !severity_matches?
+          severity_mismatch_message
+        else
+          trace_id_mismatch_message
+        end
+      end
+
+      def failure_message_when_negated
+        "expected not to have tracked #{event_name}, but it was tracked"
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      private
+
+      def find_matching_events
+        adapter = E11y.test_adapter
+        return [] unless adapter
+
+        adapter.find_events(@event_class_or_pattern)
+      end
+
+      def event_name
+        case @event_class_or_pattern
+        when Class
+          @event_class_or_pattern.name
+        else
+          @event_class_or_pattern.to_s
+        end
+      end
+
+      def count_matches?
+        return true unless @count_matcher
+
+        case @count_matcher
+        when Integer
+          @events.size == @count_matcher
+        when Array
+          operator, expected = @count_matcher
+          case operator
+          when :at_least then @events.size >= expected
+          when :at_most then @events.size <= expected
+          else false
+          end
+        end
+      end
+
+      def payload_matches?
+        return true if @payload_matchers.empty?
+
+        @events.any? do |event|
+          payload = event[:payload] || {}
+          @payload_matchers.all? do |key, expected_value|
+            actual_value = payload[key.to_s] || payload[key.to_sym]
+            actual_value == expected_value
+          end
+        end
+      end
+
+      def severity_matches?
+        return true unless @severity_matcher
+
+        @events.any? { |event| event[:severity].to_s == @severity_matcher.to_s }
+      end
+
+      def trace_id_matches?
+        return true unless @trace_id_matcher
+
+        @events.any? { |event| event[:trace_id] == @trace_id_matcher }
+      end
+
+      def no_events_message
+        adapter = E11y.test_adapter
+        if !adapter || adapter.events.empty?
+          "expected to have tracked #{event_name}, but no events were tracked at all"
+        else
+          tracked = adapter.events.map { |e| e[:event_name] }.uniq.join(", ")
+          "expected to have tracked #{event_name}, but only tracked: #{tracked}"
+        end
+      end
+
+      def count_mismatch_message
+        expected = case @count_matcher
+                   when Integer then "exactly #{@count_matcher}"
+                   when Array then "#{@count_matcher[0].to_s.tr('_', ' ')} #{@count_matcher[1]}"
+                   end
+        "expected to track #{event_name} #{expected} times, but tracked #{@events.size} times"
+      end
+
+      def payload_mismatch_message
+        "expected #{event_name} with payload #{@payload_matchers.inspect}, " \
+          "but got:\n#{@events.map { |e| "  #{e[:payload].inspect}" }.join("\n")}"
+      end
+
+      def severity_mismatch_message
+        severities = @events.map { |e| e[:severity] }.uniq.join(", ")
+        "expected #{event_name} with severity :#{@severity_matcher}, but got: #{severities}"
+      end
+
+      def trace_id_mismatch_message
+        trace_ids = @events.map { |e| e[:trace_id] }.uniq.join(", ")
+        "expected #{event_name} with trace_id #{@trace_id_matcher}, but got: #{trace_ids}"
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/e11y/testing/rspec_matchers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module E11y
+  module Testing
+    # RSpec matchers for event tracking assertions (ADR-011 F-002)
+    #
+    # @example
+    #   expect { OrdersController.create }.to have_tracked_event(Events::OrderCreated)
+    #   expect { action }.to have_tracked_event(Events::OrderPaid).with(order_id: 123)
+    #   expect { action }.to have_tracked_event(Events::OrderPaid).once
+    module RSpecMatchers
+      # rubocop:disable Naming/PredicatePrefix -- RSpec matcher convention: have_tracked_event
+      def have_tracked_event(event_class_or_pattern)
+        HaveTrackedEventMatcher.new(event_class_or_pattern)
+      end
+      # rubocop:enable Naming/PredicatePrefix
+
+      alias track_event have_tracked_event
+    end
+  end
+end

data/lib/e11y/testing/snapshot_matcher.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module E11y
+  module Testing
+    # Snapshot matcher for event comparison (ADR-011 F-006).
+    #
+    # Compares event hashes against YAML snapshots, normalizing volatile fields
+    # (timestamp, trace_id, span_id). First run creates the snapshot; subsequent
+    # runs compare against it. Use UPDATE_SNAPSHOTS=1 to update snapshots.
+    #
+    # @example
+    #   event = E11y.test_adapter.find_event(Events::OrderCreated)
+    #   expect(event).to match_snapshot("order_created_event")
+    class SnapshotMatcher
+      SNAPSHOTS_DIR = "spec/snapshots/events"
+      VOLATILE_KEYS = %i[timestamp trace_id span_id retention_until routed_at].freeze
+
+      def initialize(snapshot_name)
+        @snapshot_name = snapshot_name
+      end
+
+      def matches?(actual)
+        @actual = actual
+        @normalized = normalize_event(actual)
+        @snapshot_path = File.join(SNAPSHOTS_DIR, "#{@snapshot_name}.yml")
+
+        if update_snapshots? || !File.exist?(@snapshot_path)
+          write_snapshot(@normalized)
+          true
+        else
+          @expected = YAML.load_file(@snapshot_path)
+          @normalized == @expected
+        end
+      end
+
+      def failure_message
+        if @expected
+          "expected event to match snapshot #{@snapshot_name}, but it differed:\n" \
+            "Expected:\n#{@expected.to_yaml}\n" \
+            "Actual (normalized):\n#{@normalized.to_yaml}"
+        else
+          "snapshot #{@snapshot_name} not found at #{@snapshot_path}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected event not to match snapshot #{@snapshot_name}, but it did"
+      end
+
+      private
+
+      def normalize_event(event)
+        return {} if event.nil?
+
+        event = event.dup
+        VOLATILE_KEYS.each { |k| event.delete(k) }
+        event.delete(:context) # context contains trace_id, span_id, etc.
+        event.delete(:routing)
+        deep_stringify(event)
+      end
+
+      def deep_stringify(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| deep_stringify(v) }.transform_keys(&:to_s)
+        when Array
+          obj.map { |v| deep_stringify(v) }
+        else
+          obj
+        end
+      end
+
+      def update_snapshots?
+        %w[1 true].include?(ENV.fetch("UPDATE_SNAPSHOTS", nil))
+      end
+
+      def write_snapshot(data)
+        FileUtils.mkdir_p(File.dirname(@snapshot_path))
+        File.write(@snapshot_path, data.to_yaml)
+      end
+    end
+  end
+end

data/lib/e11y/trace_context/sampler.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module E11y
+  module TraceContext
+    # Trace entry sampler (ADR-005 §7).
+    # Decides if trace should be sampled; respects parent decision when configured.
+    class Sampler
+      class << self
+        def should_sample?(context = {})
+          cfg = E11y.config
+          respect = cfg&.tracing_respect_parent_sampling != false
+
+          return context[:sampled] if respect && context.key?(:sampled)
+
+          rate = determine_sample_rate(context, cfg)
+          rand < rate
+        end
+
+        private
+
+        def determine_sample_rate(context, cfg)
+          return 1.0 if context[:error]
+          return 1.0 if cfg&.tracing_always_sample_if&.call(context)
+
+          if context[:event_name] && cfg&.tracing_per_event_sample_rates
+            rate = cfg.tracing_per_event_sample_rates[context[:event_name].to_s]
+            return rate if rate
+          end
+
+          (cfg&.tracing_default_sample_rate || 0.1).to_f
+        end
+      end
+    end
+  end
+end

data/lib/e11y/tracing/faraday_middleware.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# This file is only loaded explicitly via E11y::Tracing.install_faraday_middleware!
+# (which calls require "faraday" first) and is NOT autoloaded by Zeitwerk on startup.
+# Faraday is an optional dependency — see e11y.gemspec.
+
+module E11y
+  module Tracing
+    # Faraday middleware that injects W3C traceparent header into outgoing requests.
+    #
+    # Register once via E11y::Tracing.install_faraday_middleware!, then use per connection:
+    #
+    #   conn = Faraday.new(url: "https://api.example.com") do |f|
+    #     f.request :e11y_tracing
+    #     f.adapter Faraday.default_adapter
+    #   end
+    #
+    # @see E11y::Tracing.install_faraday_middleware!
+    # @see E11y::Tracing::Propagator
+    class FaradayMiddleware < ::Faraday::Middleware
+      # Inject traceparent into outgoing request headers and pass to next middleware.
+      #
+      # @param env [Faraday::Env] Faraday request environment
+      # @return [Faraday::Response]
+      def call(env)
+        Propagator.inject(env.request_headers)
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/e11y/tracing/net_http_patch.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module E11y
+  module Tracing
+    # Monkey-patch for Net::HTTP that injects W3C traceparent into every request.
+    #
+    # Applied via +prepend+ so it wraps the original +#request+ method:
+    #
+    #   E11y::Tracing.patch_net_http!
+    #   # From this point all Net::HTTP requests carry the traceparent header.
+    #
+    # The patch is idempotent — prepending twice is prevented by checking
+    # +Net::HTTP.ancestors+.
+    #
+    # @see E11y::Tracing.patch_net_http!
+    # @see E11y::Tracing::Propagator
+    module NetHTTPPatch
+      # Inject traceparent header then delegate to the original Net::HTTP#request.
+      #
+      # Skips injection if traceparent is already set on the request object
+      # (e.g., caller set it manually).
+      #
+      # @param req  [Net::HTTPRequest] Outgoing HTTP request object
+      # @param body [String, nil]      Optional body
+      # @return [Net::HTTPResponse]
+      def request(req, body = nil, &)
+        header_value = Propagator.build_traceparent
+        req[Propagator::TRACEPARENT_HEADER] = header_value if header_value && !req[Propagator::TRACEPARENT_HEADER]
+        super
+      end
+    end
+  end
+end

data/lib/e11y/tracing/propagator.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module E11y
+  module Tracing
+    # W3C Trace Context propagator.
+    #
+    # Builds, injects, and parses W3C traceparent headers.
+    # Format: {version}-{trace-id}-{parent-id}-{flags}
+    # Example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
+    #
+    # @see https://www.w3.org/TR/trace-context/
+    # @see UC-009 Multi-Service Tracing
+    class Propagator
+      TRACEPARENT_VERSION = "00"
+      SAMPLED_FLAG = "01"
+      TRACEPARENT_HEADER = "traceparent"
+      TRACESTATE_HEADER = "tracestate"
+
+      # Build a W3C traceparent header value from the current trace context.
+      #
+      # Falls back to E11y::Current if explicit ids are not provided.
+      # Generates a random span_id if none is set.
+      # Returns nil when no trace_id is available.
+      #
+      # @param trace_id [String, nil] Override trace_id (optional)
+      # @param span_id  [String, nil] Override span_id (optional)
+      # @return [String, nil] e.g. "00-abc...32hex-def...16hex-01", or nil
+      def self.build_traceparent(trace_id: nil, span_id: nil)
+        t_id = trace_id || E11y::Current.trace_id
+        return nil if t_id.nil? || t_id.empty?
+
+        s_id = span_id || E11y::Current.span_id
+        s_id = SecureRandom.hex(8) if s_id.nil? || s_id.empty?
+
+        sampled = E11y::Current.respond_to?(:sampled) ? E11y::Current.sampled : true
+        flags = sampled == false ? "00" : SAMPLED_FLAG
+        "#{TRACEPARENT_VERSION}-#{t_id}-#{s_id}-#{flags}"
+      end
+
+      # Inject W3C trace context headers into a plain Hash of headers.
+      #
+      # Mutates +headers+ in place and returns it.
+      # Does NOT override an existing traceparent entry.
+      # Adds tracestate when E11y::Current.baggage is present (F-014).
+      #
+      # @param headers  [Hash]        Headers hash to mutate
+      # @param trace_id [String, nil] Override trace_id (optional)
+      # @param span_id  [String, nil] Override span_id (optional)
+      # @return [Hash] The (possibly mutated) headers hash
+      def self.inject(headers, trace_id: nil, span_id: nil)
+        unless headers[TRACEPARENT_HEADER]
+          header_value = build_traceparent(trace_id: trace_id, span_id: span_id)
+          headers[TRACEPARENT_HEADER] = header_value if header_value
+        end
+
+        if !headers[TRACESTATE_HEADER] && E11y::Current.respond_to?(:baggage) && E11y::Current.baggage&.any?
+          filtered = filter_baggage_for_propagation(E11y::Current.baggage)
+          headers[TRACESTATE_HEADER] = build_tracestate(filtered) if filtered.any?
+        end
+
+        headers
+      end
+
+      # Parse W3C tracestate header to Hash (key=value pairs).
+      # @param tracestate [String, nil] Raw header value
+      # @return [Hash] String keys and values (empty hash if invalid)
+      def self.parse_tracestate(tracestate)
+        return {} unless tracestate.is_a?(String)
+
+        tracestate.split(",").each_with_object({}) do |entry, hash|
+          key, value = entry.split("=", 2)
+          hash[key.strip] = value.to_s.strip if key && !key.strip.empty?
+        end
+      end
+
+      # Build W3C tracestate header from baggage Hash.
+      # @param baggage_hash [Hash] String keys and values
+      # @return [String] e.g. "key1=value1,key2=value2"
+      def self.build_tracestate(baggage_hash)
+        return "" unless baggage_hash.is_a?(Hash) && baggage_hash.any?
+
+        baggage_hash.map { |k, v| "#{k}=#{v}" }.join(",")
+      end
+
+      # Filter baggage to allowed keys only (ADR-006 §5.5, PII protection).
+      def self.filter_baggage_for_propagation(baggage_hash)
+        cfg = E11y.config
+        return baggage_hash if cfg.nil?
+
+        cfg.filter_baggage_for_propagation(baggage_hash)
+      end
+
+      # Parse a W3C traceparent header string.
+      #
+      # @param traceparent [String, nil] Raw header value
+      # @return [Hash, nil] +{ trace_id:, parent_span_id:, sampled: }+ or nil if invalid
+      def self.parse(traceparent)
+        return nil unless traceparent.is_a?(String)
+
+        parts = traceparent.split("-")
+        return nil unless parts.size == 4
+
+        _version, trace_id, parent_span_id, flags = parts
+        return nil if trace_id.nil? || trace_id.empty?
+
+        {
+          trace_id: trace_id,
+          parent_span_id: parent_span_id,
+          sampled: flags == SAMPLED_FLAG
+        }
+      end
+    end
+  end
+end

data/lib/e11y/tracing.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module E11y
+  # Outgoing HTTP trace context propagation (UC-009).
+  #
+  # Provides W3C Trace Context injection into outgoing HTTP requests
+  # via Faraday middleware and Net::HTTP monkey-patch.
+  #
+  # @example Enable Net::HTTP tracing
+  #   E11y::Tracing.patch_net_http!
+  #
+  # @example Enable Faraday tracing (register middleware, then use in connection)
+  #   E11y::Tracing.install_faraday_middleware!
+  #   conn = Faraday.new { |f| f.request :e11y_tracing }
+  #
+  # @see UC-009 Multi-Service Tracing
+  # @see https://www.w3.org/TR/trace-context/
+  module Tracing
+    # Install Net::HTTP tracing patch (idempotent).
+    #
+    # Prepends E11y::Tracing::NetHTTPPatch into Net::HTTP so that every
+    # outgoing request automatically carries a W3C traceparent header.
+    #
+    # @return [void]
+    def self.patch_net_http!
+      require "net/http"
+      require "e11y/tracing/net_http_patch"
+      return if ::Net::HTTP <= E11y::Tracing::NetHTTPPatch
+
+      ::Net::HTTP.prepend(E11y::Tracing::NetHTTPPatch)
+    end
+
+    # Register the Faraday middleware so it can be referenced by name (idempotent).
+    #
+    # After calling this, add +f.request :e11y_tracing+ to any Faraday connection
+    # that should propagate trace context.
+    #
+    # @return [void]
+    def self.install_faraday_middleware!
+      require "faraday"
+      require "e11y/tracing/faraday_middleware"
+      return if ::Faraday::Request.registered_middleware.key?(:e11y_tracing)
+
+      ::Faraday::Request.register_middleware(e11y_tracing: E11y::Tracing::FaradayMiddleware)
+    end
+  end
+end

data/lib/e11y/version.rb

@@ -5,5 +5,5 @@ module E11y
   # - MAJOR: Breaking changes (incompatible API changes)
   # - MINOR: New features (backwards-compatible)
   # - PATCH: Bug fixes (backwards-compatible)
-  VERSION = "0.2.0"
+  VERSION = "1.0.0"
 end

data/lib/e11y/versioning/version_extractor.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module E11y
+  module Versioning
+    # Extracts version number and base name from event class names (ADR-012 §3.2).
+    #
+    # @example
+    #   VersionExtractor.extract_version("Events::OrderPaidV2")  # => 2
+    #   VersionExtractor.extract_version("Events::OrderPaid")    # => 1
+    #   VersionExtractor.extract_base_name("Events::OrderPaidV2") # => "Events::OrderPaid"
+    class VersionExtractor
+      VERSION_REGEX = /V(\d+)$/
+
+      # @param class_name [String] Event class name (e.g. "Events::OrderPaidV2")
+      # @return [Integer] Version number (1 if no suffix)
+      def self.extract_version(class_name)
+        return 1 unless class_name
+
+        match = class_name.to_s.match(VERSION_REGEX)
+        match ? match[1].to_i : 1
+      end
+
+      # @param class_name [String] Event class name
+      # @return [String] Base name without version suffix (e.g. "Events::OrderPaid")
+      def self.extract_base_name(class_name)
+        return class_name unless class_name
+
+        class_name.to_s.sub(VERSION_REGEX, "")
+      end
+    end
+  end
+end