tasker-engine 1.0.0

data/lib/tasker/analysis/template_graph_analyzer.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Analysis
+    # Analyzes step template dependencies for workflow design validation
+    #
+    # This class provides comprehensive analysis of step template dependencies,
+    # including cycle detection, topological sorting, and dependency visualization.
+    # It's designed to help with workflow design validation and troubleshooting.
+    #
+    # The analyzer performs static analysis on step templates to identify potential
+    # issues before workflow execution, including circular dependencies, dependency
+    # depth analysis, and parallel execution opportunities.
+    #
+    # @example Basic usage
+    #   analyzer = TemplateGraphAnalyzer.new(handler.step_templates)
+    #   graph = analyzer.analyze
+    #   puts "Cycles detected: #{graph[:cycles].any?}"
+    #
+    # @example Checking for specific issues
+    #   analyzer = TemplateGraphAnalyzer.new(templates)
+    #   if analyzer.has_cycles?
+    #     puts "Circular dependencies found: #{analyzer.cycles}"
+    #   end
+    #
+    # @since 2.2.0
+    class TemplateGraphAnalyzer
+      # @return [Array<Tasker::Types::StepTemplate>] The step templates being analyzed
+      attr_reader :templates
+
+      # Initialize the analyzer with step templates
+      #
+      # @param templates [Array<Tasker::Types::StepTemplate>] Step templates to analyze
+      def initialize(templates)
+        @templates = templates
+        @dependency_map = nil
+        @analysis_cache = nil
+      end
+
+      # Perform comprehensive dependency analysis
+      #
+      # @return [Hash] Comprehensive dependency analysis containing:
+      #   - :nodes - Array of step information with dependencies
+      #   - :edges - Array of dependency relationships
+      #   - :topology - Topologically sorted step names
+      #   - :cycles - Array of detected circular dependencies
+      #   - :levels - Hash mapping steps to their dependency depth levels
+      #   - :roots - Array of steps with no dependencies
+      #   - :leaves - Array of steps with no dependents
+      #   - :summary - Summary statistics
+      def analyze
+        return @analysis_cache if @analysis_cache
+
+        nodes = build_nodes
+        edges = build_edges
+        dependency_map = build_dependency_map
+        cycles = detect_cycles(dependency_map)
+        topology = cycles.empty? ? topological_sort(dependency_map) : []
+        levels = calculate_dependency_levels(dependency_map, topology)
+        roots = find_root_steps
+        leaves = find_leaf_steps(edges)
+
+        @analysis_cache = {
+          nodes: nodes,
+          edges: edges,
+          topology: topology,
+          cycles: cycles,
+          levels: levels,
+          roots: roots,
+          leaves: leaves,
+          summary: build_summary(cycles, levels, edges)
+        }
+      end
+
+      # Check if the workflow has circular dependencies
+      #
+      # @return [Boolean] True if cycles are detected
+      def has_cycles?
+        cycles.any?
+      end
+
+      # Get detected circular dependencies
+      #
+      # @return [Array<Array<String>>] Array of detected cycles
+      def cycles
+        analyze[:cycles]
+      end
+
+      # Get topological ordering of steps
+      #
+      # @return [Array<String>] Topologically sorted step names
+      def topology
+        analyze[:topology]
+      end
+
+      # Get dependency levels for all steps
+      #
+      # @return [Hash<String, Integer>] Step name to dependency level mapping
+      def levels
+        analyze[:levels]
+      end
+
+      # Get steps with no dependencies (workflow entry points)
+      #
+      # @return [Array<String>] Root step names
+      def roots
+        analyze[:roots]
+      end
+
+      # Get steps with no dependents (workflow exit points)
+      #
+      # @return [Array<String>] Leaf step names
+      def leaves
+        analyze[:leaves]
+      end
+
+      # Clear analysis cache (useful if templates change)
+      #
+      # @return [void]
+      def clear_cache!
+        @analysis_cache = nil
+        @dependency_map = nil
+      end
+
+      private
+
+      # Build nodes with dependency information
+      #
+      # @return [Array<Hash>] Node information for each step
+      # @api private
+      def build_nodes
+        templates.map do |template|
+          {
+            name: template.name,
+            description: template.description,
+            handler_class: template.handler_class.name,
+            dependencies: template.all_dependencies,
+            dependency_count: template.all_dependencies.size
+          }
+        end
+      end
+
+      # Build edges (dependency relationships)
+      #
+      # @return [Array<Hash>] Edge information for dependencies
+      # @api private
+      def build_edges
+        edges = []
+        templates.each do |template|
+          template.all_dependencies.each do |dependency|
+            edges << {
+              from: dependency,
+              to: template.name,
+              type: template.depends_on_step == dependency ? 'single' : 'multiple'
+            }
+          end
+        end
+        edges
+      end
+
+      # Build dependency map from step templates
+      #
+      # @return [Hash<String, Array<String>>] Map of step name to its dependencies
+      # @api private
+      def build_dependency_map
+        return @dependency_map if @dependency_map
+
+        @dependency_map = templates.each_with_object({}) do |template, map|
+          map[template.name] = template.all_dependencies
+        end
+      end
+
+      # Detect circular dependencies using depth-first search
+      #
+      # @param dependency_map [Hash<String, Array<String>>] Step dependencies
+      # @return [Array<Array<String>>] Array of detected cycles
+      # @api private
+      def detect_cycles(dependency_map)
+        cycles = []
+        visited = Set.new
+        rec_stack = Set.new
+
+        dependency_map.each_key do |step|
+          next if visited.include?(step)
+
+          cycle = find_cycle_from_step(step, dependency_map, visited, rec_stack, [])
+          cycles << cycle if cycle
+        end
+
+        cycles
+      end
+
+      # Find cycle starting from a specific step
+      #
+      # @param step [String] Starting step name
+      # @param dependency_map [Hash] Step dependencies
+      # @param visited [Set] Visited steps
+      # @param rec_stack [Set] Recursion stack
+      # @param path [Array] Current path
+      # @return [Array<String>, nil] Cycle path or nil
+      # @api private
+      def find_cycle_from_step(step, dependency_map, visited, rec_stack, path)
+        return nil if visited.include?(step)
+
+        visited.add(step)
+        rec_stack.add(step)
+        current_path = path + [step]
+
+        dependency_map[step].each do |dependency|
+          if rec_stack.include?(dependency)
+            # Found cycle - return the cycle portion
+            cycle_start = current_path.index(dependency)
+            return current_path[cycle_start..] + [dependency]
+          end
+
+          cycle = find_cycle_from_step(dependency, dependency_map, visited, rec_stack, current_path)
+          return cycle if cycle
+        end
+
+        rec_stack.delete(step)
+        nil
+      end
+
+      # Perform topological sort of steps using Kahn's algorithm
+      #
+      # @param dependency_map [Hash<String, Array<String>>] Step dependencies
+      # @return [Array<String>] Topologically sorted step names
+      # @api private
+      def topological_sort(dependency_map)
+        in_degree = Hash.new(0)
+        reverse_deps = Hash.new { |h, k| h[k] = [] }
+
+        # Calculate in-degrees and reverse dependencies
+        dependency_map.each do |step, dependencies|
+          in_degree[step] ||= 0
+          dependencies.each do |dep|
+            in_degree[step] += 1
+            reverse_deps[dep] << step
+          end
+        end
+
+        # Start with steps that have no dependencies
+        queue = dependency_map.keys.select { |step| in_degree[step].zero? }
+        result = []
+
+        while queue.any?
+          current = queue.shift
+          result << current
+
+          # Remove edges from current step to its dependents
+          reverse_deps[current].each do |dependent|
+            in_degree[dependent] -= 1
+            queue << dependent if in_degree[dependent].zero?
+          end
+        end
+
+        result
+      end
+
+      # Calculate dependency levels for each step
+      #
+      # @param dependency_map [Hash<String, Array<String>>] Step dependencies
+      # @param topology [Array<String>] Topologically sorted steps
+      # @return [Hash<String, Integer>] Step name to dependency level
+      # @api private
+      def calculate_dependency_levels(dependency_map, topology)
+        levels = {}
+
+        topology.each do |step|
+          if dependency_map[step].empty?
+            levels[step] = 0
+          else
+            max_dependency_level = dependency_map[step].map { |dep| levels[dep] || 0 }.max
+            levels[step] = max_dependency_level + 1
+          end
+        end
+
+        levels
+      end
+
+      # Find steps with no dependencies
+      #
+      # @return [Array<String>] Root step names
+      # @api private
+      def find_root_steps
+        dependency_map = build_dependency_map
+        dependency_map.keys.select { |name| dependency_map[name].empty? }
+      end
+
+      # Find steps with no dependents
+      #
+      # @param edges [Array<Hash>] Dependency edges
+      # @return [Array<String>] Leaf step names
+      # @api private
+      def find_leaf_steps(edges)
+        step_names = templates.map(&:name)
+        step_names.reject { |name| edges.any? { |edge| edge[:from] == name } }
+      end
+
+      # Build summary statistics
+      #
+      # @param cycles [Array] Detected cycles
+      # @param levels [Hash] Dependency levels
+      # @param edges [Array] Dependency edges
+      # @return [Hash] Summary statistics
+      # @api private
+      def build_summary(cycles, levels, edges)
+        {
+          total_steps: templates.size,
+          total_dependencies: edges.size,
+          has_cycles: cycles.any?,
+          max_depth: levels.values.max || 0,
+          parallel_branches: count_parallel_branches(levels)
+        }
+      end
+
+      # Count parallel branches in the dependency graph
+      #
+      # @param levels [Hash<String, Integer>] Dependency levels
+      # @return [Integer] Number of parallel execution branches
+      # @api private
+      def count_parallel_branches(levels)
+        level_counts = levels.values.group_by(&:itself).transform_values(&:size)
+        level_counts.values.max || 1
+      end
+    end
+  end
+end

