easyop 0.1.1 → 0.1.3

data/lib/easyop/events/bus/adapter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Events
+    module Bus
+      # Inheritable base class for custom bus implementations.
+      #
+      # Subclass this (not +Bus::Base+) when building a transport adapter for
+      # an external message broker, pub/sub system, or any custom delivery
+      # mechanism. +Bus::Base+ defines the required interface and glob helpers.
+      # +Bus::Adapter+ adds two production-grade utilities on top:
+      #
+      #   _safe_invoke(handler, event)   — call a handler, swallow StandardError
+      #   _compile_pattern(pattern)      — glob/string → cached Regexp
+      #
+      # Both are protected so they are accessible in subclasses but not part
+      # of the external bus interface.
+      #
+      # == Minimum contract
+      #
+      # Override +#publish+ and +#subscribe+. Override +#unsubscribe+ if your
+      # transport supports subscription cancellation.
+      #
+      # == Example — minimal adapter
+      #
+      #   class PrintBus < Easyop::Events::Bus::Adapter
+      #     def initialize
+      #       super
+      #       @subs  = []
+      #       @mutex = Mutex.new
+      #     end
+      #
+      #     def publish(event)
+      #       snap = @mutex.synchronize { @subs.dup }
+      #       snap.each do |sub|
+      #         _safe_invoke(sub[:handler], event) if _pattern_matches?(sub[:pattern], event.name)
+      #       end
+      #     end
+      #
+      #     def subscribe(pattern, &block)
+      #       handle = { pattern: _compile_pattern(pattern), handler: block }
+      #       @mutex.synchronize { @subs << handle }
+      #       handle
+      #     end
+      #
+      #     def unsubscribe(handle)
+      #       @mutex.synchronize { @subs.delete(handle) }
+      #     end
+      #   end
+      #
+      # == Example — decorator (wraps another bus)
+      #
+      #   class LoggingBus < Easyop::Events::Bus::Adapter
+      #     def initialize(inner)
+      #       super()
+      #       @inner = inner
+      #     end
+      #
+      #     def publish(event)
+      #       Rails.logger.info "[bus:publish] #{event.name} payload=#{event.payload}"
+      #       @inner.publish(event)
+      #     end
+      #
+      #     def subscribe(pattern, &block)
+      #       @inner.subscribe(pattern, &block)
+      #     end
+      #
+      #     def unsubscribe(handle)
+      #       @inner.unsubscribe(handle)
+      #     end
+      #   end
+      #
+      #   Easyop::Events::Registry.bus = LoggingBus.new(Easyop::Events::Bus::Memory.new)
+      class Adapter < Base
+        protected
+
+        # Call +handler+ with +event+, rescuing any StandardError.
+        #
+        # Use this inside your +#publish+ implementation so one broken handler
+        # never prevents other handlers from running and never surfaces an
+        # exception to the event producer.
+        #
+        # @param handler [#call]
+        # @param event   [Easyop::Events::Event]
+        # @return [void]
+        def _safe_invoke(handler, event)
+          handler.call(event)
+        rescue StandardError
+          # Intentionally swallowed — individual handler failures must not
+          # propagate to the caller or block remaining handlers.
+        end
+
+        # Compile +pattern+ into a +Regexp+, memoized per unique pattern value.
+        #
+        # Results are cached in a per-instance hash so glob→Regexp conversion
+        # happens only once regardless of how many events are published.
+        #
+        # String patterns without wildcards are anchored literally.
+        # Glob patterns follow the same rules as +Bus::Base#_glob_to_regex+:
+        #   "*"  — any single dot-separated segment
+        #   "**" — any sequence of characters including dots
+        #
+        # @param pattern [String, Regexp]
+        # @return [Regexp]
+        def _compile_pattern(pattern)
+          return pattern if pattern.is_a?(Regexp)
+
+          @_pattern_cache ||= {}
+          @_pattern_cache[pattern] ||=
+            if pattern.include?("*")
+              _glob_to_regex(pattern)
+            else
+              Regexp.new("\\A#{Regexp.escape(pattern)}\\z")
+            end
+        end
+      end
+    end
+  end
+end

