e11y 0.1.0

data/lib/e11y/middleware/versioning.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Versioning Middleware (ADR-012, UC-020)
+    #
+    # Extracts version from event class name and adds `v:` field to payload.
+    # Only adds `v:` if version > 1 (reduces noise for V1 events).
+    #
+    # **Features:**
+    # - Extracts version from class name (e.g., `Events::OrderPaidV2` → `v: 2`)
+    # - Normalizes event_name (removes version suffix for consistent queries)
+    # - Only adds `v:` field if version > 1
+    # - Opt-in (must be explicitly enabled)
+    #
+    # **ADR References:**
+    # - ADR-012 §2 (Parallel Versions)
+    # - ADR-012 §3 (Naming Convention)
+    # - ADR-012 §4 (Version in Payload)
+    # - ADR-015 §3 (Middleware Order - Versioning in :pre_processing zone)
+    #
+    # **Use Case:** UC-020 (Event Versioning)
+    #
+    # @example Configuration
+    #   E11y.configure do |config|
+    #     # Enable versioning middleware (opt-in)
+    #     config.pipeline.use E11y::Middleware::Versioning
+    #   end
+    #
+    # @example V1 Event (no version in payload)
+    #   class Events::OrderPaid < E11y::Event::Base
+    #     # No version suffix → V1 (implicit)
+    #   end
+    #
+    #   # Result payload:
+    #   {
+    #     event_name: "order.paid",  # Normalized (no version)
+    #     # No `v:` field (V1 is implicit)
+    #     payload: { ... }
+    #   }
+    #
+    # @example V2 Event (version in payload)
+    #   class Events::OrderPaidV2 < E11y::Event::Base
+    #     # Version suffix → V2
+    #   end
+    #
+    #   # Result payload:
+    #   {
+    #     event_name: "order.paid",  # Normalized (no version)
+    #     v: 2,                       # Version extracted from class name
+    #     payload: { ... }
+    #   }
+    #
+    # @see ADR-012 for versioning architecture
+    # @see UC-020 for use cases
+    class Versioning < Base
+      # Version extraction regex (matches V2, V3, etc. at end of class name)
+      VERSION_REGEX = /V(\d+)$/
+
+      # Process event and add version field if needed
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Hash] Event data with version field (if > 1)
+      def call(event_data)
+        # Extract version from event_name (class name)
+        version = extract_version(event_data[:event_name])
+
+        # Add version field only if > 1 (ADR-012 §4.2)
+        event_data[:v] = version if version > 1
+
+        # Normalize event_name (remove version suffix for consistent queries)
+        event_data[:event_name] = normalize_event_name(event_data[:event_name])
+
+        event_data
+      end
+
+      private
+
+      # Extract version from event class name
+      #
+      # @param class_name [String] Event class name (e.g., "Events::OrderPaidV2")
+      # @return [Integer] Version number (default: 1)
+      #
+      # @example
+      #   extract_version("Events::OrderPaid")   => 1
+      #   extract_version("Events::OrderPaidV2") => 2
+      #   extract_version("Events::OrderPaidV3") => 3
+      def extract_version(class_name)
+        return 1 unless class_name
+
+        # Extract version from class name (e.g., "Events::OrderPaidV2" → 2)
+        match = class_name.match(VERSION_REGEX)
+        match ? match[1].to_i : 1
+      end
+
+      # Normalize event_name by removing version suffix
+      #
+      # This ensures consistent querying across versions:
+      # - "Events::OrderPaid" → "order.paid"
+      # - "Events::OrderPaidV2" → "order.paid" (same name!)
+      #
+      # **Rationale (ADR-012 §3.2):**
+      # Query: `WHERE event_name = 'order.paid'` matches ALL versions
+      #
+      # @param class_name [String] Event class name
+      # @return [String] Normalized event name (snake_case, no version)
+      #
+      # @example
+      #   normalize_event_name("Events::OrderPaid")   => "order.paid"
+      #   normalize_event_name("Events::OrderPaidV2") => "order.paid"
+      #   normalize_event_name("Events::OrderPaidV3") => "order.paid"
+      def normalize_event_name(class_name)
+        return class_name unless class_name
+
+        # Remove "Events::" namespace prefix
+        name = class_name.sub(/^Events::/, "")
+
+        # Remove version suffix (V2, V3, etc.)
+        name = name.sub(VERSION_REGEX, "")
+
+        # Convert nested namespaces to dots first
+        name = name.gsub("::", ".")
+
+        # Convert to snake_case
+        name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2') # ABCWord → ABC_Word
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2') # wordWord → word_Word
+            .downcase
+            .gsub("_", ".") # Convert underscores to dots for event names
+      end
+    end
+  end
+end