data/lib/tasker/authentication/coordinator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'none_authenticator'
+
+module Tasker
+  module Authentication
+    class Coordinator
+      class << self
+        def authenticator
+          @authenticator ||= build_authenticator
+        end
+
+        delegate :authenticate!, to: :authenticator
+
+        delegate :current_user, to: :authenticator
+
+        delegate :authenticated?, to: :authenticator
+
+        def reset!
+          @authenticator = nil
+        end
+
+        private
+
+        def build_authenticator
+          auth_config = Tasker.configuration.auth
+
+          if auth_config.authentication_enabled
+            build_custom_authenticator(auth_config)
+          else
+            NoneAuthenticator.new
+          end
+        end
+
+        def build_custom_authenticator(auth_config)
+          authenticator_class = auth_config.authenticator_class
+
+          unless authenticator_class
+            raise ConfigurationError,
+                  'Authentication is enabled but no authenticator_class is specified'
+          end
+
+          # Instantiate the host app's authenticator
+          klass = authenticator_class.constantize
+          # Pass empty options hash for now - authenticators can get config from Tasker.configuration
+          authenticator = klass.new({})
+
+          # Validate it implements the interface
+          validate_authenticator!(authenticator)
+
+          authenticator
+        end
+
+        def validate_authenticator!(authenticator)
+          required_methods = %i[authenticate! current_user]
+
+          required_methods.each do |method|
+            unless authenticator.respond_to?(method)
+              raise InterfaceError,
+                    "Authenticator #{authenticator.class} must implement ##{method}"
+            end
+          end
+
+          # Run configuration validation if supported
+          return unless authenticator.respond_to?(:validate_configuration)
+
+          # Pass configuration options for validation - authenticators can extract what they need
+          errors = authenticator.validate_configuration({})
+          return unless errors.any?
+
+          raise ConfigurationError,
+                "Authenticator configuration errors: #{errors.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/tasker/authentication/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Authentication
+    class AuthenticationError < StandardError; end
+    class ConfigurationError < StandardError; end
+    class InterfaceError < StandardError; end
+  end
+end