data/lib/easyop/events/bus/custom.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Events
+    module Bus
+      # Wraps any user-supplied bus adapter.
+      #
+      # The adapter must respond to:
+      #   #publish(event)
+      #   #subscribe(pattern, &block)
+      #
+      # Optionally:
+      #   #unsubscribe(handle)
+      #
+      # @example Wrapping a RabbitMQ adapter
+      #   class MyRabbitBus
+      #     def publish(event) = rabbit.publish(event.to_h, routing_key: event.name)
+      #     def subscribe(pattern, &block) = rabbit.subscribe(pattern) { |msg| block.call(reconstruct(msg)) }
+      #   end
+      #
+      #   Easyop::Events::Registry.bus = MyRabbitBus.new
+      #
+      # @example Passing via Custom wrapper explicitly
+      #   Easyop::Events::Registry.bus = Easyop::Events::Bus::Custom.new(MyRabbitBus.new)
+      class Custom < Base
+        # @param adapter [Object] must respond to #publish and #subscribe
+        # @raise [ArgumentError] if adapter does not meet the interface
+        def initialize(adapter)
+          unless adapter.respond_to?(:publish) && adapter.respond_to?(:subscribe)
+            raise ArgumentError,
+              "Custom bus adapter must respond to #publish(event) and " \
+              "#subscribe(pattern, &block). Got: #{adapter.inspect}"
+          end
+          @adapter = adapter
+        end
+
+        def publish(event)
+          @adapter.publish(event)
+        end
+
+        def subscribe(pattern, &block)
+          @adapter.subscribe(pattern, &block)
+        end
+
+        def unsubscribe(handle)
+          @adapter.unsubscribe(handle) if @adapter.respond_to?(:unsubscribe)
+        end
+      end
+    end
+  end
+end

data/lib/easyop/events/bus/memory.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Events
+    module Bus
+      # In-process, synchronous bus. Default adapter — requires no external gems.
+      #
+      # Thread-safe: subscriptions are protected by a Mutex, and publish snapshots
+      # the subscriber list before calling handlers so the lock is not held
+      # during handler execution (prevents deadlocks).
+      #
+      # @example
+      #   bus = Easyop::Events::Bus::Memory.new
+      #   bus.subscribe("order.placed") { |e| puts e.name }
+      #   bus.publish(Easyop::Events::Event.new(name: "order.placed"))
+      class Memory < Base
+        def initialize
+          @subscribers = []
+          @mutex       = Mutex.new
+        end
+
+        # Deliver +event+ to all matching subscribers.
+        # Handlers are called outside the lock; failures in individual handlers
+        # are swallowed so other handlers still run.
+        #
+        # @param event [Easyop::Events::Event]
+        def publish(event)
+          subs = @mutex.synchronize { @subscribers.dup }
+          subs.each do |sub|
+            sub[:handler].call(event) if _pattern_matches?(sub[:pattern], event.name)
+          rescue StandardError
+            # Individual handler failures must not prevent other handlers from running.
+          end
+        end
+
+        # Register a handler block for events matching +pattern+.
+        #
+        # @param pattern [String, Regexp]  exact name, glob, or Regexp
+        # @return [Hash] subscription handle (pass to #unsubscribe to remove)
+        def subscribe(pattern, &block)
+          entry = { pattern: pattern, handler: block }
+          @mutex.synchronize { @subscribers << entry }
+          entry
+        end
+
+        # Remove a previously registered subscription.
+        # @param handle [Hash] the value returned by #subscribe
+        def unsubscribe(handle)
+          @mutex.synchronize { @subscribers.delete(handle) }
+        end
+
+        # Remove all subscriptions. Useful in tests.
+        def clear!
+          @mutex.synchronize { @subscribers.clear }
+        end
+
+        # @return [Integer] number of active subscriptions
+        def subscriber_count
+          @mutex.synchronize { @subscribers.size }
+        end
+      end
+    end
+  end
+end

