event_system 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd219cc35083def134eddfddc6a57c5220828d20132ad7fdd05f4417c34520b6
+  data.tar.gz: 12cae4ff290aecb243ccbda04f5302863f530bf427644c9b6ce22831069c505b
+SHA512:
+  metadata.gz: 29b5cd4b592288b6752f377fea9c6e0df8e616adf48edc36513abcb112444a0e9e319c4115ab9cf80f16fba4a25d638b2cdbb4bbbc2a24bcec97996d32d992ce
+  data.tar.gz: bda5cb72cd2c946fe0524b35bf8a845627a989c5f58e79fdcbfb6b4cc8b974552ea5db3ad83c71b1abe7d9aaa65700ad9a1cd96b0131edce7bc5ddeae7fdac9c

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/README.md

@@ -0,0 +1,362 @@
+# EventSystem
+
+A flexible, agnostic event system for Ruby applications. EventSystem provides event-driven architecture with pluggable storage backends, visualization tools, and comprehensive logging. Perfect for building decoupled, maintainable applications.
+
+## Features
+
+- 🎯 **Event-Driven Architecture**: Clean separation of concerns through events
+- 💾 **Pluggable Storage**: Memory, file, and extensible storage backends
+- 📊 **Visualization Tools**: HTML timeline generation for debugging
+- 🔧 **Flexible Configuration**: Easy setup and customization
+- 🚀 **High Performance**: Optimized for both development and production
+- 📝 **Comprehensive Logging**: Built-in logging with configurable levels
+- 🔍 **Event Querying**: Filter and search events by type, time, and more
+- 🎨 **Modern API**: Clean, intuitive Ruby API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'event_system'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install event_system
+```
+
+## Quick Start
+
+### Basic Usage
+
+```ruby
+require 'event_system'
+
+# Create an event manager
+manager = EventSystem.create_manager
+
+# Create and publish an event
+manager.publish_event(:user_created, self, { user_id: 123, name: "John Doe" })
+
+# Subscribe to events
+class UserNotifier
+  include EventSystem::EventSubscriber
+  
+  def handle_event(event)
+    puts "User event: #{event.type} - #{event.data}"
+  end
+end
+
+notifier = UserNotifier.new
+manager.subscribe(:user_created, notifier)
+```
+
+### Configuration
+
+```ruby
+# Configure with file storage
+config = {
+  storage_type: :file,
+  storage_options: { directory: "logs/events" },
+  session_id: "my_app_session"
+}
+
+manager = EventSystem.create_manager(config)
+
+# Or use memory storage for testing
+manager = EventSystem.create_manager(storage_type: :memory)
+```
+
+## Usage
+
+### Creating Events
+
+```ruby
+# Create an event manually
+event = EventSystem.create_event(:order_placed, self, {
+  order_id: 456,
+  customer_id: 789,
+  amount: 99.99
+})
+
+# Publish the event
+manager.publish(event)
+```
+
+### Event Subscribers
+
+```ruby
+class OrderProcessor
+  include EventSystem::EventSubscriber
+  
+  def handle_event(event)
+    case event.type
+    when 'order_placed'
+      process_order(event.data)
+    when 'payment_received'
+      fulfill_order(event.data)
+    end
+  end
+  
+  private
+  
+  def process_order(data)
+    puts "Processing order #{data[:order_id]}"
+  end
+  
+  def fulfill_order(data)
+    puts "Fulfilling order #{data[:order_id]}"
+  end
+end
+
+# Subscribe to specific events
+processor = OrderProcessor.new
+manager.subscribe(:order_placed, processor)
+manager.subscribe(:payment_received, processor)
+
+# Subscribe to all events
+manager.subscribe_all(processor)
+```
+
+### Event Querying
+
+```ruby
+# Query events by type
+orders = manager.query_events(type: 'order_placed')
+
+# Query events by time range
+recent_events = manager.query_events(
+  start_time: 1.hour.ago,
+  end_time: Time.now
+)
+
+# Query with limit
+last_10_events = manager.query_events(limit: 10)
+
+# Query from specific session
+session_events = manager.query_events(session_id: 'session_123')
+```
+
+### Storage Backends
+
+#### Memory Storage (Default)
+
+```ruby
+# Perfect for testing and development
+manager = EventSystem.create_manager(storage_type: :memory)
+
+# Switch sessions
+manager.switch_session('test_session_1')
+manager.publish_event(:test_event, self, { data: 'test' })
+
+# Create new session
+new_session = manager.create_session('my_new_session')
+```
+
+#### File Storage
+
+```ruby
+# Persistent storage to disk
+config = {
+  storage_type: :file,
+  storage_options: { directory: 'event_logs' }
+}
+manager = EventSystem.create_manager(config)
+
+# Events are automatically saved to JSONL files
+manager.publish_event(:user_action, self, { action: 'login' })
+```
+
+### Visualization
+
+```ruby
+# Generate HTML timeline visualization
+generator = EventSystem::Visualization::TimelineGenerator.new(manager.storage)
+html_file = generator.generate_timeline('session_123', 'timeline.html')
+
+# Get event summary
+summary = generator.event_summary('session_123')
+puts summary
+# => {"user_created" => 5, "order_placed" => 3, "payment_received" => 2}
+
+# Get timeline data for custom visualizations
+timeline_data = generator.timeline_data('session_123')
+```
+
+### CLI Tool
+
+The gem includes a command-line tool for managing events:
+
+```bash
+# Generate timeline visualization
+event_system visualize session_123 timeline.html
+
+# Show statistics
+event_system stats
+
+# List available sessions
+event_system list
+
+# Query events
+event_system query session_123 order_placed
+
+# Use file storage
+event_system -s file -d /path/to/logs visualize
+```
+
+### Advanced Configuration
+
+```ruby
+# Custom configuration
+config = EventSystem::Configuration.new
+config.storage_type = :file
+config.storage_options = { directory: 'custom_logs' }
+config.session_id = 'production_session'
+config.auto_flush = true
+
+# Custom logger
+require 'logger'
+config.logger = Logger.new('event_system.log')
+
+manager = EventSystem.create_manager(config)
+```
+
+### Error Handling
+
+```ruby
+# Subscribers with error handling
+class SafeSubscriber
+  include EventSystem::EventSubscriber
+  
+  def handle_event(event)
+    # Your event handling logic
+    process_event(event)
+  rescue => e
+    # Errors are automatically logged by the event manager
+    puts "Error processing event: #{e.message}"
+  end
+end
+```
+
+## API Reference
+
+### EventSystem Module
+
+- `EventSystem.create_manager(config = nil)` - Create a new event manager
+- `EventSystem.create_event(type, source = nil, data = {})` - Create a new event
+- `EventSystem.version` - Get the current version
+
+### EventManager Class
+
+- `#publish(event)` - Publish an event
+- `#publish_event(type, source = nil, data = {})` - Create and publish an event
+- `#subscribe(event_type, subscriber)` - Subscribe to specific event type
+- `#subscribe_all(subscriber)` - Subscribe to all events
+- `#unsubscribe(event_type, subscriber)` - Unsubscribe from event type
+- `#query_events(options = {})` - Query events with filters
+- `#switch_session(session_id)` - Switch to different session
+- `#create_session(session_id = nil)` - Create new session
+- `#stats` - Get system statistics
+- `#close` - Close the event manager
+
+### Event Class
+
+- `#id` - Unique event identifier
+- `#type` - Event type
+- `#source` - Event source
+- `#data` - Event data
+- `#timestamp` - Event timestamp
+- `#to_json` - JSON representation
+- `#to_h` - Hash representation
+- `Event.from_json(json)` - Create event from JSON
+
+### Storage Backends
+
+- `EventSystem::Storage::MemoryStore` - In-memory storage
+- `EventSystem::Storage::FileStore` - File-based storage
+- `EventSystem::Storage::Base` - Abstract base class for custom storage
+
+## Examples
+
+### Web Application
+
+```ruby
+class WebApp
+  def initialize
+    @event_manager = EventSystem.create_manager(
+      storage_type: :file,
+      storage_options: { directory: 'logs/events' }
+    )
+    
+    # Subscribe to web events
+    @event_manager.subscribe(:request_received, self)
+    @event_manager.subscribe(:response_sent, self)
+  end
+  
+  def handle_request(request)
+    @event_manager.publish_event(:request_received, self, {
+      path: request.path,
+      method: request.method,
+      ip: request.ip
+    })
+  end
+  
+  def handle_event(event)
+    # Log web events
+    puts "Web event: #{event.type} - #{event.data}"
+  end
+end
+```
+
+### Microservice Communication
+
+```ruby
+class OrderService
+  def initialize
+    @event_manager = EventSystem.create_manager
+    @event_manager.subscribe(:payment_processed, self)
+  end
+  
+  def place_order(order_data)
+    @event_manager.publish_event(:order_created, self, order_data)
+  end
+  
+  def handle_event(event)
+    if event.type == 'payment_processed'
+      fulfill_order(event.data[:order_id])
+    end
+  end
+end
+```
+
+### Testing
+
+```ruby
+RSpec.describe OrderService do
+  let(:event_manager) { EventSystem.create_manager(storage_type: :memory) }
+  let(:service) { OrderService.new(event_manager) }
+  
+  it 'publishes order created event' do
+    expect(event_manager).to receive(:publish_event).with(:order_created, service, anything)
+    service.place_order({ customer_id: 123 })
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/davidslv/event_system.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/docs/event_visualizations/example_timeline.html

@@ -0,0 +1,142 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Event Timeline - 20251027_151802</title>
+    <style>
+        body { font-family: Arial, sans-serif; margin: 20px; background-color: #f5f5f5; }
+        .container { max-width: 1200px; margin: 0 auto; background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); }
+        .header { text-align: center; margin-bottom: 30px; }
+        .stats { display: flex; justify-content: space-around; margin-bottom: 30px; padding: 20px; background: #f8f9fa; border-radius: 5px; }
+        .stat { text-align: center; }
+        .stat-number { font-size: 2em; font-weight: bold; color: #007bff; }
+        .stat-label { color: #666; }
+        .timeline { position: relative; }
+        .timeline-item { margin: 20px 0; padding: 15px; border-left: 4px solid #007bff; background: #f8f9fa; border-radius: 0 5px 5px 0; }
+        .timeline-item:hover { background: #e9ecef; }
+        .event-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }
+        .event-type { font-weight: bold; color: #007bff; font-size: 1.1em; }
+        .event-time { color: #666; font-size: 0.9em; }
+        .event-source { color: #28a745; font-weight: 500; }
+        .event-data { background: white; padding: 10px; border-radius: 3px; margin-top: 10px; font-family: monospace; font-size: 0.9em; }
+        .event-id { color: #6c757d; font-size: 0.8em; }
+        .filter-controls { margin-bottom: 20px; padding: 15px; background: #e9ecef; border-radius: 5px; }
+        .filter-controls input, .filter-controls select { margin: 0 10px; padding: 5px; }
+        .no-events { text-align: center; color: #666; font-style: italic; padding: 40px; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>Event Timeline</h1>
+            <p>Session: 20251027_151802</p>
+        </div>
+        
+        <div class="stats">
+            <div class="stat">
+                <div class="stat-number">3</div>
+                <div class="stat-label">Total Events</div>
+            </div>
+            <div class="stat">
+                <div class="stat-number">3</div>
+                <div class="stat-label">Event Types</div>
+            </div>
+            <div class="stat">
+                <div class="stat-number">3</div>
+                <div class="stat-label">Sources</div>
+            </div>
+        </div>
+
+        <div class="filter-controls">
+            <label>Filter by type:</label>
+            <select id="typeFilter">
+                <option value="">All Types</option>
+                <option value="user_created">user_created</option><option value="order_placed">order_placed</option><option value="payment_received">payment_received</option>
+            </select>
+            <label>Search:</label>
+            <input type="text" id="searchFilter" placeholder="Search events...">
+        </div>
+
+        <div class="timeline" id="timeline">
+            <div class="timeline-item">
+    <div class="event-header">
+        <span class="event-type">user_created</span>
+        <span class="event-time">2025-10-27 15:18:02.333</span>
+    </div>
+    <div class="event-source">Source: UserService</div>
+    <div class="event-data">{
+  "user_id": 123,
+  "name": "John Doe"
+}</div>
+    <div class="event-id">ID: ac90fa0e-e1c1-4904-862c-c23f248a4bd0</div>
+</div>
+<div class="timeline-item">
+    <div class="event-header">
+        <span class="event-type">order_placed</span>
+        <span class="event-time">2025-10-27 15:18:02.333</span>
+    </div>
+    <div class="event-source">Source: OrderService</div>
+    <div class="event-data">{
+  "order_id": 456,
+  "amount": 99.99
+}</div>
+    <div class="event-id">ID: c118793c-d13d-4b5a-996b-d81ffefe3ce1</div>
+</div>
+<div class="timeline-item">
+    <div class="event-header">
+        <span class="event-type">payment_received</span>
+        <span class="event-time">2025-10-27 15:18:02.333</span>
+    </div>
+    <div class="event-source">Source: PaymentService</div>
+    <div class="event-data">{
+  "payment_id": 789,
+  "amount": 99.99
+}</div>
+    <div class="event-id">ID: 7aa9eafb-b029-4c4c-8bb0-7e39c9a18a2e</div>
+</div>
+
+        </div>
+    </div>
+
+    <script>
+        const events = [{"id":"ac90fa0e-e1c1-4904-862c-c23f248a4bd0","type":"user_created","timestamp":"2025-10-27T15:18:02.333Z","source":"UserService","data":{"user_id":123,"name":"John Doe"}},{"id":"c118793c-d13d-4b5a-996b-d81ffefe3ce1","type":"order_placed","timestamp":"2025-10-27T15:18:02.333Z","source":"OrderService","data":{"order_id":456,"amount":99.99}},{"id":"7aa9eafb-b029-4c4c-8bb0-7e39c9a18a2e","type":"payment_received","timestamp":"2025-10-27T15:18:02.333Z","source":"PaymentService","data":{"payment_id":789,"amount":99.99}}];
+        
+        function filterEvents() {
+            const typeFilter = document.getElementById('typeFilter').value;
+            const searchFilter = document.getElementById('searchFilter').value.toLowerCase();
+            const timeline = document.getElementById('timeline');
+            
+            const filteredEvents = events.filter(event => {
+                const typeMatch = !typeFilter || event.type === typeFilter;
+                const searchMatch = !searchFilter || 
+                    event.type.toLowerCase().includes(searchFilter) ||
+                    event.source.toLowerCase().includes(searchFilter) ||
+                    JSON.stringify(event.data).toLowerCase().includes(searchFilter);
+                return typeMatch && searchMatch;
+            });
+            
+            timeline.innerHTML = filteredEvents.length === 0 ? 
+                '<div class="no-events">No events match the current filters</div>' :
+                filteredEvents.map(event => generateEventHTML(event)).join('');
+        }
+        
+        function generateEventHTML(event) {
+            return `
+                <div class="timeline-item">
+                    <div class="event-header">
+                        <span class="event-type">${event.type}</span>
+                        <span class="event-time">${new Date(event.timestamp).toLocaleString()}</span>
+                    </div>
+                    <div class="event-source">Source: ${event.source}</div>
+                    <div class="event-data">${JSON.stringify(event.data, null, 2)}</div>
+                    <div class="event-id">ID: ${event.id}</div>
+                </div>
+            `;
+        }
+        
+        document.getElementById('typeFilter').addEventListener('change', filterEvents);
+        document.getElementById('searchFilter').addEventListener('input', filterEvents);
+    </script>
+</body>
+</html>

data/docs/example_logs/events_20251027_151744.jsonl

@@ -0,0 +1,3 @@
+{"id":"3f914a9e-e799-49b3-869f-17ce78f03aa9","type":"user_created","source":"UserService","timestamp":"2025-10-27T15:17:44.021Z","data":{"user_id":123,"name":"John Doe"}}
+{"id":"b26e2fa2-1d51-46b2-82f4-5fee6b308530","type":"order_placed","source":"OrderService","timestamp":"2025-10-27T15:17:44.022Z","data":{"order_id":456,"amount":99.99}}
+{"id":"4ede7100-a47d-4f57-8dca-9741c33f67fc","type":"payment_received","source":"PaymentService","timestamp":"2025-10-27T15:17:44.022Z","data":{"payment_id":789,"amount":99.99}}

data/docs/example_logs/events_20251027_151802.jsonl

@@ -0,0 +1,3 @@
+{"id":"ac90fa0e-e1c1-4904-862c-c23f248a4bd0","type":"user_created","source":"UserService","timestamp":"2025-10-27T15:18:02.333Z","data":{"user_id":123,"name":"John Doe"}}
+{"id":"c118793c-d13d-4b5a-996b-d81ffefe3ce1","type":"order_placed","source":"OrderService","timestamp":"2025-10-27T15:18:02.333Z","data":{"order_id":456,"amount":99.99}}
+{"id":"7aa9eafb-b029-4c4c-8bb0-7e39c9a18a2e","type":"payment_received","source":"PaymentService","timestamp":"2025-10-27T15:18:02.333Z","data":{"payment_id":789,"amount":99.99}}

data/docs/examples/basic_usage.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/event_system'
+
+puts "EventSystem Basic Usage Example"
+puts "==============================="
+
+# Create an event manager with file storage
+config = {
+  storage_type: :file,
+  storage_options: { directory: 'example_logs' }
+}
+manager = EventSystem.create_manager(config)
+
+# Create a simple subscriber
+class ExampleSubscriber
+  include EventSystem::EventSubscriber
+  
+  def initialize(name)
+    @name = name
+  end
+  
+  def handle_event(event)
+    puts "[#{@name}] Received: #{event.type} - #{event.data}"
+  end
+end
+
+# Create subscribers
+subscriber1 = ExampleSubscriber.new("Subscriber 1")
+subscriber2 = ExampleSubscriber.new("Subscriber 2")
+
+# Subscribe to events
+manager.subscribe(:user_created, subscriber1)
+manager.subscribe(:order_placed, subscriber2)
+manager.subscribe_all(subscriber1) # This will receive all events
+
+# Publish some events
+puts "\nPublishing events..."
+manager.publish_event(:user_created, "UserService", { user_id: 123, name: "John Doe" })
+manager.publish_event(:order_placed, "OrderService", { order_id: 456, amount: 99.99 })
+manager.publish_event(:payment_received, "PaymentService", { payment_id: 789, amount: 99.99 })
+
+# Query events
+puts "\nQuerying events..."
+orders = manager.query_events(type: 'order_placed')
+puts "Found #{orders.length} order events"
+
+# Generate timeline visualization
+puts "\nGenerating timeline visualization..."
+generator = EventSystem::Visualization::TimelineGenerator.new(manager.storage)
+timeline_file = generator.generate_timeline(nil, 'example_timeline.html')
+puts "Timeline saved to: #{timeline_file}"
+
+# Show statistics
+puts "\nEvent System Statistics:"
+stats = manager.stats
+puts "Storage type: #{stats[:storage][:type]}"
+puts "Total sessions: #{stats[:storage][:sessions]}"
+puts "Subscribers: #{stats[:subscribers].values.sum}"
+
+# Clean up
+manager.close
+puts "\nExample completed!"