e11y 0.2.0 → 1.1.0

data/lib/e11y/middleware/event_slo.rb

@@ -69,23 +69,30 @@ module E11y
         # Skip if SLO not enabled for this event
         # Support explicit event_class (for testing) or resolve from event_name
         event_class = event_data[:event_class] || resolve_event_class(event_data)
-        return event_data unless event_class.respond_to?(:slo_config)
-        return event_data unless event_class.slo_config&.enabled?
+        unless event_class.respond_to?(:slo_config) && event_class.slo_config&.enabled?
+          # Pass to next middleware even if SLO not enabled
+          return @app&.call(event_data) || event_data
+        end
 
         # Compute slo_status from payload
         slo_status = compute_slo_status(event_class, event_data[:payload])
-        return event_data unless slo_status
+        unless slo_status
+          # Pass to next middleware even if slo_status is nil
+          return @app&.call(event_data) || event_data
+        end
 
-        # Emit SLO metric
-        emit_slo_metric(event_class, slo_status, event_data[:payload])
+        # Emit SLO metric (with sampling correction when stratified sampling enabled)
+        emit_slo_metric(event_class, slo_status, event_data[:payload], event_data)
 
-        event_data # Passthrough (never modify event_data)
+        # Pass to next middleware (Routing writes to adapters)
+        @app&.call(event_data) || event_data
       rescue StandardError => e
         # Never fail event tracking due to SLO processing
         E11y.logger.error(
           "[E11y::Middleware::EventSlo] SLO processing failed for #{event_data[:event_name]}: #{e.message}"
         )
-        event_data
+        # Still pass to next middleware even on error
+        @app&.call(event_data) || event_data
       end
 
       private
@@ -124,15 +131,22 @@ module E11y
       end
 
       # Emit SLO metric to Yabeda/Prometheus.
+      # C11: Applies stratified sampling correction when event was sampled.
       #
       # @param event_class [Class] Event class
       # @param slo_status [String] 'success' or 'failure'
       # @param payload [Hash] Event payload
+      # @param event_data [Hash] Full event data (for sample_rate)
       # @return [void]
-      def emit_slo_metric(event_class, slo_status, payload)
+      def emit_slo_metric(event_class, slo_status, payload, _event_data = {})
         labels = build_slo_labels(event_class, slo_status, payload)
 
