e11y 0.2.0 → 1.1.0

data/lib/e11y/adapters/dev_log.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module E11y
+  module Adapters
+    # Development-only adapter that stores events in a local JSONL file
+    # and exposes a rich read API for TUI, Browser Overlay, and MCP Server.
+    #
+    # Auto-registered by Railtie in development/test environments.
+    # Do not use in production.
+    #
+    # @example Manual setup
+    #   adapter = E11y::Adapters::DevLog.new(
+    #     path: Rails.root.join("log", "e11y_dev.jsonl"),
+    #     max_size: 50.megabytes,
+    #     keep_rotated: 5
+    #   )
+    class DevLog < Base
+      # @param path           [String, Pathname]
+      # @param max_size       [Integer]  Rotation threshold in bytes (default 50 MB)
+      # @param max_lines      [Integer]  Rotation threshold in line count (default 10_000)
+      # @param keep_rotated   [Integer]  Number of .N.gz files to retain (default 5)
+      # @param enable_watcher [Boolean]  Reserved for future file-watcher integration
+      def initialize(path: "log/e11y_dev.jsonl",
+                     max_size: FileStore::DEFAULT_MAX_SIZE,
+                     max_lines: FileStore::DEFAULT_MAX_LINES,
+                     keep_rotated: FileStore::DEFAULT_KEEP_ROTATED,
+                     enable_watcher: false)
+        super({})
+        @store          = FileStore.new(path: path, max_size: max_size,
+                                        max_lines: max_lines, keep_rotated: keep_rotated)
+        @query          = Query.new(@store.path)
+        @enable_watcher = enable_watcher
+      end
+
+      # Write a single event to the JSONL file.
+      #
+      # @param event_data [Hash] Event from the E11y pipeline
+      # @return [Boolean] true on success, false on error
+      def write(event_data)
+        @store.append(serialize(event_data))
+        true
+      rescue StandardError => e
+        warn "[E11y::DevLog] write failed: #{e.message}"
+        false
+      end
+
+      # --- Read API (delegated to Query) ---
+
+      # @see Query#stored_events
+      def stored_events(limit: 1000, severity: nil, source: nil)
+        @query.stored_events(limit: limit, severity: severity, source: source)
+      end
+
+      # @see Query#find_event
+      def find_event(id) = @query.find_event(id)
+
+      # @see Query#search
+      def search(query_str, limit: 500) = @query.search(query_str, limit: limit)
+
+      # @see Query#events_by_name
+      def events_by_name(name, limit: 500)
+        @query.stored_events(limit: limit).select { |e| e["event_name"] == name }
+      end
+
+      # @see Query#events_by_severity
+      def events_by_severity(sev, limit: 500)
+        @query.stored_events(limit: limit, severity: sev)
+      end
+
+      # @see Query#events_by_trace
+      def events_by_trace(trace_id) = @query.events_by_trace(trace_id)
+
+      # @see Query#interactions
+      def interactions(window_ms: 500, limit: 50, source: nil)
+        @query.interactions(window_ms: window_ms, limit: limit, source: source)
+      end
+
+      # @see Query#stats
+      def stats = @query.stats
+
+      # @see Query#updated_since?
+      def updated_since?(timestamp) = @query.updated_since?(timestamp)
+
+      # @see Query#clear!
+      def clear! = @query.clear!
+
+      # Advertise dev_log and readable capabilities.
+      def capabilities
+        super.merge(dev_log: true, readable: true)
+      end
+
+      private
+
+      def serialize(event_data)
+        data = event_data.is_a?(::Hash) ? event_data.transform_keys(&:to_s) : {}
+        enrich_ids!(data)
+        enrich_metadata!(data)
+        ::JSON.generate(data)
+      end
+
+      def enrich_ids!(data)
+        data["id"]        ||= ::SecureRandom.uuid
+        data["timestamp"] ||= ::Time.now.utc.iso8601(3)
+      end
+
+      def enrich_metadata!(data)
+        source = ::Thread.current[:e11y_source] || "web"
+        meta   = (data["metadata"] || {}).dup
+        meta["source"]     ||= source
+        meta["started_at"] ||= data["timestamp"]
+        data["metadata"] = meta
+      end
+    end
+  end
+end

data/lib/e11y/adapters/file.rb

@@ -26,11 +26,8 @@ module E11y
     #
     #   adapter.write(event_name: "user.login", severity: :info)
     #
-    # @example With Registry
-    #   E11y::Adapters::Registry.register(
-    #     :file_logger,
-    #     E11y::Adapters::File.new(path: "log/events.log")
-    #   )
+    # @example Configuration
+    #   config.adapters[:file] = E11y::Adapters::File.new(path: "log/events.log")
     # rubocop:disable Metrics/ClassLength
     # File adapter contains file rotation and buffering logic as cohesive unit
     class File < Base
