e11y 0.1.0

data/lib/e11y/event/value_sampling_config.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module E11y
+  module Event
+    # Configuration for value-based sampling at event class level (FEAT-4848)
+    #
+    # Allows events to define sampling thresholds based on payload values.
+    #
+    # @example High-value payment events
+    #   class PaymentEvent < E11y::Event::Base
+    #     sample_by_value :amount, greater_than: 1000
+    #   end
+    #
+    # @example Range-based sampling
+    #   class OrderEvent < E11y::Event::Base
+    #     sample_by_value :total, in_range: 100..500
+    #   end
+    #
+    # @example Multiple conditions (OR logic)
+    #   class TransactionEvent < E11y::Event::Base
+    #     sample_by_value :amount, greater_than: 5000
+    #     sample_by_value :status, equals: "vip"
+    #   end
+    class ValueSamplingConfig
+      attr_reader :field, :comparisons
+
+      # Initialize value sampling configuration
+      #
+      # @param field [String, Symbol] Field to extract value from
+      # @param comparisons [Hash] Comparison rules
+      # @option comparisons [Numeric] :greater_than (>) Sample if value > threshold
+      # @option comparisons [Numeric] :less_than (<) Sample if value < threshold
+      # @option comparisons [Object] :equals (==) Sample if value == threshold
+      # @option comparisons [Range] :in_range Sample if value in range
+      def initialize(field, comparisons = {})
+        @field = field
+        @comparisons = comparisons
+        validate_comparisons!
+      end
+
+      # Check if event_data matches sampling criteria
+      #
+      # @param event_data [Hash] Event payload
+      # @param extractor [E11y::Sampling::ValueExtractor] Value extractor
+      # @return [Boolean] true if value matches any comparison
+      def matches?(event_data, extractor)
+        value = extractor.extract(event_data, field)
+
+        comparisons.any? do |comparison_type, threshold|
+          case comparison_type
+          when :greater_than
+            value > threshold
+          when :less_than
+            value < threshold
+          when :equals
+            value == threshold
+          when :in_range
+            threshold.cover?(value)
+          else
+            false
+          end
+        end
+      end
+
+      private
+
+      def validate_comparisons!
+        raise ArgumentError, "At least one comparison required" if comparisons.empty?
+
+        comparisons.each do |type, threshold|
+          unless %i[greater_than less_than equals in_range].include?(type)
+            raise ArgumentError, "Invalid comparison type: #{type}"
+          end
+
+          raise ArgumentError, "in_range requires a Range" if type == :in_range && !threshold.is_a?(Range)
+
+          if %i[greater_than less_than].include?(type) && !threshold.is_a?(Numeric)
+            raise ArgumentError, "#{type} requires a Numeric threshold"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/base_audit_event.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    # Base class for audit events
+    #
+    # Audit events are compliance-critical events that must never be lost.
+    # They use the audit pipeline (Phase 4) which:
+    # - Signs events for non-repudiation
+    # - Encrypts sensitive data
+    # - Routes to audit-specific storage
+    # - Skips PII filtering (original data must be preserved)
+    #
+    # IMPORTANT: This base class does NOT set a default severity.
+    # Users must explicitly set severity based on the event's criticality:
+    # - :info for routine audit logging (e.g., "user viewed document")
+    # - :warn for suspicious actions (e.g., "unauthorized access attempt")
+    # - :error for violations (e.g., "failed authentication after 5 attempts")
+    # - :fatal for critical security events (e.g., "security breach detected")
+    #
+    # @example Audit event with explicit severity
+    #   class UserLoginAudit < E11y::Events::BaseAuditEvent
+    #     severity :info  # Explicitly set based on criticality
+    #
+    #     schema do
+    #       required(:user_id).filled(:integer)
+    #       required(:ip_address).filled(:string)
+    #       required(:timestamp).filled(:time)
+    #     end
+    #   end
+    #
+    #   UserLoginAudit.track(user_id: 123, ip_address: "192.168.1.1", timestamp: Time.now)
+    class BaseAuditEvent < E11y::Event::Base
+      include E11y::Presets::AuditEvent
+
+      # Audit events use the audit pipeline (Phase 4)
+      # For now, this is a marker - audit pipeline will be implemented later
+      def self.audit_event?
+        true
+      end
+    end
+  end
+end

