event_system 0.1.0

data/exe/event_system

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/event_system'
+require 'optparse'
+
+class EventSystemCLI
+  def initialize
+    @options = {}
+    @parser = OptionParser.new do |opts|
+      opts.banner = "Usage: event_system [options] command"
+      
+      opts.on("-s", "--storage TYPE", "Storage type (memory, file)") do |type|
+        @options[:storage_type] = type.to_sym
+      end
+      
+      opts.on("-d", "--directory DIR", "Directory for file storage") do |dir|
+        @options[:storage_options] ||= {}
+        @options[:storage_options][:directory] = dir
+      end
+      
+      opts.on("-v", "--verbose", "Verbose output") do
+        @options[:verbose] = true
+      end
+      
+      opts.on("-h", "--help", "Show this help message") do
+        puts opts
+        exit
+      end
+    end
+  end
+
+  def run(args)
+    @parser.parse!(args)
+    
+    command = args.shift
+    case command
+    when "visualize"
+      visualize_command(args)
+    when "stats"
+      stats_command(args)
+    when "list"
+      list_command(args)
+    when "query"
+      query_command(args)
+    else
+      puts "Unknown command: #{command}"
+      puts "Available commands: visualize, stats, list, query"
+      exit 1
+    end
+  end
+
+  private
+
+  def create_manager
+    config = {
+      storage_type: @options[:storage_type] || :file,
+      storage_options: @options[:storage_options] || { directory: "event_logs" }
+    }
+    
+    EventSystem.create_manager(config)
+  end
+
+  def visualize_command(args)
+    manager = create_manager
+    session_id = args[0]
+    output_file = args[1]
+    
+    generator = EventSystem::Visualization::TimelineGenerator.new(manager.storage)
+    output_path = generator.generate_timeline(session_id, output_file)
+    
+    if output_path
+      puts "Timeline generated: #{output_path}"
+    else
+      puts "No events found for visualization"
+      exit 1
+    end
+  end
+
+  def stats_command(args)
+    manager = create_manager
+    stats = manager.stats
+    
+    puts "Event System Statistics:"
+    puts "========================"
+    puts "Storage: #{stats[:storage][:type]}"
+    puts "Sessions: #{stats[:storage][:sessions]}"
+    puts "Subscribers: #{stats[:subscribers].values.sum}"
+    puts
+    puts "Event types:"
+    stats[:subscribers].each do |type, count|
+      puts "  #{type}: #{count} subscribers"
+    end
+  end
+
+  def list_command(args)
+    manager = create_manager
+    sessions = manager.storage.list_sessions
+    
+    puts "Available Sessions:"
+    puts "==================="
+    if sessions.empty?
+      puts "No sessions found"
+    else
+      sessions.each do |session|
+        events = manager.storage.load_session(session)
+        puts "#{session} (#{events.length} events)"
+      end
+    end
+  end
+
+  def query_command(args)
+    manager = create_manager
+    session_id = args[0]
+    event_type = args[1]
+    
+    options = {}
+    options[:session_id] = session_id if session_id
+    options[:type] = event_type if event_type
+    
+    events = manager.query_events(options)
+    
+    puts "Query Results (#{events.length} events):"
+    puts "======================================"
+    events.each do |event|
+      puts "[#{event.timestamp}] #{event.type} from #{event.source_to_string}"
+      if @options[:verbose]
+        puts "  Data: #{event.data}"
+        puts "  ID: #{event.id}"
+        puts
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  cli = EventSystemCLI.new
+  cli.run(ARGV)
+end

