easyop 0.1.2 → 0.1.4

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

data/lib/easyop/plugins/events.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Plugins
+    # Emits domain events after an operation completes.
+    #
+    # Install on a base operation class to inherit into all subclasses:
+    #
+    #   class ApplicationOperation
+    #     include Easyop::Operation
+    #     plugin Easyop::Plugins::Events
+    #   end
+    #
+    # Then declare events on individual operations:
+    #
+    #   class PlaceOrder < ApplicationOperation
+    #     emits "order.placed", on: :success, payload: [:order_id, :total]
+    #     emits "order.failed", on: :failure, payload: ->(ctx) { { error: ctx.error } }
+    #     emits "order.attempted", on: :always
+    #
+    #     def call
+    #       ctx.order_id = Order.create!(ctx.to_h).id
+    #     end
+    #   end
+    #
+    # Plugin options:
+    #   bus:      [Bus::Base, nil]  per-class bus override (default: global registry bus)
+    #   metadata: [Hash, Proc, nil] extra metadata merged into every event from this class
+    #
+    # `emits` DSL options:
+    #   on:      [:success (default), :failure, :always]
+    #   payload: [Proc, Array, nil]  Proc receives ctx; Array slices ctx keys; nil = full ctx.to_h
+    #   guard:   [Proc, nil]         extra condition — event only fires if truthy
+    module Events
+      def self.install(base, bus: nil, metadata: nil, **_options)
+        base.extend(ClassMethods)
+        base.prepend(RunWrapper)
+        base.instance_variable_set(:@_events_bus,      bus)
+        base.instance_variable_set(:@_events_metadata, metadata)
+      end
+
+      module ClassMethods
+        # Declare an event this operation emits after execution.
+        #
+        # @example
+        #   emits "order.placed", on: :success, payload: [:order_id]
+        #   emits "order.failed", on: :failure, payload: ->(ctx) { { error: ctx.error } }
+        #
+        # @param name   [String]
+        # @param on     [Symbol]        :success (default), :failure, or :always
+        # @param payload [Proc, Array, nil]
+        # @param guard  [Proc, nil]     optional condition — fires only when truthy
+        def emits(name, on: :success, payload: nil, guard: nil)
+          _emitted_events << { name: name.to_s, on: on, payload: payload, guard: guard }
+        end
+
+        # @api private — inheritable list of emits declarations
+        def _emitted_events
+          @_emitted_events ||= _inherited_emitted_events
+        end
+
+        # @api private — bus for this class (falls back to superclass, then global registry)
+        def _events_bus
+          if instance_variable_defined?(:@_events_bus)
+            @_events_bus
+          elsif superclass.respond_to?(:_events_bus)
+            superclass._events_bus
+          end
+        end
+
+        # @api private — metadata for this class (falls back to superclass)
+        def _events_metadata
+          if instance_variable_defined?(:@_events_metadata)
+            @_events_metadata
+          elsif superclass.respond_to?(:_events_metadata)
+            superclass._events_metadata
+          end
+        end
+
+        private
+
+        def _inherited_emitted_events
+          superclass.respond_to?(:_emitted_events) ? superclass._emitted_events.dup : []
+        end
+      end
+
+      module RunWrapper
+        # Wraps _easyop_run to publish declared events in an ensure block.
+        # Events fire AFTER the operation completes — success, failure, or exception.
+        def _easyop_run(ctx, raise_on_failure:)
+          super
+        ensure
+          _events_publish_all(ctx)
+        end
+
+        private
+
+        def _events_publish_all(ctx)
+          declarations = self.class._emitted_events
+          return if declarations.empty?
+
+          bus = self.class._events_bus || Easyop::Events::Registry.bus
+
+          declarations.each do |decl|
+            next unless _events_should_fire?(decl, ctx)
+
+            event = _events_build_event(decl, ctx)
+            bus.publish(event)
+          rescue StandardError
+            # Individual publish failures must never crash the operation.
+            # Log if Rails is available.
+            _events_log_warning($ERROR_INFO)
+          end
+        end
+
+        def _events_should_fire?(decl, ctx)
+          case decl[:on]
+          when :success then return false unless ctx.success?
+          when :failure then return false unless ctx.failure?
+          when :always  then nil # always fire
+          end
+
+          guard = decl[:guard]
+          guard ? guard.call(ctx) : true
+        end
+
+        def _events_build_event(decl, ctx)
+          Easyop::Events::Event.new(
+            name:      decl[:name],
+            payload:   _events_extract_payload(decl[:payload], ctx),
+            metadata:  _events_build_metadata(ctx),
+            source:    self.class.name
+          )
+        end
+
+        def _events_extract_payload(payload_spec, ctx)
+          case payload_spec
+          when Proc  then payload_spec.call(ctx)
+          when Array then ctx.slice(*payload_spec)
+          when nil   then ctx.to_h
+          else payload_spec
+          end
+        end
+
+        def _events_build_metadata(ctx)
+          meta = self.class._events_metadata
+          case meta
+          when Proc then meta.call(ctx)
+          when Hash then meta.dup
+          else {}
+          end
+        end
+
+        def _events_log_warning(err)
+          return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+          Rails.logger.warn "[EasyOp::Events] Failed to publish event: #{err.message}"
+        end
+      end
+    end
+  end
+end

