active_subscriber 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '08f3097b061295b4d01fdc6d527cb57c3305abcffd7e0b1a24c8b4124327e3a3'
+  data.tar.gz: c844b38c89b0c48b8b7be6ba25d943f86a8d6210505ffb8193a0dbb2f1c5fce4
+SHA512:
+  metadata.gz: d554add5eef74326f58c6fc244db11b07ebb069f196b84c8ce54d9fa6a69df101eccb3f486a036ac63beff055e02ad7a83d5510903814202b893f2ab2c415762
+  data.tar.gz: dc184ec881bbd3d4d84b0d1fe502628342779a0359de9f40e98268e858650408fef234a83546504216fe58c685ec96e4815283021754ccf74cf0098d9eadaac5

data/.rspec

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

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-06-03
+
+### Added
+
+- Initial release of ActiveSubscriber
+- Publisher module for publishing events using ActiveSupport::Notifications
+- Base subscriber class with DSL for event subscription
+- Support for specific event subscription and pattern matching
+- Lifecycle callbacks (before, after, around)
+- Rails engine integration with automatic subscriber loading
+- AnalyticsHelper for controllers
+- Generators for installation and subscriber creation
+- Configuration system with minimal options
+- Thread-safe subscriber registry
+- Automatic method dispatch based on event names
+- Error handling and logging
+- Comprehensive documentation and examples
+
+### Features
+
+- Auto-loading of subscribers from `app/subscribers/` directory
+- Support for custom subscriber paths
+- Event filtering capabilities
+- Timing wrapper methods for performance tracking
+- Rails integration with proper autoloading and reloading
+- Generator templates for easy setup

data/DEVELOPMENT_PLAN.md

