active_subscriber 0.1.0

data/lib/active_subscriber/configuration.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveSubscriber
+  class Configuration
+    attr_reader :subscriber_paths, :namespace
+    attr_accessor :enabled, :event_filter, :auto_load, :async
+
+    def initialize
+      @enabled = true
+      @subscriber_paths = ['app/subscribers']
+      @event_filter = nil
+      @auto_load = true
+      @namespace = 'active_subscriber'
+      @async = defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.production? : false
+    end
+
+    def subscriber_paths=(value)
+      raise ArgumentError, "subscriber_paths must be an Array, got #{value.class}" unless value.is_a?(Array)
+
+      @subscriber_paths = value
+    end
+
+    def namespace=(value)
+      unless value.nil? || value.is_a?(String)
+        raise ArgumentError, "namespace must be a String or nil, got #{value.class}"
+      end
+
+      @namespace = value
+    end
+
+    def event_allowed?(event_name)
+      return true unless event_filter
+
+      case event_filter
+      when Proc
+        event_filter.call(event_name)
+      when String, Regexp
+        event_name.match?(event_filter)
+      else
+        true
+      end
+    end
+
+    def reset!
+      @enabled = true
+      @subscriber_paths = ['app/subscribers']
+      @event_filter = nil
+      @auto_load = true
+      @namespace = 'active_subscriber'
+      @async = false
+    end
+  end
+end

data/lib/active_subscriber/engine.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+
+module ActiveSubscriber
+  class Engine < ::Rails::Engine
+    isolate_namespace ActiveSubscriber
+
+    config.active_subscriber = ActiveSupport::OrderedOptions.new
+
+    initializer 'active_subscriber.configure' do |app|
+      ActiveSubscriber.configure do |config|
+        # Apply any configuration from Rails config
+        config.enabled = app.config.active_subscriber.enabled if app.config.active_subscriber.enabled.present?
+
+        if app.config.active_subscriber.subscriber_paths.present?
+          config.subscriber_paths = app.config.active_subscriber.subscriber_paths
+        end
+
+        if app.config.active_subscriber.event_filter.present?
+          config.event_filter = app.config.active_subscriber.event_filter
+        end
+
+        config.auto_load = app.config.active_subscriber.auto_load if app.config.active_subscriber.auto_load.present?
+      end
+    end
+
+    initializer 'active_subscriber.load_subscribers', after: :load_config_initializers do
+      ActiveSupport.on_load(:active_record) do
+        ActiveSubscriber.loader.load_subscribers
+      end
+    end
+
+    # Reload subscribers in development when files change
+    config.to_prepare do
+      ActiveSubscriber.loader.reload_subscribers if Rails.env.development?
+    end
+
+    # Add app/subscribers to autoload paths
+    config.before_configuration do
+      config.autoload_paths << Rails.root.join('app', 'subscribers') if Rails.root
+    end
+
+    # Ensure cleanup on application shutdown
+    at_exit do
+      ActiveSubscriber.registry.clear if defined?(ActiveSubscriber)
+    end
+  end
+end

data/lib/active_subscriber/helpers/analytics_helper.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActiveSubscriber
+  module Helpers
+    module AnalyticsHelper
+      extend ActiveSupport::Concern
+
+      included do
+        include ActiveSubscriber::Publisher
+      end
+
+      def track_analytics(event_name, properties = {}, context = {})
+        analytics_context = build_analytics_context.merge(context)
+        publish_event(event_name, properties, analytics_context)
+      end
+
+      def track_analytics_with_timing(event_name, properties = {}, context = {}, &block)
+        analytics_context = build_analytics_context.merge(context)
+        publish_event_with_timing(event_name, properties, analytics_context, &block)
+      end
+
+      private
+
+      def build_analytics_context
+        context = {
+          controller: controller_name,
+          action: action_name,
+          timestamp: Time.current
+        }
+
+        # Add request information if available
+        if defined?(request) && request
+          context.merge!(
+            user_agent: request.user_agent,
+            ip_address: request.remote_ip,
+            referer: request.referer,
+            request_id: request.request_id
+          )
+        end
+
+        # Add user information if current_user is available
+        if respond_to?(:current_user) && current_user
+          context[:user_id] = current_user.id
+          context[:user_type] = current_user.class.name
+        end
+
+        # Add session information if available
+        context[:session_id] = session.id if respond_to?(:session) && session.respond_to?(:id)
+
+        context
+      end
+    end
+  end
+end