data/lib/easyop/plugins/recording.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module Easyop
   module Plugins
     # Records operation executions to a database model.
@@ -18,6 +20,15 @@ module Easyop
     #   duration_ms     :float
     #   performed_at    :datetime, null: false
     #
+    # Optional flow-tracing columns:
+    #   root_reference_id     :string   # shared across entire execution tree
+    #   reference_id          :string   # unique to this operation execution
+    #   parent_operation_name :string   # class name of the direct parent
+    #   parent_reference_id   :string   # reference_id of the direct parent
+    #
+    # Optional result column:
+    #   result_data           :text     # stored as JSON — selected ctx keys after call
+    #
     # Opt out per operation class:
     #   class MyOp < ApplicationOperation
     #     recording false
@@ -26,15 +37,24 @@ module Easyop
     # Options:
     #   model:         (required) ActiveRecord class
     #   record_params: true       pass false to skip params serialization
+    #   record_result: nil        configure result capture at plugin level (Hash/Proc/Symbol)
     module Recording
       # Sensitive keys scrubbed from params_data before persisting.
       SCRUBBED_KEYS = %i[password password_confirmation token secret api_key].freeze
 
-      def self.install(base, model:, record_params: true, **_options)
+      # Internal ctx keys used for flow tracing — excluded from params_data.
+      INTERNAL_CTX_KEYS = %i[
+        __recording_root_reference_id
+        __recording_parent_operation_name
+        __recording_parent_reference_id
+      ].freeze
+
+      def self.install(base, model:, record_params: true, record_result: nil, **_options)
         base.extend(ClassMethods)
         base.prepend(RunWrapper)
-        base.instance_variable_set(:@_recording_model,        model)
-        base.instance_variable_set(:@_recording_record_params, record_params)
+        base.instance_variable_set(:@_recording_model,         model)
+        base.instance_variable_set(:@_recording_record_params,  record_params)
+        base.instance_variable_set(:@_recording_record_result,  record_result)
       end
 
       module ClassMethods
@@ -62,6 +82,33 @@ module Easyop
             true
           end
         end
+
+        # DSL for capturing result data after the operation runs.
+        # Three forms:
+        #   record_result attrs: :key           # one or more ctx keys
+        #   record_result { |ctx| { k: ctx.k } } # block
+        #   record_result :build_result         # private instance method name
+        def record_result(value = nil, attrs: nil, &block)
+          @_recording_record_result = if block
+            block
+          elsif attrs
+            { attrs: attrs }
+          elsif value.is_a?(Symbol)
+            value
+          else
+            value
+          end
+        end
+
+        def _recording_record_result_config
+          if instance_variable_defined?(:@_recording_record_result)
+            @_recording_record_result
+          elsif superclass.respond_to?(:_recording_record_result_config)
+            superclass._recording_record_result_config
+          else
+            nil
+          end
+        end
       end
 
       module RunWrapper
@@ -70,6 +117,23 @@ module Easyop
           return super unless (model = self.class._recording_model)
           return super unless self.class.name # skip anonymous classes
 
+          # -- Flow tracing --
+          # Each operation gets its own reference_id. The root_reference_id is
+          # shared across the entire execution tree via ctx (set once, inherited).
+          reference_id      = SecureRandom.uuid
+          root_reference_id = ctx[:__recording_root_reference_id] ||= SecureRandom.uuid
+
+          # Read current parent context — these become THIS operation's parent fields.
+          parent_operation_name = ctx[:__recording_parent_operation_name]
+          parent_reference_id   = ctx[:__recording_parent_reference_id]
+
+          # Set THIS operation as the parent for any children that run inside super.
+          # Save the previous values so we can restore them after (for siblings).
+          prev_parent_name = parent_operation_name
+          prev_parent_id   = parent_reference_id
+          ctx[:__recording_parent_operation_name] = self.class.name
+          ctx[:__recording_parent_reference_id]   = reference_id
+
           start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           super
         ensure
@@ -78,22 +142,37 @@ module Easyop
           # branch the tap block would be skipped and failures inside flows would
           # never be persisted.
           if start
+            # Restore parent context so sibling steps see the correct parent.
+            ctx[:__recording_parent_operation_name] = prev_parent_name
+            ctx[:__recording_parent_reference_id]   = prev_parent_id
+
             ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
