easyop 0.1.0

data/lib/easyop/plugins/async.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Plugins
+    # Enables async execution via ActiveJob.
+    #
+    # Usage:
+    #   class Newsletter::SendBroadcast < ApplicationOperation
+    #     plugin Easyop::Plugins::Async, queue: "broadcasts"
+    #   end
+    #
+    #   # Enqueue immediately:
+    #   Newsletter::SendBroadcast.call_async(subject: "Hello", body: "World")
+    #
+    #   # With scheduling options:
+    #   Newsletter::SendBroadcast.call_async(attrs, wait: 10.minutes)
+    #   Newsletter::SendBroadcast.call_async(attrs, wait_until: Date.tomorrow.noon)
+    #   Newsletter::SendBroadcast.call_async(attrs, queue: "low_priority")
+    #
+    # ActiveRecord objects are serialized by (class, id) and re-fetched in the job.
+    # Only serializable values (String, Integer, Float, Boolean, nil, Hash, Array,
+    # or ActiveRecord::Base) should be passed.
+    module Async
+      def self.install(base, queue: "default", **_options)
+        base.extend(ClassMethods)
+        base.instance_variable_set(:@_async_default_queue, queue)
+      end
+
+      module ClassMethods
+        # Enqueue the operation as a background job.
+        #
+        #   MyOp.call_async(email: "x@y.com")
+        #   MyOp.call_async(email: "x@y.com", wait: 5.minutes, queue: "low")
+        def call_async(attrs = {}, wait: nil, wait_until: nil, queue: nil, **extra_attrs)
+          merged_attrs = attrs.merge(extra_attrs)
+          _async_ensure_active_job!
+          job = Easyop::Plugins::Async.job_class
+          job = job.set(queue: queue || _async_default_queue)
+          job = job.set(wait: wait)             if wait
+          job = job.set(wait_until: wait_until) if wait_until
+          job.perform_later(name, _async_serialize(merged_attrs))
+        end
+
+        def _async_default_queue
+          @_async_default_queue ||
+            (superclass.respond_to?(:_async_default_queue) ? superclass._async_default_queue : "default")
+        end
+
+        private
+
+        def _async_ensure_active_job!
+          return if defined?(ActiveJob::Base)
+          raise LoadError, "ActiveJob is required for async operations."
+        end
+
+        # Serialize attrs for GlobalID / JSON storage.
+        # AR objects → { "__ar_class" => "User", "__ar_id" => 42 }
+        def _async_serialize(attrs)
+          attrs.each_with_object({}) do |(k, v), h|
+            h[k.to_s] = if defined?(ActiveRecord::Base) && v.is_a?(ActiveRecord::Base)
+                           { "__ar_class" => v.class.name, "__ar_id" => v.id }
+                         else
+                           v
+                         end
+          end
+        end
+      end
+
+      # The ActiveJob that deserializes and runs the operation.
+      # Defined lazily so this file can be required before ActiveJob loads.
+      def self.job_class
+        @job_class ||= begin
+          raise LoadError, "ActiveJob is required for Easyop::Plugins::Async" unless defined?(ActiveJob::Base)
+
+          klass = Class.new(ActiveJob::Base) do
+            queue_as :default
+
+            def perform(operation_class, attrs)
+              op_klass = operation_class.constantize
+              deserialized = attrs.each_with_object({}) do |(k, v), h|
+                h[k.to_sym] = if v.is_a?(Hash) && v["__ar_class"]
+                                 v["__ar_class"].constantize.find(v["__ar_id"])
+                               else
+                                 v
+                               end
+              end
+              op_klass.call(deserialized)
+            end
+          end
+
+          # Give the anonymous class a constant name for serialization
+          Easyop::Plugins::Async.const_set(:Job, klass) unless const_defined?(:Job)
+          klass
+        end
+      end
+    end
+  end
+end

data/lib/easyop/plugins/base.rb