@@ -152,7 +149,7 @@ module E11y
 
       # Open file for writing
       def open_file!
-        @file = ::File.open(@path, "a")
+        @file = ::File.new(@path, "a")
         @file.sync = true
         @current_date = Date.today if @rotation == :daily
       end

data/lib/e11y/adapters/in_memory.rb

@@ -39,6 +39,7 @@ module E11y
     #   test_adapter = E11y::Adapters::InMemory.new(max_events: nil)
     #
     # @see ADR-004 §9.1 (In-Memory Test Adapter)
+    # rubocop:disable Metrics/ClassLength
     class InMemory < Base
       # Default maximum number of events to store
       DEFAULT_MAX_EVENTS = 1000
@@ -118,17 +119,28 @@ module E11y
         end
       end
 
+      alias clear clear!
+
       # Find events matching pattern
       #
-      # @param pattern [String, Regexp] Pattern to match against event_name
+      # @param pattern [String, Regexp, Class] Event name pattern or event class
       # @return [Array<Hash>] Matching events
       #
       # @example
       #   adapter.find_events(/order/)  # All order.* events
       #   adapter.find_events("order.paid")  # Exact match
+      #   adapter.find_events(Events::OrderPaid)  # By event class
       def find_events(pattern)
-        pattern = Regexp.new(Regexp.escape(pattern)) if pattern.is_a?(String)
-        @events.select { |event| event[:event_name].to_s.match?(pattern) }
+        pattern = event_pattern_for(pattern)
+        @events.select { |event| event_matches?(event, pattern) }
+      end
+
+      # Find first event matching pattern
+      #
+      # @param pattern [String, Regexp, Class] Event name pattern or event class
+      # @return [Hash, nil] First matching event or nil
+      def find_event(pattern)
+        find_events(pattern).first
       end
 
       # Count events by name
@@ -138,8 +150,10 @@ module E11y
       #
       # @example
       #   adapter.event_count  # Total events
-      #   adapter.event_count("order.paid")  # Specific event count
-      def event_count(event_name: nil)
+      #   adapter.event_count("order.paid")  # Specific event count (positional)
+      #   adapter.event_count(event_name: "order.paid")  # Specific event count (keyword)
+      def event_count(event_name = nil, **kwargs)
+        event_name ||= kwargs[:event_name]
         if event_name
           @events.count { |event| event[:event_name] == event_name }
         else
@@ -147,6 +161,16 @@ module E11y
         end
       end
 
+      # Get the most recently written event.
+      #
+      # @return [Hash, nil] The last event, or nil if none
+      #
+      # @example
+      #   adapter.last_event  # Most recently written event
+      def last_event
+        events.last
+      end
+
       # Get last N events
       #
       # @param count [Integer] Number of events to return
@@ -205,6 +229,28 @@ module E11y
 
       private
 
+      def event_pattern_for(pattern)
+        case pattern
+        when Class then pattern
+        when String, Regexp then pattern.is_a?(String) ? Regexp.new(Regexp.escape(pattern)) : pattern
+        else raise ArgumentError, "Pattern must be Class, String, or Regexp, got #{pattern.class}"
+        end
+      end
+
+      def event_matches?(event, pattern)
+        return event[:event_name].to_s.match?(pattern) if pattern.is_a?(Regexp)
+        return event_matches_class?(event, pattern) if pattern.is_a?(Class)
+
+        false
+      end
+
+      def event_matches_class?(event, klass)
+        event[:event_class] == klass ||
+          event[:event_class]&.name == klass.name ||
+          event[:event_name].to_s == (klass.respond_to?(:event_name) ? klass.event_name : klass.name) ||
+          event[:event_name].to_s.include?(klass.name)
+      end
+
       # Enforce max_events limit by dropping oldest events (FIFO)
       #
       # @return [void]
@@ -218,5 +264,6 @@ module E11y
         @dropped_count += excess
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/adapters/in_memory_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "in_memory"
+
+module E11y
+  module Adapters
+    # InMemoryTest Adapter — extends InMemory with test-specific helpers.
+    #
+    # Overrides `last_event` to skip Rails auto-instrumentation events
+    # (E11y::Events::Rails::*) that fire after each HTTP request and
+    # would otherwise obscure the event your test just tracked.
+    #
+    # Use this adapter in test suites; use `InMemory` in production configs.
+    #
+    # @example
+    #   let(:adapter) { E11y::Adapters::InMemoryTest.new }
+    #   before { E11y.register_adapter :memory, adapter }
+    class InMemoryTest < InMemory
+      # Return the last event that was NOT fired by Rails auto-instrumentation.
+      #
+      # @return [Hash, nil]
+      def last_event
+        events.reverse_each.find do |e|
+          !e[:event_name].to_s.start_with?("E11y::Events::Rails::")
+        end
+      end
+    end
+  end
+end