data/lib/event_system/configuration.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module EventSystem
+  # Configuration class for the EventSystem
+  # Provides a centralized way to configure storage, logging, and other options
+  class Configuration
+    attr_accessor :storage_type, :storage_options, :logger, :session_id, :auto_flush
+
+    # Initialize a new configuration
+    def initialize
+      @storage_type = :memory
+      @storage_options = {}
+      @logger = nil
+      @session_id = nil
+      @auto_flush = true
+    end
+
+    # Get the storage class based on the configured type
+    # @return [Class] The storage class to use
+    def storage_class
+      case @storage_type
+      when :memory
+        Storage::MemoryStore
+      when :file
+        Storage::FileStore
+      else
+        raise ArgumentError, "Unknown storage type: #{@storage_type}. Available types: :memory, :file"
+      end
+    end
+
+    # Create a new storage instance with the current configuration
+    # @return [EventSystem::Storage::Base] A new storage instance
+    def create_storage
+      storage_class.new(*storage_constructor_args)
+    end
+
+    # Get the logger instance, creating a default one if none is set
+    # @return [Logger] The logger instance
+    def logger
+      @logger ||= create_default_logger
+    end
+
+    # Set the logger
+    # @param logger [Logger] The logger to use
+    def logger=(logger)
+      @logger = logger
+    end
+
+    # Get the current session ID, creating one if none is set
+    # @return [String] The current session ID
+    def session_id
+      @session_id ||= Time.now.strftime("%Y%m%d_%H%M%S")
+    end
+
+    # Set the session ID
+    # @param session_id [String] The session ID to use
+    def session_id=(session_id)
+      @session_id = session_id
+    end
+
+    # Reset the configuration to defaults
+    # @return [void]
+    def reset!
+      @storage_type = :memory
+      @storage_options = {}
+      @logger = nil
+      @session_id = nil
+      @auto_flush = true
+    end
+
+    # Validate the current configuration
+    # @return [Boolean] True if configuration is valid
+    def valid?
+      return false unless [:memory, :file].include?(@storage_type)
+      return false if @storage_options.nil?
+
+      case @storage_type
+      when :file
+        directory = @storage_options[:directory] || @storage_options['directory']
+        return false if directory.nil? || directory.empty?
+      end
+
+      true
+    end
+
+    # Get configuration as a hash
+    # @return [Hash] Configuration as a hash
+    def to_h
+      {
+        storage_type: @storage_type,
+        storage_options: @storage_options,
+        session_id: @session_id,
+        auto_flush: @auto_flush
+      }
+    end
+
+    private
+
+    # Get arguments for storage constructor
+    # @return [Array] Arguments for the storage constructor
+    def storage_constructor_args
+      case @storage_type
+      when :memory
+        [@session_id]
+      when :file
+        directory = @storage_options[:directory] || @storage_options['directory'] || "event_logs"
+        [directory, @session_id]
+      else
+        []
+      end
+    end
+
+    # Create a default logger
+    # @return [Logger] A default logger instance
+    def create_default_logger
+      require 'logger'
+      logger = Logger.new($stdout)
+      logger.level = Logger::INFO
+      logger.formatter = proc do |severity, datetime, progname, msg|
+        "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity}: #{msg}\n"
+      end
+      logger
+    end
+  end
+end

data/lib/event_system/event.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'securerandom'
+
+module EventSystem
+  # Base class for all events in the system
+  # Provides unique ID generation, timestamp handling, and serialization
+  class Event
+    attr_reader :id, :timestamp, :source, :type, :data
+
+    # Initialize a new event
+    # @param type [String, Symbol] The event type identifier
+    # @param source [Object] The source/originator of the event
+    # @param data [Hash] Additional event data
+    # @param id [String, nil] Optional event ID, generated if not provided
+    # @param timestamp [Time, String, nil] Optional timestamp, current time if not provided
+    def initialize(type, source = nil, data = {}, id = nil, timestamp = nil)
+      @id = id || SecureRandom.uuid
+      @type = type.to_s
+      @source = source
+      @data = data
+      @timestamp = parse_timestamp(timestamp)
+    end
+
+    # String representation of the event
+    # @return [String] Human-readable event string
+    def to_s
+      "[#{@timestamp}] #{@type}: #{@data.inspect}"
+    end
+
+    # Hash representation of the event
+    # @return [Hash] Event data as a hash
+    def to_h
+      {
+        id: @id,
+        type: @type,
+        source: source_to_string,
+        timestamp: @timestamp.iso8601(3),
+        data: safe_serialize(@data)
+      }
+    end
+
+    # JSON representation of the event
+    # @return [String] Event data as a JSON string
+    def to_json(*_args)
+      to_h.to_json
+    end
+
+    # Create an event from its JSON representation
+    # @param json [String] JSON representation of an event
+    # @return [Event] Reconstructed event
+    def self.from_json(json)
+      data = JSON.parse(json, symbolize_names: true)
+
+      new(
+        data[:type],
+        data[:source],
+        data[:data] || {},
+        data[:id],
+        data[:timestamp]
+      )
+    end
+
+    # Check if two events are equal (by ID)
+    # @param other [Event] The other event to compare
+    # @return [Boolean] True if events have the same ID
+    def ==(other)
+      other.is_a?(Event) && @id == other.id
+    end
+
+    # Hash code for the event (based on ID)
+    # @return [Integer] Hash code
+    def hash
+      @id.hash
+    end
+
+    # Check if the event is of a specific type
+    # @param event_type [String, Symbol] The event type to check
+    # @return [Boolean] True if the event matches the type
+    def type?(event_type)
+      @type == event_type.to_s
+    end
+
+    # Convert source to string representation
+    # @return [String] String representation of the source
+    def source_to_string
+      case @source
+      when nil
+        'unknown'
+      when String
+        @source
+      else
+        @source.to_s
+      end
+    end
+
+    private
+
+    # Parse timestamp from various formats
+    # @param timestamp [Time, String, nil] The timestamp to parse
+    # @return [Time] Parsed timestamp
+    def parse_timestamp(timestamp)
+      case timestamp
+      when Time
+        timestamp.utc
+      when String
+        Time.parse(timestamp).utc
+      when nil
+        Time.now.utc
+      else
+        raise ArgumentError, "Invalid timestamp type: #{timestamp.class}"
+      end
+    end
+
+    # Safely serialize data by handling non-serializable objects
+    # @param value [Object] The value to serialize
+    # @return [Object] A serializable version of the value
+    def safe_serialize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), h|
+          h[k] = safe_serialize(v)
+        end
+      when Array
+        value.map { |v| safe_serialize(v) }
+      when Numeric, String, true, false, nil
+        value
+      else
+        # For complex objects, convert to string representation
+        value.to_s
+      end
+    rescue
+      # If any error occurs during serialization, return a safe fallback
+      "#<#{value.class} - non-serializable>"
+    end
+  end
+end