data/lib/tasker/authentication/interface.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Authentication
+    # Interface that host application authenticators must implement
+    module Interface
+      # Required: Authenticate the request, raise exception if fails
+      # @param controller [ActionController::Base] The controller instance
+      # @return [void] Should raise exception on authentication failure
+      def authenticate!(controller)
+        raise NotImplementedError, 'Authenticator must implement #authenticate!'
+      end
+
+      # Required: Get the current authenticated user
+      # @param controller [ActionController::Base] The controller instance
+      # @return [Object, nil] The authenticated user object or nil
+      def current_user(controller)
+        raise NotImplementedError, 'Authenticator must implement #current_user'
+      end
+
+      # Optional: Check if user is authenticated (uses current_user by default)
+      # @param controller [ActionController::Base] The controller instance
+      # @return [Boolean] true if authenticated, false otherwise
+      def authenticated?(controller)
+        current_user(controller).present?
+      end
+
+      # Optional: Configuration validation for the authenticator
+      # @param _options [Hash] Configuration options (unused in default implementation)
+      # @return [Array<String>] Array of validation error messages, empty if valid
+      def validate_configuration(_options = {})
+        []
+      end
+    end
+  end
+end

data/lib/tasker/authentication/none_authenticator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'interface'
+
+module Tasker
+  module Authentication
+    class NoneAuthenticator
+      include Interface
+
+      def authenticate!(_controller)
+        # No authentication required - always succeeds
+        true
+      end
+
+      def current_user(_controller)
+        # No user in no-auth mode
+        nil
+      end
+
+      def authenticated?(_controller)
+        # Always considered "authenticated" in no-auth mode
+        true
+      end
+    end
+  end
+end