data/lib/e11y/middleware.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module E11y
+  # Middleware pipeline for event processing.
+  #
+  # Provides zone-based middleware architecture with clear modification rules.
+  #
+  # @see E11y::Middleware::Base
+  # @see ADR-015 Middleware Execution Order
+  module Middleware
+  end
+end

data/lib/e11y/pii/patterns.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module E11y
+  module PII
+    # Universal PII patterns for automatic detection
+    #
+    # Patterns are used by PIIFiltering middleware to automatically detect
+    # and mask/hash sensitive data in event payloads.
+    #
+    # @see E11y::Middleware::PIIFiltering
+    # @see ADR-006 PII Security
+    # @see UC-007 PII Filtering
+    module Patterns
+      # Email pattern (RFC 5322 simplified)
+      EMAIL = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/
+
+      # Password-like field names
+      PASSWORD_FIELDS = /password|passwd|pwd|secret|token|api[_-]?key/i
+
+      # Social Security Number (US format: XXX-XX-XXXX)
+      SSN = /\b\d{3}-\d{2}-\d{4}\b/
+
+      # Credit card number (Visa, MC, Amex, Discover)
+      # Luhn algorithm validation not included (performance trade-off)
+      CREDIT_CARD = /\b(?:\d{4}[- ]?){3}\d{4}\b/
+
+      # IPv4 address
+      IPV4 = /\b(?:\d{1,3}\.){3}\d{1,3}\b/
+
+      # Phone number (various formats)
+      PHONE = /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/
+
+      # All patterns combined for bulk detection
+      ALL = [
+        EMAIL,
+        PASSWORD_FIELDS,
+        SSN,
+        CREDIT_CARD,
+        IPV4,
+        PHONE
+      ].freeze
+
+      # Field name patterns that indicate PII
+      # Used for field-level detection (case-insensitive)
+      FIELD_PATTERNS = {
+        email: /email|e[_-]?mail/i,
+        password: /password|passwd|pwd|secret|token|api[_-]?key/i,
+        ssn: /ssn|social[_-]?security|tax[_-]?id/i,
+        credit_card: /card|cc[_-]?number|credit[_-]?card|pan/i,
+        phone: /phone|mobile|tel|telephone/i,
+        ip: /\Aip\z|ip[_-]?address|remote[_-]?addr/i,
+        address: /\Aaddress\z|street|city|zip|postal/i,
+        name: /name|first[_-]?name|last[_-]?name|full[_-]?name/i,
+        dob: /birth|dob|date[_-]?of[_-]?birth/i
+      }.freeze
+
+      # Check if field name matches PII pattern
+      #
+      # @param field_name [String, Symbol] Field name to check
+      # @return [Symbol, nil] PII type if matched, nil otherwise
+      #
+      # @example
+      #   Patterns.detect_field_type(:email) # => :email
+      #   Patterns.detect_field_type(:user_email) # => :email
+      #   Patterns.detect_field_type(:id) # => nil
+      def self.detect_field_type(field_name)
+        field_str = field_name.to_s
+        FIELD_PATTERNS.each do |type, pattern|
+          return type if field_str.match?(pattern)
+        end
+        nil
+      end
+
+      # Check if value matches any PII pattern
+      #
+      # @param value [String] Value to check
+      # @return [Boolean] true if PII detected
+      #
+      # @example
+      #   Patterns.contains_pii?("user@example.com") # => true
+      #   Patterns.contains_pii?("123-45-6789") # => true
+      #   Patterns.contains_pii?("hello world") # => false
+      def self.contains_pii?(value)
+        return false unless value.is_a?(String)
+
+        ALL.any? { |pattern| value.match?(pattern) }
+      end
+    end
+  end
+end