data/lib/active_subscriber/loader.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module ActiveSubscriber
+  class Loader
+    def initialize
+      @loaded_paths = Set.new
+    end
+
+    def load_subscribers
+      return unless ActiveSubscriber.configuration.auto_load
+
+      ActiveSubscriber.configuration.subscriber_paths.each do |path|
+        load_subscribers_from_path(path)
+      end
+    end
+
+    def reload_subscribers
+      ActiveSubscriber.registry.clear
+      @loaded_paths.clear
+      load_subscribers
+    end
+
+    private
+
+    def load_subscribers_from_path(path)
+      return unless Dir.exist?(path)
+      return if @loaded_paths.include?(path)
+
+      @loaded_paths << path
+
+      Dir.glob(File.join(path, '**', '*.rb')).each do |file|
+        load_subscriber_file(file)
+      end
+    end
+
+    def load_subscriber_file(file_path)
+      if defined?(Rails) && Rails.respond_to?(:env)
+        return if Rails.env.production? && !File.exist?(file_path)
+
+        if Rails.env.development?
+          load file_path
+        else
+          require file_path
+        end
+      else
+        require file_path
+      end
+    rescue LoadError, StandardError => e
+      ActiveSubscriber.logger.error "ActiveSubscriber: Failed to load subscriber file #{file_path}: #{e.message}"
+    end
+  end
+end