-            _recording_persist!(ctx, model, ms)
+            _recording_persist!(ctx, model, ms,
+              root_reference_id:     root_reference_id,
+              reference_id:          reference_id,
+              parent_operation_name: parent_operation_name,
+              parent_reference_id:   parent_reference_id)
           end
         end
 
         private
 
-        def _recording_persist!(ctx, model, duration_ms)
+        def _recording_persist!(ctx, model, duration_ms,
+                                root_reference_id: nil, reference_id: nil,
+                                parent_operation_name: nil, parent_reference_id: nil)
           attrs = {
-            operation_name: self.class.name,
-            success:        ctx.success?,
-            error_message:  ctx.error,
-            performed_at:   Time.current,
-            duration_ms:    duration_ms
+            operation_name:        self.class.name,
+            success:               ctx.success?,
+            error_message:         ctx.error,
+            performed_at:          Time.current,
+            duration_ms:           duration_ms,
+            root_reference_id:     root_reference_id,
+            reference_id:          reference_id,
+            parent_operation_name: parent_operation_name,
+            parent_reference_id:   parent_reference_id
           }
           attrs[:params_data] = _recording_safe_params(ctx) if self.class._recording_record_params?
+          attrs[:result_data] = _recording_safe_result(ctx) if self.class._recording_record_result_config
 
           # Only write columns the model actually has
           safe = attrs.select { |k, _| model.column_names.include?(k.to_s) }
@@ -104,13 +183,35 @@ module Easyop
 
         def _recording_safe_params(ctx)
           ctx.to_h
-             .except(*SCRUBBED_KEYS)
+             .except(*SCRUBBED_KEYS, *INTERNAL_CTX_KEYS)
              .transform_values { |v| v.is_a?(ActiveRecord::Base) ? { id: v.id, class: v.class.name } : v }
              .to_json
         rescue
           nil
         end
 
+        def _recording_safe_result(ctx)
+          config = self.class._recording_record_result_config
+          return nil unless config
+
+          raw = case config
+                when Hash
+                  keys = Array(config[:attrs])
+                  keys.each_with_object({}) { |k, h| h[k] = ctx[k] }
+                when Proc
+                  config.call(ctx)
+                when Symbol
+                  send(config)
+                end
+
+          return nil unless raw.is_a?(Hash)
+
+          raw.transform_values { |v| v.is_a?(ActiveRecord::Base) ? { id: v.id, class: v.class.name } : v }
+             .to_json
+        rescue
+          nil
+        end
+
         def _recording_warn(err)
           return unless defined?(Rails) && Rails.respond_to?(:logger)
           Rails.logger.warn "[EasyOp::Recording] Failed to record #{self.class.name}: #{err.message}"

data/lib/easyop/schema.rb

@@ -161,7 +161,7 @@ module Easyop
       if Easyop.config.strict_types
         ctx.fail!(error: msg, errors: ctx.errors.merge(field.name => msg))
       else
-        warn "[Easyop] #{msg}"
+        $stderr.puts "[Easyop] #{msg}"
       end
     end
   end

data/lib/easyop/version.rb

@@ -1,3 +1,3 @@
 module Easyop
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

data/lib/easyop.rb

@@ -18,6 +18,17 @@ require_relative "easyop/flow"
 # require "easyop/plugins/recording"
 # require "easyop/plugins/async"
 
+# Domain event plugins — require together or individually:
+# require "easyop/events/event"
+# require "easyop/events/bus"
+# require "easyop/events/bus/memory"
+# require "easyop/events/bus/active_support_notifications"
+# require "easyop/events/bus/custom"
+# require "easyop/events/bus/adapter"   # inherit this to build a custom bus
+# require "easyop/events/registry"
+# require "easyop/plugins/events"
+# require "easyop/plugins/event_handlers"
+
 module Easyop
   # Convenience: inherit from this instead of including Easyop::Operation
   # when you want a common base class for all your operations.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easyop
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Pawel Niemczyk
@@ -53,12 +53,21 @@ files:
 - lib/easyop.rb
 - lib/easyop/configuration.rb
 - lib/easyop/ctx.rb
+- lib/easyop/events/bus.rb
+- lib/easyop/events/bus/active_support_notifications.rb
+- lib/easyop/events/bus/adapter.rb
+- lib/easyop/events/bus/custom.rb
+- lib/easyop/events/bus/memory.rb
+- lib/easyop/events/event.rb
+- lib/easyop/events/registry.rb
 - lib/easyop/flow.rb
 - lib/easyop/flow_builder.rb
 - lib/easyop/hooks.rb
 - lib/easyop/operation.rb
 - lib/easyop/plugins/async.rb
 - lib/easyop/plugins/base.rb
+- lib/easyop/plugins/event_handlers.rb
+- lib/easyop/plugins/events.rb
 - lib/easyop/plugins/instrumentation.rb
 - lib/easyop/plugins/recording.rb
 - lib/easyop/plugins/transactional.rb