data/lib/e11y/pii.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# E11y::PII module - PII detection and filtering utilities
+#
+# This module provides PII pattern detection and filtering strategies
+# for the PIIFiltering middleware.
+#
+# @see E11y::PII::Patterns
+# @see E11y::Middleware::PIIFiltering
+module E11y
+  module PII
+  end
+end

data/lib/e11y/pipeline/builder.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module E11y
+  module Pipeline
+    # Builder for configuring and validating middleware pipelines.
+    #
+    # Provides zone-based middleware organization with boot-time validation
+    # to ensure correct execution order per ADR-015 §3.4.
+    #
+    # @example Basic Pipeline Configuration
+    #   builder = E11y::Pipeline::Builder.new
+    #
+    #   builder.use E11y::Middleware::TraceContext
+    #   builder.use E11y::Middleware::Validation
+    #   builder.use E11y::Middleware::PIIFiltering
+    #
+    #   builder.validate_zones! # Boot-time validation
+    #
+    #   pipeline = builder.build(final_app)
+    #   pipeline.call(event_data)
+    #
+    # @example Zone-Based Configuration
+    #   builder.zone(:pre_processing) do
+    #     use E11y::Middleware::TraceContext
+    #     use E11y::Middleware::Validation
+    #   end
+    #
+    #   builder.zone(:security) do
+    #     use E11y::Middleware::PIIFiltering
+    #   end
+    #
+    # @see E11y::Middleware::Base
+    # @see ADR-015 §3.4 Middleware Zones & Modification Rules
+    class Builder
+      # Middleware entry: [middleware_class, args, options]
+      MiddlewareEntry = Struct.new(:middleware_class, :args, :options, keyword_init: true)
+
+      # @return [Array<MiddlewareEntry>] Registered middlewares
+      attr_reader :middlewares
+
+      def initialize
+        @middlewares = []
+      end
+
+      # Add a middleware to the pipeline.
+      #
+      # @param middleware_class [Class] Middleware class (must inherit from Base)
+      # @param args [Array] Positional arguments for middleware constructor
+      # @param options [Hash] Keyword arguments for middleware constructor
+      # @return [self] For method chaining
+      #
+      # @example
+      #   builder.use E11y::Middleware::TraceContext
+      #   builder.use E11y::Middleware::RateLimiting, limit: 1000
+      #
+      # @see ADR-015 Pipeline Flow
+      def use(middleware_class, *args, **options)
+        unless middleware_class < E11y::Middleware::Base
+          raise ArgumentError,
+                "Middleware #{middleware_class} must inherit from E11y::Middleware::Base"
+        end
+
+        @middlewares << MiddlewareEntry.new(
+          middleware_class: middleware_class,
+          args: args,
+          options: options
+        )
+
+        self
+      end
+
+      # Configure middlewares within a specific zone.
+      #
+      # This is a convenience method for organizing middleware configuration.
+      # Zone validation happens at boot-time via {#validate_zones!}.
+      #
+      # @param zone [Symbol] The zone name (must be valid per Middleware::Base::VALID_ZONES)
+      # @yield Block for configuring middlewares in this zone (executed in builder context)
+      # @return [self] For method chaining
+      #
+      # @example
+      #   builder.zone(:security) do
+      #     use E11y::Middleware::PIIFiltering
+      #   end
+      #
+      # @see ADR-015 §3.4.2 Middleware Zones
+      def zone(zone, &block)
+        unless E11y::Middleware::Base::VALID_ZONES.include?(zone)
+          raise ArgumentError,
+                "Invalid zone: #{zone.inspect}. " \
+                "Must be one of #{E11y::Middleware::Base::VALID_ZONES.inspect}"
+        end
+
+        instance_eval(&block) if block
+        self
+      end
+
+      # Build the middleware pipeline.
+      #
+      # Constructs a chain of middleware instances, passing each middleware
+      # to the next one in reverse order (Rack pattern).
+      #
+      # @param app [#call] The final application/endpoint in the chain
+      # @return [#call] The complete middleware pipeline
+      #
+      # @example
+      #   pipeline = builder.build(final_app)
+      #   result = pipeline.call(event_data)
+      def build(app)
+        @middlewares.reverse.reduce(app) do |next_app, entry|
+          entry.middleware_class.new(next_app, *entry.args, **entry.options)
+        end
+      end
+
+      # Validate middleware zone ordering at boot time.
+      #
+      # Ensures middlewares are ordered correctly according to their declared zones.
+      # This prevents zone violations like PII filtering running after custom middleware.
+      #
+      # Delegates to {E11y::Pipeline::ZoneValidator} for validation logic.
+      #
+      # @return [void]
+      # @raise [E11y::InvalidPipelineError] if zone ordering is invalid
+      #
+      # @example Boot-time validation
+      #   Rails.application.config.after_initialize do
+      #     E11y.pipeline_builder.validate_zones!
+      #   end
+      #
+      # @see E11y::Pipeline::ZoneValidator
+      # @see ADR-015 §3.4.5 Zone Validation
+      def validate_zones!
+        validator = E11y::Pipeline::ZoneValidator.new(@middlewares)
+        validator.validate_boot_time!
+      end
+
+      # Clear all registered middlewares.
+      #
+      # @return [void]
+      def clear
+        @middlewares.clear
+      end
+
+      private
+
+      # Get numeric index for a zone (for ordering validation)
+      #
+      # @param zone [Symbol] Zone name
+      # @return [Integer] Zone index (0-4)
+      def zone_index(zone)
+        E11y::Middleware::Base::VALID_ZONES.index(zone) || -1
+      end
+    end
+  end
+end