data/lib/e11y/adapters/loki.rb

@@ -41,11 +41,8 @@ module E11y
     #     batch_timeout: 5
     #   )
     #
-    # @example With Registry
-    #   E11y::Adapters::Registry.register(
-    #     :loki_logger,
-    #     E11y::Adapters::Loki.new(url: ENV["LOKI_URL"])
-    #   )
+    # @example Configuration
+    #   config.adapters[:loki] = E11y::Adapters::Loki.new(url: ENV["LOKI_URL"])
     #
     # @example With Cardinality Protection (C04 Resolution - Enterprise)
     #   # Enable for high-traffic environments to prevent label explosion
@@ -82,8 +79,9 @@ module E11y
       # @option config [Integer] :batch_timeout (5) Max seconds to wait before flushing batch
       # @option config [Boolean] :compress (true) Enable gzip compression
       # @option config [String] :tenant_id (nil) Loki tenant ID (X-Scope-OrgID header)
-      # @option config [Boolean] :enable_cardinality_protection (false) Enable cardinality protection for labels (C04)
-      # @option config [Integer] :max_label_cardinality (100) Max unique values per label when protection enabled
+      # @option config [Boolean] :enable_cardinality_protection (true) Enable cardinality protection for labels (C04)
+      # @option config [Integer] :max_label_cardinality (1000) Max unique values per label when protection enabled.
+      #   Labels = event_name + severity only (payload stays in log line). 1000 covers ~1000 event types.
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       # Adapter initialization requires many instance variable assignments
       def initialize(config = {})
@@ -91,20 +89,22 @@ module E11y
         @labels = config.fetch(:labels, {})
         @batch_size = config.fetch(:batch_size, DEFAULT_BATCH_SIZE)
         @batch_timeout = config.fetch(:batch_timeout, DEFAULT_BATCH_TIMEOUT)
+        @timeout = config.fetch(:timeout, 5)
+        @health_check_timeout = [@timeout, 2].min
         @compress = config.fetch(:compress, true)
         @tenant_id = config[:tenant_id]
-        @enable_cardinality_protection = config.fetch(:enable_cardinality_protection, false)
-        @max_label_cardinality = config.fetch(:max_label_cardinality, 100)
+        @enable_cardinality_protection = config.fetch(:enable_cardinality_protection, true)
+        @max_label_cardinality = config.fetch(:max_label_cardinality, 1000)
 
         @buffer = []
         @buffer_mutex = Mutex.new
         @connection = nil
         @last_flush = Time.now
 
-        # C04: Optional cardinality protection (disabled by default for logs)
+        # C04: Cardinality protection for labels (enabled by default per ADR-009 §8)
         if @enable_cardinality_protection
           @cardinality_protection = E11y::Metrics::CardinalityProtection.new(
-            max_unique_values: @max_label_cardinality
+            cardinality_limit: @max_label_cardinality
           )
         end
 
@@ -155,11 +155,22 @@ module E11y
         end
       end
 
-      # Check if adapter is healthy
+      # Loki health check endpoint
+      READY_PATH = "/ready"
+
+      # Check if adapter is healthy (Loki server reachable)
+      #
+      # Performs actual HTTP GET to /ready. Returns false on connection failure,
+      # timeout, or non-2xx response.
       #
-      # @return [Boolean] True if connection is established
+      # @return [Boolean] True if Loki responds with 2xx
       def healthy?
-        @connection&.respond_to?(:get)
+        return false unless @connection
+
+        response = @connection.get(READY_PATH)
+        (200..299).cover?(response.status)
+      rescue Faraday::Error, Errno::ECONNREFUSED, Errno::ETIMEDOUT
+        false
       end
 
       # Adapter capabilities
@@ -194,7 +205,6 @@ module E11y
       #
       # @see ADR-004 Section 7.1 (Retry Policy via gem-level middleware)
       # @see ADR-004 Section 6.1 (Connection pooling via HTTP client)
-      # rubocop:disable Metrics/MethodLength
       # HTTP client configuration requires detailed retry and connection settings
       def build_connection!
         @connection = Faraday.new(url: @url) do |f|
@@ -218,7 +228,6 @@ module E11y
           f.adapter Faraday.default_adapter
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Check if buffer should be flushed
       def flush_if_needed!
@@ -280,22 +289,23 @@ module E11y
 
       # Extract labels from event
       #
+      # Uses normalized event_name (e.g., "Events::TestLoki" -> "test.loki") for consistent
+      # querying via LogQL. Matches Versioning middleware convention.
+      #
       # @param event_data [Hash] Event data
       # @return [Hash] Labels for Loki stream
       def extract_labels(event_data)
         event_labels = {
-          event_name: event_data[:event_name].to_s,
+          event_name: normalize_event_name_for_labels(event_data[:event_name].to_s),
           severity: event_data[:severity].to_s
         }
 
         # Merge static and event labels
         all_labels = @labels.merge(event_labels)
 
