e11y 0.1.0

data/lib/e11y/buffers/ring_buffer.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module E11y
+  module Buffers
+    # Lock-free SPSC (Single-Producer, Single-Consumer) ring buffer
+    #
+    # Thread-safe ring buffer using atomic operations for high-throughput event buffering.
+    # Designed for 100K+ events/sec with minimal contention.
+    #
+    # Architecture:
+    # - Fixed capacity (default: 100,000 events)
+    # - Atomic read/write pointers (Concurrent::AtomicFixnum)
+    # - Backpressure strategies: :drop_oldest (default), :drop_newest, :block
+    # - Zero-copy flush operations
+    #
+    # Performance:
+    # - Target: 100K events/sec throughput
+    # - Latency: <10μs per push/pop operation (p99)
+    # - Memory: Fixed allocation (capacity * avg_event_size)
+    #
+    # References:
+    # - ADR-001 §3.3.1 (Ring Buffer Specification)
+    # - UC-001 (Request-Scoped Debug Buffering)
+    #
+    # @example Basic usage
+    #   buffer = E11y::Buffers::RingBuffer.new(capacity: 1000)
+    #   buffer.push(event_hash)
+    #   events = buffer.pop(100) # Batch pop
+    #
+    # @example With backpressure
+    #   buffer = E11y::Buffers::RingBuffer.new(
+    #     capacity: 1000,
+    #     overflow_strategy: :drop_oldest
+    #   )
+    #   buffer.push(event) # Drops oldest if full
+    #
+    # @see ADR-001 §3.3.1
+    class RingBuffer
+      # Default buffer capacity (100K events)
+      DEFAULT_CAPACITY = 100_000
+
+      # Available overflow strategies
+      OVERFLOW_STRATEGIES = %i[drop_oldest drop_newest block].freeze
+
+      # Default overflow strategy
+      DEFAULT_OVERFLOW_STRATEGY = :drop_oldest
+
+      # Maximum block time for :block strategy (milliseconds)
+      DEFAULT_MAX_BLOCK_TIME_MS = 1000
+
+      attr_reader :capacity, :overflow_strategy
+
+      # Initialize a new ring buffer
+      #
+      # @param capacity [Integer] Maximum number of events (default: 100,000)
+      # @param overflow_strategy [Symbol] Strategy when buffer is full
+      #   - :drop_oldest - Drop oldest event, keep newest (default)
+      #   - :drop_newest - Drop new event, keep existing
+      #   - :block - Wait until space available (up to max_block_time)
+      # @param max_block_time_ms [Integer] Max wait time for :block strategy (default: 1000ms)
+      #
+      # @raise [ArgumentError] if capacity <= 0 or invalid overflow_strategy
+      #
+      # @example
+      #   buffer = RingBuffer.new(capacity: 10_000, overflow_strategy: :drop_oldest)
+      def initialize(capacity: DEFAULT_CAPACITY, overflow_strategy: DEFAULT_OVERFLOW_STRATEGY,
+                     max_block_time_ms: DEFAULT_MAX_BLOCK_TIME_MS)
+        raise ArgumentError, "capacity must be > 0" if capacity <= 0
+
+        unless OVERFLOW_STRATEGIES.include?(overflow_strategy)
+          raise ArgumentError,
+                "overflow_strategy must be one of #{OVERFLOW_STRATEGIES.inspect}"
+        end
+
+        @capacity = capacity
+        @overflow_strategy = overflow_strategy
+        @max_block_time_ms = max_block_time_ms
+
+        # Fixed-size array for storage
+        @buffer = Array.new(capacity)
+
+        # Atomic pointers (SPSC pattern)
+        @write_index = Concurrent::AtomicFixnum.new(0) # Producer writes here
+        @read_index = Concurrent::AtomicFixnum.new(0)  # Consumer reads here
+        @size = Concurrent::AtomicFixnum.new(0)        # Current occupancy
+      end
+
+      # Push an event into the buffer (Producer)
+      #
+      # This is a single-producer operation - only ONE thread should call push().
+      # Uses atomic operations to ensure thread-safety with pop() (consumer).
+      #
+      # Behavior on overflow:
+      # - :drop_oldest - Removes oldest event, adds new one (always succeeds)
+      # - :drop_newest - Discards new event, keeps buffer unchanged
+      # - :block - Waits up to max_block_time for space, then drops
+      #
+      # @param event [Hash] Event hash to buffer
+      # @return [Boolean] true if event was added, false if dropped
+      #
+      # @example
+      #   success = buffer.push({ event_name: "test", payload: {} })
+      #   # => true (or false if dropped)
+      def push(event)
+        current_size = @size.value
+
+        if current_size >= @capacity
+          # Buffer full - handle backpressure
+          return handle_overflow(event)
+        end
+
+        # Write to buffer
+        write_pos = @write_index.value % @capacity
+        @buffer[write_pos] = event
+
+        # Increment pointers atomically
+        @write_index.increment
+        @size.increment
+
+        true
+      end
+
+      # Pop events from buffer (Consumer)
+      #
+      # This is a single-consumer operation - only ONE thread should call pop().
+      # Returns up to batch_size events in FIFO order.
+      #
+      # @param batch_size [Integer] Maximum events to pop (default: 100)
+      # @return [Array<Hash>] Array of events (may be empty)
+      #
+      # @example
+      #   events = buffer.pop(50)
+      #   # => [{ event_name: "test", ... }, ...]
+      def pop(batch_size = 100)
+        events = []
+        current_size = @size.value
+
+        # Limit batch size to available events
+        actual_batch_size = [batch_size, current_size].min
+
+        actual_batch_size.times do
+          read_pos = @read_index.value % @capacity
+          event = @buffer[read_pos]
+
+          events << event if event
+
+          # Clear slot to allow GC
+          @buffer[read_pos] = nil
+
+          # Increment pointers atomically
+          @read_index.increment
+          @size.decrement
+        end
+
+        events
+      end
+
+      # Flush all events from buffer
+      #
+      # Empties the buffer and returns all events in FIFO order.
+      # This is equivalent to pop(size), but more explicit.
+      #
+      # @return [Array<Hash>] All buffered events
+      #
+      # @example
+      #   all_events = buffer.flush_all
+      #   # => [event1, event2, ...]
+      def flush_all
+        pop(@size.value)
+      end
+
+      # Current number of events in buffer
+      #
+      # @return [Integer] Number of buffered events
+      def size
+        @size.value
+      end
+
+      # Check if buffer is empty
+      #
+      # @return [Boolean] true if no events buffered
+      def empty?
+        @size.value.zero?
+      end
+
+      # Check if buffer is full
+      #
+      # @return [Boolean] true if buffer is at capacity
+      def full?
+        @size.value >= @capacity
+      end
+
+      # Calculate buffer utilization percentage
+      #
+      # @return [Float] Utilization (0.0 to 1.0)
+      #
+      # @example
+      #   buffer.utilization # => 0.75 (75% full)
+      def utilization
+        @size.value.to_f / @capacity
+      end
+
+      private
+
+      # Handle buffer overflow according to strategy
+      #
+      # @param event [Hash] Event that caused overflow
+      # @return [Boolean] true if event was eventually added, false if dropped
+      # rubocop:disable Metrics/MethodLength
+      def handle_overflow(event)
+        case @overflow_strategy
+        when :drop_oldest
+          # Drop oldest event, add new one
+          pop(1) # Remove one old event
+          push(event) # Retry push (recursive, but will succeed)
+        when :drop_newest
+          # Drop new event, keep buffer unchanged
+          increment_metric("e11y.buffer.overflow.drop_newest")
+          false
+        when :block
+          # Wait for space, with timeout
+          wait_for_space
+          if full?
+            # Timeout reached, drop event
+            increment_metric("e11y.buffer.overflow.block_timeout")
+            false
+          else
+            push(event) # Retry after space freed
+          end
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Wait for buffer space (with timeout)
+      #
+      # Sleeps briefly until space is available or timeout reached.
+      # Used by :block overflow strategy.
+      #
+      # @return [void]
+      def wait_for_space
+        start_time = Time.now.to_f
+        timeout_seconds = @max_block_time_ms / 1000.0
+
+        while full?
+          elapsed = Time.now.to_f - start_time
+          break if elapsed >= timeout_seconds
+
+          # Brief sleep to avoid busy-wait
+          sleep 0.001 # 1ms
+        end
+      end
+
+      # Increment metric (placeholder for Phase 3: Metrics)
+      #
+      # TODO Phase 3: Replace with actual Yabeda metrics
+      #
+      # @param metric_name [String] Metric to increment
+      # @return [void]
+      def increment_metric(metric_name)
+        # Placeholder - will be implemented in Phase 3
+        # Yabeda.e11y.buffer_overflow.increment(strategy: @overflow_strategy)
+      end
+    end
+  end
+end