data/lib/easyop/events/bus.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Events
+    # Namespace for bus adapters.
+    # All adapters inherit from Easyop::Events::Bus::Base.
+    module Bus
+      # Abstract base for bus adapters.
+      #
+      # Subclasses must implement:
+      #   #publish(event)          — deliver event to matching subscribers
+      #   #subscribe(pattern, &block) — register a handler block
+      #
+      # Optionally override:
+      #   #unsubscribe(handle)     — remove a subscription (handle is return value of #subscribe)
+      class Base
+        # @param event [Easyop::Events::Event]
+        def publish(event)
+          raise NotImplementedError, "#{self.class}#publish must be implemented"
+        end
+
+        # @param pattern [String, Regexp]  event name, glob ("order.*"), or Regexp
+        # @yield [event] called when a matching event is published
+        # @return [Object] subscription handle (adapter-specific)
+        def subscribe(pattern, &block)
+          raise NotImplementedError, "#{self.class}#subscribe must be implemented"
+        end
+
+        # Remove a subscription created by #subscribe.
+        # @param handle [Object] the value returned by #subscribe
+        def unsubscribe(handle)
+          # default no-op — adapters may override
+        end
+
+        private
+
+        # Returns true when +pattern+ matches +event_name+.
+        # Supports exact strings, glob patterns ("order.*", "order.**"), and Regexp.
+        #
+        # Glob rules:
+        #   "*"  — matches any segment that doesn't cross a dot
+        #   "**" — matches any string including dots (greedy)
+        #
+        # @param pattern    [String, Regexp]
+        # @param event_name [String]
+        def _pattern_matches?(pattern, event_name)
+          case pattern
+          when Regexp
+            pattern.match?(event_name)
+          when String
+            pattern.include?("*") ? _glob_to_regex(pattern).match?(event_name) : pattern == event_name
+          end
+        end
+
+        # @param glob [String]  e.g. "order.*" or "warehouse.**"
+        # @return [Regexp]
+        def _glob_to_regex(glob)
+          escaped = Regexp.escape(glob)
+                          .gsub("\\*\\*", ".+")
+                          .gsub("\\*",    "[^.]+")
+          Regexp.new("\\A#{escaped}\\z")
+        end
+      end
+    end
+  end
+end

data/lib/easyop/events/event.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Events
+    # An immutable domain event value object.
+    #
+    # @example
+    #   event = Easyop::Events::Event.new(
+    #     name:    "order.placed",
+    #     payload: { order_id: 42, total: 9900 },
+    #     source:  "PlaceOrder"
+    #   )
+    #   event.name     # => "order.placed"
+    #   event.payload  # => { order_id: 42, total: 9900 }
+    #   event.frozen?  # => true
+    class Event
+      attr_reader :name, :payload, :metadata, :timestamp, :source
+
+      # @param name      [String]  event name, e.g. "order.placed"
+      # @param payload   [Hash]    domain data extracted from ctx
+      # @param metadata  [Hash]    extra envelope data (correlation_id, etc.)
+      # @param timestamp [Time]    defaults to Time.now
+      # @param source    [String]  class name of the emitting operation
+      def initialize(name:, payload: {}, metadata: {}, timestamp: nil, source: nil)
+        @name      = name.to_s.freeze
+        @payload   = payload.freeze
+        @metadata  = metadata.freeze
+        @timestamp = (timestamp || Time.now).freeze
+        @source    = source&.freeze
+        freeze
+      end
+
+      # @return [Hash] serializable hash representation
+      def to_h
+        { name: @name, payload: @payload, metadata: @metadata,
+          timestamp: @timestamp, source: @source }
+      end
+
+      def inspect
+        "#<Easyop::Events::Event name=#{@name.inspect} source=#{@source.inspect}>"
+      end
+    end
+  end
+end