-        # C04: Apply cardinality protection if enabled (enterprise use case)
-        # Disabled by default - Loki is a log system, labels are for stream filtering only
-        if @enable_cardinality_protection && @cardinality_protection
-          all_labels = @cardinality_protection.filter(all_labels, "loki.stream")
-        end
+        # C04: Cardinality protection for labels only. Labels = event_name + severity (payload
+        # stays in log line). Filter by user_uuid via LogQL: | json | user_uuid="xxx"
+        all_labels = @cardinality_protection.filter(all_labels, "loki.stream") if @enable_cardinality_protection && @cardinality_protection
 
         all_labels.transform_keys(&:to_s)
       end
@@ -305,7 +315,17 @@ module E11y
       # @param event_data [Hash] Event data
       # @return [Array] [timestamp_ns, line]
       def format_loki_entry(event_data)
-        timestamp_ns = (event_data[:timestamp] || Time.now).to_f * 1_000_000_000
+        # Parse timestamp - can be Time object, ISO8601 string, or nil
+        timestamp = event_data[:timestamp]
+        timestamp = if timestamp.is_a?(String)
+                      Time.parse(timestamp)
+                    elsif timestamp.nil?
+                      Time.now
+                    else
+                      timestamp
+                    end
+
+        timestamp_ns = timestamp.to_f * 1_000_000_000
         line = event_data.to_json
 
         [timestamp_ns.to_i.to_s, line]
@@ -323,6 +343,21 @@ module E11y
         io.string
       end
 
+      # Normalize event name for Loki labels (matches Versioning middleware convention)
+      #
+      # @param name [String] Event name (e.g., "Events::TestLoki")
+      # @return [String] Normalized name (e.g., "test.loki")
+      def normalize_event_name_for_labels(name)
+        return name if name.nil? || name.empty?
+
+        n = name.sub(/^Events::/, "").sub(/V\d+$/, "")
+        n.gsub("::", ".")
+         .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .downcase
+         .tr("_", ".")
+      end
+
       # Build HTTP headers
       #
       # @return [Hash] Headers for Loki request

data/lib/e11y/adapters/null.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module E11y
+  module Adapters
+    # Null Adapter — silently discards all events.
+    #
+    # Designed for use in tests and development environments where you want
+    # to suppress all output while still being able to assert that events
+    # were tracked (via the `events` reader).
+    #
+    # @example In tests
+    #   RSpec.configure do |config|
+    #     config.before do
+    #       E11y.configure do |c|
+    #         c.adapters[:null] = E11y::Adapters::NullAdapter.new
+    #       end
+    #     end
+    #   end
+    #
+    # @example Asserting events
+    #   null_adapter = E11y::Adapters::NullAdapter.new
+    #   E11y.configure { |c| c.adapters[:null] = null_adapter }
+    #
+    #   Events::OrderPaid.track(order_id: "123", amount: 99.99)
+    #
+    #   expect(null_adapter.events.size).to eq(1)
+    #   expect(null_adapter.events.last[:event_name]).to eq("order.paid")
+    class Null < Base
+      attr_reader :events
+
+      # @param config [Hash] Options
+      # @option config [Boolean] :store_events (true) When false, truly discards (no retention).
+      #   Use store_events: false for memory profiling to measure pipeline-only allocations.
+      def initialize(config = {})
+        super
+        @store_events = config.fetch(:store_events, true)
+        @events = []
+        @mutex = Mutex.new
+      end
+
+      # Accept event. When store_events: true, stores for inspection. When false, truly discards.
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] always true
+      # rubocop:disable Naming/PredicateMethod -- implements Base adapter interface
+      def write(event_data)
+        @mutex.synchronize { @events << event_data.dup } if @store_events
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Accept batch. When store_events: true, stores for inspection. When false, truly discards.
+      #
+      # @param events [Array<Hash>] Event payloads
+      # @return [Boolean] always true
+      # rubocop:disable Naming/PredicateMethod -- implements Base adapter interface
+      def write_batch(events)
+        @mutex.synchronize { @events.concat(events.map(&:dup)) } if @store_events
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Clear all stored events (useful between test examples).
+      #
+      # @return [void]
+      def clear!
+        @mutex.synchronize { @events.clear }
+      end
+
+      def healthy?
+        true
+      end
+
+      def capabilities
+        { batching: true, compression: false, async: false, streaming: false, null: true }
+      end
+    end
+
+    # Convenience alias matching Quick Start documentation.
+    NullAdapter = Null
+  end
+end