data/lib/event_system/event_manager.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative 'event'
+require_relative 'event_subscriber'
+require_relative 'configuration'
+require_relative 'storage/base'
+require_relative 'storage/memory_store'
+require_relative 'storage/file_store'
+
+module EventSystem
+  # Central event management class that handles event publication and subscription
+  # Provides a complete event-driven architecture with pluggable storage backends
+  class EventManager
+    attr_reader :config, :storage
+
+    # Initialize a new event manager
+    # @param config [EventSystem::Configuration, Hash, nil] Configuration object, hash, or nil for defaults
+    def initialize(config = nil)
+      @config = case config
+                when Configuration
+                  config
+                when Hash
+                  Configuration.new.tap do |c|
+                    c.storage_type = config[:storage_type] || :memory
+                    c.storage_options = config[:storage_options] || {}
+                    c.logger = config[:logger]
+                    c.session_id = config[:session_id]
+                    c.auto_flush = config[:auto_flush] != false
+                  end
+                else
+                  Configuration.new
+                end
+
+      @subscribers = Hash.new { |h, k| h[k] = [] }
+      @storage = @config.create_storage
+      @logger = @config.logger
+
+      @logger.info("EventSystem initialized with #{@config.storage_type} storage")
+    end
+
+    # Subscribe to events of a specific type
+    # @param event_type [String, Symbol] The event type to subscribe to
+    # @param subscriber [Object] The subscriber that will handle the events
+    # @return [void]
+    def subscribe(event_type, subscriber)
+      event_type = event_type.to_s
+      @subscribers[event_type] << subscriber
+      @logger.debug("Subscribed #{subscriber.class} to #{event_type}")
+    end
+
+    # Unsubscribe from events of a specific type
+    # @param event_type [String, Symbol] The event type to unsubscribe from
+    # @param subscriber [Object] The subscriber to remove
+    # @return [void]
+    def unsubscribe(event_type, subscriber)
+      event_type = event_type.to_s
+      @subscribers[event_type].delete(subscriber)
+      @logger.debug("Unsubscribed #{subscriber.class} from #{event_type}")
+    end
+
+    # Subscribe to all event types
+    # @param subscriber [Object] The subscriber that will handle all events
+    # @return [void]
+    def subscribe_all(subscriber)
+      @subscribers[:all] << subscriber
+      @logger.debug("Subscribed #{subscriber.class} to all events")
+    end
+
+    # Unsubscribe from all event types
+    # @param subscriber [Object] The subscriber to remove
+    # @return [void]
+    def unsubscribe_all(subscriber)
+      @subscribers[:all].delete(subscriber)
+      @logger.debug("Unsubscribed #{subscriber.class} from all events")
+    end
+
+    # Publish an event to all subscribers
+    # @param event [EventSystem::Event] The event to publish
+    # @return [void]
+    def publish(event)
+      @logger.debug("Publishing event: #{event}")
+
+      # Store the event if storage is configured
+      @storage&.store(event)
+
+      # Deliver to type-specific subscribers
+      deliver_to_subscribers(event.type, event)
+
+      # Deliver to universal subscribers
+      deliver_to_subscribers(:all, event)
+    end
+
+    # Create and publish an event in one step
+    # @param type [String, Symbol] The event type
+    # @param source [Object] The source of the event
+    # @param data [Hash] Additional event data
+    # @return [EventSystem::Event] The published event
+    def publish_event(type, source = nil, data = {})
+      @logger.debug("Publishing event: #{type}, source: #{source}, data: #{data}")
+      event = Event.new(type, source, data)
+      publish(event)
+      event
+    end
+
+    # Query for events based on options
+    # @param options [Hash] Query options
+    # @return [Array<EventSystem::Event>] Matching events
+    def query_events(options = {})
+      @storage&.query(options) || []
+    end
+
+    # Get the current session ID
+    # @return [String, nil] The current session ID, or nil if no event store
+    def current_session
+      @storage&.current_session
+    end
+
+    # Switch to a different session
+    # @param session_id [String] The session ID to switch to
+    # @return [void]
+    def switch_session(session_id)
+      @storage&.switch_session(session_id)
+      @logger.info("Switched to session: #{session_id}")
+    end
+
+    # Create a new session
+    # @param session_id [String, nil] Optional session ID, defaults to timestamp
+    # @return [String] The new session ID
+    def create_session(session_id = nil)
+      session_id = @storage&.create_session(session_id) || session_id || Time.now.strftime("%Y%m%d_%H%M%S")
+      @logger.info("Created new session: #{session_id}")
+      session_id
+    end
+
+    # Get statistics about the event system
+    # @return [Hash] Statistics about the event system
+    def stats
+      {
+        subscribers: @subscribers.transform_values(&:length),
+        storage: @storage&.stats || {},
+        config: @config.to_h
+      }
+    end
+
+    # Close the event manager and release resources
+    # @return [void]
+    def close
+      @storage&.close
+      @logger.info("EventSystem closed")
+    end
+
+    # Check if the event manager is ready for use
+    # @return [Boolean] True if ready
+    def ready?
+      @storage&.available? || false
+    end
+
+    private
+
+    # Deliver an event to subscribers of a specific type
+    # @param event_type [String] The event type
+    # @param event [EventSystem::Event] The event to deliver
+    # @return [void]
+    def deliver_to_subscribers(event_type, event)
+      subscribers = @subscribers[event_type] || []
+      
+      # Sort subscribers by priority if they support it
+      sorted_subscribers = subscribers.sort_by do |subscriber|
+        if subscriber.respond_to?(:event_priority)
+          subscriber.event_priority
+        else
+          0
+        end
+      end
+
+      sorted_subscribers.each do |subscriber|
+        begin
+          # Check if subscriber handles this event type
+          if subscriber.respond_to?(:handles_event_type?) && !subscriber.handles_event_type?(event_type)
+            next
+          end
+
+          subscriber.handle_event(event)
+        rescue => e
+          @logger.error("Error in subscriber #{subscriber.class} handling #{event_type}: #{e.message}")
+          @logger.error(e.backtrace.join("\n"))
+        end
+      end
+    end
+  end
+end

