active_subscriber 0.1.0

data/INSTALLATION_GUIDE.md

@@ -0,0 +1,193 @@
+# ActiveSubscriber Installation Guide for Rails Apps
+
+## Step 1: Add to Gemfile
+
+Add this line to your Rails application's Gemfile:
+
+```ruby
+# If you're testing locally, use the path to this gem
+gem 'active_subscriber', path: '/path/to/active_subscriber'
+
+# Or if you've published it to a git repository
+# gem 'active_subscriber', git: 'https://github.com/afomera/active_subscriber.git'
+```
+
+## Step 2: Bundle Install
+
+```bash
+bundle install
+```
+
+## Step 3: Run the Install Generator
+
+```bash
+rails generate active_subscriber:install
+```
+
+This will create:
+
+- `config/initializers/active_subscriber.rb` - Configuration file
+- `app/subscribers/` directory - Where your subscribers go
+
+## Step 4: Test the Installation
+
+### Option A: Use the Rails Console Test Script
+
+1. Copy the contents of `rails_console_test.rb`
+2. Open your Rails console: `rails console`
+3. Paste and run the test script
+
+### Option B: Manual Testing
+
+In your Rails console:
+
+```ruby
+# 1. Check if ActiveSubscriber is loaded
+ActiveSubscriber::VERSION
+
+# 2. Create a test subscriber
+class MyTestSubscriber < ActiveSubscriber::Base
+  subscribe_to :my_test_event
+
+  def handle_my_test_event(data)
+    puts "Received event: #{data}"
+  end
+end
+
+# 3. Register it
+ActiveSubscriber.registry.register(MyTestSubscriber)
+
+# 4. Create a publisher
+class MyPublisher
+  include ActiveSubscriber::Publisher
+end
+
+# 5. Publish an event
+MyPublisher.publish_event("my_test_event", { message: "Hello!" })
+```
+
+## Step 5: Create Your First Real Subscriber
+
+```bash
+rails generate active_subscriber:subscriber Analytics --events user_signed_in user_signed_up
+```
+
+This creates `app/subscribers/analytics_subscriber.rb`
+
+## Step 6: Use in Your Application
+
+### In a Service:
+
+```ruby
+class UserService
+  include ActiveSubscriber::Publisher
+
+  def sign_in_user(user)
+    # ... sign in logic ...
+    publish_event("user_signed_in", { user_id: user.id })
+  end
+end
+```
+
+### In a Controller:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ActiveSubscriber::Helpers::AnalyticsHelper
+end
+
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+    track_analytics("post.viewed", { post_id: @post.id })
+  end
+end
+```
+
+## Troubleshooting
+
+### Issue: Events not being received
+
+1. **Check if ActiveSubscriber is enabled:**
+
+   ```ruby
+   ActiveSubscriber.enabled?
+   ```
+
+2. **Check if subscribers are registered:**
+
+   ```ruby
+   ActiveSubscriber.registry.subscribers
+   ```
+
+3. **Check ActiveSupport::Notifications directly:**
+
+   ```ruby
+   ActiveSupport::Notifications.instrument("test", { data: "test" })
+   ```
+
+4. **Check Rails logs** for any error messages
+
+### Issue: Subscribers not auto-loading
+
+1. **Check configuration:**
+
+   ```ruby
+   ActiveSubscriber.configuration.auto_load
+   ActiveSubscriber.configuration.subscriber_paths
+   ```
+
+2. **Manually load subscribers:**
+
+   ```ruby
+   ActiveSubscriber.loader.load_subscribers
+   ```
+
+3. **Check if files exist:**
+   ```ruby
+   Dir.glob(Rails.root.join("app/subscribers/**/*.rb"))
+   ```
+
+### Issue: Rails engine not loading
+
+1. **Check if the engine is loaded:**
+
+   ```ruby
+   Rails.application.railties.map(&:class)
+   ```
+
+2. **Manually require the engine:**
+   ```ruby
+   require 'active_subscriber/engine'
+   ```
+
+## Configuration Options
+
+In `config/initializers/active_subscriber.rb`:
+
+```ruby
+ActiveSubscriber.configure do |config|
+  # Enable/disable the entire system
+  config.enabled = true
+
+  # Paths to look for subscribers
+  config.subscriber_paths = ["app/subscribers", "lib/subscribers"]
+
+  # Filter events (optional)
+  config.event_filter = ->(event_name) {
+    !event_name.start_with?("internal.")
+  }
+
+  # Auto-load subscribers on startup
+  config.auto_load = true
+end
+```
+
+## Next Steps
+
+1. Run the test script to verify everything works
+2. Create your first subscriber using the generator
+3. Start publishing events from your services/controllers
+4. Monitor Rails logs to see events being processed
+
+If you encounter any issues, run the Rails console test script first to diagnose the problem.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Andrea Fomera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,287 @@
+# ActiveSubscriber
+
+ActiveSubscriber provides a clean interface for implementing the publisher-subscriber pattern in Rails applications using ActiveSupport Notifications, with automatic subscriber discovery and lifecycle callbacks.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_subscriber'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install active_subscriber
+```
+
+## Quick Start
+
+1. **Install ActiveSubscriber:**
+
+```bash
+rails generate active_subscriber:install
+```
+
+2. **Create a subscriber:**
+
+```bash
+rails generate active_subscriber:subscriber Analytics --events user_signed_in user_signed_up
+```
+
+3. **Include the Publisher module in your services:**
+
+```ruby
+class AnalyticsService
+  include ActiveSubscriber::Publisher
+
+  def self.track_analytics(event_name, properties = {}, context: analytics_context)
+    publish_event(event_name, properties, context)
+  end
+
+  def self.track_analytics_with_timing(event_name, properties = {}, context = {}, &block)
+    publish_event_with_timing(event_name, properties, context, &block)
+  end
+end
+```
+
+4. **Include the helper in your controllers:**
+
+```ruby
+class PostController < ApplicationController
+  include ActiveSubscriber::Helpers::AnalyticsHelper
+
+  def index
+    @posts = Post.all
+    track_analytics("posts.viewed", { count: @posts.count })
+  end
+end
+```
+
+## Usage
+
+### Creating Subscribers
+
+Subscribers inherit from `ActiveSubscriber::Base` and can subscribe to specific events or event patterns:
+
+```ruby
+class LoggingSubscriber < ActiveSubscriber::Base
+  subscribe_to :user_signed_in, :user_signed_up
+  subscribe_to_pattern "analytics.*"
+
+  # Lifecycle callbacks
+  after_handle_event :increment_stats
+  around_handle_event :with_timing
+  before_handle_event :setup_context
+
+  def handle_user_signed_in(data)
+    Rails.logger.info "User signed in: #{data[:payload][:user_id]}"
+  end
+
+  def handle_user_signed_up(data)
+    Rails.logger.info "New user signed up: #{data[:payload][:user_id]}"
+  end
+
+  def handle_all_events(event_name, data)
+    Rails.logger.info "Analytics event: #{event_name}"
+  end
+
+  private
+
+  def increment_stats
+    # Called after handling any event
+  end
+
+  def with_timing
+    start_time = Time.current
+    yield
+    duration = Time.current - start_time
+    Rails.logger.debug "Event handled in #{duration * 1000}ms"
+  end
+
+  def setup_context
+    # Called before handling any event
+  end
+end
+```
+
+### Publishing Events
+
+#### Using the Publisher Module
+
+```ruby
+class UserService
+  include ActiveSubscriber::Publisher
+
+  def sign_in_user(user)
+    # ... sign in logic ...
+
+    publish_event("user_signed_in", { user_id: user.id }, { ip: request.ip })
+  end
+
+  def create_user(params)
+    result = publish_event_with_timing("user_creation", { email: params[:email] }) do
+      User.create!(params)
+    end
+
+    publish_event("user_signed_up", { user_id: result.id })
+    result
+  end
+end
+```
+
+#### Using the Analytics Helper
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ActiveSubscriber::Helpers::AnalyticsHelper
+
+  def show
+    @post = Post.find(params[:id])
+    track_analytics("post.viewed", {
+      post_id: @post.id,
+      category: @post.category
+    })
+  end
+end
+```
+
+### Event Data Structure
+
+Events published through ActiveSubscriber include:
+
+```ruby
+{
+  payload: { /* your custom data */ },
+  context: { /* additional context */ },
+  published_at: Time.current,
+  publisher: "YourServiceClass"
+}
+```
+
+When using the analytics helper, additional context is automatically added:
+
+```ruby
+{
+  controller: "posts",
+  action: "show",
+  user_id: current_user&.id,
+  user_agent: request.user_agent,
+  ip_address: request.remote_ip,
+  # ... more request context
+}
+```
+
+## Configuration
+
+Configure ActiveSubscriber in `config/initializers/active_subscriber.rb`:
+
+```ruby
+ActiveSubscriber.configure do |config|
+  # Enable or disable ActiveSubscriber (default: true)
+  config.enabled = true
+
+  # Namespace for Notification events
+  config.namespace = "my_app"
+
+  # Paths where subscribers are located (default: ["app/subscribers"])
+  config.subscriber_paths = ["app/subscribers", "lib/subscribers"]
+
+  # Filter events (optional)
+  config.event_filter = ->(event_name) { !event_name.start_with?("internal.") }
+
+  # Auto-load subscribers (default: true)
+  config.auto_load = true
+end
+```
+
+## Lifecycle Callbacks
+
+Subscribers support three types of lifecycle callbacks:
+
+- `before_handle_event` - Called before handling any event
+- `after_handle_event` - Called after handling any event
+- `around_handle_event` - Wraps the event handling (must yield)
+
+```ruby
+class TimingSubscriber < ActiveSubscriber::Base
+  subscribe_to_pattern ".*"
+
+  around_handle_event :with_timing
+  after_handle_event :log_completion
+
+  def handle_all_events(event_name, data)
+    # Handle the event
+  end
+
+  private
+
+  def with_timing
+    start_time = Time.current
+    yield
+    @duration = Time.current - start_time
+  end
+
+  def log_completion
+    Rails.logger.info "Event completed in #{@duration * 1000}ms"
+  end
+end
+```
+
+## Pattern Matching
+
+Subscribe to events using patterns with wildcards:
+
+```ruby
+class PatternSubscriber < ActiveSubscriber::Base
+  subscribe_to_pattern "user.*"        # Matches user.created, user.updated, etc.
+  subscribe_to_pattern "analytics.*"   # Matches analytics.page_view, analytics.click, etc.
+  subscribe_to_pattern ".*"            # Matches all events
+
+  def handle_all_events(event_name, data)
+    case event_name
+    when /^user\./
+      handle_user_event(event_name, data)
+    when /^analytics\./
+      handle_analytics_event(event_name, data)
+    end
+  end
+end
+```
+
+## Error Handling
+
+ActiveSubscriber includes built-in error handling. If a subscriber raises an exception, it will be logged but won't prevent other subscribers from processing the event.
+
+Errors are logged to `Rails.logger` with the format:
+
+```
+ActiveSubscriber: Error handling event 'event_name': Error message
+```
+
+## Thread Safety
+
+ActiveSubscriber is designed to be thread-safe:
+
+- The subscriber registry uses a mutex for thread-safe registration
+- No shared mutable state in core components
+- Each subscriber instance handles events independently
+
+## Acknowledgements
+
+This gem was inspired by a project at a previous role that needed a clean way to handle pub/sub notifications for third-party analytics. ActiveSubscriber is written entirely on personal time and resources, but the design is heavily informed by the needs of that work — along with my own.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/afomera/active_subscriber.

data/REQUIREMENTS.md

@@ -0,0 +1,60 @@
+# ActiveSubscriber requirements
+
+Implement pub/sub pattern with ActiveSupport Notifications for apps to implement Subscribers to handle event logic.
+
+So ideally..
+
+```ruby
+class AnalyticsService
+  include ActiveSubscriber::Publisher
+
+  def self.track_analytics(event_name, properties = {}, context: analytics_context)
+    publish_event(event_name, properties, context)
+  end
+
+  def self.track_analytics_with_timing(event_name, properties..., &block)
+    # ...
+  end
+end
+```
+
+```ruby
+class PostController
+  include AnalyticsHelper
+
+  def index
+    @post = Post.all
+    track_analytics("viewed_post", { post_id: @post.id })
+  end
+end
+```
+
+```ruby
+# app/subscribers/logging_subscriber.rb
+class LoggingSubscriber < ActiveSubscriber::Base
+  subscribe_to :user_signed_in, :user_signed_up
+  subscribe_to_pattern ".*"
+
+  after_handle_event :increment_stats
+  around_handle_event :....
+  before_handle_event :....
+
+  def handle_user_signed_in(context)
+    # called only on user_signed_in event automatically if it responds to it
+  end
+
+  def handle_all_events(event_name, context)
+    # called for all events
+  end
+
+  private
+
+  def increment_stats
+    puts "Increment stats counter"
+  end
+end
+```
+
+There should be a job that handles sending the handle\_ methods, and it should be able to be put in the background for performance reasons.
+
+Also needs a way to configure the namespace for the active support notifications and whatnot. We'd have external subscribers like UserPilot and Mixpanel in the future

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/active_subscriber/base.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module ActiveSubscriber
+  class Base
+    class << self
+      def subscribed_events
+        @subscribed_events ||= []
+      end
+
+      def subscribed_patterns
+        @subscribed_patterns ||= []
+      end
+
+      def before_handle_callbacks
+        @before_handle_callbacks ||= []
+      end
+
+      def after_handle_callbacks
+        @after_handle_callbacks ||= []
+      end
+
+      def around_handle_callbacks
+        @around_handle_callbacks ||= []
+      end
+
+      def subscribe_to(*event_names)
+        @subscribed_events ||= []
+        @subscribed_events.concat(event_names.map(&:to_s))
+        @subscribed_events.uniq!
+
+        if defined?(ActiveSubscriber) && ActiveSubscriber.respond_to?(:configuration) && ActiveSubscriber.configuration.auto_load
+          ActiveSubscriber.registry.register(self)
+        end
+      end
+
+      def subscribe_to_pattern(pattern)
+        @subscribed_patterns ||= []
+        pattern_regex = case pattern
+                        when String
+                          Regexp.new(pattern.gsub('*', '.*'))
+                        when Regexp
+                          pattern
+                        else
+                          Regexp.new(pattern.to_s.gsub('*', '.*'))
+                        end
+        @subscribed_patterns << pattern_regex
+        @subscribed_patterns.uniq!
+
+        if defined?(ActiveSubscriber) && ActiveSubscriber.respond_to?(:configuration) && ActiveSubscriber.configuration.auto_load
+          ActiveSubscriber.registry.register(self)
+        end
+      end
+
+      def before_handle_event(method_name)
+        @before_handle_callbacks ||= []
+        @before_handle_callbacks << method_name
+      end
+
+      def after_handle_event(method_name)
+        @after_handle_callbacks ||= []
+        @after_handle_callbacks << method_name
+      end
+
+      def around_handle_event(method_name)
+        @around_handle_callbacks ||= []
+        @around_handle_callbacks << method_name
+      end
+    end
+
+    def handle_event(event_name, data)
+      run_callbacks do
+        handler_method = "handle_#{event_name.gsub('.', '_').gsub('-', '_')}"
+
+        if respond_to?(handler_method, true)
+          send(handler_method, data)
+        elsif respond_to?(:handle_all_events, true)
+          handle_all_events(event_name, data)
+        end
+      end
+    end
+
+    private
+
+    def run_callbacks(&block)
+      # Run before callbacks
+      self.class.before_handle_callbacks.each do |callback|
+        next unless respond_to?(callback, true)
+
+        begin
+          send(callback)
+        rescue StandardError => e
+          ActiveSubscriber.logger.error "ActiveSubscriber: Error in before callback '#{callback}': #{e.message}"
+          ActiveSubscriber.logger.error e.backtrace.join("\n") if e.backtrace
+        end
+      end
+
+      # Run around callbacks or yield directly
+      if self.class.around_handle_callbacks.any?
+        run_around_callbacks(0, &block)
+      else
+        yield
+      end
+
+      # Run after callbacks
+      self.class.after_handle_callbacks.each do |callback|
+        next unless respond_to?(callback, true)
+
+        begin
+          send(callback)
+        rescue StandardError => e
+          ActiveSubscriber.logger.error "ActiveSubscriber: Error in after callback '#{callback}': #{e.message}"
+          ActiveSubscriber.logger.error e.backtrace.join("\n") if e.backtrace
+        end
+      end
+    end
+
+    def run_around_callbacks(index, &block)
+      if index < self.class.around_handle_callbacks.length
+        callback = self.class.around_handle_callbacks[index]
+        if respond_to?(callback, true)
+          begin
+            send(callback) do
+              run_around_callbacks(index + 1, &block)
+            end
+          rescue StandardError => e
+            ActiveSubscriber.logger.error "ActiveSubscriber: Error in around callback '#{callback}': #{e.message}"
+            ActiveSubscriber.logger.error e.backtrace.join("\n") if e.backtrace
+            run_around_callbacks(index + 1, &block)
+          end
+        else
+          run_around_callbacks(index + 1, &block)
+        end
+      else
+        yield
+      end
+    end
+  end
+end