e11y 0.2.0 → 1.0.0

data/lib/e11y/debug/pipeline_inspector.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+
+module E11y
+  module Debug
+    # Debug utility to trace events through the pipeline with per-middleware logging.
+    #
+    # Runs the full pipeline including adapter writes. For debugging, use Stdout or
+    # InMemory adapter. Stub adapters in tests if needed.
+    #
+    # @see E11y.trace
+    class PipelineInspector
+      # Wraps a middleware to log enter/exit for pipeline tracing.
+      class TracingWrapper
+        def initialize(middleware_class, next_app, name, args: [], options: {})
+          @middleware_class = middleware_class
+          @next_app = next_app
+          @name = name
+          @args = args
+          @options = options
+        end
+
+        def call(event_data)
+          log_enter(@name)
+          result = @middleware_class.new(@next_app, *@args, **@options).call(event_data)
+          log_exit(@name)
+          result
+        end
+
+        private
+
+        def log_enter(name)
+          prefix = $stdout.tty? ? "\e[33m" : ""
+          suffix = $stdout.tty? ? "\e[0m" : ""
+          print "  #{prefix}#{name}#{suffix}... "
+        end
+
+        def log_exit(_name)
+          mark = $stdout.tty? ? "\e[32m✓\e[0m" : "✓"
+          puts mark
+        end
+      end
+
+      class << self
+        # Traces an event through the pipeline with per-middleware logging.
+        # Note: adapters WILL receive the event.
+        #
+        # @param event_class [Class] Event class
+        # @param payload [Hash] Event payload
+        # @return [Hash] event_data after pipeline
+        def trace_event(event_class, **payload)
+          event_name = event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name
+          puts "\n🔍 Tracing Event Pipeline: #{event_name}\n\n"
+          event_data = build_event_data(event_class, payload)
+          pipeline = build_tracing_pipeline
+          result = pipeline.call(event_data)
+          puts "\n✅ Pipeline trace complete\n"
+          result
+        end
+
+        private
+
+        def build_event_data(event_class, payload)
+          {
+            event_class: event_class,
+            event_name: event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name,
+            payload: payload,
+            severity: event_class.respond_to?(:severity) ? event_class.severity : :info,
+            version: event_class.respond_to?(:version) ? event_class.version : 1,
+            adapters: event_class.respond_to?(:adapters) ? event_class.adapters : nil,
+            timestamp: Time.now.utc,
+            retention_period: event_class.respond_to?(:retention_period) ? event_class.retention_period : 30.days,
+            context: {}
+          }
+        end
+
+        def build_tracing_pipeline
+          builder = E11y.configuration.pipeline
+          final_app = ->(event_data) { event_data }
+
+          builder.middlewares.reverse.reduce(final_app) do |next_app, entry|
+            name = entry.middleware_class.name.split("::").last
+            TracingWrapper.new(
+              entry.middleware_class,
+              next_app,
+              name,
+              args: entry.args,
+              options: entry.options
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/documentation/generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module E11y
+  module Documentation
+    # Generates Markdown documentation for registered E11y events.
+    class Generator
+      def self.generate(output_dir, criteria: {}, grep: nil)
+        classes = criteria.any? ? E11y::Registry.where(**criteria) : E11y::Registry.event_classes
+        classes = classes.select { |c| (c.respond_to?(:event_name) ? c.event_name : c.name).to_s.include?(grep) } if grep
+
+        FileUtils.mkdir_p(output_dir)
+        write_index(output_dir, classes)
+        classes.each { |klass| write_event_doc(output_dir, klass) }
+      end
+
+      def self.write_index(output_dir, classes)
+        lines = ["# E11y Events", "", "| Event | Class | Severity |", "|-------|-------|----------|"]
+        classes.each do |klass|
+          name = klass.respond_to?(:event_name) ? klass.event_name : klass.name
+          sev = klass.respond_to?(:severity) ? klass.severity : "—"
+          lines << "| #{name} | #{klass.name} | #{sev} |"
+        end
+        File.write(File.join(output_dir, "README.md"), "#{lines.join("\n")}\n")
+      end
+
+      def self.write_event_doc(output_dir, klass)
+        name = klass.respond_to?(:event_name) ? klass.event_name : klass.name
+        schema_keys = extract_schema_keys(klass)
+        sev = klass.respond_to?(:severity) ? klass.severity : "—"
+        lines = ["# #{name}", "", "- **Class:** #{klass.name}", "- **Severity:** #{sev}"]
+        lines << "- **Schema keys:** #{schema_keys.join(', ')}" if schema_keys&.any?
+        lines << ""
+        File.write(File.join(output_dir, "#{name.to_s.tr('.', '_')}.md"), "#{lines.join("\n")}\n")
+      end
+
+      def self.extract_schema_keys(klass)
+        return nil unless klass.respond_to?(:compiled_schema)
+
+        schema = klass.compiled_schema
+        return nil if schema.nil? || !schema.respond_to?(:key_map)
+
+        schema.key_map.keys.map(&:name)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/e11y/event/base.rb

@@ -81,22 +81,38 @@ module E11y
         # - Auto-calculated retention_until from retention_period
         #
         # @param payload [Hash] Event data matching the schema
+        # @yield Optional block — measured for duration; adds :duration_ms to payload
         # @return [Hash] Event hash (includes metadata)
         #
-        # @example
+        # @example Without block
         #   UserSignupEvent.track(user_id: 123, email: "user@example.com")
         #   # => { event_name: "UserSignupEvent", payload: {...}, severity: :info, adapters: [:logs], ... }
         #
+        # @example With block (duration measurement)
+        #   Events::OrderPaid.track(order_id: '123') { ExternalPaymentService.charge! }
+        #   # => payload includes duration_ms automatically
+        #
         # @raise [E11y::ValidationError] if payload doesn't match schema (when validation runs)
-        def track(**payload)
+        def track(**payload, &block)
           return unless E11y.config.enabled
 
+          # Block form: execute block, measure duration, capture return value
+          block_result = nil
+          if block
+            start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+            block_result = yield
+            payload = payload.merge(duration_ms: Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - start)
+          end
+
+          # Severity: payload override (e.g. exception → :error) or class default
+          resolved_severity = payload[:severity] || payload["severity"] || severity
+
           # Build event data hash for pipeline processing
           event_data = {
             event_class: self,
             event_name: event_name,
             payload: payload,
-            severity: severity,
+            severity: resolved_severity,
             version: version,
             adapters: adapters,
             timestamp: Time.now.utc,
@@ -109,8 +125,8 @@ module E11y
           # Routing middleware is the LAST middleware and it writes to adapters directly
           E11y.config.built_pipeline.call(event_data)
 
-          # Return event data for testing/debugging
-          event_data
+          # With block: return block's result (caller cares about it); without: return event_data
+          block ? block_result : event_data
         end
 
         # Build event hash
@@ -240,9 +256,7 @@ module E11y
         #   end
         def severity(value = nil)
           if value
-            unless SEVERITIES.include?(value)
-              raise ArgumentError, "Invalid severity: #{value}. Must be one of: #{SEVERITIES.join(', ')}"
-            end
+            raise ArgumentError, "Invalid severity: #{value}. Must be one of: #{SEVERITIES.join(', ')}" unless SEVERITIES.include?(value)
 
             @severity = value
           end
@@ -263,13 +277,15 @@ module E11y
         #   class OrderPaidEventV2 < E11y::Event::Base
         #     version 2
         #   end
+        VERSION_REGEX = /V(\d+)$/
+
         def version(value = nil)
           @version = value if value
-          # Return explicitly set version OR inherit from parent (if set) OR default to 1
           return @version if @version
-          return superclass.version if superclass != E11y::Event::Base && superclass.instance_variable_get(:@version)
 
-          1
+          # Auto-extract from class name (e.g. OrderPaidV2 → 2)
+          match = name&.match(VERSION_REGEX)
+          match ? match[1].to_i : 1
         end
 
         # Set or get retention period for this event
@@ -299,14 +315,15 @@ module E11y
           @retention_period = value if value
           # Return explicitly set retention_period OR inherit from parent (if set) OR config default OR final fallback
           return @retention_period if @retention_period
-          if superclass != E11y::Event::Base && superclass.instance_variable_get(:@retention_period)
-            return superclass.retention_period
-          end
+          return superclass.retention_period if superclass != E11y::Event::Base && superclass.instance_variable_get(:@retention_period)
 
           # Fallback to configuration or 30 days
           E11y.configuration&.default_retention_period || 30.days
         end
 
+        # Convenience alias — matches Quick Start documentation.
+        alias retention retention_period
+
         # Set or get adapters for this event
         #
         # Adapters are referenced by NAME (e.g., :logs, :errors_tracker).
@@ -331,16 +348,42 @@ module E11y
           return @adapters if @adapters
           return superclass.adapters if superclass != E11y::Event::Base && superclass.instance_variable_get(:@adapters)
 
+          # No explicit adapters: inherit from parent or resolve from severity
+          # (audit events and regular events both use severity-based mapping)
           resolved_adapters
         end
 
-        # Get event name (normalized)
+        # Get or set event name (normalized)
         #
-        # @return [String] Event name without version suffix
+        # When called with a value, stores it and auto-registers the class in `E11y::Registry`.
+        # When called without a value, derives the name from the class name (stripping version suffix).
         #
-        # @example
+        # @param value [String, Symbol, nil] Explicit event name to set, or nil to read
+        # @return [String] Event name
+        #
+        # @example Explicit name
+        #   class OrderPaidEvent < E11y::Event::Base
+        #     event_name "order.paid"
+        #   end
+        #
+        # @example Auto-derived name
         #   OrderPaidEventV2.event_name # => "OrderPaidEvent"
-        def event_name
+        def event_name(value = nil)
+          if value
+            @event_name = value.to_s
+            @event_name_explicit = true
+            # Auto-register in E11y::Registry when an explicit name is set.
+            # Guard with defined? so that loading order does not matter.
+            # NOTE: call register AFTER setting @event_name_explicit so that any
+            # re-entrant call to event_name (from Registry#register) returns the
+            # correct value instead of falling through to the auto-derive path.
+            E11y::Registry.register(self) if defined?(E11y::Registry)
+            return @event_name
+          end
+
+          # Return explicitly-set name unconditionally (works for anonymous classes too)
+          return @event_name if @event_name_explicit
+
           # Don't cache for anonymous classes (name returns nil)
           return @event_name if @event_name && name
 
@@ -365,7 +408,6 @@ module E11y
         #   class CriticalEvent < E11y::Event::Base
         #     sample_rate 1.0  # 100% sampling
         #   end
-        # rubocop:disable Metrics/CyclomaticComplexity
         def sample_rate(value = nil)
           if value
             unless value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
@@ -377,13 +419,10 @@ module E11y
 
           # Return explicitly set sample_rate OR inherit from parent (if set) OR nil (use resolve_sample_rate)
           return @sample_rate if @sample_rate
-          if superclass != E11y::Event::Base && superclass.instance_variable_get(:@sample_rate)
-            return superclass.sample_rate
-          end
+          return superclass.sample_rate if superclass != E11y::Event::Base && superclass.instance_variable_get(:@sample_rate)
 
           nil
         end
-        # rubocop:enable Metrics/CyclomaticComplexity
 
         # Configure value-based sampling (FEAT-4849)
         #
@@ -460,9 +499,7 @@ module E11y
 
           # Return explicitly set config OR inherit from parent (if set) OR nil
           return @adaptive_sampling if @adaptive_sampling
-          if superclass != E11y::Event::Base && superclass.instance_variable_get(:@adaptive_sampling)
-            return superclass.adaptive_sampling
-          end
+          return superclass.adaptive_sampling if superclass != E11y::Event::Base && superclass.instance_variable_get(:@adaptive_sampling)
 
           nil
         end
@@ -476,12 +513,36 @@ module E11y
         def resolve_rate_limit
           case severity
           when :error, :fatal
-            nil # Unlimited - не теряем ошибки
+            nil # Unlimited - never drop errors
           else
             1000 # 1000 events/sec
           end
         end
 
+        # Set a per-event-class rate limit for the RateLimiting middleware.
+        #
+        # Overrides the global rate limit for events of this class.
+        # error/fatal events are always exempt (never rate-limited).
+        #
+        # @param count [Integer] Max events allowed per window
+        # @param window [Numeric, ActiveSupport::Duration] Time window in seconds (default: 1.0)
+        #
+        # @example Strict limit for login failures (brute-force protection)
+        #   class Events::UserLoginFailed < E11y::Event::Base
+        #     rate_limit 100, window: 60
+        #   end
+        def rate_limit(count, window: 1.0)
+          @rate_limit_count = count
+          @rate_limit_window = window.to_f
+        end
+
+        # Per-event rate limit configuration.
+        #
+        # @return [Hash] { count: Integer|nil, window: Float|nil }
+        def rate_limit_config
+          { count: @rate_limit_count, window: @rate_limit_window }
+        end
+
         private
 
         # Determine if validation should run for this event
@@ -581,21 +642,21 @@ module E11y
         #   end
         def contains_pii(value = nil)
           if value.nil?
-            # Getter
+            return superclass.contains_pii if !instance_variable_defined?(:@contains_pii) && superclass.respond_to?(:contains_pii)
+
             @contains_pii
           else
-            # Setter
             @contains_pii = value
           end
         end
 
-        # Determine the PII filtering tier for this event.
-        # @return [Symbol] :tier1, :tier2, or :tier3
-        def pii_tier
+        # PII filtering mode for this event.
+        # @return [Symbol] :no_pii, :rails_filters, or :explicit_pii
+        def pii_filtering_mode
           case contains_pii
-          when false then :tier1
-          when true then :tier3
-          else :tier2 # Default if not explicitly declared
+          when false then :no_pii
+          when true then :explicit_pii
+          else :rails_filters # Default if not explicitly declared
           end
         end
 
@@ -610,15 +671,22 @@ module E11y
         #     allows :user_id, :amount
         #   end
         def pii_filtering(&)
-          @pii_filtering_config ||= { fields: {} }
+          if @pii_filtering_config.nil?
+            parent_config = superclass.respond_to?(:pii_filtering_config) && superclass.pii_filtering_config
+            @pii_filtering_config = parent_config ? { fields: parent_config[:fields].dup } : { fields: {} }
+          end
           builder = PIIFilteringBuilder.new(@pii_filtering_config)
           builder.instance_eval(&)
         end
 
-        # Get PII filtering configuration
+        # Get PII filtering configuration (inherits from superclass if not defined)
         #
-        # @return [Hash] PII filtering config
-        attr_reader :pii_filtering_config
+        # @return [Hash, nil] PII filtering config
+        def pii_filtering_config
+          return @pii_filtering_config if instance_variable_defined?(:@pii_filtering_config) && @pii_filtering_config
+
+          superclass.pii_filtering_config if superclass.respond_to?(:pii_filtering_config)
+        end
 
         # PII Filtering DSL Builder
         #
@@ -666,6 +734,30 @@ module E11y
           def allows(*fields)
             fields.each { |field| @config[:fields][field] = { strategy: :allow } }
           end
+
+          # Per-field config with exclude_adapters (Tier 3 per-adapter filtering).
+          #
+          # @param field [Symbol] Field name
+          # @yield Block with strategy, exclude_adapters
+          # @example
+          #   field :email do
+          #     strategy :hash
+          #     exclude_adapters [:file_audit]  # Audit gets original (GDPR)
+          #   end
+          def field(field_name, &)
+            return unless block_given?
+
+            opts = { strategy: :allow }
+            dsl = Class.new do
+              attr_reader :opts
+
+              def initialize(opts) = @opts = opts
+              def strategy(val) = @opts.[]=(:strategy, val)
+              def exclude_adapters(adapters) = @opts.[]=(:exclude_adapters, Array(adapters).map(&:to_sym))
+            end.new(opts)
+            dsl.instance_eval(&)
+            @config[:fields][field_name] = opts
+          end
         end
 
         # === Audit Event DSL (ADR-006, UC-012) ===
@@ -705,6 +797,33 @@ module E11y
           @audit_event == true
         end
 
+        # === DLQ Filter DSL (ADR-013, UC-021) ===
+
+        # Declare whether this event should be saved to DLQ on failure.
+        #
+        # @param value [Boolean, nil] true = save, false = discard, nil = use severity + default
+        # @example
+        #   class Events::PaymentFailed < E11y::Event::Base
+        #     use_dlq true
+        #   end
+        #
+        #   class Events::DebugTrace < E11y::Event::Base
+        #     use_dlq false
+        #   end
+        def use_dlq(value = nil)
+          if value.nil?
+            return superclass.use_dlq if !instance_variable_defined?(:@use_dlq) && superclass.respond_to?(:use_dlq)
+
+            @use_dlq
+          else
+            @use_dlq = value
+          end
+        end
+
+        def use_dlq?
+          use_dlq == true
+        end
+
         # Configure cryptographic signing for audit event
         #
         # By default, all audit events are signed with HMAC-SHA256.
@@ -759,7 +878,7 @@ module E11y
           audit_event? && signing_enabled?
         end
 
-        # === Metrics DSL (ADR-002, UC-003) ===
+        # === Metrics DSL (ADR-002, UC-003 Event Metrics) ===
 
         # Define metrics for this event
         #
@@ -810,6 +929,23 @@ module E11y
           register_metrics_in_registry!
         end
 
+        # Single-call metric shorthand — equivalent to a one-metric `metrics` block.
+        #
+        # @param type [Symbol] :counter, :histogram, or :gauge
+        # @param name [Symbol] Metric name
+        # @param opts [Hash] Options: tags:, value: (histogram/gauge), buckets: (histogram)
+        #
+        # @example
+        #   metric :counter, name: :orders_total, tags: [:currency]
+        #   metric :histogram, name: :order_amount, value: :amount, tags: [:currency]
+        def metric(type, name:, **opts)
+          raise ArgumentError, "Unknown metric type: #{type}. Use :counter, :histogram, or :gauge" unless %i[counter histogram gauge].include?(type)
+
+          @metrics_config ||= []
+          @metrics_config << { type: type, name: name }.merge(opts).compact
+          register_metrics_in_registry!
+        end
+
         # Get metrics configuration
         #
         # @return [Array<Hash>] Metrics configuration
@@ -911,48 +1047,6 @@ module E11y
           end
         end
       end
-
-      # Builder for PII filtering DSL
-      class PIIFilteringBuilder
-        def initialize(config)
-          @config = config
-        end
-
-        # Mask fields (strategy: :mask)
-        def masks(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :mask }
-          end
-        end
-
-        # Hash fields (strategy: :hash)
-        def hashes(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :hash }
-          end
-        end
-
-        # Allow fields (strategy: :allow)
-        def allows(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :allow }
-          end
-        end
-
-        # Partial mask fields (strategy: :partial)
-        def partials(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :partial }
-          end
-        end
-
-        # Redact fields (strategy: :redact)
-        def redacts(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :redact }
-          end
-        end
-      end
     end
     # rubocop:enable Metrics/ClassLength
   end

data/lib/e11y/event/value_sampling_config.rb

@@ -69,7 +69,6 @@ module E11y
 
       private
 
-      # rubocop:disable Metrics/CyclomaticComplexity
       # Validation requires checking multiple comparison types and threshold types
       def validate_comparisons!
         raise ArgumentError, "At least one comparison required" if comparisons.empty?
@@ -79,12 +78,9 @@ module E11y
 
           raise ArgumentError, "in_range requires a Range" if type == :in_range && !threshold.is_a?(Range)
 
-          if NUMERIC_COMPARISON_TYPES.include?(type) && !threshold.is_a?(Numeric)
-            raise ArgumentError, "#{type} requires a Numeric threshold"
-          end
+          raise ArgumentError, "#{type} requires a Numeric threshold" if NUMERIC_COMPARISON_TYPES.include?(type) && !threshold.is_a?(Numeric)
         end
       end
-      # rubocop:enable Metrics/CyclomaticComplexity
     end
   end
 end

data/lib/e11y/events/rails/database/query.rb

@@ -16,10 +16,7 @@ module E11y
         # @example Custom override
         #   # config/initializers/e11y.rb
         #   E11y.configure do |config|
-        #     config.rails_instrumentation.event_class_for(
-        #       'sql.active_record',
-        #       MyApp::CustomDatabaseQuery
-        #     )
+        #     config.rails_instrumentation_custom_mappings['sql.active_record'] = MyApp::CustomDatabaseQuery
         #   end
         #
         # @see ADR-008 §4.3 (Built-in Event Classes)

data/lib/e11y/events/rails/job/failed.rb

@@ -12,6 +12,8 @@ module E11y
             optional(:job_class).maybe(:string)
             optional(:job_id).maybe(:string)
             optional(:queue).maybe(:string)
+            optional(:error_class).maybe(:string)
+            optional(:error_message).maybe(:string)
           end
 
           severity :error