e11y 0.2.0 → 1.1.0

data/lib/e11y/registry.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module E11y
+  # Thread-safe auto-populating registry for discovering and inspecting all defined E11y event classes.
+  #
+  # Events are registered automatically when `event_name` is set on a subclass of `E11y::Event::Base`.
+  # The registry is always-on (no configuration needed) and is safe for concurrent use.
+  #
+  # @example Discover all events
+  #   E11y::Registry.event_classes
+  #   # => [Events::OrderCreated, Events::PaymentFailed, ...]
+  #
+  # @example Find an event class by name
+  #   E11y::Registry.find("order.created")
+  #   # => Events::OrderCreated
+  #
+  # @example Filter events by severity
+  #   E11y::Registry.where(severity: :error)
+  #   # => [Events::PaymentFailed, ...]
+  #
+  # @example Generate documentation
+  #   E11y::Registry.to_documentation
+  #   # => [{ name: "order.created", class: "Events::OrderCreated", ... }, ...]
+  #
+  # @see UC-022 Event Registry
+  class Registry
+    class << self
+      # Singleton instance
+      #
+      # @return [Registry]
+      def instance
+        @instance ||= new
+      end
+
+      # Register an event class. Delegates to singleton instance.
+      #
+      # @param event_class [Class] Event class to register
+      # @return [void]
+      def register(event_class)
+        instance.register(event_class)
+      end
+
+      # Find event class by name. Delegates to singleton instance.
+      #
+      # @param event_name [String] Event name
+      # @param version [Integer, nil] Specific version (nil = latest)
+      # @return [Class, nil] Event class or nil
+      def find(event_name, version: nil)
+        instance.find(event_name, version: version)
+      end
+
+      # Return all registered event classes. Delegates to singleton instance.
+      #
+      # @return [Array<Class>]
+      def event_classes
+        instance.event_classes
+      end
+
+      # Filter events by criteria. Delegates to singleton instance.
+      #
+      # @param criteria [Hash] Filter criteria (:severity, :version, :adapter)
+      # @return [Array<Class>]
+      def where(**criteria)
+        instance.where(**criteria)
+      end
+
+      # Validate that an event is properly configured. Delegates to singleton instance.
+      #
+      # @param event_name [String]
+      # @return [Boolean]
+      def validate(event_name)
+        instance.validate(event_name)
+      end
+
+      # Clear all registered events. Delegates to singleton instance.
+      #
+      # @return [void]
+      def clear!
+        instance.clear!
+      end
+
+      # Number of unique event names registered. Delegates to singleton instance.
+      #
+      # @return [Integer]
+      def size
+        instance.size
+      end
+
+      # Generate documentation hash for all events. Delegates to singleton instance.
+      #
+      # @return [Array<Hash>]
+      def to_documentation
+        instance.to_documentation
+      end
+
+      # Return all versions of an event (ADR-012 §6.2).
+      #
+      # @param event_name [String] Event name
+      # @return [Array<Hash>] [{ version: N, class: Klass }, ...] sorted by version
+      def all_versions(event_name)
+        instance.all_versions(event_name)
+      end
+
+      # Return event names that have multiple versions (ADR-012 §6.2).
+      #
+      # @return [Array<String>]
+      def versioned_events
+        instance.versioned_events
+      end
+
+      # Reset the singleton instance (primarily for test isolation).
+      #
+      # After calling this, the next call to `.instance` creates a fresh registry.
+      # Note: previously registered events will NOT be re-registered unless their
+      # class definitions are re-evaluated.
+      #
+      # @return [void]
+      # @api private
+      def reset!
+        @instance = nil
+      end
+    end
+
+    # Initialize a new Registry instance.
+    #
+    # Creates an empty, thread-safe registry backed by a Mutex-protected Hash.
+    def initialize
+      @registry = {} # event_name (String) => Array<Class>
+      @mutex = Mutex.new
+    end
+
+    # Register an event class.
+    #
+    # Safe to call multiple times with the same class — idempotent.
+    # Silently ignores classes that do not respond to `event_name`
+    # or return a blank name (e.g. intermediate abstract classes).
+    #
+    # @param event_class [Class] Event class to register
+    # @return [void]
+    def register(event_class)
+      return unless event_class.respond_to?(:event_name)
+
+      name = begin
+        event_class.event_name
+      rescue StandardError
+        nil
+      end
+
+      return if name.nil? || name.empty? || name == "AnonymousEvent"
+
+      @mutex.synchronize do
+        @registry[name] ||= []
+        @registry[name] << event_class unless @registry[name].include?(event_class)
+      end
+    end
+
+    # Find event class by name.
+    #
+    # When multiple classes share the same event name (versioning), returns the
+    # latest-registered one by default. Pass `version:` to find a specific version.
+    #
+    # @param event_name [String, Symbol] Event name to look up
+    # @param version [Integer, nil] Specific version number (nil = latest)
+    # @return [Class, nil] Matching event class or nil
+    def find(event_name, version: nil)
+      entries = @mutex.synchronize { @registry[event_name.to_s]&.dup }
+      return nil if entries.nil? || entries.empty?
+
+      if version
+        entries.find { |klass| klass.respond_to?(:version) && klass.version == version }
+      else
+        entries.last # latest registered = latest version
+      end
+    end
+
+    # Return all registered event classes as a flat array.
+    #
+    # The returned array is a copy — mutating it does not affect the registry.
+    #
+    # @return [Array<Class>]
+    def event_classes
+      @mutex.synchronize { @registry.values.flatten.dup }
+    end
+
+    # Filter registered events by criteria.
+    #
+    # Supported criteria keys:
+    # - `:severity` — matches `klass.default_severity` or `klass.severity`
+    # - `:version`  — matches `klass.version`
+    # - `:adapter`  — matches if `klass.adapters` includes the value
+    #
+    # Unknown criteria keys always produce no matches (conservative).
+    #
+    # @param criteria [Hash]
+    # @return [Array<Class>]
+    def where(**criteria)
+      event_classes.select do |klass|
+        criteria.all? do |key, value|
+          case key
+          when :severity
+            # Support both default_severity and severity readers
+            reader = klass.respond_to?(:default_severity) ? :default_severity : :severity
+            klass.respond_to?(reader) && klass.public_send(reader) == value
+          when :version
+            klass.respond_to?(:version) && klass.version == value
+          when :adapter
+            klass.respond_to?(:adapters) && Array(klass.adapters).include?(value)
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # Validate that a registered event has a compiled schema.
+    #
+    # Returns `false` for unknown events.
+    # Returns `true` if the class is registered and has a non-nil `compiled_schema`.
+    #
+    # @param event_name [String]
+    # @return [Boolean]
+    # rubocop:disable Naming/PredicateMethod -- "validate" is the established API name
+    def validate(event_name)
+      klass = find(event_name)
+      return false unless klass
+
+      klass.respond_to?(:compiled_schema) && !klass.compiled_schema.nil?
+    end
+    # rubocop:enable Naming/PredicateMethod
+
+    # Remove all entries from the registry.
+    #
+    # Primarily used in tests to avoid cross-test pollution.
+    #
+    # @return [void]
+    def clear!
+      @mutex.synchronize { @registry.clear }
+    end
+
+    # Number of unique event names in the registry.
+    #
+    # Note: multiple versions of the same event name count as 1.
+    #
+    # @return [Integer]
+    def size
+      @mutex.synchronize { @registry.size }
+    end
+
+    # Return all versions of an event (ADR-012 §6.2).
+    #
+    # @param event_name [String] Event name
+    # @return [Array<Hash>] [{ version: N, class: Klass }, ...] sorted by version
+    def all_versions(event_name)
+      entries = @mutex.synchronize { @registry[event_name.to_s]&.dup }
+      return [] if entries.nil? || entries.empty?
+
+      entries
+        .map { |klass| { version: klass.respond_to?(:version) ? klass.version : 1, class: klass } }
+        .sort_by { |h| h[:version] }
+    end
+
+    # Return event names that have multiple versions (ADR-012 §6.2).
+    #
+    # @return [Array<String>]
+    def versioned_events
+      @mutex.synchronize do
+        @registry.select { |_name, entries| entries.size >= 2 }.keys
+      end
+    end
+
+    # Generate a documentation-friendly hash for every registered event class.
+    #
+    # @return [Array<Hash>] Each entry contains `:name`, `:class`, `:version`,
+    #   `:severity`, and `:schema_keys` (absent when not applicable).
+    def to_documentation
+      event_classes.map do |klass|
+        {
+          name: klass.respond_to?(:event_name) ? klass.event_name : klass.name,
+          class: klass.name,
+          version: klass.respond_to?(:version) ? klass.version : nil,
+          severity: klass.respond_to?(:severity) ? klass.severity : nil,
+          schema_keys: extract_schema_keys(klass)
+        }.compact
+      end
+    end
+
+    private
+
+    # Extract schema key names from an event class.
+    #
+    # Uses `compiled_schema.key_map` when available, falling back gracefully.
+    #
+    # @param klass [Class] Event class
+    # @return [Array<String>, nil]
+    def extract_schema_keys(klass)
+      return nil unless klass.respond_to?(:compiled_schema)
+
+      schema = klass.compiled_schema
+      return nil unless schema.respond_to?(:key_map)
+
+      schema.key_map.keys.map(&:name)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/e11y/reliability/circuit_breaker.rb