data/lib/tasker/authorization/base_coordinator.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Authorization
+    # Base authorization coordinator providing the foundation for authorization logic.
+    #
+    # This class implements the core authorization interface that can be extended
+    # by host applications to provide custom authorization logic. It follows the
+    # same dependency injection pattern as the authentication system.
+    #
+    # Host applications should inherit from this class and implement the
+    # `authorized?` method to provide their authorization logic.
+    #
+    # @example Basic usage
+    #   coordinator = BaseCoordinator.new(current_user)
+    #   coordinator.authorize!('tasker.task', :show, { task_id: 123 })
+    #
+    # @example Custom implementation
+    #   class MyAuthorizationCoordinator < BaseCoordinator
+    #     protected
+    #
+    #     def authorized?(resource, action, context = {})
+    #       case resource
+    #       when 'tasker.task'
+    #         user.can_access_tasks?
+    #       else
+    #         false
+    #       end
+    #     end
+    #   end
+    class BaseCoordinator
+      # Initialize the authorization coordinator
+      #
+      # @param user [Object, nil] The user object to authorize against
+      def initialize(user = nil)
+        @user = user
+      end
+
+      # Authorize an action and raise an exception if not permitted
+      #
+      # This method checks authorization and raises an UnauthorizedError
+      # if the action is not permitted.
+      #
+      # @param resource [String] The resource being accessed (e.g., 'tasker.task')
+      # @param action [Symbol, String] The action being performed (e.g., :show)
+      # @param context [Hash] Additional context for authorization decisions
+      # @raise [UnauthorizedError] When the action is not authorized
+      # @return [true] When the action is authorized
+      def authorize!(resource, action, context = {})
+        unless can?(resource, action, context)
+          raise UnauthorizedError,
+                "Not authorized to #{action} on #{resource}"
+        end
+
+        true
+      end
+
+      # Check if an action is authorized
+      #
+      # This method performs the authorization check without raising an exception.
+      # It validates the resource and action exist, then delegates to the
+      # `authorized?` method for the actual authorization logic.
+      #
+      # @param resource [String] The resource being accessed
+      # @param action [Symbol, String] The action being performed
+      # @param context [Hash] Additional context for authorization decisions
+      # @return [Boolean] True if the action is authorized
+      def can?(resource, action, context = {})
+        # Allow all actions if authorization is disabled
+        return true unless authorization_enabled?
+
+        # Validate resource and action exist in the registry
+        unless ResourceRegistry.action_exists?(resource, action)
+          raise ArgumentError, "Unknown resource:action '#{resource}:#{action}'"
+        end
+
+        # Delegate to subclass implementation
+        authorized?(resource, action, context)
+      end
+
+      protected
+
+      # Authorization logic to be implemented by subclasses
+      #
+      # This method should be overridden by host applications to provide
+      # their specific authorization logic. The default implementation
+      # denies all access.
+      #
+      # @param _resource [String] The resource being accessed (unused in base implementation)
+      # @param _action [Symbol, String] The action being performed (unused in base implementation)
+      # @param _context [Hash] Additional context for authorization decisions (unused in base implementation)
+      # @return [Boolean] True if the action should be authorized
+      def authorized?(_resource, _action, _context = {})
+        # Default implementation: deny all access
+        # Subclasses should override this method
+        false
+      end
+
+      # Check if authorization is enabled in the configuration
+      #
+      # @return [Boolean] True if authorization is enabled
+      def authorization_enabled?
+        Tasker.configuration.auth.authorization_enabled
+      end
+
+      # The user object for authorization checks
+      #
+      # @return [Object, nil] The current user
+      attr_reader :user
+    end
+  end
+end

