e11y 0.1.0

data/lib/e11y/adapters/file.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "json"
+require "zlib"
+
+module E11y
+  module Adapters
+    # File adapter for writing events to local files with rotation and compression.
+    #
+    # Features:
+    # - JSONL format (one JSON object per line)
+    # - Automatic rotation (by size, time, or daily)
+    # - Optional gzip compression on rotation
+    # - Thread-safe writes
+    # - Batch write support
+    #
+    # @example Basic usage
+    #   adapter = E11y::Adapters::File.new(
+    #     path: "log/e11y.log",
+    #     rotation: :daily,
+    #     max_size: 100 * 1024 * 1024, # 100MB
+    #     compress: true
+    #   )
+    #
+    #   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")
+    #   )
+    class File < Base
+      # Default maximum file size before rotation (100MB)
+      DEFAULT_MAX_SIZE = 100 * 1024 * 1024
+
+      # Default rotation strategy
+      DEFAULT_ROTATION = :daily
+
+      attr_reader :path, :rotation, :max_size, :compress_on_rotate
+
+      # Initialize File adapter
+      #
+      # @param config [Hash] Configuration options
+      # @option config [String] :path (required) Path to log file
+      # @option config [Symbol] :rotation (:daily) Rotation strategy (:daily, :size, :none)
+      # @option config [Integer] :max_size (100MB) Max file size before rotation (for :size strategy)
+      # @option config [Boolean] :compress (true) Compress rotated files with gzip
+      def initialize(config = {})
+        @path = config[:path]
+        @rotation = config.fetch(:rotation, DEFAULT_ROTATION)
+        @max_size = config.fetch(:max_size, DEFAULT_MAX_SIZE)
+        @compress_on_rotate = config.fetch(:compress, true)
+        @file = nil
+        @mutex = Mutex.new
+        @current_date = nil
+
+        super
+
+        ensure_directory!
+        open_file!
+      end
+
+      # Write a single event to file
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] Success status
+      def write(event_data)
+        @mutex.synchronize do
+          rotate_if_needed!
+
+          line = format_event(event_data)
+          @file.puts(line)
+          @file.flush
+        end
+
+        true
+      rescue StandardError => e
+        warn "E11y File adapter error: #{e.message}"
+        false
+      end
+
+      # Write a batch of events to file
+      #
+      # @param events [Array<Hash>] Array of event payloads
+      # @return [Boolean] Success status
+      def write_batch(events)
+        @mutex.synchronize do
+          rotate_if_needed!
+
+          events.each do |event_data|
+            line = format_event(event_data)
+            @file.puts(line)
+          end
+
+          @file.flush
+        end
+
+        true
+      rescue StandardError => e
+        warn "E11y File adapter batch error: #{e.message}"
+        false
+      end
+
+      # Close the file handle
+      def close
+        @mutex.synchronize do
+          @file&.close
+          @file = nil
+        end
+      end
+
+      # Check if adapter is healthy
+      #
+      # @return [Boolean] True if file is writable
+      def healthy?
+        @mutex.synchronize do
+          return false unless @file
+
+          !@file.closed?
+        end
+      end
+
+      # Adapter capabilities
+      #
+      # @return [Hash] Capability flags
+      def capabilities
+        super.merge(
+          batching: true,
+          compression: @compress_on_rotate,
+          streaming: true
+        )
+      end
+
+      private
+
+      # Validate configuration
+      def validate_config!
+        raise ArgumentError, "File adapter requires :path" unless @path
+        raise ArgumentError, "Invalid rotation: #{@rotation}" unless %i[daily size none].include?(@rotation)
+        raise ArgumentError, "max_size must be positive" if @max_size && @max_size <= 0
+      end
+
+      # Ensure directory exists
+      def ensure_directory!
+        dir = ::File.dirname(@path)
+        FileUtils.mkdir_p(dir) unless ::File.directory?(dir)
+      end
+
+      # Open file for writing
+      def open_file!
+        @file = ::File.open(@path, "a")
+        @file.sync = true
+        @current_date = Date.today if @rotation == :daily
+      end
+
+      # Format event as JSONL
+      #
+      # @param event_data [Hash] Event payload
+      # @return [String] JSON string
+      def format_event(event_data)
+        event_data.to_json
+      end
+
+      # Check if rotation is needed and perform it
+      def rotate_if_needed!
+        case @rotation
+        when :daily
+          rotate_daily!
+        when :size
+          rotate_by_size!
+        end
+      end
+
+      # Rotate file if date changed
+      def rotate_daily!
+        today = Date.today
+        return unless @current_date && today != @current_date
+
+        perform_rotation!
+        @current_date = today
+      end
+
+      # Rotate file if size exceeded
+      def rotate_by_size!
+        return unless @file.size >= @max_size
+
+        perform_rotation!
+      end
+
+      # Perform actual file rotation
+      def perform_rotation!
+        @file.close if @file
+
+        timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+        rotated_path = "#{@path}.#{timestamp}"
+
+        ::File.rename(@path, rotated_path) if ::File.exist?(@path)
+
+        compress_file(rotated_path) if @compress_on_rotate
+
+        open_file!
+      end
+
+      # Compress rotated file with gzip
+      #
+      # @param file_path [String] Path to file to compress
+      def compress_file(file_path)
+        return unless ::File.exist?(file_path)
+
+        Zlib::GzipWriter.open("#{file_path}.gz") do |gz|
+          ::File.open(file_path, "rb") do |file|
+            gz.write(file.read)
+          end
+        end
+
+        ::File.delete(file_path)
+      rescue StandardError => e
+        warn "E11y File adapter compression error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/e11y/adapters/in_memory.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module E11y
+  module Adapters
+    # InMemory Adapter - Test adapter for specs and debugging
+    #
+    # Stores events in memory for testing and inspection.
+    # Not for production use - events are lost on restart.
+    #
+    # **⚠️ Memory Safety:**
+    # - Default limit: 1000 events (prevents unbounded growth)
+    # - Auto-drops oldest events when limit reached (FIFO)
+    # - Configure limit based on test needs
+    #
+    # **Features:**
+    # - Thread-safe event storage
+    # - Batch tracking
+    # - Query methods for tests
+    # - Manual clear support
+    # - Automatic memory limit enforcement
+    #
+    # @example Usage in tests
+    #   let(:test_adapter) { E11y::Adapters::InMemory.new }
+    #
+    #   before { E11y.register_adapter :test, test_adapter }
+    #   after { test_adapter.clear! }
+    #
+    #   it "tracks events" do
+    #     Events::OrderPaid.track(order_id: '123')
+    #     expect(test_adapter.events.size).to eq(1)
+    #     expect(test_adapter.events.first[:event_name]).to eq('order.paid')
+    #   end
+    #
+    # @example Custom limit
+    #   # For tests with many events
+    #   test_adapter = E11y::Adapters::InMemory.new(max_events: 10_000)
+    #
+    #   # Unlimited (use with caution!)
+    #   test_adapter = E11y::Adapters::InMemory.new(max_events: nil)
+    #
+    # @see ADR-004 §9.1 (In-Memory Test Adapter)
+    class InMemory < Base
+      # Default maximum number of events to store
+      DEFAULT_MAX_EVENTS = 1000
+
+      # All events written to adapter
+      #
+      # @return [Array<Hash>] Array of event payloads
+      attr_reader :events
+
+      # All batches written to adapter
+      #
+      # @return [Array<Array<Hash>>] Array of event batches
+      attr_reader :batches
+
+      # Maximum number of events to store
+      #
+      # @return [Integer, nil] Max events or nil for unlimited
+      attr_reader :max_events
+
+      # Number of events dropped due to limit
+      #
+      # @return [Integer] Dropped event count
+      attr_reader :dropped_count
+
+      # Initialize adapter
+      #
+      # @param config [Hash] Configuration options
+      # @option config [Integer, nil] :max_events (1000) Maximum events to store (nil = unlimited)
+      def initialize(config = {})
+        super
+        @max_events = config.fetch(:max_events, DEFAULT_MAX_EVENTS)
+        @events = []
+        @batches = []
+        @dropped_count = 0
+        @mutex = Mutex.new
+      end
+
+      # Write event to memory
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] true on success
+      def write(event_data)
+        @mutex.synchronize do
+          @events << event_data
+          enforce_limit!
+        end
+        true
+      end
+
+      # Write batch of events to memory
+      #
+      # @param events [Array<Hash>] Array of event payloads
+      # @return [Boolean] true on success
+      def write_batch(events)
+        @mutex.synchronize do
+          @events.concat(events)
+          @batches << events
+          enforce_limit!
+        end
+        true
+      end
+
+      # Clear all stored events and batches
+      #
+      # @return [void]
+      def clear!
+        @mutex.synchronize do
+          @events.clear
+          @batches.clear
+          @dropped_count = 0
+        end
+      end
+
+      # Find events matching pattern
+      #
+      # @param pattern [String, Regexp] Pattern to match against event_name
+      # @return [Array<Hash>] Matching events
+      #
+      # @example
+      #   adapter.find_events(/order/)  # All order.* events
+      #   adapter.find_events("order.paid")  # Exact match
+      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) }
+      end
+
+      # Count events by name
+      #
+      # @param event_name [String, nil] Event name to count, or nil for total
+      # @return [Integer] Event count
+      #
+      # @example
+      #   adapter.event_count  # Total events
+      #   adapter.event_count("order.paid")  # Specific event count
+      def event_count(event_name: nil)
+        if event_name
+          @events.count { |event| event[:event_name] == event_name }
+        else
+          @events.size
+        end
+      end
+
+      # Get last N events
+      #
+      # @param count [Integer] Number of events to return
+      # @return [Array<Hash>] Last N events
+      #
+      # @example
+      #   adapter.last_events(5)  # Last 5 events
+      def last_events(count = 10)
+        @events.last(count)
+      end
+
+      # Get first N events
+      #
+      # @param count [Integer] Number of events to return
+      # @return [Array<Hash>] First N events
+      #
+      # @example
+      #   adapter.first_events(5)  # First 5 events
+      def first_events(count = 10)
+        @events.first(count)
+      end
+
+      # Find events by severity
+      #
+      # @param severity [Symbol] Severity level to filter by
+      # @return [Array<Hash>] Events with matching severity
+      #
+      # @example
+      #   adapter.events_by_severity(:error)  # All error events
+      def events_by_severity(severity)
+        @events.select { |event| event[:severity] == severity }
+      end
+
+      # Check if any events match pattern
+      #
+      # @param pattern [String, Regexp] Pattern to match
+      # @return [Boolean] true if any events match
+      #
+      # @example
+      #   adapter.any_event?(/order/)  # Any order.* events?
+      def any_event?(pattern)
+        find_events(pattern).any?
+      end
+
+      # Adapter capabilities
+      #
+      # @return [Hash] Capability flags
+      def capabilities
+        {
+          batching: true,
+          compression: false,
+          async: false,
+          streaming: false
+        }
+      end
+
+      private
+
+      # Enforce max_events limit by dropping oldest events (FIFO)
+      #
+      # @return [void]
+      def enforce_limit!
+        return if max_events.nil? # Unlimited
+
+        return unless @events.size > max_events
+
+        excess = @events.size - max_events
+        @events.shift(excess)
+        @dropped_count += excess
+      end
+    end
+  end
+end