@@ -0,0 +1,275 @@
+# ActiveSubscriber Gem Development Plan
+
+## Overview
+
+Building a Rails engine that implements a pub/sub pattern using ActiveSupport Notifications, providing a clean interface for event publishing and subscribing with automatic subscriber discovery and minimal configuration.
+
+## Architecture Design
+
+```mermaid
+graph TB
+    A[Rails Application] --> B[ActiveSubscriber Engine]
+    B --> C[Publisher Module]
+    B --> D[Base Subscriber Class]
+    B --> E[Helper Modules]
+    B --> F[Auto-loader]
+    B --> G[Configuration]
+
+    C --> H[ActiveSupport::Notifications]
+    D --> H
+    F --> I[app/subscribers/]
+    F --> J[Custom Paths]
+
+    K[Controllers] --> E
+    L[Services] --> C
+    M[Subscribers] --> D
+```
+
+## Gem Structure
+
+```
+active_subscriber/
+├── lib/
+│   ├── active_subscriber.rb                 # Main entry point
+│   ├── active_subscriber/
+│   │   ├── engine.rb                       # Rails engine
+│   │   ├── version.rb                      # Version constant
+│   │   ├── configuration.rb                # Configuration class
+│   │   ├── publisher.rb                    # Publisher module
+│   │   ├── base.rb                         # Base subscriber class
+│   │   ├── registry.rb                     # Subscriber registry
+│   │   ├── loader.rb                       # Auto-loader
+│   │   └── helpers/
+│   │       └── analytics_helper.rb         # Controller helper
+│   └── generators/
+│       └── active_subscriber/
+│           ├── install_generator.rb        # Installation generator
+│           └── subscriber_generator.rb     # Subscriber generator
+├── app/
+│   └── subscribers/                        # Default subscriber location
+├── config/
+│   └── initializers/
+│       └── active_subscriber.rb            # Default configuration
+├── active_subscriber.gemspec
+├── Gemfile
+├── README.md
+└── spec/                                   # Test suite
+```
+
+## Core Components
+
+### 1. Engine Setup (`lib/active_subscriber/engine.rb`)
+
+- Rails engine that integrates with Rails application lifecycle
+- Handles auto-loading of subscribers from `app/subscribers/`
+- Sets up initializers and configuration
+
+### 2. Publisher Module (`lib/active_subscriber/publisher.rb`)
+
+- Provides `publish_event` method
+- Wraps ActiveSupport::Notifications.instrument
+- Handles event naming conventions and context passing
+
+### 3. Base Subscriber Class (`lib/active_subscriber/base.rb`)
+
+- DSL for subscribing to events (`subscribe_to`, `subscribe_to_pattern`)
+- Lifecycle callbacks (`before_handle_event`, `after_handle_event`, `around_handle_event`)
+- Automatic method dispatch based on event names
+- Pattern matching support for wildcard subscriptions
+
+### 4. Registry System (`lib/active_subscriber/registry.rb`)
+
+- Tracks all registered subscribers
+- Manages event subscriptions
+- Handles subscriber lifecycle
+
+### 5. Auto-loader (`lib/active_subscriber/loader.rb`)
+
+- Scans `app/subscribers/` directory
+- Loads subscriber classes automatically
+- Supports custom paths through configuration
+
+### 6. Configuration (`lib/active_subscriber/configuration.rb`)
+
+- Enable/disable functionality
+- Basic event filtering
+- Custom subscriber paths
+- Minimal, focused options
+
+## Implementation Plan
+
+### Phase 1: Core Infrastructure
+
+1. **Gem Setup**
+
+   - Create gemspec with Rails engine dependencies
+   - Set up basic file structure
+   - Configure RSpec for testing
+
+2. **Engine Foundation**
+
+   - Implement Rails engine class
+   - Set up auto-loading hooks
+   - Create basic configuration system
+
+3. **Publisher Module**
+   - Implement event publishing interface
+   - Add context handling
+   - Create timing wrapper methods
+
+### Phase 2: Subscriber System
+
+1. **Base Subscriber Class**
+
+   - Implement DSL for event subscription
+   - Add method dispatch logic
+   - Create lifecycle callback system
+
+2. **Registry and Auto-loading**
+
+   - Build subscriber registry
+   - Implement auto-discovery from `app/subscribers/`
+   - Add support for custom paths
+
+3. **Pattern Matching**
+   - Implement regex-based event matching
+   - Handle wildcard subscriptions
+   - Optimize performance for pattern matching
+
+### Phase 3: Rails Integration
+
+1. **Helper Modules**
+
+   - Create AnalyticsHelper for controllers
+   - Add convenience methods for common patterns
+   - Integrate with Rails request lifecycle
+
+2. **Generators**
+
+   - Install generator for initial setup
+   - Subscriber generator for creating new subscribers
+   - Configuration templates
+
+3. **Initializers**
+   - Default configuration setup
+   - Auto-loading initialization
+   - Integration with Rails boot process
+
+### Phase 4: Testing and Documentation
+
+1. **Comprehensive Test Suite**
+
+   - Unit tests for all components
+   - Integration tests with Rails
+   - Performance benchmarks
+
+2. **Documentation**
+   - README with usage examples
+   - API documentation
+   - Rails integration guide
+
+## Key Features
+
+### Event Publishing
+
+```ruby
+class AnalyticsService
+  include ActiveSubscriber::Publisher
+
+  def self.track_analytics(event_name, properties = {}, context: analytics_context)
+    publish_event(event_name, properties, context)
+  end
+end
+```
+
+### Subscriber Definition
+
+```ruby
+class LoggingSubscriber < ActiveSubscriber::Base
+  subscribe_to :user_signed_in, :user_signed_up
+  subscribe_to_pattern "analytics.*"
+
+  after_handle_event :increment_stats
+
+  def handle_user_signed_in(context)
+    # Automatic method dispatch
+  end
+
+  def handle_all_events(event_name, context)
+    # Pattern-matched events
+  end
+end
+```
+
+### Controller Integration
+
+```ruby
+class PostController < ApplicationController
+  include ActiveSubscriber::Helpers::AnalyticsHelper
+
+  def index
+    @posts = Post.all
+    track_analytics("posts.viewed", { count: @posts.count })
+  end
+end
+```
+
+## Configuration Options
+
+```ruby
+ActiveSubscriber.configure do |config|
+  config.enabled = true
+  config.subscriber_paths = ["app/subscribers", "lib/subscribers"]
+  config.event_filter = ->(event_name) { !event_name.start_with?("internal.") }
+  config.auto_load = true
+end
+```
+
+## Installation and Setup
+
+1. **Gem Installation**
+
+   ```ruby
+   # Gemfile
+   gem 'active_subscriber'
+   ```
+
+2. **Generator Usage**
+
+   ```bash
+   rails generate active_subscriber:install
+   rails generate active_subscriber:subscriber Analytics
+   ```
+
+3. **Manual Setup**
+   - Subscribers auto-loaded from `app/subscribers/`
+   - Include modules where needed
+   - Configure through initializer if customization needed
+
+## Technical Considerations
+
+### Performance
+
+- Lazy loading of subscribers to minimize boot time impact
+- Efficient pattern matching using compiled regex
+- Minimal overhead for event publishing
+
+### Error Handling
+
+- Graceful degradation when subscribers fail
+- Configurable error handling strategies
+- Logging of subscription and event processing errors
+
+### Thread Safety
+
+- Thread-safe subscriber registry
+- Proper handling of concurrent event processing
+- No shared mutable state in core components
+
+### Rails Integration
+
+- Respect Rails autoloading and reloading in development
+- Integration with Rails logging system
+- Proper cleanup during application shutdown
+
+This plan provides a solid foundation for building a Rails-integrated pub/sub system that's easy to use, well-integrated with Rails conventions, and focused on the core functionality outlined in the requirements.

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in active_subscriber.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'rspec-rails', '~> 5.0'
+gem 'rubocop', '~> 1.21'
+gem 'rubocop-rails', '~> 2.0'
+gem 'rubocop-rspec', '~> 2.0'
+
+# For testing with Rails
+gem 'rails', '>= 8.0'
+gem 'sqlite3', '>= 1.4'