data/lib/easyop/events/registry.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Events
+    # Thread-safe global registry for the event bus and handler subscriptions.
+    #
+    # The Registry is the coordination point between the Events plugin (producer)
+    # and the EventHandlers plugin (subscriber). Neither plugin references the other
+    # directly — they communicate only through the bus managed here.
+    #
+    # Configure the bus once at boot (e.g. in a Rails initializer):
+    #
+    #   Easyop::Events::Registry.bus = :memory           # default, in-process
+    #   Easyop::Events::Registry.bus = :active_support   # ActiveSupport::Notifications
+    #   Easyop::Events::Registry.bus = MyRabbitBus.new   # custom adapter
+    #
+    # Or via the global config:
+    #
+    #   Easyop.configure { |c| c.event_bus = :active_support }
+    #
+    # IMPORTANT: Configure the bus BEFORE handler classes are loaded (before
+    # autoloading runs in Rails). Subscriptions are registered at class load time
+    # and are bound to whatever bus is active at that moment.
+    class Registry
+      @mutex = Mutex.new
+
+      class << self
+        # Set the global bus adapter.
+        #
+        # @param bus_or_symbol [:memory, :active_support, Bus::Base, Object]
+        def bus=(bus_or_symbol)
+          @mutex.synchronize { @bus = _resolve_bus(bus_or_symbol) }
+        end
+
+        # Returns the active bus adapter. Defaults to a Memory bus.
+        #
+        # Falls back to Easyop.config.event_bus if set, then :memory.
+        #
+        # @return [Bus::Base]
+        def bus
+          @mutex.synchronize do
+            @bus ||= _resolve_bus(
+              defined?(Easyop.config) && Easyop.config.respond_to?(:event_bus) && Easyop.config.event_bus ||
+              :memory
+            )
+          end
+        end
+
+        # Register a handler operation as a subscriber for +pattern+.
+        #
+        # Called automatically by the EventHandlers plugin when `on` is declared.
+        #
+        # @param pattern       [String, Regexp]  event name or glob
+        # @param handler_class [Class]           operation class to invoke
+        # @param async         [Boolean]         use call_async (requires Async plugin)
+        # @param options       [Hash]            e.g. queue: "low"
+        def register_handler(pattern:, handler_class:, async: false, **options)
+          entry = { pattern: pattern, handler_class: handler_class,
+                    async: async, options: options }
+
+          @mutex.synchronize { _subscriptions << entry }
+
+          bus.subscribe(pattern) { |event| _dispatch(event, entry) }
+        end
+
+        # Returns a copy of all registered handler entries (for introspection).
+        #
+        # @return [Array<Hash>]
+        def subscriptions
+          @mutex.synchronize { _subscriptions.dup }
+        end
+
+        # Reset the registry: drop all subscriptions and replace the bus with a
+        # fresh Memory instance. Intended for use in tests (called in before/after hooks).
+        def reset!
+          @mutex.synchronize do
+            @bus           = nil
+            @subscriptions = nil
+          end
+        end
+
+        private
+
+        def _subscriptions
+          @subscriptions ||= []
+        end
+
+        # @api private — exposed for specs
+        def _dispatch(event, entry)
+          handler_class = entry[:handler_class]
+
+          if entry[:async] && handler_class.respond_to?(:call_async)
+            # Serialize Event to a plain hash for ActiveJob compatibility.
+            attrs = event.payload.merge(event_data: event.to_h)
+            queue = entry[:options][:queue]
+            handler_class.call_async(attrs, **(queue ? { queue: queue } : {}))
+          else
+            # Sync: pass Event object directly — ctx.event is the live Event instance.
+            handler_class.call(event: event, **event.payload)
+          end
+        rescue StandardError
+          # Handler failures must not propagate back to the publisher.
+        end
+
+        def _resolve_bus(bus_or_symbol)
+          case bus_or_symbol
+          when :memory
+            Bus::Memory.new
+          when :active_support
+            Bus::ActiveSupportNotifications.new
+          when Bus::Base
+            bus_or_symbol
+          when nil
+            Bus::Memory.new
+          else
+            if bus_or_symbol.respond_to?(:publish) && bus_or_symbol.respond_to?(:subscribe)
+              Bus::Custom.new(bus_or_symbol)
+            else
+              raise ArgumentError,
+                "Unknown bus: #{bus_or_symbol.inspect}. " \
+                "Use :memory, :active_support, or a bus adapter instance."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/easyop/plugins/async.rb