data/lib/e11y/pipeline/zone_validator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module E11y
+  module Pipeline
+    # Validator for middleware zone rules and constraints.
+    #
+    # Provides boot-time validation to ensure middleware zones are correctly
+    # ordered and PII bypass is prevented.
+    #
+    # **Design Decision:** Only boot-time validation is performed.
+    # Runtime validation was deemed unnecessary as:
+    # - Boot-time validation catches all configuration errors
+    # - Runtime validation adds ~1ms overhead per event
+    # - Pipeline configuration is static after boot
+    #
+    # @see ADR-015 §3.4.5 Zone Validation
+    # @see ADR-015 §3.4.4 Custom Middleware Constraints
+    class ZoneValidator
+      # Error raised when zone ordering is invalid
+      class ZoneOrderError < E11y::InvalidPipelineError; end
+
+      # Zone ordering constraints (valid transitions)
+      ZONE_ORDER = %i[
+        pre_processing
+        security
+        routing
+        post_processing
+        adapters
+      ].freeze
+
+      # @param middlewares [Array<MiddlewareEntry>] Middleware entries to validate
+      def initialize(middlewares)
+        @middlewares = middlewares
+      end
+
+      # Validate zone ordering at boot time.
+      #
+      # Ensures middlewares are ordered correctly according to their declared zones.
+      # This is a comprehensive check that runs once during application boot.
+      #
+      # @return [void]
+      # @raise [ZoneOrderError] if zone ordering is invalid
+      #
+      # @example
+      #   validator = ZoneValidator.new(pipeline.middlewares)
+      #   validator.validate_boot_time!
+      def validate_boot_time!
+        return if @middlewares.empty?
+
+        previous_zone_index = -1
+
+        @middlewares.each_with_index do |entry, index|
+          middleware_zone = entry.middleware_class.middleware_zone
+
+          # Skip middlewares without declared zone (optional)
+          next unless middleware_zone
+
+          current_zone_index = zone_index(middleware_zone)
+
+          # Validate zone progression (must be non-decreasing)
+          if current_zone_index < previous_zone_index
+            previous_entry = @middlewares[index - 1]
+            previous_zone = previous_entry.middleware_class.middleware_zone
+
+            raise ZoneOrderError,
+                  build_zone_order_error(entry.middleware_class, middleware_zone,
+                                         previous_entry.middleware_class, previous_zone)
+          end
+
+          previous_zone_index = current_zone_index
+        end
+      end
+
+      private
+
+      # Get numeric index for a zone (for ordering validation)
+      #
+      # @param zone [Symbol] Zone name
+      # @return [Integer] Zone index (0-4)
+      def zone_index(zone)
+        ZONE_ORDER.index(zone) || -1
+      end
+
+      # Build detailed error message for zone order violations
+      #
+      # @param current_middleware [Class] Current middleware class
+      # @param current_zone [Symbol] Current middleware zone
+      # @param previous_middleware [Class] Previous middleware class
+      # @param previous_zone [Symbol] Previous middleware zone
+      # @return [String] Formatted error message
+      def build_zone_order_error(current_middleware, current_zone,
+                                 previous_middleware, previous_zone)
+        <<~ERROR
+          Invalid middleware zone order detected:
+
+          #{current_middleware.name} (zone: #{current_zone})
+          cannot follow
+          #{previous_middleware.name} (zone: #{previous_zone})
+
+          Valid zone order: #{ZONE_ORDER.join(' → ')}
+
+          This violation prevents proper middleware execution and may
+          create security risks (e.g., PII bypass).
+
+          See ADR-015 §3.4 for middleware zone guidelines.
+        ERROR
+      end
+    end
+  end
+end

