easyop 0.1.2 → 0.1.4

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Events
+    module Bus
+      # Bus adapter backed by ActiveSupport::Notifications.
+      #
+      # Requires activesupport (not auto-required). Raises LoadError if unavailable.
+      #
+      # @example
+      #   Easyop::Events::Registry.bus = :active_support
+      #
+      #   # or manually:
+      #   bus = Easyop::Events::Bus::ActiveSupportNotifications.new
+      #   Easyop::Events::Registry.bus = bus
+      class ActiveSupportNotifications < Base
+        # Publish +event+ via ActiveSupport::Notifications.instrument.
+        # The full event hash (name, payload, metadata, timestamp, source) is passed
+        # as the AS notification payload.
+        #
+        # @param event [Easyop::Events::Event]
+        def publish(event)
+          _ensure_as!
+          ::ActiveSupport::Notifications.instrument(event.name, event.to_h)
+        end
+
+        # Subscribe to events matching +pattern+ via ActiveSupport::Notifications.subscribe.
+        # Glob patterns are converted to Regexp before passing to AS.
+        #
+        # @param pattern [String, Regexp]
+        # @return [Object] AS subscription handle
+        def subscribe(pattern, &block)
+          _ensure_as!
+
+          as_pattern = _as_pattern(pattern)
+
+          ::ActiveSupport::Notifications.subscribe(as_pattern) do |*args|
+            as_event     = ::ActiveSupport::Notifications::Event.new(*args)
+            p            = as_event.payload
+
+            # Reconstruct an Easyop::Events::Event from the AS notification payload.
+            easyop_event = Event.new(
+              name:      (p[:name] || as_event.name).to_s,
+              payload:   p[:payload]  || {},
+              metadata:  p[:metadata] || {},
+              timestamp: p[:timestamp],
+              source:    p[:source]
+            )
+            block.call(easyop_event)
+          end
+        end
+
+        # Unsubscribe using the handle returned by #subscribe.
+        # @param handle [Object] AS subscription object
+        def unsubscribe(handle)
+          _ensure_as!
+          ::ActiveSupport::Notifications.unsubscribe(handle)
+        end
+
+        private
+
+        # Convert a pattern for use with AS::Notifications.subscribe.
+        # AS accepts exact strings or Regexp (not globs), so convert globs first.
+        def _as_pattern(pattern)
+          case pattern
+          when Regexp then pattern
+          when String
+            pattern.include?("*") ? _glob_to_regex(pattern) : pattern
+          end
+        end
+
+        def _ensure_as!
+          return if defined?(::ActiveSupport::Notifications)
+
+          raise LoadError,
+            "ActiveSupport::Notifications is required for this bus adapter. " \
+            "Add 'activesupport' to your Gemfile."
+        end
+      end
+    end
+  end
+end

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/flow.rb

@@ -1,3 +1,5 @@
+require 'securerandom'
+
 module Easyop
   # Compose a sequence of operations that share a single ctx.
   #
@@ -11,6 +13,27 @@ module Easyop
   #     flow ValidateCart, ChargeCard, CreateOrder, NotifyUser
   #   end
   #
+  # ## Recording plugin integration (flow tracing)
+  #
+  # When steps have the Recording plugin installed, `CallBehavior#call` forwards
+  # the parent ctx keys so every step log entry shows the flow as its parent:
+  #
+  #   # Bare flow — flow itself is not recorded but steps see it as parent:
+  #   class ProcessOrder
+  #     include Easyop::Flow
+  #     flow ValidateCart, ChargeCard
+  #   end
+  #
+  # For full tree reconstruction (flow appears in operation_logs as the root
+  # entry) inherit from your recorded base class and opt out of the transaction
+  # so step-level transactions are not shadowed by an outer one:
+  #
+  #   class ProcessOrder < ApplicationOperation
+  #     include Easyop::Flow
+  #     transactional false   # EasyOp handles rollback; steps own their transactions
+  #     flow ValidateCart, ChargeCard
+  #   end
+  #
   #   result = ProcessOrder.call(user: user, cart: cart)
   #   result.on_success { |ctx| redirect_to order_path(ctx.order) }
   #   result.on_failure { |ctx| flash[:alert] = ctx.error }
@@ -31,6 +54,25 @@ module Easyop
     # otherwise place Operation earlier in the ancestor chain than Flow itself).
     module CallBehavior
       def call
+        # ── Flow-tracing forwarding for the Recording plugin ──────────────────
+        # When Recording is NOT installed on this flow class (i.e. the flow does
+        # not inherit from a base operation that has Recording), set the
+        # __recording_parent_* ctx keys manually so every step operation knows
+        # this flow is its parent.  When Recording IS installed on the flow (its
+        # RunWrapper runs before `call` is reached), it has already set up the
+        # parent context correctly — we detect that via _recording_enabled? and
+        # skip to avoid a conflict.  If Recording is not used at all, these ctx
+        # keys are unused and ignored.
+        _flow_tracing = self.class.name &&
+                        !self.class.respond_to?(:_recording_enabled?)
+        if _flow_tracing
+          ctx[:__recording_root_reference_id]     ||= SecureRandom.uuid
+          _prev_parent_name                         = ctx[:__recording_parent_operation_name]
+          _prev_parent_id                           = ctx[:__recording_parent_reference_id]
+          ctx[:__recording_parent_operation_name]   = self.class.name
+          ctx[:__recording_parent_reference_id]     = SecureRandom.uuid
+        end
+
         pending_guard = nil
 
         self.class._flow_steps.each do |step|
@@ -56,6 +98,12 @@ module Easyop
       rescue Ctx::Failure
         ctx.rollback!
         raise
+      ensure
+        # Restore parent context so any caller above this flow sees the right parent.
+        if _flow_tracing
+          ctx[:__recording_parent_operation_name] = _prev_parent_name
+          ctx[:__recording_parent_reference_id]   = _prev_parent_id
+        end
       end
     end