data/lib/e11y/buffers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# E11y::Buffers module - Event buffering implementations
+#
+# This module contains buffer implementations for high-throughput event storage:
+# - RingBuffer: Lock-free SPSC ring buffer (100K+ events/sec)
+# - AdaptiveBuffer: Memory-aware buffer with backpressure (Phase 1.2.2)
+#
+# @see E11y::Buffers::RingBuffer
+# @see ADR-001 §3.3 (Buffer Architecture)
+module E11y
+  module Buffers
+  end
+end

data/lib/e11y/console.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module E11y
+  # Console helpers for Rails console
+  #
+  # Provides convenient methods for debugging and introspection in Rails console.
+  #
+  # @example Usage in Rails console
+  #   E11y.stats          # Show E11y statistics
+  #   E11y.test_event     # Track a test event
+  #   E11y.events         # List all registered events
+  #   E11y.adapters       # List all adapters
+  #   E11y.reset!         # Clear buffers
+  #
+  # @see ADR-008 §9 (Console & Development)
+  module Console
+    # Enable console helpers
+    #
+    # Called automatically by E11y::Railtie when Rails console starts.
+    #
+    # @return [void]
+    def self.enable!
+      define_helper_methods
+      configure_for_console
+    end
+
+    # Define helper methods on E11y module
+    # @return [void]
+    def self.define_helper_methods
+      E11y.singleton_class.class_eval do
+        # Show E11y statistics
+        # @return [Hash] Statistics hash
+        def stats
+          {
+            enabled: E11y.config.enabled,
+            environment: E11y.config.environment,
+            service_name: E11y.config.service_name,
+            adapters: E11y::Adapters::Registry.all.map do |a|
+              {
+                name: a.name,
+                class: a.class.name,
+                healthy: a.healthy?
+              }
+            end,
+            buffer: {
+              size: buffer_size,
+              max_size: E11y.config.buffer&.max_size
+            }
+          }
+        end
+
+        # Track a test event
+        # @return [void]
+        def test_event
+          # TODO: Implement test event tracking
+          # For now, just print a message
+          puts "✅ E11y test event would be tracked here"
+          puts "   (Waiting for Events::Console::Test implementation)"
+        end
+
+        # List all registered event classes
+        # @return [Array<String>] Event class names
+        def events
+          # TODO: Implement event registry
+          puts "📋 E11y events list"
+          puts "   (Waiting for Event registry implementation)"
+          []
+        end
+
+        # List all registered adapters
+        # @return [Array<Hash>] Adapter details
+        def adapters
+          E11y::Adapters::Registry.all.map do |adapter|
+            {
+              name: adapter.name,
+              class: adapter.class.name,
+              healthy: adapter.healthy?,
+              capabilities: adapter.capabilities
+            }
+          end
+        end
+
+        # Reset buffers (clear all buffered events)
+        # @return [void]
+        def reset!
+          # TODO: Implement buffer clearing
+          puts "✅ E11y buffers would be cleared here"
+          puts "   (Waiting for Buffer#clear! implementation)"
+        end
+
+        private
+
+        # Get current buffer size
+        # @return [Integer] Number of buffered events
+        def buffer_size
+          # TODO: Implement buffer size tracking
+          0
+        end
+      end
+    end
+
+    # Configure E11y for console-friendly output
+    # @return [void]
+    def self.configure_for_console
+      E11y.configure do |config|
+        # Console-friendly output
+        config.adapters&.clear
+
+        # Use stdout adapter with pretty printing
+        config.adapters&.register :stdout, E11y::Adapters::Stdout.new(
+          colorize: true
+        )
+
+        # Show all severities
+        # TODO: Implement severity_threshold config
+        # config.severity_threshold = :debug
+      end
+    rescue StandardError => e
+      warn "[E11y] Failed to configure console: #{e.message}"
+    end
+  end
+end

