tasker-rb 0.1.1

data/lib/tasker_core/registry/resolvers/method_dispatch_wrapper.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module Registry
+    module Resolvers
+      # TAS-93: Method Dispatch Wrapper
+      #
+      # Wraps a handler to redirect the standard `.call()` interface to
+      # a specified method name. This enables handlers with multiple
+      # entry points (e.g., process, refund, validate) to be invoked
+      # through the unified `.call()` interface.
+      #
+      # == Background
+      #
+      # The worker execution system always invokes `handler.call(context)`.
+      # When a HandlerDefinition specifies `method: refund`, we need to
+      # redirect that call to `handler.refund(context)`.
+      #
+      # == Usage
+      #
+      #   # Original handler
+      #   class PaymentHandler
+      #     def process(context); end
+      #     def refund(context); end
+      #   end
+      #
+      #   # Wrap for refund dispatch
+      #   handler = PaymentHandler.new
+      #   wrapped = MethodDispatchWrapper.new(handler, :refund)
+      #
+      #   # Now call() invokes refund()
+      #   wrapped.call(context) # => handler.refund(context)
+      #
+      # == When Wrapping Occurs
+      #
+      # The ResolverChain automatically wraps handlers when:
+      # - HandlerDefinition has `method` set to something other than 'call'
+      # - The resolved handler doesn't already respond to `.call()`
+      #
+      class MethodDispatchWrapper
+        attr_reader :handler, :target_method
+
+        # Create a method dispatch wrapper
+        #
+        # @param handler [Object] The underlying handler instance
+        # @param target_method [Symbol, String] Method to invoke on call()
+        def initialize(handler, target_method)
+          @handler = handler
+          @target_method = target_method.to_sym
+          validate!
+        end
+
+        # Invoke the target method on the wrapped handler
+        #
+        # @param args [Array] Arguments to pass through
+        # @param kwargs [Hash] Keyword arguments to pass through
+        # @param block [Proc] Block to pass through
+        # @return [Object] Result from the target method
+        def call(*, **kwargs, &)
+          if kwargs.empty?
+            @handler.public_send(@target_method, *, &)
+          else
+            @handler.public_send(@target_method, *, **kwargs, &)
+          end
+        end
+
+        # Delegate respond_to? to the underlying handler
+        #
+        # @param method_name [Symbol] Method to check
+        # @param include_private [Boolean] Include private methods
+        # @return [Boolean]
+        # rubocop:disable Style/OptionalBooleanParameter -- Must match Ruby's respond_to? signature
+        def respond_to?(method_name, include_private = false)
+          method_name.to_sym == :call || @handler.respond_to?(method_name, include_private)
+        end
+        # rubocop:enable Style/OptionalBooleanParameter
+
+        # Delegate respond_to_missing? to the underlying handler
+        def respond_to_missing?(method_name, include_private = false)
+          @handler.respond_to_missing?(method_name, include_private)
+        end
+
+        # Forward method_missing to underlying handler for delegation
+        #
+        # @param method_name [Symbol] Method name
+        # @param args [Array] Arguments
+        # @param block [Proc] Block
+        def method_missing(method_name, *, &)
+          if @handler.respond_to?(method_name)
+            @handler.public_send(method_name, *, &)
+          else
+            super
+          end
+        end
+
+        # String representation for debugging
+        #
+        # @return [String]
+        def to_s
+          "#<MethodDispatchWrapper handler=#{@handler.class} method=#{@target_method}>"
+        end
+
+        # Inspect for debugging
+        #
+        # @return [String]
+        def inspect
+          to_s
+        end
+
+        # Access the underlying handler class
+        #
+        # @return [Class]
+        def handler_class
+          @handler.class
+        end
+
+        # Check if this is wrapping a particular class
+        #
+        # @param klass [Class] Class to check
+        # @return [Boolean]
+        def wraps?(klass)
+          @handler.is_a?(klass)
+        end
+
+        # Unwrap to get the original handler
+        #
+        # @return [Object] The underlying handler
+        def unwrap
+          @handler
+        end
+
+        private
+
+        # Validate the wrapper can dispatch to target method
+        def validate!
+          return if @handler.respond_to?(@target_method)
+
+          raise ArgumentError,
+                "Handler #{@handler.class} does not respond to ##{@target_method}"
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/registry/resolvers/registry_resolver.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative 'base_resolver'
+
+module TaskerCore
+  module Registry
+    module Resolvers
+      # TAS-93: Developer-Friendly Base Class for Custom Resolvers
+      #
+      # RegistryResolver provides a DSL for creating custom handler resolvers
+      # with pattern matching, prefix matching, and explicit handler registration.
+      #
+      # == Usage Examples
+      #
+      # === Pattern-Based Resolution
+      #
+      #   class PaymentResolver < RegistryResolver
+      #     # Match handlers by pattern
+      #     handles_pattern(/^Payments::.*Handler$/)
+      #
+      #     # Custom resolution logic
+      #     def resolve_handler(definition, config)
+      #       klass = definition.callable.constantize
+      #       klass.new(config: definition.initialization)
+      #     end
+      #   end
+      #
+      # === Prefix-Based Resolution
+      #
+      #   class LegacyResolver < RegistryResolver
+      #     handles_prefix 'Legacy::'
+      #     priority_value 50
+      #
+      #     def resolve_handler(definition, config)
+      #       # Custom instantiation for legacy handlers
+      #       LegacyAdapter.wrap(definition.callable.constantize)
+      #     end
+      #   end
+      #
+      # === Explicit Handler Registration
+      #
+      #   class ExplicitResolver < RegistryResolver
+      #     register_handler 'payment.process', PaymentHandler
+      #     register_handler 'payment.refund', RefundHandler
+      #   end
+      #
+      # == DSL Methods
+      #
+      # - `handles_pattern(regex)` - Match callable names by regex
+      # - `handles_prefix(prefix)` - Match callable names by prefix
+      # - `register_handler(key, handler)` - Explicit key → handler mapping
+      # - `priority_value(n)` - Set resolver priority (default: 50)
+      # - `resolver_name(name)` - Set human-readable name
+      #
+      class RegistryResolver < BaseResolver
+        class << self
+          # DSL: Set pattern to match callable names
+          def handles_pattern(pattern)
+            @pattern = pattern
+          end
+
+          # DSL: Set prefix to match callable names
+          def handles_prefix(prefix)
+            @prefix = prefix
+          end
+
+          # DSL: Register explicit handler mapping
+          def register_handler(key, handler_or_class)
+            @handlers ||= {}
+            @handlers[key.to_s] = handler_or_class
+          end
+
+          # DSL: Set resolver priority
+          def priority_value(value)
+            @priority = value
+          end
+
+          # DSL: Set resolver name
+          def resolver_name(value)
+            @resolver_name = value
+          end
+
+          # Accessors for DSL values
+          attr_reader :pattern, :prefix, :handlers
+
+          def configured_priority
+            @priority || 50 # Default: between explicit (10) and inferential (100)
+          end
+
+          def configured_name
+            @resolver_name || name.demodulize.underscore
+          end
+
+          # Inherit DSL configuration in subclasses
+          def inherited(subclass)
+            super
+            subclass.instance_variable_set(:@handlers, @handlers&.dup || {})
+          end
+        end
+
+        def initialize
+          super
+          @handlers = self.class.handlers&.dup || {}
+          @logger = TaskerCore::Logger.instance
+        end
+
+        # @return [String] Human-readable resolver name
+        def name
+          self.class.configured_name
+        end
+
+        # @return [Integer] Resolution priority
+        def priority
+          self.class.configured_priority
+        end
+
+        # Check if this resolver can handle the definition
+        #
+        # Resolution order:
+        # 1. Check explicit handler registration
+        # 2. Check pattern match
+        # 3. Check prefix match
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional context
+        # @return [Boolean]
+        def can_resolve?(definition, _config)
+          callable = definition.callable.to_s
+
+          # Check explicit registration
+          return true if @handlers.key?(callable)
+
+          # Check pattern
+          return true if self.class.pattern && callable.match?(self.class.pattern)
+
+          # Check prefix
+          return true if self.class.prefix && callable.start_with?(self.class.prefix)
+
+          false
+        end
+
+        # Resolve the handler from the definition
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional context
+        # @return [Object, nil] Handler instance or nil
+        def resolve(definition, config)
+          callable = definition.callable.to_s
+
+          # Try explicit registration first
+          if @handlers.key?(callable)
+            handler = @handlers[callable]
+            return instantiate_handler(handler, definition.initialization)
+          end
+
+          # Otherwise, delegate to subclass implementation
+          resolve_handler(definition, config)
+        rescue StandardError => e
+          @logger.debug("RegistryResolver #{name}: Failed to resolve '#{callable}': #{e.message}")
+          nil
+        end
+
+        # @return [Array<String>] List of explicitly registered callables
+        def registered_callables
+          @handlers.keys
+        end
+
+        # Register a handler at runtime
+        #
+        # @param key [String] Handler key/callable name
+        # @param handler [Object] Handler class or instance
+        def register(key, handler)
+          @handlers[key.to_s] = handler
+        end
+
+        # Unregister a handler at runtime
+        #
+        # @param key [String] Handler key to remove
+        # @return [Object, nil] Removed handler or nil
+        def unregister(key)
+          @handlers.delete(key.to_s)
+        end
+
+        protected
+
+        # Override in subclass to provide custom resolution logic
+        #
+        # This is called when no explicit handler is registered.
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional context
+        # @return [Object, nil] Handler instance or nil
+        def resolve_handler(_definition, _config)
+          nil # Default: no custom resolution
+        end
+
+        # Instantiate a handler with configuration
+        #
+        # Handles:
+        # - Classes with (config:) keyword arg
+        # - Classes with no-arg constructor
+        # - Already-instantiated objects
+        #
+        # @param handler [Class, Object] Handler class or instance
+        # @param initialization [Hash] Configuration to pass
+        # @return [Object] Handler instance
+        def instantiate_handler(handler, initialization)
+          return handler unless handler.is_a?(Class)
+
+          arity = handler.instance_method(:initialize).arity
+
+          if arity.positive? || (arity.negative? && accepts_config_kwarg?(handler))
+            handler.new(config: initialization || {})
+          else
+            handler.new
+          end
+        end
+
+        private
+
+        # Check if the class accepts config: keyword argument
+        def accepts_config_kwarg?(klass)
+          params = klass.instance_method(:initialize).parameters
+          params.any? { |type, name| %i[key keyreq].include?(type) && name == :config }
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/registry/resolvers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# TAS-93: Step Handler Resolver Infrastructure
+#
+# This module provides the resolver chain pattern for step handler resolution.
+# Resolvers are tried in priority order until one successfully resolves.
+#
+# == Built-in Resolvers
+#
+# - ExplicitMappingResolver (priority 10): Explicit key → handler mappings
+# - ClassConstantResolver (priority 100): Class path inference via const_get
+#
+# == Custom Resolvers
+#
+# Extend RegistryResolver for developer-friendly custom resolution:
+#
+#   class PaymentResolver < TaskerCore::Registry::Resolvers::RegistryResolver
+#     handles_pattern(/^Payments::/)
+#     priority_value 50
+#
+#     def resolve_handler(definition, config)
+#       # Custom resolution logic
+#     end
+#   end
+#
+# == Method Dispatch
+#
+# When HandlerDefinition specifies `method: refund`, the chain automatically
+# wraps the handler with MethodDispatchWrapper to redirect .call() → .refund()
+#
+require_relative 'resolvers/base_resolver'
+require_relative 'resolvers/registry_resolver'
+require_relative 'resolvers/explicit_mapping_resolver'
+require_relative 'resolvers/class_constant_resolver'
+require_relative 'resolvers/method_dispatch_wrapper'
+
+module TaskerCore
+  module Registry
+    module Resolvers
+    end
+  end
+end

