e11y 0.1.0

data/lib/e11y/railtie.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Skip Railtie if Rails is not available
+return unless defined?(Rails)
+
+require "rails/railtie"
+
+module E11y
+  # Rails integration via Railtie
+  #
+  # Provides zero-config Rails integration:
+  # - Auto-initialization on Rails boot
+  # - Middleware insertion (request context, tracing)
+  # - ActiveSupport::Notifications integration
+  # - Rails.logger bridge (optional)
+  # - Console helpers
+  #
+  # @example Basic usage (no config needed)
+  #   # In Rails app, E11y auto-configures:
+  #   # - Service name from Rails.application.name
+  #   # - Environment from Rails.env
+  #   # - Adapters: stdout (dev), loki (prod)
+  #
+  # @example Custom configuration
+  #   # config/initializers/e11y.rb
+  #   E11y.configure do |config|
+  #     config.service_name = "my-app"
+  #     config.adapters.register :loki, E11y::Adapters::Loki.new(url: ENV['LOKI_URL'])
+  #   end
+  #
+  # @see ADR-008 §3 (Railtie & Initialization)
+  class Railtie < Rails::Railtie
+    # Run before framework initialization
+    config.before_initialize do
+      # Set up basic configuration from Rails
+      E11y.configure do |config|
+        config.environment = Rails.env.to_s
+        config.service_name = derive_service_name
+        config.enabled = !Rails.env.test? # Disabled in tests by default
+      end
+    end
+
+    # Run after framework initialization
+    config.after_initialize do
+      next unless E11y.config.enabled
+
+      # Setup instruments (each can be enabled/disabled separately)
+      setup_rails_instrumentation if E11y.config.rails_instrumentation&.enabled
+      setup_logger_bridge if E11y.config.logger_bridge&.enabled
+      setup_sidekiq if defined?(::Sidekiq) && E11y.config.sidekiq&.enabled
+      setup_active_job if defined?(::ActiveJob) && E11y.config.active_job&.enabled
+    end
+
+    # Middleware insertion
+    initializer "e11y.middleware" do |app|
+      next unless E11y.config.enabled
+
+      # Insert E11y request middleware before Rails logger
+      # This ensures trace context is set up before any Rails logging
+      app.middleware.insert_before(
+        Rails::Rack::Logger,
+        E11y::Middleware::Request
+      )
+    end
+
+    # Console helpers
+    console do
+      next unless E11y.config.enabled
+
+      require "e11y/console"
+      E11y::Console.enable!
+
+      puts "E11y loaded. Try: E11y.stats"
+    end
+
+    # Rake task helpers
+    rake_tasks do
+      next unless E11y.config.enabled
+
+      # TODO: Add rake tasks (e11y:stats, e11y:test_event, etc.)
+      # load 'e11y/tasks.rake'
+    end
+
+    # Derive service name from Rails application class
+    # @return [String] Service name (e.g., "my_app")
+    def self.derive_service_name
+      Rails.application.class.module_parent_name.underscore
+    rescue StandardError
+      "rails_app"
+    end
+
+    # Setup Rails instrumentation (ActiveSupport::Notifications → E11y)
+    # @return [void]
+    def self.setup_rails_instrumentation
+      require "e11y/instruments/rails_instrumentation"
+      E11y::Instruments::RailsInstrumentation.setup!
+    end
+
+    # Setup Rails.logger bridge (optional, replaces Rails.logger)
+    # @return [void]
+    def self.setup_logger_bridge
+      require "e11y/logger/bridge"
+      E11y::Logger::Bridge.setup!
+    end
+
+    # Setup Sidekiq integration (client + server middleware)
+    # @return [void]
+    def self.setup_sidekiq
+      require "e11y/instruments/sidekiq"
+
+      # Configure server middleware
+      ::Sidekiq.configure_server do |config|
+        config.server_middleware do |chain|
+          chain.add E11y::Instruments::Sidekiq::ServerMiddleware
+        end
+      end
+
+      # Configure client middleware
+      ::Sidekiq.configure_client do |config|
+        config.client_middleware do |chain|
+          chain.add E11y::Instruments::Sidekiq::ClientMiddleware
+        end
+      end
+    end
+
+    # Setup ActiveJob integration (callbacks)
+    # @return [void]
+    def self.setup_active_job
+      require "e11y/instruments/active_job"
+
+      # Include callbacks into ApplicationJob (if defined)
+      ::ApplicationJob.include(E11y::Instruments::ActiveJob::Callbacks) if defined?(::ApplicationJob)
+
+      # Also include into ActiveJob::Base as fallback
+      ::ActiveJob::Base.include(E11y::Instruments::ActiveJob::Callbacks)
+    end
+  end
+end