@@ -0,0 +1,27 @@
+module Easyop
+  module Plugins
+    # Abstract base for EasyOp plugins.
+    #
+    # A plugin is any object responding to `.install(base_class, **options)`.
+    # Inherit from Base for convenience and documentation:
+    #
+    #   module MyPlugin < Easyop::Plugins::Base
+    #     def self.install(base, **options)
+    #       base.prepend(RunWrapper)
+    #       base.extend(ClassMethods)
+    #     end
+    #   end
+    #
+    # Plugins are activated via the `plugin` DSL on operation classes:
+    #
+    #   class ApplicationOperation
+    #     include Easyop::Operation
+    #     plugin MyPlugin, option: :value
+    #   end
+    class Base
+      def self.install(_base, **_options)
+        raise NotImplementedError, "#{name}.install(base, **options) must be implemented"
+      end
+    end
+  end
+end

data/lib/easyop/plugins/instrumentation.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Plugins
+    # Instruments every operation call via ActiveSupport::Notifications.
+    #
+    # Install on ApplicationOperation (propagates to all subclasses):
+    #
+    #   class ApplicationOperation
+    #     include Easyop::Operation
+    #     plugin Easyop::Plugins::Instrumentation
+    #   end
+    #
+    # Event: "easyop.operation.call"
+    # Payload keys:
+    #   :operation  — String class name, e.g. "Users::Register"
+    #   :success    — Boolean
+    #   :error      — String | nil  (ctx.error on failure)
+    #   :duration   — Float ms
+    #   :ctx        — The Easyop::Ctx object (read-only reference)
+    #
+    # Subscribe manually:
+    #   ActiveSupport::Notifications.subscribe("easyop.operation.call") do |event|
+    #     Rails.logger.info "[EasyOp] #{event.payload[:operation]} — #{event.payload[:success] ? 'ok' : 'FAILED'}"
+    #   end
+    #
+    # Or use the built-in log subscriber:
+    #   Easyop::Plugins::Instrumentation.attach_log_subscriber
+    module Instrumentation
+      EVENT = "easyop.operation.call"
+
+      def self.install(base, **_options)
+        base.prepend(RunWrapper)
+      end
+
+      # Attach a default subscriber that logs to Rails.logger (or stdout).
+      # Call once in an initializer: Easyop::Plugins::Instrumentation.attach_log_subscriber
+      def self.attach_log_subscriber
+        ActiveSupport::Notifications.subscribe(EVENT) do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          p     = event.payload
+          next if p[:operation].nil?
+
+          status = p[:success] ? "ok" : "FAILED"
+          ms     = event.duration.round(1)
+          line   = "[EasyOp] #{p[:operation]} #{status} (#{ms}ms)"
+          line  += " — #{p[:error]}" if p[:error]
+
+          logger = defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : Logger.new($stdout)
+          if p[:success]
+            logger.info line
+          else
+            logger.warn line
+          end
+        end
+      end
+
+      module RunWrapper
+        def _easyop_run(ctx, raise_on_failure:)
+          start   = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          payload = { operation: self.class.name, success: nil, error: nil, duration: nil, ctx: ctx }
+
+          ActiveSupport::Notifications.instrument(EVENT, payload) do
+            super.tap do
+              payload[:success]  = ctx.success?
+              payload[:error]    = ctx.error if ctx.failure?
+              payload[:duration] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/easyop/plugins/recording.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Easyop
+  module Plugins
+    # Records operation executions to a database model.
+    #
+    # Usage:
+    #   class ApplicationOperation
+    #     include Easyop::Operation
+    #     plugin Easyop::Plugins::Recording, model: OperationLog
+    #   end
+    #
+    # Required model columns (create with the generator migration):
+    #   operation_name  :string,   null: false
+    #   success         :boolean,  null: false
+    #   error_message   :string
+    #   params_data     :text               # stored as JSON
+    #   duration_ms     :float
+    #   performed_at    :datetime, null: false
+    #
+    # Opt out per operation class:
+    #   class MyOp < ApplicationOperation
+    #     recording false
+    #   end
+    #
+    # Options:
+    #   model:         (required) ActiveRecord class
+    #   record_params: true       pass false to skip params serialization
+    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)
+        base.extend(ClassMethods)
+        base.prepend(RunWrapper)
+        base.instance_variable_set(:@_recording_model,        model)
+        base.instance_variable_set(:@_recording_record_params, record_params)
+      end
+
+      module ClassMethods
+        # Disable recording for this class: `recording false`
+        def recording(enabled)
+          @_recording_enabled = enabled
+        end
+
+        def _recording_enabled?
+          return @_recording_enabled if instance_variable_defined?(:@_recording_enabled)
+          superclass.respond_to?(:_recording_enabled?) ? superclass._recording_enabled? : true
+        end
+
+        def _recording_model
+          @_recording_model ||
+            (superclass.respond_to?(:_recording_model) ? superclass._recording_model : nil)
+        end
+
+        def _recording_record_params?
+          if instance_variable_defined?(:@_recording_record_params)
+            @_recording_record_params
+          elsif superclass.respond_to?(:_recording_record_params?)
+            superclass._recording_record_params?
+          else
+            true
+          end
+        end
+      end
+
+      module RunWrapper
+        def _easyop_run(ctx, raise_on_failure:)
+          return super unless self.class._recording_enabled?
+          return super unless (model = self.class._recording_model)
+          return super unless self.class.name # skip anonymous classes
+
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          super.tap do
+            ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+            _recording_persist!(ctx, model, ms)
+          end
+        end
+
+        private
+
+        def _recording_persist!(ctx, model, duration_ms)
+          attrs = {
+            operation_name: self.class.name,
+            success:        ctx.success?,
+            error_message:  ctx.error,
+            performed_at:   Time.current,
+            duration_ms:    duration_ms
+          }
+          attrs[:params_data] = _recording_safe_params(ctx) if self.class._recording_record_params?
+
+          # Only write columns the model actually has
+          safe = attrs.select { |k, _| model.column_names.include?(k.to_s) }
+          model.create!(safe)
+        rescue => e
+          _recording_warn(e)
+        end
+
+        def _recording_safe_params(ctx)
+          ctx.to_h
+             .except(*SCRUBBED_KEYS)
+             .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}"
+        end
+      end
+    end
+  end
+end