data/lib/e11y/events/base_payment_event.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    # Base class for payment and high-value events
+    #
+    # Payment events require special handling:
+    # - 100% sampling (never miss a payment)
+    # - Unlimited rate limit (never drop payment events)
+    # - Multiple adapters (Loki + Sentry for alerting)
+    # - High-priority tracking
+    #
+    # @example Creating a payment event
+    #   class PaymentProcessed < E11y::Events::BasePaymentEvent
+    #     schema do
+    #       required(:payment_id).filled(:integer)
+    #       required(:amount).filled(:float)
+    #       required(:currency).filled(:string)
+    #       required(:user_id).filled(:integer)
+    #     end
+    #   end
+    #
+    #   PaymentProcessed.track(
+    #     payment_id: 123,
+    #     amount: 99.99,
+    #     currency: "USD",
+    #     user_id: 456
+    #   )
+    class BasePaymentEvent < E11y::Event::Base
+      include E11y::Presets::HighValueEvent
+    end
+  end
+end

data/lib/e11y/events/rails/cache/delete.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Cache
+        # Built-in event for cache deletes (cache_delete.active_support)
+        class Delete < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:key).maybe(:string)
+          end
+
+          severity :debug
+          sample_rate 0.1 # Sample cache deletes at 10%
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/cache/read.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Cache
+        # Built-in event for cache reads (cache_read.active_support)
+        class Read < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:key).maybe(:string)
+            optional(:hit).maybe(:bool)
+            optional(:super_operation).maybe(:string)
+          end
+
+          severity :debug
+          sample_rate 0.01 # Sample cache reads at 1% (very high volume)
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/cache/write.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Cache
+        # Built-in event for cache writes (cache_write.active_support)
+        class Write < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:key).maybe(:string)
+            optional(:super_operation).maybe(:string)
+          end
+
+          severity :debug
+          sample_rate 0.01 # Sample cache writes at 1%
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Database
+        # Built-in event for SQL queries (sql.active_record)
+        #
+        # Tracks database queries from ActiveRecord with timing and connection info.
+        #
+        # @example Usage (automatic via Rails Instrumentation)
+        #   # Automatically tracked when Rails executes SQL:
+        #   User.where(email: 'user@example.com').first
+        #   # → Events::Rails::Database::Query tracked
+        #
+        # @example Custom override
+        #   # config/initializers/e11y.rb
+        #   E11y.configure do |config|
+        #     config.rails_instrumentation.event_class_for(
+        #       'sql.active_record',
+        #       MyApp::CustomDatabaseQuery
+        #     )
+        #   end
+        #
+        # @see ADR-008 §4.3 (Built-in Event Classes)
+        class Query < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:name).maybe(:string)
+            optional(:sql).maybe(:string)
+            optional(:connection_id).maybe(:integer)
+            optional(:binds).maybe(:array)
+            optional(:allocations).maybe(:integer)
+          end
+
+          severity :debug # SQL queries are debug-level by default
+
+          # Sample SQL queries at 10% (can be overridden)
+          sample_rate 0.1
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/http/redirect.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Http
+        # Built-in event for redirects (redirect_to.action_controller)
+        class Redirect < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:location).maybe(:string)
+            optional(:status).maybe(:integer)
+          end
+
+          severity :info
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/http/request.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Http
+        # Built-in event for HTTP requests (process_action.action_controller)
+        class Request < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:controller).maybe(:string)
+            optional(:action).maybe(:string)
+            optional(:format).maybe(:string)
+            optional(:status).maybe(:integer)
+            optional(:view_runtime).maybe(:float)
+            optional(:db_runtime).maybe(:float)
+            optional(:allocations).maybe(:integer)
+          end
+
+          severity :info
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/http/send_file.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Http
+        # Built-in event for file sending (send_file.action_controller)
+        class SendFile < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:path).maybe(:string)
+            optional(:filename).maybe(:string)
+          end
+
+          severity :info
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/http/start_processing.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Http
+        # Event for `start_processing.action_controller` ASN notification
+        #
+        # Fired when Rails starts processing a controller action.
+        #
+        # @see https://guides.rubyonrails.org/active_support_instrumentation.html#start-processing-action-controller
+        class StartProcessing < E11y::Event::Base
+          schema do
+            required(:controller).filled(:string)
+            required(:action).filled(:string)
+            required(:method).filled(:string)
+            required(:path).filled(:string)
+            required(:format).filled(:string)
+          end
+
+          severity :debug
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Job
+        # Built-in event for completed jobs (perform.active_job)
+        class Completed < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:job_class).maybe(:string)
+            optional(:job_id).maybe(:string)
+            optional(:queue).maybe(:string)
+          end
+
+          severity :info
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Job
+        # Built-in event for enqueued jobs (enqueue.active_job)
+        class Enqueued < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:job_class).maybe(:string)
+            optional(:job_id).maybe(:string)
+            optional(:queue).maybe(:string)
+          end
+
+          severity :info
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Job
+        # Built-in event for failed jobs
+        class Failed < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:job_class).maybe(:string)
+            optional(:job_id).maybe(:string)
+            optional(:queue).maybe(:string)
+          end
+
+          severity :error
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Job
+        # Built-in event for scheduled jobs (enqueue_at.active_job)
+        class Scheduled < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:job_class).maybe(:string)
+            optional(:job_id).maybe(:string)
+            optional(:queue).maybe(:string)
+            optional(:scheduled_at).maybe(:time)
+          end
+
+          severity :info
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module Job
+        # Built-in event for started jobs (perform_start.active_job)
+        class Started < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:job_class).maybe(:string)
+            optional(:job_id).maybe(:string)
+            optional(:queue).maybe(:string)
+          end
+
+          severity :info
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/log.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "e11y/event/base"
+
+module E11y
+  module Events
+    module Rails
+      # Base class for all Rails.logger events
+      #
+      # This is an ABSTRACT class - use specific severity classes instead:
+      # - Events::Rails::Log::Debug
+      # - Events::Rails::Log::Info
+      # - Events::Rails::Log::Warn
+      # - Events::Rails::Log::Error
+      # - Events::Rails::Log::Fatal
+      #
+      # @see E11y::Logger::Bridge
+      class Log < E11y::Event::Base
+        schema do
+          required(:message).filled(:string)
+          optional(:caller_location).filled(:string)
+        end
+
+        # Debug logs (verbose, typically disabled in production)
+        class Debug < Log
+          severity :debug
+          adapters [:logs]
+        end
+
+        # Info logs (general information)
+        class Info < Log
+          severity :info
+          adapters [:logs]
+        end
+
+        # Warning logs (potential issues)
+        class Warn < Log
+          severity :warn
+          adapters [:logs]
+        end
+
+        # Error logs (errors that need attention)
+        class Error < Log
+          severity :error
+          adapters %i[logs errors_tracker] # Send to Sentry!
+        end
+
+        # Fatal logs (critical errors, system-breaking)
+        class Fatal < Log
+          severity :fatal
+          adapters %i[logs errors_tracker] # Send to Sentry!
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events/rails/view/render.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module E11y
+  module Events
+    module Rails
+      module View
+        # Built-in event for view rendering (render_template.action_view)
+        class Render < E11y::Event::Base
+          schema do
+            required(:event_name).filled(:string)
+            required(:duration).filled(:float)
+            optional(:identifier).maybe(:string)
+            optional(:layout).maybe(:string)
+            optional(:allocations).maybe(:integer)
+          end
+
+          severity :debug
+          sample_rate 0.1 # Sample view renders at 10%
+        end
+      end
+    end
+  end
+end

data/lib/e11y/events.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module E11y
+  # Base event classes for common patterns
+  #
+  # These classes provide pre-configured base classes for typical event types.
+  # Users can inherit from these instead of E11y::Event::Base for less boilerplate.
+  #
+  # @example Using a base event class
+  #   class UserLoginAudit < E11y::Events::BaseAuditEvent
+  #     schema do
+  #       required(:user_id).filled(:integer)
+  #       required(:ip_address).filled(:string)
+  #     end
+  #   end
+  module Events
+  end
+end