data/lib/e11y/current.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/current_attributes"
+
+module E11y
+  # Request/job-scoped context using ActiveSupport::CurrentAttributes (Rails Way).
+  #
+  # Stores trace_id, span_id, parent_trace_id, and other request/job-scoped data.
+  # Automatically managed by E11y::Middleware::Request (HTTP) or
+  # Sidekiq/ActiveJob middleware (background jobs).
+  #
+  # **Hybrid Tracing (C17 Resolution)**:
+  # - HTTP Requests: new trace_id, parent_trace_id = nil
+  # - Background Jobs: new trace_id, parent_trace_id = enqueuing request's trace_id
+  #
+  # @example Setting request context (HTTP)
+  #   E11y::Current.trace_id = "abc123"
+  #   E11y::Current.user_id = 42
+  #   # parent_trace_id is nil for requests
+  #
+  # @example Setting context (Background job with parent link)
+  #   E11y::Current.trace_id = "xyz789"         # NEW trace for job
+  #   E11y::Current.parent_trace_id = "abc123"  # Link to parent request
+  #
+  # @example Accessing context
+  #   E11y::Current.trace_id        # => "xyz789"
+  #   E11y::Current.parent_trace_id # => "abc123"
+  #
+  # @example Resetting context
+  #   E11y::Current.reset
+  #
+  # @see ADR-005 §8.3 (C17 Resolution: Hybrid Background Job Tracing)
+  # @see UC-009 (Multi-Service Tracing with parent_trace_id)
+  # @see UC-010 (Background Job Tracking)
+  # @see https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :trace_id
+    attribute :span_id
+    attribute :parent_trace_id # ✅ NEW: Link to parent trace (C17 Resolution)
+    attribute :request_id
+    attribute :user_id
+    attribute :ip_address
+    attribute :user_agent
+    attribute :request_method
+    attribute :request_path
+  end
+end