-        E11y::Metrics.increment(:slo_event_result_total, labels)
+        # C11: Apply sampling correction for accurate SLO with stratified sampling
+        stratum = slo_status == "success" ? :success : :error
+        correction = E11y::Sampling.stratified_tracker.sampling_correction(stratum)
+        value = (correction * 100).round / 100.0 # Round to 2 decimals for Prometheus
+
+        E11y::Metrics.increment(:slo_event_result_total, labels, value: value)
       rescue StandardError => e
         E11y.logger.error(
           "[E11y::Middleware::EventSlo] Failed to emit SLO metric for #{event_class.name}: #{e.message}"

data/lib/e11y/middleware/otel_span.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # OtelSpan middleware — creates OpenTelemetry spans from events (ADR-007 §6, F2).
+    #
+    # When config.opentelemetry_span_creation_patterns is set, creates OTel spans
+    # for matching events. Errors/fatal always create spans.
+    #
+    # @see E11y::OpenTelemetry::SpanCreator
+    # @see ADR-007 §6 Traces Signal Export
+    class OtelSpan < Base
+      middleware_zone :adapters
+
+      def call(event_data)
+        if defined?(::OpenTelemetry::Trace) && defined?(E11y::OpenTelemetry::SpanCreator)
+          E11y::OpenTelemetry::SpanCreator.create_span_from_event(event_data)
+        end
+        @app.call(event_data)
+      end
+    end
+  end
+end

data/lib/e11y/middleware/pii_filter.rb

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
+require "active_support/parameter_filter"
+
 module E11y
   module Middleware
-    # PII Filter Middleware - 3-Tier Strategy
+    # PII Filter Middleware
     #
     # Filters Personally Identifiable Information (PII) from event payloads
-    # before they reach adapters. Implements ADR-006 3-tier security model.
+    # before they reach adapters. Implements ADR-006 security model.
     #
-    # **Three-Tier Strategy:**
-    # - Tier 1: No PII (`contains_pii false`) - Skip filtering (0ms overhead)
-    # - Tier 2: Default - Rails filters only (~0.05ms overhead)
-    # - Tier 3: Explicit PII (`contains_pii true`) - Deep filtering (~0.2ms overhead)
+    # **Filtering modes:**
+    # - :no_pii — Skip filtering (contains_pii false, 0ms overhead)
+    # - :rails_filters — Rails filter_parameters only (~0.05ms overhead)
+    # - :explicit_pii — Field strategies, optionally per-adapter via exclude_adapters (~0.2ms)
     #
-    # @example Basic Usage (Tier 2 - Default)
+    # @example Basic Usage (:rails_filters - default)
     #   class Events::OrderCreated < E11y::Event::Base
     #     schema do
     #       required(:order_id).filled(:string)
@@ -20,12 +22,12 @@ module E11y
     #     end
     #   end
     #
-    # @example Tier 1: No PII (High Performance)
+    # @example :no_pii (skip filtering)
     #   class Events::HealthCheck < E11y::Event::Base
-    #     contains_pii false  # Skip all filtering
+    #     contains_pii false
     #   end
     #
-    # @example Tier 3: Explicit PII (Deep Filtering)
+    # @example :explicit_pii (field strategies)
     #   class Events::UserRegistered < E11y::Event::Base
     #     contains_pii true
     #
@@ -40,7 +42,6 @@ module E11y
     # @see UC-007 PII Filtering
     # @see E11y::PII::Patterns
     # rubocop:disable Metrics/ClassLength
-    # PII filter is a cohesive security component with 3-tier filtering strategy
     class PIIFilter < Base
       middleware_zone :security
 
@@ -53,27 +54,24 @@ module E11y
         @config = config
       end
 
-      # Process event and filter PII based on tier
+      # Process event and filter PII based on filtering mode
       #
       # @param event_data [Hash] Event data with payload
       # @return [Hash] Processed event data
       # rubocop:disable Lint/DuplicateBranch
-      # Unknown tiers intentionally fallback to no filtering (same as tier1)
       def call(event_data)
-        # Determine filtering tier
-        tier = determine_tier(event_data)
+        return @app.call(event_data) if event_data[:dlq_replayed]
+
+        mode = filtering_mode(event_data)
 
-        case tier
-        when :tier1
-          # Tier 1: No PII - Skip filtering (0ms overhead)
+        case mode
+        when :no_pii
           @app.call(event_data)
-        when :tier2
-          # Tier 2: Rails filters only (~0.05ms overhead)
+        when :rails_filters
           filtered_data = apply_rails_filters(event_data)
           @app.call(filtered_data)
-        when :tier3
-          # Tier 3: Deep filtering (~0.2ms overhead)
-          filtered_data = apply_deep_filtering(event_data)
+        when :explicit_pii
+          filtered_data = apply_explicit_pii_filtering(event_data)
           @app.call(filtered_data)
         else
           @app.call(event_data)
@@ -83,16 +81,11 @@ module E11y
 
       private
 
-      # Determine PII filtering tier for event
-      #
-      # @param event_data [Hash] Event data
-      # @return [Symbol] :tier1, :tier2, or :tier3
-      def determine_tier(event_data)
+      def filtering_mode(event_data)
         event_class = event_data[:event_class]
-        return :tier2 unless event_class.respond_to?(:pii_tier)
+        return :rails_filters unless event_class.respond_to?(:pii_filtering_mode)
 
-        # Return tier directly from event class
-        event_class.pii_tier
+        event_class.pii_filtering_mode
       end
 
       # Apply Rails filter_parameters (Tier 2)
@@ -109,52 +102,71 @@ module E11y
         filtered_data
       end
 
-      # Apply deep PII filtering (Tier 3)
-      #
-      # @param event_data [Hash] Event data
-      # @return [Hash] Filtered event data
-      def apply_deep_filtering(event_data)
+      # :explicit_pii — field strategies, optionally payload_rewrites when exclude_adapters present.
+      def apply_explicit_pii_filtering(event_data)
         event_class = event_data[:event_class]
         return event_data unless event_class
 
-        # Clone to avoid modifying original
-        filtered_data = deep_dup(event_data)
-
-        # Get PII filtering config from event class
         pii_config = event_class.pii_filtering_config if event_class.respond_to?(:pii_filtering_config)
-        return filtered_data unless pii_config
+        return event_data unless pii_config
+
+        # 1. Base payload (most restrictive)
+        base_payload = apply_field_strategies(deep_dup(event_data[:payload]), pii_config, nil)
+        base_payload = apply_pattern_filtering(base_payload, pii_config, [])
 
-        # Apply field-level strategies
-        filtered_data[:payload] = apply_field_strategies(
-          filtered_data[:payload],
-          pii_config
-        )
+        filtered_data = deep_dup(event_data)
+        filtered_data[:payload] = base_payload
 
-        # Apply pattern-based filtering
-        filtered_data[:payload] = apply_pattern_filtering(
-          filtered_data[:payload]
-        )
+        # 2. payload_rewrites: per-adapter overrides for exclude_adapters fields only
+        has_exclude_adapters = pii_config[:fields]&.any? { |_, v| v[:exclude_adapters]&.any? }
+        filtered_data[:payload_rewrites] = build_payload_rewrites(event_data, pii_config) if has_exclude_adapters
 
         filtered_data
       end
 
+      # Build payload_rewrites: { adapter_name => { field => original_value } }
+      # Only fields with exclude_adapters.include?(adapter) get original value.
+      def build_payload_rewrites(event_data, pii_config)
+        adapters = AdapterResolver.resolve(event_data)
+        return {} unless adapters.any?
+
+        original_payload = event_data[:payload] || {}
+        rewrites = {}
+
+        adapters.each do |adapter_name|
+          adapter_rewrites = {}
+          pii_config[:fields]&.each do |field, opts|
+            next unless opts[:exclude_adapters]&.include?(adapter_name)
+
+            key = original_payload.key?(field) ? field : field.to_s
+            adapter_rewrites[key] = original_payload[key] if original_payload.key?(key)
+          end
+          rewrites[adapter_name] = adapter_rewrites if adapter_rewrites.any?
+        end
+        rewrites
+      end
+
       # Apply field-level filtering strategies
       #
       # @param payload [Hash] Payload to filter
       # @param config [Hash] PII configuration
+      # @param adapter_name [Symbol, nil] When set, use :skip for fields with exclude_adapters.include?(adapter_name)
       # @return [Hash] Filtered payload
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
-      # Field strategies require case/when for each PII filtering strategy type
-      def apply_field_strategies(payload, config)
+      # rubocop:disable Metrics/MethodLength
+      def apply_field_strategies(payload, config, adapter_name = nil)
         return payload unless config
 
         filtered = {}
 
         payload.each do |key, value|
-          strategy = config.dig(:fields, key, :strategy) || :allow
+          normalized_key = key.is_a?(Symbol) ? key : key.to_sym
+          field_config = config.dig(:fields, normalized_key) || {}
+          strategy = field_config[:strategy] || :allow
+
+          # Per-adapter: use :skip for excluded adapters (e.g. audit gets original)
+          strategy = :allow if adapter_name && field_config[:exclude_adapters]&.include?(adapter_name)
 
           # rubocop:disable Lint/DuplicateBranch
-          # Unknown strategies intentionally fallback to allow (same as :allow)
           filtered[key] = case strategy
                           when :mask
                             "[FILTERED]"
@@ -164,7 +176,7 @@ module E11y
                             partial_mask(value)
                           when :redact
                             nil
-                          when :allow
+                          when :allow, :skip
                             value
                           else
                             value
@@ -174,34 +186,45 @@ module E11y
 
         filtered
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+      # rubocop:enable Metrics/MethodLength
 
       # Apply pattern-based filtering to string values
-      #
-      # @param data [Object] Data to filter (recursively)
-      # @return [Object] Filtered data
-      def apply_pattern_filtering(data)
+      def apply_pattern_filtering(data, pii_config = nil, path = [])
         case data
-        when Hash
-          data.transform_values { |v| apply_pattern_filtering(v) }
-        when Array
-          data.map { |v| apply_pattern_filtering(v) }
-        when String
-          filter_string_patterns(data)
-        else
-          data
+        when Hash then apply_pattern_filtering_hash(data, pii_config, path)
+        when Array then data.map { |v| apply_pattern_filtering(v, pii_config, path) }
+        when String then filter_string_if_needed(data, path, pii_config)
+        else data
         end
       end
 
-      # Filter PII patterns in string
+      def apply_pattern_filtering_hash(data, pii_config, path)
+        data.each_with_object({}) do |(k, v), acc|
+          key_sym = k.is_a?(Symbol) ? k : k.to_sym
+          acc[k] = apply_pattern_filtering(v, pii_config, path + [key_sym])
+        end
+      end
+
+      def filter_string_if_needed(str, path, pii_config)
+        path_under_allowed_key?(path, pii_config) ? str : filter_string_patterns(str)
+      end
+
+      # Check if any ancestor key in path is explicitly allowed
+      def path_under_allowed_key?(path, pii_config)
+        return false unless pii_config && pii_config[:fields]
+
+        allowed_keys = pii_config[:fields].select { |_k, v| %i[allow skip].include?(v[:strategy]) }.keys
+        path.any? { |p| allowed_keys.include?(p) }
+      end
+
+      # Filter PII patterns in string (VALUE_PATTERNS only, not PASSWORD_FIELDS)
       #
       # @param str [String] String to filter
       # @return [String] Filtered string
       def filter_string_patterns(str)
         result = str.dup
 
-        # Apply all PII patterns
-        E11y::PII::Patterns::ALL.each do |pattern|
+        E11y::PII::Patterns::VALUE_PATTERNS.each do |pattern|
           result = result.gsub(pattern, "[FILTERED]")
         end
 
@@ -261,12 +284,18 @@ module E11y
       # Get Rails parameter filter
       #
       # Uses Rails.application.config.filter_parameters for PII filtering.
+      # When Rails is not loaded (e.g. unit tests), uses empty filter (no-op).
       #
       # @return [ActiveSupport::ParameterFilter] Parameter filter
       def parameter_filter
-        @parameter_filter ||= ActiveSupport::ParameterFilter.new(
-          Rails.application.config.filter_parameters
-        )
+        return @parameter_filter if defined?(@parameter_filter) && !@parameter_filter.nil?
+
+        filters = if defined?(Rails) && Rails.application
+                    Rails.application.config.filter_parameters
+                  else
+                    []
+                  end
+        @parameter_filter = ActiveSupport::ParameterFilter.new(filters)
       end
     end
     # rubocop:enable Metrics/ClassLength

data/lib/e11y/middleware/rate_limiting.rb

@@ -30,7 +30,7 @@ module E11y
     #
     # @example Critical Event Bypass (C02)
     #   # Payment events bypass rate limiting → DLQ if limited
-    #   config.dlq_filter.always_save_patterns = [/^payment\./]
+    #   config.dlq_filter.should_save?(event_data) # Event DSL: use_dlq
     #
     #   # Result: Rate-limited payment events go to DLQ, not dropped
     #
@@ -40,22 +40,33 @@ module E11y
       # Initialize rate limiting middleware
       #
       # @param app [Object] Next middleware in pipeline
-      # @param global_limit [Integer] Max events/sec globally (default: 10_000)
-      # @param per_event_limit [Integer] Max events/sec per event type (default: 1_000)
-      # @param window [Float] Time window in seconds (default: 1.0)
-      def initialize(app, global_limit: 10_000, per_event_limit: 1_000, window: 1.0)
+      # @param global_limit [Integer] Max events/sec globally (default: from E11y.config)
+      # @param per_event_limit [Integer] Max events/sec per event type (default: from E11y.config)
+      # @param window [Float] Time window in seconds (default: from E11y.config)
+      def initialize(app, global_limit: nil, per_event_limit: nil, window: nil)
         super(app)
-        @global_limit = global_limit
-        @per_event_limit = per_event_limit
-        @window = window
+        config = E11y.config
+        # When explicit limits are passed (e.g. from pipeline options), enable for this instance
+        explicit_opts = global_limit || per_event_limit || window
+        @enabled = explicit_opts ? true : config.rate_limiting_enabled
+        @global_limit = global_limit || config.rate_limiting_global_limit
+        @global_window = window || config.rate_limiting_global_window
+        @window = @global_window # Alias for spec compatibility
+        @per_event_limit = per_event_limit || config.rate_limiting_per_event_limit
+        @explicit_per_event = per_event_limit && window
 
         # Token buckets for rate limiting
-        @global_bucket = TokenBucket.new(capacity: @global_limit, refill_rate: @global_limit, window: @window)
+        @global_bucket = TokenBucket.new(
+          capacity: @global_limit,
+          refill_rate: @global_limit,
+          window: @global_window
+        )
         @per_event_buckets = Hash.new do |hash, event_name|
+          limit_cfg = @explicit_per_event ? { limit: @per_event_limit, window: @window } : config.rate_limit_for(event_name)
           hash[event_name] = TokenBucket.new(
-            capacity: @per_event_limit,
-            refill_rate: @per_event_limit,
-            window: @window
+            capacity: limit_cfg[:limit],
+            refill_rate: limit_cfg[:limit],
+            window: limit_cfg[:window]
           )
         end
 
@@ -67,6 +78,8 @@ module E11y
       # @param event_data [Hash] Event payload
       # @return [Hash, nil] Event data if allowed, nil if rate limited
       def call(event_data)
+        return @app.call(event_data) unless @enabled
+
         event_name = event_data[:event_name]
 
         # Check global rate limit
@@ -83,7 +96,7 @@ module E11y
         end
 
         # Rate limit not exceeded - continue pipeline
-        event_data
+        @app.call(event_data)
       end
 
       private
@@ -97,16 +110,31 @@ module E11y
       def handle_rate_limited(event_data, limit_type)
         event_name = event_data[:event_name]
 
-        # Log rate limiting
-        warn "[E11y] Rate limit exceeded (#{limit_type}) for event: #{event_name}"
+        # Log rate limiting (via E11y.logger so it respects Rails.logger in test env)
+        E11y.logger&.warn("[E11y] Rate limit exceeded (#{limit_type}) for event: #{event_name}")
 
         # C02 Resolution: Check if event should be saved to DLQ
-        return unless should_save_to_dlq?(event_data)
-
-        save_to_dlq(event_data, limit_type)
+        if should_save_to_dlq?(event_data)
+          record_dropped_metric(event_data, "rate_limited_#{limit_type}_dlq")
+          save_to_dlq(event_data, limit_type)
+        else
+          record_dropped_metric(event_data, "rate_limited_#{limit_type}")
+        end
+      end
 
-        # Non-critical events are dropped (no DLQ)
-        # TODO: Track metric e11y.rate_limiter.dropped
+      # Record e11y_events_dropped_total metric (non-fatal, safe when Metrics unavailable)
+      #
+      # @param event_data [Hash] Event payload
+      # @param reason [String] Drop reason (e.g., sampled_out, rate_limited_global)
+      def record_dropped_metric(event_data, reason)
+        return unless defined?(E11y::Metrics) && E11y::Metrics.respond_to?(:increment)
+
+        E11y::Metrics.increment(:e11y_events_dropped_total, {
+                                  reason: reason,
+                                  event_type: event_data[:event_name].to_s
+                                })
+      rescue StandardError
+        # non-fatal
       end
 
       # Check if rate-limited event should be saved to DLQ (C02 Resolution)
@@ -120,9 +148,8 @@ module E11y
         dlq_filter = E11y.config.dlq_filter
         return false unless dlq_filter
 
-        # Check if event matches always_save_patterns
-        event_name = event_data[:event_name]
-        dlq_filter.always_save_patterns&.any? { |pattern| pattern.match?(event_name) }
+        # Use DLQ filter (Event DSL: use_dlq, severity, default)
+        dlq_filter.should_save?(event_data)
       end
 
       # Save rate-limited critical event to DLQ (C02 Resolution)
@@ -135,19 +162,19 @@ module E11y
         dlq_storage = E11y.config.dlq_storage
         return unless dlq_storage
 
+        per_event_limit = limit_type == :per_event ? E11y.config.rate_limit_for(event_data[:event_name])[:limit] : @per_event_limit
         dlq_storage.save(event_data, metadata: {
                            reason: "rate_limited_#{limit_type}",
                            limit_type: limit_type,
                            global_limit: @global_limit,
-                           per_event_limit: @per_event_limit,
+                           per_event_limit: per_event_limit,
                            timestamp: Time.now.utc.iso8601
                          })
 
-        warn "[E11y] Rate-limited critical event saved to DLQ: #{event_data[:event_name]}"
-        # TODO: Track metric e11y.rate_limiter.dlq_saved
+        E11y.logger&.warn("[E11y] Rate-limited critical event saved to DLQ: #{event_data[:event_name]}")
       rescue StandardError => e
         # Don't fail if DLQ save fails (C18 Resolution)
-        warn "[E11y] Failed to save rate-limited event to DLQ: #{e.message}"
+        E11y.logger&.warn("[E11y] Failed to save rate-limited event to DLQ: #{e.message}")
       end
 
       # Token Bucket implementation for rate limiting