data/lib/tasker_core/registry.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# TAS-93: Resolver chain infrastructure (load first - used by HandlerRegistry)
+require_relative 'registry/resolvers'
+require_relative 'registry/resolver_chain'
+
+require_relative 'registry/handler_registry'
+
+module TaskerCore
+  module Registry
+  end
+end

data/lib/tasker_core/step_handler/api.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'mixins'
+
+module TaskerCore
+  module StepHandler
+    # API step handler that provides HTTP functionality.
+    #
+    # ## TAS-112: Composition Pattern (DEPRECATED CLASS)
+    #
+    # This class is provided for backward compatibility. For new code, use the mixin pattern:
+    #
+    # ```ruby
+    # class MyApiHandler < TaskerCore::StepHandler::Base
+    #   include TaskerCore::StepHandler::Mixins::API
+    #
+    #   def call(context)
+    #     response = get('/users')
+    #     success(result: response.body)
+    #   end
+    # end
+    # ```
+    #
+    # ## Key Features
+    # - Faraday HTTP client with full configuration support
+    # - Automatic error classification (RetryableError vs PermanentError)
+    # - Retry-After header support for server-requested backoff
+    # - SSL configuration, headers, query parameters
+    class Api < Base
+      include Mixins::API
+
+      # Legacy process method for Rails engine compatibility
+      # New handlers should implement call(context) instead
+      #
+      # @param _task [Object] Task (unused, for Rails compatibility)
+      # @param _sequence [Object] Sequence (unused, for Rails compatibility)
+      # @param _step [Object] Step (unused, for Rails compatibility)
+      # @return [Faraday::Response] HTTP response object
+      def process(_task, _sequence, _step)
+        url = config[:url] || config['url']
+        response = connection.get(url)
+        process_response(response)
+        response
+      end
+    end
+  end
+end