data/lib/e11y/pipeline.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module E11y
+  # Pipeline management for event processing middleware.
+  #
+  # Provides zone-based pipeline configuration with boot-time validation.
+  #
+  # @see E11y::Pipeline::Builder
+  # @see ADR-015 Middleware Execution Order
+  module Pipeline
+  end
+end

data/lib/e11y/presets/audit_event.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module E11y
+  module Presets
+    # Preset for audit events (compliance-critical)
+    #
+    # Audit events are compliance-critical events that must never be lost,
+    # regardless of their severity level. They use a separate audit pipeline that:
+    # - Signs events for non-repudiation
+    # - Encrypts sensitive data
+    # - Routes to audit-specific storage
+    # - Skips PII filtering (original data must be preserved)
+    #
+    # IMPORTANT: Audit events can have ANY severity (info, warn, error, fatal).
+    # The severity should be set by the user based on the event's criticality.
+    #
+    # @example Audit event with info severity (just logging an action)
+    #   class UserViewedDocumentAudit < E11y::Event::Base
+    #     include E11y::Presets::AuditEvent
+    #     severity :info  # User explicitly sets severity
+    #
+    #     schema do
+    #       required(:user_id).filled(:integer)
+    #       required(:document_id).filled(:integer)
+    #     end
+    #   end
+    #
+    # @example Audit event with fatal severity (security breach)
+    #   class SecurityBreachAudit < E11y::Event::Base
+    #     include E11y::Presets::AuditEvent
+    #     severity :fatal  # User explicitly sets severity
+    #
+    #     schema do
+    #       required(:breach_type).filled(:string)
+    #       required(:affected_users).filled(:integer)
+    #     end
+    #   end
+    module AuditEvent
+      def self.included(base)
+        base.class_eval do
+          # Audit events will use audit pipeline (Phase 4)
+          # Severity is NOT set by preset - user decides based on event criticality
+        end
+
+        # Extend class with audit-specific methods
+        base.extend(ClassMethods)
+      end
+
+      # Class methods for audit events
+      module ClassMethods
+        # Override resolve_rate_limit to unlimited for audit events
+        # Audit events must NEVER be dropped, regardless of severity
+        def resolve_rate_limit
+          nil # Unlimited - compliance requirement
+        end
+
+        # Override resolve_sample_rate to 100% for audit events
+        # Audit events must ALL be tracked, regardless of severity
+        def resolve_sample_rate
+          1.0 # 100% - compliance requirement
+        end
+      end
+    end
+  end
+end