data/lib/active_subscriber/publisher.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ActiveSubscriber
+  module Publisher
+    def publish_event(event_name, payload = {}, context = {})
+      return unless ActiveSubscriber.enabled?
+
+      namespaced_event = namespace_event(event_name)
+      return unless ActiveSubscriber.configuration.event_allowed?(namespaced_event)
+
+      event_data = {
+        payload: payload,
+        context: context,
+        published_at: Time.current,
+        publisher: self.class.name || 'Anonymous'
+      }
+
+      ActiveSupport::Notifications.instrument(namespaced_event, event_data)
+    end
+
+    def publish_event_with_timing(event_name, payload = {}, context = {})
+      return yield unless ActiveSubscriber.enabled?
+
+      namespaced_event = namespace_event(event_name)
+      return yield unless ActiveSubscriber.configuration.event_allowed?(namespaced_event)
+
+      start_time = Time.current
+      result = yield
+      end_time = Time.current
+
+      event_data = {
+        payload: payload,
+        context: context,
+        published_at: start_time,
+        completed_at: end_time,
+        duration: (end_time - start_time) * 1000,
+        publisher: self.class.name || 'Anonymous'
+      }
+
+      ActiveSupport::Notifications.instrument(namespaced_event, event_data)
+      result
+    end
+
+    private
+
+    def namespace_event(event_name)
+      namespace = ActiveSubscriber.configuration.namespace
+      return event_name.to_s if namespace.nil? || namespace.empty?
+
+      "#{namespace}.#{event_name}"
+    end
+
+    module ClassMethods
+      def publish_event(event_name, payload = {}, context = {})
+        return unless ActiveSubscriber.enabled?
+
+        namespaced_event = namespace_event(event_name)
+        return unless ActiveSubscriber.configuration.event_allowed?(namespaced_event)
+
+        event_data = {
+          payload: payload,
+          context: context,
+          published_at: Time.current,
+          publisher: name || 'Anonymous'
+        }
+
+        ActiveSupport::Notifications.instrument(namespaced_event, event_data)
+      end
+
+      def publish_event_with_timing(event_name, payload = {}, context = {})
+        return yield unless ActiveSubscriber.enabled?
+
+        namespaced_event = namespace_event(event_name)
+        return yield unless ActiveSubscriber.configuration.event_allowed?(namespaced_event)
+
+        start_time = Time.current
+        result = yield
+        end_time = Time.current
+
+        event_data = {
+          payload: payload,
+          context: context,
+          published_at: start_time,
+          completed_at: end_time,
+          duration: (end_time - start_time) * 1000,
+          publisher: name || 'Anonymous'
+        }
+
+        ActiveSupport::Notifications.instrument(namespaced_event, event_data)
+        result
+      end
+
+      private
+
+      def namespace_event(event_name)
+        namespace = ActiveSubscriber.configuration.namespace
+        return event_name.to_s if namespace.nil? || namespace.empty?
+
+        "#{namespace}.#{event_name}"
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/active_subscriber/registry.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module ActiveSubscriber
+  class Registry
+    def initialize
+      @subscribers = []
+      @subscriptions = {}
+      @mutex = Mutex.new
+    end
+
+    def register(subscriber_class)
+      @mutex.synchronize do
+        if @subscribers.include?(subscriber_class)
+          cleanup_subscriptions(subscriber_class)
+        else
+          @subscribers << subscriber_class
+        end
+
+        setup_subscriptions(subscriber_class)
+      end
+    end
+
+    def unregister(subscriber_class)
+      @mutex.synchronize do
+        @subscribers.delete(subscriber_class)
+        cleanup_subscriptions(subscriber_class)
+      end
+    end
+
+    def subscribers
+      @subscribers.dup
+    end
+
+    def clear
+      @mutex.synchronize do
+        @subscriptions.each_value do |subscription|
+          ActiveSupport::Notifications.unsubscribe(subscription)
+        end
+        @subscriptions.clear
+        @subscribers.clear
+      end
+    end
+
+    private
+
+    def setup_subscriptions(subscriber_class)
+      subscriber_class.subscribed_events.each do |event_name|
+        namespaced_event = namespace_event(event_name)
+        subscription = ActiveSupport::Notifications.subscribe(namespaced_event) do |name, _started, _finished, _unique_id, data|
+          next unless ActiveSubscriber.enabled?
+          next unless ActiveSubscriber.configuration.event_allowed?(name)
+
+          instance = subscriber_class.new
+          handle_event(instance, event_name, data)
+        end
+
+        if subscription
+          @subscriptions["#{subscriber_class.name}:#{event_name}"] = subscription
+        else
+          ActiveSubscriber.logger.warn "ActiveSubscriber: Failed to create subscription for #{event_name}"
+        end
+      rescue StandardError => e
+        ActiveSubscriber.logger.error "ActiveSubscriber: Error setting up subscription for #{event_name}: #{e.message}"
+      end
+
+      subscriber_class.subscribed_patterns.each do |pattern|
+        namespaced_pattern = namespace_pattern(pattern)
+        subscription = ActiveSupport::Notifications.subscribe(namespaced_pattern) do |name, _started, _finished, _unique_id, data|
+          next unless ActiveSubscriber.enabled?
+          next unless ActiveSubscriber.configuration.event_allowed?(name)
+
+          instance = subscriber_class.new
+          event_name = name.sub(/^#{ActiveSubscriber.configuration.namespace}\./, '')
+          handle_event(instance, event_name, data)
+        end
+
+        if subscription
+          @subscriptions["#{subscriber_class.name}:pattern:#{pattern}"] = subscription
+        else
+          ActiveSubscriber.logger.warn "ActiveSubscriber: Failed to create subscription for pattern #{pattern}"
+        end
+      rescue StandardError => e
+        ActiveSubscriber.logger.error "ActiveSubscriber: Error setting up subscription for pattern #{pattern}: #{e.message}"
+      end
+    end
+
+    def namespace_event(event_name)
+      namespace = ActiveSubscriber.configuration.namespace
+      return event_name.to_s if namespace.nil? || namespace.empty?
+
+      "#{namespace}.#{event_name}"
+    end
+
+    def namespace_pattern(pattern)
+      namespace = ActiveSubscriber.configuration.namespace
+      return pattern if namespace.nil? || namespace.empty?
+
+      case pattern
+      when Regexp
+        Regexp.new("#{Regexp.escape(namespace)}\\.#{pattern.source}", pattern.options)
+      else
+        Regexp.new("#{Regexp.escape(namespace)}\\.#{pattern}")
+      end
+    end
+
+    def cleanup_subscriptions(subscriber_class)
+      keys_to_remove = @subscriptions.keys.select { |key| key.start_with?("#{subscriber_class.name}:") }
+      keys_to_remove.each do |key|
+        ActiveSupport::Notifications.unsubscribe(@subscriptions[key])
+        @subscriptions.delete(key)
+      end
+    end
+
+    def handle_event(instance, event_name, data)
+      if ActiveSubscriber.configuration.async
+        ActiveSubscriber::SubscriberJob.perform_later(instance.class.name, event_name, data)
+      else
+        instance.handle_event(event_name, data)
+      end
+    rescue StandardError => e
+      ActiveSubscriber.logger.error "ActiveSubscriber: Error handling event '#{event_name}': #{e.message}"
+      ActiveSubscriber.logger.error e.backtrace.join("\n") if e.backtrace
+    end
+  end
+end

data/lib/active_subscriber/subscriber_job.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'active_job'
+
+module ActiveSubscriber
+  class SubscriberJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(subscriber_class_name, event_name, data)
+      subscriber_class = subscriber_class_name.safe_constantize
+
+      if subscriber_class.nil?
+        raise ArgumentError, "ActiveSubscriber::SubscriberJob: Unknown subscriber class '#{subscriber_class_name}'"
+      end
+
+      instance = subscriber_class.new
+      instance.handle_event(event_name, data)
+    rescue StandardError => e
+      ActiveSubscriber.logger.error "ActiveSubscriber::SubscriberJob: Error handling event '#{event_name}' with #{subscriber_class_name}: #{e.message}"
+      ActiveSubscriber.logger.error e.backtrace.join("\n") if e.backtrace
+      raise e
+    end
+  end
+end

data/lib/active_subscriber/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveSubscriber
+  VERSION = '0.1.0'
+end

data/lib/active_subscriber.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'active_support'
+require 'active_support/notifications'
+
+require_relative 'active_subscriber/version'
+require_relative 'active_subscriber/configuration'
+require_relative 'active_subscriber/subscriber_job'
+require_relative 'active_subscriber/registry'
+require_relative 'active_subscriber/publisher'
+require_relative 'active_subscriber/base'
+require_relative 'active_subscriber/loader'
+require_relative 'active_subscriber/helpers/analytics_helper'
+
+if defined?(Rails)
+  require_relative 'active_subscriber/engine'
+end
+
+module ActiveSubscriber
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    def loader
+      @loader ||= Loader.new
+    end
+
+    def enabled?
+      configuration.enabled
+    end
+
+    def logger
+      @logger ||= if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+                     Rails.logger
+                   else
+                     Logger.new($stdout)
+                   end
+    end
+
+    attr_writer :logger
+  end
+end

data/lib/generators/active_subscriber/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ActiveSubscriber
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Install ActiveSubscriber in your Rails application'
+
+      def create_initializer
+        template 'initializer.rb', 'config/initializers/active_subscriber.rb'
+      end
+
+      def create_subscribers_directory
+        empty_directory 'app/subscribers'
+        create_file 'app/subscribers/.keep', ''
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+
+      private
+
+      def readme(path)
+        say File.read(File.join(File.dirname(__FILE__), 'templates', path))
+      end
+    end
+  end
+end

data/lib/generators/active_subscriber/subscriber_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ActiveSubscriber
+  module Generators
+    class SubscriberGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Generate a new ActiveSubscriber subscriber'
+
+      class_option :events, type: :array, default: [], desc: 'Events to subscribe to'
+      class_option :patterns, type: :array, default: [], desc: 'Event patterns to subscribe to'
+
+      def create_subscriber_file
+        template 'subscriber.rb', File.join('app/subscribers', class_path, "#{file_name}_subscriber.rb")
+      end
+
+      private
+
+      def events_list
+        options[:events].map { |event| ":#{event}" }.join(', ')
+      end
+
+      def patterns_list
+        options[:patterns].map { |pattern| "\"#{pattern}\"" }.join(', ')
+      end
+
+      def has_events?
+        options[:events].any?
+      end
+
+      def has_patterns?
+        options[:patterns].any?
+      end
+
+      def handler_methods
+        options[:events].map do |event|
+          method_name = "handle_#{event.gsub('.', '_').gsub('-', '_')}"
+          <<~METHOD
+            def #{method_name}(data)
+              # Handle #{event} event
+              Rails.logger.info "#{class_name}Subscriber: Handling #{event} event"
+            end
+          METHOD
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/generators/active_subscriber/templates/README

@@ -0,0 +1,32 @@
+===============================================================================
+
+ActiveSubscriber has been installed!
+
+Next steps:
+
+1. Configure ActiveSubscriber in config/initializers/active_subscriber.rb
+2. Create your first subscriber:
+   
+   rails generate active_subscriber:subscriber Analytics --events user_signed_in user_signed_up
+
+3. Include the Publisher module in your services:
+
+   class AnalyticsService
+     include ActiveSubscriber::Publisher
+
+     def self.track_event(name, data = {})
+       publish_event(name, data)
+     end
+   end
+
+4. Include the AnalyticsHelper in your controllers:
+
+   class ApplicationController < ActionController::Base
+     include ActiveSubscriber::Helpers::AnalyticsHelper
+   end
+
+5. Start publishing events and let your subscribers handle them!
+
+For more information, visit: https://github.com/afomera/active_subscriber
+
+===============================================================================

data/lib/generators/active_subscriber/templates/initializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+ActiveSubscriber.configure do |config|
+  # Enable or disable ActiveSubscriber
+  # config.enabled = true
+
+  # Namespace for all events (recommended to avoid conflicts)
+  # config.namespace = "my_app"
+
+  # Paths where subscribers are located
+  # config.subscriber_paths = ["app/subscribers"]
+
+  # Filter events (optional)
+  # config.event_filter = ->(event_name) { !event_name.start_with?("internal.") }
+
+  # Auto-load subscribers
+  # config.auto_load = true
+
+  # Process events asynchronously using background jobs (defaults to Rails.env.production?)
+  # config.async = Rails.env.production?
+end