data/Gemfile.lock

@@ -0,0 +1,304 @@
+PATH
+  remote: .
+  specs:
+    active_subscriber (0.1.0)
+      activesupport (>= 6.0)
+      rails (>= 6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+    actionmailer (8.0.2)
+      actionpack (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.0.2)
+      actionview (= 8.0.2)
+      activesupport (= 8.0.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.0.2)
+      actionpack (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.0.2)
+      activesupport (= 8.0.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.3.6)
+    activemodel (8.0.2)
+      activesupport (= 8.0.2)
+    activerecord (8.0.2)
+      activemodel (= 8.0.2)
+      activesupport (= 8.0.2)
+      timeout (>= 0.4.0)
+    activestorage (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activesupport (= 8.0.2)
+      marcel (~> 1.0)
+    activesupport (8.0.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.1)
+    builder (3.3.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.3)
+    crass (1.0.6)
+    date (3.4.1)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    erb (5.0.1)
+    erubi (1.13.1)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.12.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    mini_mime (1.1.5)
+    minitest (5.27.0)
+    net-imap (0.5.8)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.19.0-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.0-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.0-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.0-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.0-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-linux-musl)
+      racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
+    rack (3.1.15)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (8.0.2)
+      actioncable (= 8.0.2)
+      actionmailbox (= 8.0.2)
+      actionmailer (= 8.0.2)
+      actionpack (= 8.0.2)
+      actiontext (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activemodel (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      bundler (>= 1.15.0)
+      railties (= 8.0.2)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rdoc (6.14.0)
+      erb
+      psych (>= 4.0.0)
+    regexp_parser (2.10.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.4)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-rails (5.1.2)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
+      railties (>= 5.2)
+      rspec-core (~> 3.10)
+      rspec-expectations (~> 3.10)
+      rspec-mocks (~> 3.10)
+      rspec-support (~> 3.10)
+    rspec-support (3.13.4)
+    rubocop (1.75.8)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.45.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.27.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rails (2.32.0)
+      activesupport (>= 4.2.0)
+      lint_roller (~> 1.1)
+      rack (>= 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+    rubocop-rspec (2.31.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    sqlite3 (2.9.0-aarch64-linux-gnu)
+    sqlite3 (2.9.0-aarch64-linux-musl)
+    sqlite3 (2.9.0-arm-linux-gnu)
+    sqlite3 (2.9.0-arm-linux-musl)
+    sqlite3 (2.9.0-arm64-darwin)
+    sqlite3 (2.9.0-x86_64-darwin)
+    sqlite3 (2.9.0-x86_64-linux-gnu)
+    sqlite3 (2.9.0-x86_64-linux-musl)
+    stringio (3.1.7)
+    thor (1.3.2)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.2.0)
+    uri (1.0.3)
+    useragent (0.16.11)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  active_subscriber!
+  rails (>= 8.0)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rspec-rails (~> 5.0)
+  rubocop (~> 1.21)
+  rubocop-rails (~> 2.0)
+  rubocop-rspec (~> 2.0)
+  sqlite3 (>= 1.4)
+
+BUNDLED WITH
+   2.6.2