e11y 0.1.0

data/lib/e11y/middleware/rate_limiting.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Rate Limiting Middleware (UC-011, C02 Resolution)
+    #
+    # Protects adapters from event floods using token bucket algorithm.
+    # Critical events bypass rate limiting and go to DLQ (C02 Resolution).
+    #
+    # **Features:**
+    # - Global rate limit (e.g., 10K events/sec)
+    # - Per-event type rate limit (e.g., 1K payment.retry/sec)
+    # - In-memory token bucket (no Redis dependency)
+    # - Critical events bypass (C02 Resolution)
+    # - DLQ integration for rate-limited critical events
+    #
+    # **ADR References:**
+    # - ADR-013 §4.6 (C02 Resolution - Rate Limiting × DLQ Filter)
+    # - ADR-015 §3 (Middleware Order - RateLimiting in :routing zone)
+    #
+    # **Use Case:** UC-011 (Rate Limiting - DoS Protection)
+    #
+    # @example Configuration
+    #   E11y.configure do |config|
+    #     config.pipeline.use E11y::Middleware::RateLimiting,
+    #       global_limit: 10_000,        # Max 10K events/sec globally
+    #       per_event_limit: 1_000,      # Max 1K events/sec per event type
+    #       window: 1.0                  # 1 second window
+    #   end
+    #
+    # @example Critical Event Bypass (C02)
+    #   # Payment events bypass rate limiting → DLQ if limited
+    #   config.dlq_filter.always_save_patterns = [/^payment\./]
+    #
+    #   # Result: Rate-limited payment events go to DLQ, not dropped
+    #
+    # @see ADR-013 §4.6 for C02 Resolution details
+    # @see UC-011 for rate limiting use cases
+    class RateLimiting < Base
+      # 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)
+        super(app)
+        @global_limit = global_limit
+        @per_event_limit = per_event_limit
+        @window = window
+
+        # Token buckets for rate limiting
+        @global_bucket = TokenBucket.new(capacity: @global_limit, refill_rate: @global_limit, window: @window)
+        @per_event_buckets = Hash.new do |hash, event_name|
+          hash[event_name] = TokenBucket.new(
+            capacity: @per_event_limit,
+            refill_rate: @per_event_limit,
+            window: @window
+          )
+        end
+
+        @mutex = Mutex.new
+      end
+
+      # Process event through rate limiting
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Hash, nil] Event data if allowed, nil if rate limited
+      def call(event_data)
+        event_name = event_data[:event_name]
+
+        # Check global rate limit
+        unless @global_bucket.allow?
+          handle_rate_limited(event_data, :global)
+          return nil
+        end
+
+        # Check per-event rate limit
+        per_event_bucket = @mutex.synchronize { @per_event_buckets[event_name] }
+        unless per_event_bucket.allow?
+          handle_rate_limited(event_data, :per_event)
+          return nil
+        end
+
+        # Rate limit not exceeded - continue pipeline
+        event_data
+      end
+
+      private
+
+      # Handle rate-limited event (C02 Resolution)
+      #
+      # Critical events are saved to DLQ, non-critical events are dropped.
+      #
+      # @param event_data [Hash] Event payload
+      # @param limit_type [Symbol] :global or :per_event
+      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}"
+
+        # 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)
+
+        # Non-critical events are dropped (no DLQ)
+        # TODO: Track metric e11y.rate_limiter.dropped
+      end
+
+      # Check if rate-limited event should be saved to DLQ (C02 Resolution)
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] true if event should be saved to DLQ
+      def should_save_to_dlq?(event_data)
+        return false unless E11y.config.respond_to?(:dlq_filter)
+
+        # Use DLQ filter to determine if event is critical
+        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) }
+      end
+
+      # Save rate-limited critical event to DLQ (C02 Resolution)
+      #
+      # @param event_data [Hash] Event payload
+      # @param limit_type [Symbol] :global or :per_event
+      def save_to_dlq(event_data, limit_type)
+        return unless E11y.config.respond_to?(:dlq_storage)
+
+        dlq_storage = E11y.config.dlq_storage
+        return unless dlq_storage
+
+        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,
+                           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
+      rescue StandardError => e
+        # Don't fail if DLQ save fails (C18 Resolution)
+        warn "[E11y] Failed to save rate-limited event to DLQ: #{e.message}"
+      end
+
+      # Token Bucket implementation for rate limiting
+      #
+      # Thread-safe token bucket algorithm for rate limiting.
+      #
+      # @see https://en.wikipedia.org/wiki/Token_bucket
+      class TokenBucket
+        # Initialize token bucket
+        #
+        # @param capacity [Integer] Maximum tokens in bucket
+        # @param refill_rate [Float] Tokens added per second
+        # @param window [Float] Time window in seconds
+        def initialize(capacity:, refill_rate:, window:)
+          @capacity = capacity
+          @refill_rate = refill_rate
+          @window = window
+          @tokens = capacity.to_f
+          @last_refill = Time.now
+          @mutex = Mutex.new
+        end
+
+        # Check if request is allowed (consumes 1 token if available)
+        #
+        # @return [Boolean] true if request allowed
+        def allow?
+          @mutex.synchronize do
+            refill_tokens
+            if @tokens >= 1.0
+              @tokens -= 1.0
+              true
+            else
+              false
+            end
+          end
+        end
+
+        # Current token count (for debugging)
+        #
+        # @return [Float] Current tokens available
+        def tokens
+          @mutex.synchronize do
+            refill_tokens
+            @tokens
+          end
+        end
+
+        private
+
+        # Refill tokens based on elapsed time
+        def refill_tokens
+          now = Time.now
+          elapsed = now - @last_refill
+          return if elapsed <= 0
+
+          # Calculate tokens to add (refill_rate tokens per second)
+          tokens_to_add = elapsed * @refill_rate
+          @tokens = [@tokens + tokens_to_add, @capacity].min
+          @last_refill = now
+        end
+      end
+    end
+  end
+end