data/lib/event_system/event_subscriber.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module EventSystem
+  # Interface for components that respond to events
+  # Classes including this module must implement the handle_event method
+  module EventSubscriber
+    # Handle an event that this subscriber is interested in
+    # @param event [EventSystem::Event] The event to handle
+    # @return [void]
+    def handle_event(event)
+      raise NotImplementedError, "#{self.class} must implement handle_event(event)"
+    end
+
+    # Check if this subscriber is interested in a specific event type
+    # Override this method to provide filtering logic
+    # @param event_type [String] The event type to check
+    # @return [Boolean] True if this subscriber handles the event type
+    def handles_event_type?(event_type)
+      true # Default: handle all event types
+    end
+
+    # Get the priority for this subscriber (lower numbers = higher priority)
+    # Override this method to control event handling order
+    # @return [Integer] Priority level (default: 0)
+    def event_priority
+      0
+    end
+  end
+end

data/lib/event_system/storage/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module EventSystem
+  module Storage
+    # Abstract base class for event storage implementations
+    # All concrete event store classes should implement these methods
+    class Base
+      # Store an event
+      # @param event [EventSystem::Event] The event to store
+      # @return [void]
+      def store(event)
+        raise NotImplementedError, "#{self.class} must implement store(event)"
+      end
+
+      # Query for events based on options
+      # @param options [Hash] Query options (type, time range, limit, etc.)
+      # @return [Array<EventSystem::Event>] Matching events
+      def query(options = {})
+        raise NotImplementedError, "#{self.class} must implement query(options)"
+      end
+
+      # Load all events from a session
+      # @param session_id [String, nil] Session ID to load, or current session if nil
+      # @return [Array<EventSystem::Event>] Events from the session
+      def load_session(session_id = nil)
+        raise NotImplementedError, "#{self.class} must implement load_session(session_id)"
+      end
+
+      # List available sessions
+      # @return [Array<String>] List of session IDs
+      def list_sessions
+        raise NotImplementedError, "#{self.class} must implement list_sessions"
+      end
+
+      # Get the current session ID
+      # @return [String, nil] Current session ID
+      def current_session
+        raise NotImplementedError, "#{self.class} must implement current_session"
+      end
+
+      # Close the event store and release resources
+      # @return [void]
+      def close
+        # Optional method, default implementation does nothing
+      end
+
+      # Check if the storage is available
+      # @return [Boolean] True if storage is ready for use
+      def available?
+        true
+      end
+
+      # Get storage statistics
+      # @return [Hash] Storage statistics
+      def stats
+        {
+          type: self.class.name,
+          available: available?,
+          sessions: list_sessions.length
+        }
+      end
+    end
+  end
+end