@@ -115,7 +115,7 @@ module E11y
 
       # Handle OPEN state (fast fail).
       def handle_open_circuit
-        increment_metric("e11y.circuit_breaker.rejected")
+        E11y::Metrics.increment(:e11y_circuit_breaker_transitions_total, adapter: @adapter_name, event: "rejected")
 
         raise CircuitOpenError, "Circuit breaker open for #{@adapter_name} " \
                                 "(opened at #{@opened_at}, timeout: #{@timeout_seconds}s)"
@@ -137,12 +137,10 @@ module E11y
           @failure_count = 0
           @success_count += 1
         end
-
-        increment_metric("e11y.circuit_breaker.success")
       end
 
       # Handle failed execution in CLOSED state.
-      def on_failure(error)
+      def on_failure(_error)
         @mutex.synchronize do
           @failure_count += 1
           @last_failure_time = Time.now
@@ -150,8 +148,6 @@ module E11y
           # 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.
@@ -162,18 +158,14 @@ module E11y
           # 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)
+      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.
@@ -183,7 +175,8 @@ module E11y
         @failure_count = 0 # Reset for next cycle
         @success_count = 0
 
-        increment_metric("e11y.circuit_breaker.opened")
+        E11y::Metrics.increment(:e11y_circuit_breaker_transitions_total, adapter: @adapter_name, event: "opened")
+        track_circuit_state_gauge
       end
 
       # Transition to HALF_OPEN state.