data/lib/e11y/presets/debug_event.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module E11y
+  module Presets
+    # Preset for debug events (development/troubleshooting)
+    #
+    # Debug events have:
+    # - Low priority (debug severity)
+    # - Standard rate limit (1000/sec)
+    # - Low sampling (1% - reduces noise)
+    # - Only logs adapter (no error tracking/alerting)
+    #
+    # Adapter name:
+    # - :logs → centralized logging (implementation: Loki, Elasticsearch, CloudWatch, etc.)
+    #
+    # @example
+    #   class DebugCacheHitEvent < E11y::Event::Base
+    #     include E11y::Presets::DebugEvent
+    #
+    #     schema do
+    #       required(:cache_key).filled(:string)
+    #       required(:hit).filled(:bool)
+    #     end
+    #   end
+    module DebugEvent
+      def self.included(base)
+        base.class_eval do
+          severity :debug
+          adapters :logs # Adapter name
+        end
+      end
+    end
+  end
+end

data/lib/e11y/presets/high_value_event.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module E11y
+  module Presets
+    # Preset for high-value events (payments, transactions)
+    #
+    # High-value events require:
+    # - High priority (success severity)
+    # - Unlimited rate limit (never drop payment events)
+    # - 100% sampling (all payment events)
+    # - Multiple adapters (logs + errors_tracker for full observability)
+    #
+    # Adapter names:
+    # - :logs → centralized logging (implementation: Loki, Elasticsearch, CloudWatch, etc.)
+    # - :errors_tracker → error tracking with alerting (implementation: Sentry, Rollbar, Bugsnag, etc.)
+    #
+    # @example
+    #   class PaymentProcessedEvent < E11y::Event::Base
+    #     include E11y::Presets::HighValueEvent
+    #
+    #     schema do
+    #       required(:payment_id).filled(:integer)
+    #       required(:amount).filled(:float)
+    #     end
+    #   end
+    module HighValueEvent
+      def self.included(base)
+        base.class_eval do
+          severity :success
+          adapters :logs, :errors_tracker # Adapter names
+        end
+
+        # Extend class with overridden methods
+        base.extend(ClassMethods)
+      end
+
+      # Class methods that override default behavior
+      module ClassMethods
+        # Override resolve_rate_limit to unlimited for high-value events
+        def resolve_rate_limit
+          nil # Unlimited - never drop payment events
+        end
+
+        # Override resolve_sample_rate to 100% for high-value events
+        def resolve_sample_rate
+          1.0 # 100% - track all payment events
+        end
+      end
+    end
+  end
+end

data/lib/e11y/presets.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module E11y
+  # Presets for common event patterns
+  #
+  # Presets are modules that can be included in event classes to provide
+  # pre-configured settings (severity, adapters, sample rate, etc.)
+  #
+  # @example Using a preset
+  #   class MyDebugEvent < E11y::Event::Base
+  #     include E11y::Presets::DebugEvent
+  #
+  #     schema do
+  #       required(:debug_info).filled(:string)
+  #     end
+  #   end
+  module Presets
+  end
+end