data/lib/easyop/plugins/transactional.rb

@@ -0,0 +1,69 @@
+module Easyop
+  module Plugins
+    # Wraps the entire operation (including before/after hooks) in a database
+    # transaction. On ctx.fail! or any unhandled exception the transaction rolls back.
+    #
+    # Supports ActiveRecord and Sequel out of the box.
+    #
+    # Usage — include style (classic):
+    #   class TransferFunds
+    #     include Easyop::Operation
+    #     include Easyop::Plugins::Transactional
+    #   end
+    #
+    # Usage — plugin DSL (recommended, works with ApplicationOperation):
+    #   class ApplicationOperation
+    #     include Easyop::Operation
+    #     plugin Easyop::Plugins::Transactional
+    #   end
+    #
+    # Or opt in per operation:
+    #   class TransferFunds < ApplicationOperation
+    #     plugin Easyop::Plugins::Transactional
+    #   end
+    #
+    # To opt out when the parent has it:
+    #   class ReadOnlyOp < ApplicationOperation
+    #     transactional false
+    #   end
+    module Transactional
+      # Support the `plugin` DSL: `plugin Easyop::Plugins::Transactional`
+      def self.install(base, **_options)
+        base.include(self)
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.around(:_transactional_wrap)
+      end
+
+      module ClassMethods
+        # Opt out of transaction wrapping: `transactional false`
+        def transactional(enabled)
+          @_transactional_enabled = enabled
+        end
+
+        def _transactional_enabled?
+          return @_transactional_enabled if instance_variable_defined?(:@_transactional_enabled)
+          superclass.respond_to?(:_transactional_enabled?) ? superclass._transactional_enabled? : true
+        end
+      end
+
+      private
+
+      def _transactional_wrap
+        return yield unless self.class._transactional_enabled?
+
+        db = if defined?(ActiveRecord::Base)
+               ActiveRecord::Base
+             elsif defined?(Sequel::Model)
+               Sequel::Model.db
+             else
+               raise "Easyop::Plugins::Transactional requires ActiveRecord or Sequel"
+             end
+
+        db.transaction { yield }
+      end
+    end
+  end
+end

data/lib/easyop/rescuable.rb