data/lib/e11y/reliability/circuit_breaker.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module E11y
+  module Reliability
+    # Circuit Breaker pattern implementation for adapter reliability.
+    #
+    # Prevents cascading failures by opening circuit when adapter fails repeatedly.
+    # Three states: CLOSED (healthy), OPEN (failing), HALF_OPEN (testing recovery).
+    #
+    # @example Usage in adapter
+    #   circuit_breaker = CircuitBreaker.new(adapter_name: "loki", config: config)
+    #
+    #   circuit_breaker.call do
+    #     # Send event to adapter
+    #     adapter.send(event)
+    #   end
+    #
+    # @see ADR-013 §5 (Circuit Breaker)
+    # @see UC-021 §4 (Circuit Breaker for Adapters)
+    class CircuitBreaker
+      # Circuit is closed (healthy) - all requests pass through
+      STATE_CLOSED = :closed
+
+      # Circuit is open (failing) - all requests fail fast
+      STATE_OPEN = :open
+
+      # Circuit is half-open (testing recovery) - limited requests allowed
+      STATE_HALF_OPEN = :half_open
+
+      # Circuit breaker opened error (fast fail)
+      class CircuitOpenError < StandardError; end
+
+      # @param adapter_name [String] Name of the adapter (for metrics)
+      # @param config [Hash] Configuration options
+      # @option config [Integer] :failure_threshold Number of failures before opening circuit (default: 5)
+      # @option config [Integer] :timeout_seconds Seconds before transitioning to half-open (default: 60)
+      # @option config [Integer] :half_open_attempts Success attempts needed in half-open to close (default: 2)
+      def initialize(adapter_name:, config: {})
+        @adapter_name = adapter_name
+        @failure_threshold = config[:failure_threshold] || 5
+        @timeout_seconds = config[:timeout_seconds] || 60
+        @half_open_attempts = config[:half_open_attempts] || 2
+
+        @state = STATE_CLOSED
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_time = nil
+        @opened_at = nil
+        @mutex = Mutex.new
+      end
+
+      # Execute block with circuit breaker protection.
+      #
+      # @yield Block to execute (adapter send)
+      # @return [Object] Result of block execution
+      # @raise [CircuitOpenError] if circuit is open
+      # @raise [StandardError] if block raises and circuit transitions to open
+      def call(&)
+        check_state_transition
+
+        case @state
+        when STATE_CLOSED
+          execute_with_closed_circuit(&)
+        when STATE_OPEN
+          handle_open_circuit
+        when STATE_HALF_OPEN
+          execute_with_half_open_circuit(&)
+        end
+      end
+
+      # Check if circuit is healthy (closed state).
+      #
+      # @return [Boolean] true if circuit is closed
+      def healthy?
+        @state == STATE_CLOSED
+      end
+
+      # Get current circuit breaker statistics.
+      #
+      # @return [Hash] Statistics hash
+      def stats
+        {
+          adapter: @adapter_name,
+          state: @state,
+          failure_count: @failure_count,
+          success_count: @success_count,
+          last_failure: @last_failure_time,
+          opened_at: @opened_at
+        }
+      end
+
+      private
+
+      # Execute block in CLOSED state (normal operation).
+      def execute_with_closed_circuit
+        result = yield
+        on_success
+        result
+      rescue StandardError => e
+        on_failure(e)
+        raise
+      end
+
+      # Execute block in HALF_OPEN state (testing recovery).
+      def execute_with_half_open_circuit
+        result = yield
+        on_half_open_success
+        result
+      rescue StandardError => e
+        on_half_open_failure(e)
+        raise
+      end
+
+      # Handle OPEN state (fast fail).
+      def handle_open_circuit
+        increment_metric("e11y.circuit_breaker.rejected")
+
+        raise CircuitOpenError, "Circuit breaker open for #{@adapter_name} " \
+                                "(opened at #{@opened_at}, timeout: #{@timeout_seconds}s)"
+      end
+
+      # Check if circuit should transition states.
+      def check_state_transition
+        return unless @state == STATE_OPEN
+
+        @mutex.synchronize do
+          # Transition OPEN → HALF_OPEN after timeout
+          transition_to_half_open if Time.now - @opened_at >= @timeout_seconds
+        end
+      end
+
+      # Handle successful execution in CLOSED state.
+      def on_success
+        @mutex.synchronize do
+          @failure_count = 0
+          @success_count += 1
+        end
+
+        increment_metric("e11y.circuit_breaker.success")
+      end
+
+      # Handle failed execution in CLOSED state.
+      def on_failure(error)
+        @mutex.synchronize do
+          @failure_count += 1
+          @last_failure_time = Time.now
+
+          # Transition CLOSED → OPEN if threshold exceeded
+          transition_to_open if @failure_count >= @failure_threshold
+        end
+
+        increment_metric("e11y.circuit_breaker.failure", error: error.class.name)
+      end
+
+      # Handle successful execution in HALF_OPEN state.
+      def on_half_open_success
+        @mutex.synchronize do
+          @success_count += 1
+
+          # Transition HALF_OPEN → CLOSED after enough successes
+          transition_to_closed if @success_count >= @half_open_attempts
+        end
+
+        increment_metric("e11y.circuit_breaker.half_open_success")
+      end
+
+      # Handle failed execution in HALF_OPEN state.
+      def on_half_open_failure(error)
+        @mutex.synchronize do
+          # Single failure in HALF_OPEN → back to OPEN
+          transition_to_open
+        end
+
+        increment_metric("e11y.circuit_breaker.half_open_failure", error: error.class.name)
+      end
+
+      # Transition to OPEN state.
+      def transition_to_open
+        @state = STATE_OPEN
+        @opened_at = Time.now
+        @failure_count = 0 # Reset for next cycle
+        @success_count = 0
+
+        increment_metric("e11y.circuit_breaker.opened")
+      end
+
+      # Transition to HALF_OPEN state.
+      def transition_to_half_open
+        @state = STATE_HALF_OPEN
+        @success_count = 0 # Reset success counter for testing
+
+        increment_metric("e11y.circuit_breaker.half_opened")
+      end
+
+      # Transition to CLOSED state.
+      def transition_to_closed
+        @state = STATE_CLOSED
+        @failure_count = 0
+        @success_count = 0
+        @opened_at = nil
+        @last_failure_time = nil
+
+        increment_metric("e11y.circuit_breaker.closed")
+      end
+
+      # Increment circuit breaker metric.
+      #
+      # @param metric_name [String] Metric name
+      # @param tags [Hash] Additional tags
+      def increment_metric(metric_name, tags = {})
+        # TODO: Integrate with Yabeda metrics
+        # E11y::Metrics.increment(metric_name, tags.merge(adapter: @adapter_name, state: @state))
+      end
+    end
+  end
+end