data/lib/tasker/authorization/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Authorization
+    # Base error class for all authorization-related errors
+    class AuthorizationError < StandardError; end
+
+    # Raised when a user is not authorized to perform a specific action
+    #
+    # This error should be raised when authorization checks fail, typically
+    # resulting in a 403 Forbidden HTTP response.
+    #
+    # @example
+    #   raise UnauthorizedError, "Not authorized to delete task 123"
+    class UnauthorizedError < AuthorizationError; end
+
+    # Raised when authorization configuration is invalid
+    #
+    # This error indicates problems with the authorization setup, such as
+    # missing coordinator classes or invalid configuration options.
+    #
+    # @example
+    #   raise ConfigurationError, "Authorization coordinator class 'InvalidClass' not found"
+    class ConfigurationError < AuthorizationError; end
+  end
+end

data/lib/tasker/authorization/resource_constants.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Authorization
+    # Constants for authorization resource names and actions.
+    #
+    # This module provides centralized constants for all authorization
+    # resource identifiers, making the codebase more maintainable and
+    # reducing the risk of typos in resource strings.
+    #
+    # @example Using resource constants
+    #   coordinator.authorize!(RESOURCES::TASK, ACTIONS::SHOW)
+    #   ResourceRegistry.resource_exists?(RESOURCES::WORKFLOW_STEP)
+    module ResourceConstants
+      # Resource name constants
+      module RESOURCES
+        TASK = 'tasker.task'
+        WORKFLOW_STEP = 'tasker.workflow_step'
+        TASK_DIAGRAM = 'tasker.task_diagram'
+        HEALTH_STATUS = 'tasker.health_status'
+        HANDLER = 'tasker.handler'
+        METRICS = 'tasker.metrics'
+        ANALYTICS = 'tasker.analytics'
+
+        # Get all resource constants as an array
+        #
+        # @return [Array<String>] All defined resource names
+        def self.all
+          [TASK, WORKFLOW_STEP, TASK_DIAGRAM, HEALTH_STATUS, HANDLER, METRICS, ANALYTICS]
+        end
+
+        # Check if a resource constant is defined
+        #
+        # @param resource [String] Resource name to check
+        # @return [Boolean] True if the resource is defined
+        def self.include?(resource)
+          all.include?(resource)
+        end
+      end
+
+      # Common action constants used across resources
+      module ACTIONS
+        INDEX = :index
+        SHOW = :show
+        CREATE = :create
+        UPDATE = :update
+        DESTROY = :destroy
+        RETRY = :retry
+        CANCEL = :cancel
+
+        # Standard CRUD actions
+        #
+        # @return [Array<Symbol>] Standard CRUD action symbols
+        def self.crud
+          [INDEX, SHOW, CREATE, UPDATE, DESTROY]
+        end
+
+        # Task-specific actions
+        #
+        # @return [Array<Symbol>] Actions specific to tasks
+        def self.task_specific
+          [RETRY, CANCEL]
+        end
+
+        # All defined actions
+        #
+        # @return [Array<Symbol>] All action constants
+        def self.all
+          [INDEX, SHOW, CREATE, UPDATE, DESTROY, RETRY, CANCEL]
+        end
+      end
+    end
+  end
+end