@@ -0,0 +1,68 @@
+module Easyop
+  # Lightweight rescue_from DSL, modelled after ActiveSupport::Rescuable.
+  # Works without ActiveSupport and can be used standalone.
+  #
+  # Usage:
+  #   rescue_from SomeError, with: :handle_it
+  #   rescue_from OtherError, AnotherError do |e|
+  #     ctx.fail!(error: e.message)
+  #   end
+  #
+  # Handlers are checked in definition order (first match wins).
+  # Subclasses inherit their parent's handlers.
+  module Rescuable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Register a handler for one or more exception classes.
+      # Pass `with: :method_name` or a block.
+      def rescue_from(*klasses, with: nil, &block)
+        raise ArgumentError, "Provide `with:` or a block" unless with || block_given?
+
+        handler = with || block
+        klasses.each do |klass|
+          _rescue_handlers << [klass, handler]
+        end
+      end
+
+      # Own handlers defined directly on this class (not inherited).
+      def _rescue_handlers
+        @_rescue_handlers ||= []
+      end
+
+      # Full ordered list: own handlers first, then ancestors' (child wins).
+      def _all_rescue_handlers
+        parent = superclass
+        parent_handlers = parent.respond_to?(:_all_rescue_handlers) ? parent._all_rescue_handlers : []
+        _rescue_handlers + parent_handlers
+      end
+    end
+
+    # Attempt to handle `exception` with a registered handler.
+    # Returns true if handled, false if no matching handler found.
+    def rescue_with_handler(exception)
+      handler = handler_for_rescue(exception)
+      return false unless handler
+
+      case handler
+      when Symbol then send(handler, exception)
+      when Proc   then instance_exec(exception, &handler)
+      end
+      true
+    end
+
+    private
+
+    def handler_for_rescue(exception)
+      self.class._all_rescue_handlers.each do |klass, handler|
+        klass_const = klass.is_a?(String) ? Object.const_get(klass) : klass
+        return handler if exception.is_a?(klass_const)
+      rescue NameError
+        next  # constant not loaded yet — skip
+      end
+      nil
+    end
+  end
+end

data/lib/easyop/schema.rb

@@ -0,0 +1,168 @@
+module Easyop
+  # Optional typed schema DSL for Operation inputs and outputs.
+  #
+  # When included (automatically when you use `params` or `result` in an
+  # Operation), it adds before/after hooks that validate ctx against the
+  # declared schema using the configured type adapter.
+  #
+  # Usage:
+  #   params do
+  #     required :email,    String
+  #     required :amount,   Integer
+  #     optional :note,     String
+  #     optional :retry,    :boolean, default: false
+  #   end
+  #
+  #   result do
+  #     required :record, ActiveRecord::Base
+  #     optional :token,  String
+  #   end
+  #
+  # Type symbols (:boolean, :string, :integer, :float) are mapped to native
+  # Ruby classes. Pass an actual class (String, User, etc.) for strict is_a?
+  # checking. Type validation only happens if Easyop.config.type_adapter != :none.
+  module Schema
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Declare input schema. Validated before `call` runs.
+      def params(&block)
+        schema = FieldSchema.new
+        schema.instance_eval(&block)
+        @_param_schema = schema
+
+        # Register as a before hook (prepend so it runs first)
+        _before_hooks.unshift(:_validate_params!)
+      end
+      alias inputs params
+
+      # Declare output schema. Validated after `call` returns (not in ensure).
+      def result(&block)
+        schema = FieldSchema.new
+        schema.instance_eval(&block)
+        @_result_schema = schema
+
+        _after_hooks.push(:_validate_result!)
+      end
+      alias outputs result
+
+      def _param_schema
+        @_param_schema
+      end
+
+      def _result_schema
+        @_result_schema
+      end
+    end
+
+    # ── Instance validation methods ───────────────────────────────────────────
+
+    def _validate_params!
+      schema = self.class._param_schema
+      return unless schema
+      schema.validate!(ctx, phase: :params)
+    end
+
+    def _validate_result!
+      schema = self.class._result_schema
+      return unless schema && ctx.success?
+      schema.validate!(ctx, phase: :result)
+    end
+  end
+
+  # Describes a set of typed fields (used for both params and result schemas).
+  class FieldSchema
+    TYPE_MAP = {
+      string:  String,
+      integer: Integer,
+      float:   Float,
+      boolean: [TrueClass, FalseClass],
+      symbol:  Symbol,
+      any:     BasicObject,
+    }.freeze
+
+    Field = Struct.new(:name, :type, :required, :default, :has_default, keyword_init: true)
+
+    def initialize
+      @fields = []
+    end
+
+    def required(name, type = nil, **opts)
+      add_field(name, type, required: true, **opts)
+    end
+
+    def optional(name, type = nil, **opts)
+      add_field(name, type, required: false, **opts)
+    end
+
+    def fields
+      @fields.dup
+    end
+
+    # Validate ctx against this schema.
+    # Raises Ctx::Failure on hard errors; emits warnings otherwise
+    # depending on Easyop.config.strict_types.
+    def validate!(ctx, phase: :params)
+      @fields.each do |field|
+        val = ctx[field.name]
+
+        # Apply default if not set
+        if val.nil? && field.has_default
+          ctx[field.name] = field.default.respond_to?(:call) ? field.default.call : field.default
+          val = ctx[field.name]
+        end
+
+        # Required check
+        if field.required && val.nil?
+          ctx.fail!(
+            error:  "Missing required #{phase} field: #{field.name}",
+            errors: ctx.errors.merge(field.name => "is required")
+          )
+        end
+
+        # Type check (skip if nil and optional)
+        next if val.nil?
+        next if field.type.nil?
+
+        type_check!(ctx, field, val, phase)
+      end
+    end
+
+    private
+
+    def add_field(name, type, required:, default: :__no_default__, **_rest)
+      resolved = resolve_type(type)
+      @fields << Field.new(
+        name:        name.to_sym,
+        type:        resolved,
+        required:    required,
+        default:     default == :__no_default__ ? nil : default,
+        has_default: default != :__no_default__
+      )
+    end
+
+    def resolve_type(type)
+      return nil if type.nil?
+      return type if type.is_a?(Class) || type.is_a?(Array)
+
+      TYPE_MAP[type.to_sym] || (raise ArgumentError, "Unknown type shorthand: #{type.inspect}")
+    end
+
+    def type_check!(ctx, field, val, phase)
+      types = Array(field.type)
+      valid = types.any? { |t| t == BasicObject || val.is_a?(t) }
+      return if valid
+
+      msg = "Type mismatch in #{phase} field :#{field.name} — " \
+            "expected #{types.map(&:name).join(" | ")}, got #{val.class}"
+
+      if Easyop.config.strict_types
+        ctx.fail!(error: msg, errors: ctx.errors.merge(field.name => msg))
+      else
+        warn "[Easyop] #{msg}"
+      end
+    end
+  end
+end