@@ -27,6 +27,18 @@ module Easyop
       end
 
       module ClassMethods
+        # Declares a non-default queue for this operation class and its subclasses.
+        #
+        # @example
+        #   class Weather::BaseOperation < ApplicationOperation
+        #     queue :weather
+        #   end
+        #
+        # @param name [String, Symbol] queue name
+        def queue(name)
+          @_async_default_queue = name.to_s
+        end
+
         # Enqueue the operation as a background job.
         #
         #   MyOp.call_async(email: "x@y.com")

data/lib/easyop/plugins/event_handlers.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Plugins
+    # Subscribes an operation class to handle domain events.
+    #
+    # The handler operation receives the event payload merged into ctx, plus
+    # ctx.event (the Easyop::Events::Event object itself for sync dispatch).
+    #
+    # Basic usage:
+    #
+    #   class SendOrderConfirmation < ApplicationOperation
+    #     plugin Easyop::Plugins::EventHandlers
+    #
+    #     on "order.placed"
+    #
+    #     def call
+    #       event    = ctx.event        # Easyop::Events::Event
+    #       order_id = ctx.order_id     # payload keys merged into ctx
+    #       OrderMailer.confirm(order_id).deliver_later
+    #     end
+    #   end
+    #
+    # Async dispatch (requires Easyop::Plugins::Async also installed):
+    #
+    #   class IndexOrder < ApplicationOperation
+    #     plugin Easyop::Plugins::Async, queue: "indexing"
+    #     plugin Easyop::Plugins::EventHandlers
+    #
+    #     on "order.*",      async: true
+    #     on "inventory.**", async: true, queue: "low"
+    #
+    #     def call
+    #       # For async dispatch ctx.event_data is a Hash (serialized for ActiveJob).
+    #       # Reconstruct if needed: Easyop::Events::Event.new(**ctx.event_data)
+    #       SearchIndex.reindex(ctx.order_id)
+    #     end
+    #   end
+    #
+    # Wildcard patterns:
+    #   "order.*"     — matches order.placed, order.shipped (not order.payment.failed)
+    #   "warehouse.**" — matches warehouse.stock.updated, warehouse.zone.moved, etc.
+    module EventHandlers
+      def self.install(base, **_options)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Subscribe this operation to events matching +pattern+.
+        #
+        # Registration happens at class-load time and is bound to the bus that is
+        # active when the class is evaluated. Configure the bus before loading
+        # handler classes (e.g. in a Rails initializer that runs before autoloading).
+        #
+        # @param pattern [String, Regexp]  event name or glob
+        # @param async   [Boolean]         enqueue via call_async (requires Async plugin)
+        # @param options [Hash]            e.g. queue: "low" (overrides Async default)
+        def on(pattern, async: false, **options)
+          _event_handler_registrations << { pattern: pattern, async: async, options: options }
+
+          Easyop::Events::Registry.register_handler(
+            pattern:       pattern,
+            handler_class: self,
+            async:         async,
+            **options
+          )
+        end
+
+        # @api private — list of registrations declared on this class
+        def _event_handler_registrations
+          @_event_handler_registrations ||= []
+        end
+      end
+    end
+  end
+end