data/lib/e11y/reliability/dlq/file_storage.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+
+module E11y
+  module Reliability
+    module DLQ
+      # File-based Dead Letter Queue storage.
+      #
+      # Stores failed events to a JSONL file for later analysis/replay.
+      # Each line is a JSON object representing a failed event with metadata.
+      #
+      # @example Usage
+      #   dlq = FileStorage.new(file_path: "log/e11y_dlq.jsonl")
+      #   dlq.save(event_data, metadata: { error: "Timeout", retry_count: 3 })
+      #
+      # @see ADR-013 §4 (Dead Letter Queue)
+      # @see UC-021 §3 (DLQ File Storage)
+      class FileStorage
+        # @param file_path [String] Path to DLQ file (default: log/e11y_dlq.jsonl)
+        # @param max_file_size_mb [Integer] Maximum file size in MB before rotation (default: 100)
+        # @param retention_days [Integer] Days to retain DLQ files (default: 30)
+        def initialize(file_path: nil, max_file_size_mb: 100, retention_days: 30)
+          @file_path = file_path || default_file_path
+          @max_file_size_bytes = max_file_size_mb * 1024 * 1024
+          @retention_days = retention_days
+          @mutex = Mutex.new
+
+          ensure_directory_exists
+        end
+
+        # Save failed event to DLQ.
+        #
+        # @param event_data [Hash] Event data
+        # @param metadata [Hash] Failure metadata (error, retry_count, adapter, etc.)
+        # @return [String] Event ID (UUID)
+        def save(event_data, metadata: {})
+          event_id = SecureRandom.uuid
+          timestamp = Time.now.utc
+
+          dlq_entry = {
+            id: event_id,
+            timestamp: timestamp.iso8601(3),
+            event_name: event_data[:event_name],
+            event_data: event_data,
+            metadata: metadata.merge(
+              failed_at: timestamp.iso8601(3),
+              retry_count: metadata[:retry_count] || 0,
+              error_message: metadata[:error]&.message,
+              error_class: metadata[:error]&.class&.name
+            )
+          }
+
+          write_entry(dlq_entry)
+          rotate_if_needed
+          cleanup_old_files
+
+          increment_metric("e11y.dlq.saved", event_name: event_data[:event_name])
+
+          event_id
+        end
+
+        # List DLQ entries with optional filters.
+        #
+        # @param limit [Integer] Maximum entries to return
+        # @param offset [Integer] Number of entries to skip
+        # @param filters [Hash] Filter options (event_name, after, before)
+        # @return [Array<Hash>] Array of DLQ entries
+        def list(limit: 100, offset: 0, filters: {})
+          entries = []
+
+          return entries unless File.exist?(@file_path)
+
+          File.foreach(@file_path).with_index do |line, index|
+            next if index < offset
+            break if entries.size >= limit
+
+            entry = JSON.parse(line, symbolize_names: true)
+
+            # Apply filters
+            next if filters[:event_name] && entry[:event_name] != filters[:event_name]
+            next if filters[:after] && Time.parse(entry[:timestamp]) < filters[:after]
+            next if filters[:before] && Time.parse(entry[:timestamp]) > filters[:before]
+
+            entries << entry
+          end
+
+          entries
+        rescue JSON::ParserError => e
+          # Log parsing error but don't crash
+          increment_metric("e11y.dlq.parse_error", error: e.class.name)
+          entries
+        end
+
+        # Get DLQ statistics.
+        #
+        # @return [Hash] Statistics (total_entries, file_size_mb, oldest_entry, newest_entry)
+        def stats
+          return default_stats unless File.exist?(@file_path)
+
+          file_size_bytes = File.size(@file_path)
+          total_entries = File.foreach(@file_path).count
+
+          oldest_entry = nil
+          newest_entry = nil
+
+          # Read first and last line for oldest/newest timestamps
+          File.foreach(@file_path).with_index do |line, index|
+            entry = JSON.parse(line, symbolize_names: true)
+            oldest_entry = entry[:timestamp] if index.zero?
+            newest_entry = entry[:timestamp]
+          end
+
+          {
+            total_entries: total_entries,
+            file_size_mb: (file_size_bytes / 1024.0 / 1024.0).round(2),
+            oldest_entry: oldest_entry,
+            newest_entry: newest_entry,
+            file_path: @file_path
+          }
+        rescue StandardError => e
+          increment_metric("e11y.dlq.stats_error", error: e.class.name)
+          default_stats
+        end
+
+        # Replay single event from DLQ.
+        #
+        # @param event_id [String] Event ID to replay
+        # @return [Boolean] true if replayed successfully
+        def replay(event_id)
+          entry = find_entry(event_id)
+          return false unless entry
+
+          # Re-dispatch event through E11y pipeline
+          # TODO: Implement E11y::Pipeline.dispatch
+          # E11y::Pipeline.dispatch(entry[:event_data], metadata: entry[:metadata].merge(replayed: true))
+
+          # For now, just mark as replayed
+          increment_metric("e11y.dlq.replayed", event_name: entry[:event_name])
+          true
+        rescue StandardError => e
+          increment_metric("e11y.dlq.replay_failed", error: e.class.name)
+          false
+        end
+
+        # Replay batch of events from DLQ.
+        #
+        # @param event_ids [Array<String>] Event IDs to replay
+        # @return [Hash] Result summary (success_count, failure_count)
+        def replay_batch(event_ids)
+          success_count = 0
+          failure_count = 0
+
+          event_ids.each do |event_id|
+            if replay(event_id)
+              success_count += 1
+            else
+              failure_count += 1
+            end
+          end
+
+          { success_count: success_count, failure_count: failure_count }
+        end
+
+        # Delete entry from DLQ.
+        #
+        # Note: This is a simplified implementation.
+        # In production, consider using a database or append-only log with tombstones.
+        #
+        # @param event_id [String] Event ID to delete
+        # @return [Boolean] true if deleted
+        def delete(_event_id)
+          # TODO: Implement deletion (requires rewriting file)
+          # For JSONL, deletion is expensive (requires full file rewrite)
+          # Consider marking as deleted instead or using database
+          false
+        end
+
+        private
+
+        # Get default file path (log/e11y_dlq.jsonl).
+        def default_file_path
+          if defined?(Rails) && Rails.root
+            Rails.root.join("log", "e11y_dlq.jsonl").to_s
+          else
+            File.join("log", "e11y_dlq.jsonl")
+          end
+        end
+
+        # Ensure log directory exists.
+        def ensure_directory_exists
+          dir = File.dirname(@file_path)
+          FileUtils.mkdir_p(dir)
+        end
+
+        # Write DLQ entry to file (thread-safe).
+        def write_entry(entry)
+          @mutex.synchronize do
+            File.open(@file_path, "a") do |f|
+              f.flock(File::LOCK_EX)
+              f.puts(JSON.generate(entry))
+            end
+          end
+        end
+
+        # Rotate file if size exceeds max_file_size.
+        def rotate_if_needed
+          return unless File.exist?(@file_path)
+          return if File.size(@file_path) < @max_file_size_bytes
+
+          @mutex.synchronize do
+            # Rotate: log/e11y_dlq.jsonl → log/e11y_dlq.2026-01-20T12:34:56Z.jsonl
+            timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+            rotated_path = @file_path.sub(/\.jsonl$/, ".#{timestamp}.jsonl")
+
+            FileUtils.mv(@file_path, rotated_path)
+
+            increment_metric("e11y.dlq.rotated", new_file: rotated_path)
+          end
+        end
+
+        # Cleanup old rotated files.
+        def cleanup_old_files
+          dir = File.dirname(@file_path)
+          base_name = File.basename(@file_path, ".jsonl")
+
+          # Find all rotated files: e11y_dlq.*.jsonl
+          pattern = File.join(dir, "#{base_name}.*.jsonl")
+
+          Dir.glob(pattern).each do |file|
+            next unless File.file?(file)
+
+            file_age_days = (Time.now - File.mtime(file)) / 86_400
+
+            if file_age_days > @retention_days
+              File.delete(file)
+              increment_metric("e11y.dlq.cleaned_up", file: file)
+            end
+          end
+        end
+
+        # Find DLQ entry by ID.
+        def find_entry(event_id)
+          return nil unless File.exist?(@file_path)
+
+          File.foreach(@file_path) do |line|
+            entry = JSON.parse(line, symbolize_names: true)
+            return entry if entry[:id] == event_id
+          end
+
+          nil
+        rescue JSON::ParserError
+          nil
+        end
+
+        # Default stats when file doesn't exist.
+        def default_stats
+          {
+            total_entries: 0,
+            file_size_mb: 0.0,
+            oldest_entry: nil,
+            newest_entry: nil,
+            file_path: @file_path
+          }
+        end
+
+        # Increment DLQ metric.
+        def increment_metric(metric_name, tags = {})
+          # TODO: Integrate with Yabeda metrics
+          # E11y::Metrics.increment(metric_name, tags)
+        end
+      end
+    end
+  end
+end