data/lib/easyop/skip.rb

@@ -0,0 +1,22 @@
+module Easyop
+  module Skip
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def skip_if(&block)
+        @_skip_predicate = block
+      end
+
+      def _skip_predicate
+        @_skip_predicate
+      end
+
+      # Returns true if this step should be skipped for the given ctx.
+      def skip?(ctx)
+        @_skip_predicate ? @_skip_predicate.call(ctx) : false
+      end
+    end
+  end
+end

data/lib/easyop/version.rb

@@ -0,0 +1,3 @@
+module Easyop
+  VERSION = "0.1.0"
+end

data/lib/easyop.rb

@@ -0,0 +1,41 @@
+require_relative "easyop/version"
+require_relative "easyop/configuration"
+require_relative "easyop/ctx"
+require_relative "easyop/hooks"
+require_relative "easyop/rescuable"
+require_relative "easyop/skip"
+require_relative "easyop/schema"
+require_relative "easyop/operation"
+require_relative "easyop/flow_builder"
+require_relative "easyop/flow"
+
+# Optional plugins — not auto-required
+# require_relative "easyop/plugins/transactional"
+
+# Optional plugins — require explicitly or via Bundler:
+# require "easyop/plugins/base"
+# require "easyop/plugins/instrumentation"
+# require "easyop/plugins/recording"
+# require "easyop/plugins/async"
+
+module Easyop
+  # Convenience: inherit from this instead of including Easyop::Operation
+  # when you want a common base class for all your operations.
+  #
+  #   class ApplicationOperation
+  #     include Easyop::Operation
+  #
+  #     rescue_from StandardError, with: :handle_unexpected
+  #
+  #     private
+  #
+  #     def handle_unexpected(e)
+  #       Sentry.capture_exception(e)
+  #       ctx.fail!(error: "An unexpected error occurred")
+  #     end
+  #   end
+  #
+  #   class MyOp < ApplicationOperation
+  #     ...
+  #   end
+end