@@ -191,7 +184,8 @@ module E11y
         @state = STATE_HALF_OPEN
         @success_count = 0 # Reset success counter for testing
 
-        increment_metric("e11y.circuit_breaker.half_opened")
+        E11y::Metrics.increment(:e11y_circuit_breaker_transitions_total, adapter: @adapter_name, event: "half_opened")
+        track_circuit_state_gauge
       end
 
       # Transition to CLOSED state.
@@ -202,16 +196,20 @@ module E11y
         @opened_at = nil
         @last_failure_time = nil
 
-        increment_metric("e11y.circuit_breaker.closed")
+        E11y::Metrics.increment(:e11y_circuit_breaker_transitions_total, adapter: @adapter_name, event: "closed")
+        track_circuit_state_gauge
       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))
+      # Track circuit breaker state gauge via ReliabilityMonitor.
+      def track_circuit_state_gauge
+        return unless defined?(E11y::SelfMonitoring::ReliabilityMonitor)
+
+        E11y::SelfMonitoring::ReliabilityMonitor.track_circuit_state(
+          adapter_name: @adapter_name,
+          state: @state.to_s
+        )
+      rescue StandardError => e
+        E11y.logger&.warn("E11y CircuitBreaker gauge error: #{e.message}")
       end
     end
     # rubocop:enable Metrics/ClassLength

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module E11y
+  module Reliability
+    module DLQ
+      # Abstract base class for Dead Letter Queue storage backends.
+      #
+      # Subclass this to implement a custom DLQ backend (file, Redis, database, etc.).
+      # All methods raise NotImplementedError by default except replay_batch (which
+      # delegates to replay).
+      #
+      # @see DLQ::FileAdapter for the file-based implementation
+      class Base
+        # Save a failed event to the DLQ.
+        #
+        # @param event_data [Hash] Event data
+        # @param metadata [Hash] Failure metadata
+        # @return [String] event ID
+        def save(event_data, metadata: {})
+          raise NotImplementedError, "#{self.class}#save is not implemented"
+        end
+
+        # List DLQ entries.
+        #
+        # @param limit [Integer]
+        # @param offset [Integer]
+        # @param filters [Hash]
+        # @return [Array<Hash>]
+        def list(limit: 100, offset: 0, filters: {})
+          raise NotImplementedError, "#{self.class}#list is not implemented"
+        end
+
+        # Return DLQ statistics.
+        #
+        # @return [Hash]
+        def stats
+          raise NotImplementedError, "#{self.class}#stats is not implemented"
+        end
+
+        # Replay a single event.
+        #
+        # @param event_id [String]
+        # @return [Boolean]
+        def replay(event_id)
+          raise NotImplementedError, "#{self.class}#replay is not implemented"
+        end
+
+        # Replay a batch of events. Delegates to replay for each ID.
+        #
+        # @param event_ids [Array<String>]
+        # @return [Hash] { success_count: Integer, failure_count: Integer }
+        def replay_batch(event_ids)
+          success_count = 0
+          failure_count = 0
+          event_ids.each do |id|
+            replay(id) ? success_count += 1 : failure_count += 1
+          end
+          { success_count: success_count, failure_count: failure_count }
+        end
+
+        # Delete an entry from the DLQ.
+        #
+        # @param event_id [String]
+        # @return [Boolean]
+        def delete(event_id)
+          raise NotImplementedError, "#{self.class}#delete is not implemented"
+        end
+      end
+    end
+  end
+end