data/lib/e11y/middleware/request.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "rack/request"
+require "securerandom"
+
+module E11y
+  module Middleware
+    # Request Middleware for Rails/Rack applications
+    #
+    # Provides request-scoped context and trace propagation:
+    # - Extracts or generates trace_id
+    # - Sets up request context (E11y::Current)
+    # - Manages request-scoped buffer (optional)
+    # - Tracks HTTP request lifecycle
+    #
+    # @example Basic usage
+    #   # Automatically inserted by E11y::Railtie
+    #   # app.middleware.insert_before(Rails::Rack::Logger, E11y::Middleware::Request)
+    #
+    # @example Manual usage (non-Rails)
+    #   use E11y::Middleware::Request
+    #
+    # @see ADR-008 §8.1 (Request Middleware)
+    # @see ADR-005 §3 (Trace Context Management)
+    class Request
+      # Initialize middleware
+      # @param app [Object] Rack app
+      def initialize(app)
+        @app = app
+      end
+
+      # Process request
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response [status, headers, body]
+      def call(env)
+        request = Rack::Request.new(env)
+
+        # Extract or generate trace_id
+        trace_id = extract_trace_id(request) || generate_trace_id
+        span_id = generate_span_id
+
+        # Set request context (ActiveSupport::CurrentAttributes)
+        E11y::Current.trace_id = trace_id
+        E11y::Current.span_id = span_id
+        E11y::Current.request_id = request_id(env)
+        E11y::Current.user_id = extract_user_id(env)
+        E11y::Current.ip_address = request.ip
+        E11y::Current.user_agent = request.user_agent
+        E11y::Current.request_method = request.request_method
+        E11y::Current.request_path = request.path
+
+        # Start request-scoped buffer (for debug events)
+        E11y::Buffers::RequestScopedBuffer.start! if E11y.config.request_buffer&.enabled
+
+        # Track request start time for SLO
+        start_time = Time.now
+
+        # Call next middleware/app
+        status, headers, body = @app.call(env)
+
+        # Track SLO metrics (if enabled)
+        track_http_request_slo(env, status, start_time)
+
+        # Add trace headers to response
+        headers["X-E11y-Trace-Id"] = trace_id
+        headers["X-E11y-Span-Id"] = span_id
+
+        [status, headers, body]
+      rescue StandardError
+        # Flush request buffer on error (includes debug events)
+        E11y::Buffers::RequestScopedBuffer.flush_on_error! if E11y.config.request_buffer&.enabled
+
+        raise # Re-raise original exception
+      ensure
+        # Flush request buffer on success (not on error, already flushed above)
+        # We need to check if we're here from normal completion or exception
+        # If there was an exception, buffer was already flushed in rescue block
+        if !$ERROR_INFO && E11y.config.request_buffer&.enabled # No exception occurred
+          E11y::Buffers::RequestScopedBuffer.flush!
+        end
+
+        # Reset context
+        E11y::Current.reset
+      end
+
+      private
+
+      # Extract trace_id from request headers (W3C Trace Context or custom headers)
+      # @param request [Rack::Request] Rack request
+      # @return [String, nil] Trace ID or nil if not found
+      def extract_trace_id(request)
+        # W3C Trace Context (traceparent header)
+        # Format: version-trace_id-span_id-flags
+        # Example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
+        traceparent = request.get_header("HTTP_TRACEPARENT")
+        return traceparent.split("-")[1] if traceparent
+
+        # X-Request-ID (Rails default)
+        request.get_header("HTTP_X_REQUEST_ID") ||
+          # X-Trace-Id (custom)
+          request.get_header("HTTP_X_TRACE_ID")
+      end
+
+      # Extract request_id from Rack env
+      # @param env [Hash] Rack environment
+      # @return [String] Request ID
+      def request_id(env)
+        env["action_dispatch.request_id"] || generate_trace_id
+      end
+
+      # Generate new trace_id
+      # @return [String] 32-character hex trace ID
+      def generate_trace_id
+        SecureRandom.hex(16)
+      end
+
+      # Generate new span_id
+      # @return [String] 16-character hex span ID
+      def generate_span_id
+        SecureRandom.hex(8)
+      end
+
+      # Extract user_id from Rack env (Warden, Devise, or session)
+      # @param env [Hash] Rack environment
+      # @return [Integer, String, nil] User ID if available
+      def extract_user_id(env)
+        # Warden (Devise)
+        return env["warden"]&.user&.id if env["warden"]
+
+        # Rack session
+        env["rack.session"]&.[]("user_id")
+      end
+
+      # Track HTTP request for SLO metrics (if enabled).
+      #
+      # @param env [Hash] Rack environment
+      # @param status [Integer] HTTP status code
+      # @param start_time [Time] Request start time
+      # @return [void]
+      # @api private
+      def track_http_request_slo(env, status, start_time)
+        return unless E11y.config.slo_tracking&.enabled
+
+        duration_ms = ((Time.now - start_time) * 1000).round(2)
+
+        # Extract controller and action from Rails routing
+        controller = env["action_controller.instance"]&.controller_name || "unknown"
+        action = env["action_controller.instance"]&.action_name || "unknown"
+
+        require "e11y/slo/tracker"
+        E11y::SLO::Tracker.track_http_request(
+          controller: controller,
+          action: action,
+          status: status,
+          duration_ms: duration_ms
+        )
+      rescue StandardError => e
+        # Don't fail if SLO tracking fails
+        warn "[E11y] SLO tracking error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/e11y/middleware/routing.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Routing middleware routes events to appropriate buffers/adapters.
+    #
+    # This is the FINAL middleware in the pipeline (adapters zone),
+    # running AFTER all processing (TraceContext, Validation, PII Filtering,
+    # Rate Limiting, Sampling, Versioning).
+    #
+    # **Phase 1 Implementation:**
+    # - Determines target adapters from event configuration
+    # - Logs routing decisions for debugging
+    # - Increments metrics for observability
+    # - Does NOT actually send events (Phase 2: Collector will handle delivery)
+    #
+    # **Routing Logic:**
+    # 1. Get adapters from event_data[:adapters] (configured in Event class)
+    # 2. Determine buffer type based on severity/flags
+    # 3. Log/metric routing decision
+    # 4. Pass event_data to next app (Collector in Phase 2)
+    #
+    # @see ADR-015 §3.1 Pipeline Flow (line 113-117)
+    # @see ADR-001 §3 Adapter Architecture
+    # @see UC-001 Request-Scoped Debug Buffering
+    #
+    # @example Standard event routing
+    #   event_data = {
+    #     event_name: 'Events::OrderPaid',
+    #     severity: :info,
+    #     adapters: [:logs, :errors_tracker],
+    #     payload: { ... }
+    #   }
+    #
+    #   # Routes to: main buffer → [:logs, :errors_tracker] adapters
+    #
+    # @example Debug event routing (request-scoped)
+    #   event_data = {
+    #     event_name: 'Events::DebugInfo',
+    #     severity: :debug,
+    #     adapters: [:logs],
+    #     payload: { ... }
+    #   }
+    #
+    #   # Routes to: request-scoped buffer (buffered, flushed on error)
+    #
+    # @example Audit event routing
+    #   event_data = {
+    #     event_name: 'Events::PermissionChanged',
+    #     severity: :warn,
+    #     audit_event: true,
+    #     adapters: [:audit_encrypted],
+    #     payload: { ... }
+    #   }
+    #
+    #   # Routes to: audit buffer → [:audit_encrypted] adapter
+    class Routing < Base
+      middleware_zone :adapters
+
+      # Routes event to appropriate buffer/adapters.
+      #
+      # @param event_data [Hash] The event data to route
+      # @option event_data [Array<Symbol>] :adapters Target adapter names (required)
+      # @option event_data [Symbol] :severity Event severity (required)
+      # @option event_data [Boolean] :audit_event Audit event flag (optional)
+      # @return [Hash, nil] Event data (passed to Collector in Phase 2), or nil if dropped
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def call(event_data)
+        # Skip if no adapters or severity
+        unless event_data[:adapters] && event_data[:severity]
+          increment_metric("e11y.middleware.routing.skipped")
+          return @app.call(event_data)
+        end
+
+        adapters = event_data[:adapters]
+        severity = event_data[:severity]
+        audit_event = event_data[:audit_event] || false
+
+        # Determine buffer type
+        buffer_type = determine_buffer_type(severity, audit_event)
+
+        # Add routing metadata to event_data
+        event_data[:routing] = {
+          buffer_type: buffer_type,
+          adapters: adapters,
+          routed_at: Time.now.utc
+        }
+
+        # Increment metrics
+        increment_metric("e11y.middleware.routing.routed",
+                         buffer: buffer_type,
+                         severity: severity,
+                         adapters_count: adapters.size)
+
+        # Log routing decision (for Phase 1 debugging)
+        log_routing_decision(event_data, buffer_type, adapters) if debug_enabled?
+
+        # Pass to next app (Collector in Phase 2)
+        @app.call(event_data)
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      private
+
+      # Determine which buffer type to use based on severity and flags.
+      #
+      # @param severity [Symbol] Event severity
+      # @param audit_event [Boolean] Audit event flag
+      # @return [Symbol] Buffer type (:main, :request_scoped, :audit)
+      #
+      # Routing rules:
+      # - Audit events → :audit buffer (separate pipeline, no PII filtering)
+      # - Debug events → :request_scoped buffer (buffered, flushed on error)
+      # - Other events → :main buffer (immediate sending)
+      def determine_buffer_type(severity, audit_event)
+        return :audit if audit_event
+        return :request_scoped if severity == :debug
+
+        :main
+      end
+
+      # Log routing decision for debugging (Phase 1).
+      #
+      # @param event_data [Hash] Event data
+      # @param buffer_type [Symbol] Determined buffer type
+      # @param adapters [Array<Symbol>] Target adapters
+      # @return [void]
+      def log_routing_decision(event_data, buffer_type, adapters)
+        # TODO: Replace with structured logging in Phase 2
+        # Rails.logger.debug "[E11y] Routing: #{event_data[:event_name]} → #{buffer_type} → #{adapters.inspect}"
+      end
+
+      # Check if debug logging is enabled.
+      #
+      # @return [Boolean]
+      def debug_enabled?
+        # TODO: Read from configuration in Phase 2
+        # E11y.configuration.debug_enabled
+        false # Disabled in Phase 1
+      end
+
+      # Placeholder for metrics instrumentation.
+      #
+      # @param metric_name [String] Metric name
+      # @param tags [Hash] Metric tags
+      # @return [void]
+      def increment_metric(_metric_name, **_tags)
+        # TODO: Integrate with Yabeda/Prometheus in Phase 2
+        # Yabeda.e11y.middleware_routing_routed.increment(
+        #   buffer: buffer,
+        #   severity: severity,
+        #   adapters_count: adapters_count
+        # )
+      end
+    end
+  end
+end