fractor 0.1.6 → 0.1.7

data/lib/fractor/supervisor_logger.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Handles logging for Supervisor operations.
+  # Extracted from Supervisor to follow Single Responsibility Principle.
+  class SupervisorLogger
+    attr_reader :logger, :debug_enabled
+
+    def initialize(logger: :default, debug: false)
+      @logger = if logger == :default
+                  Fractor.logger
+                else
+                  logger
+                end
+      @debug_enabled = debug
+    end
+
+    # Log debug message (only when debug mode is enabled)
+    def debug(message)
+      return unless @debug_enabled
+
+      if @logger
+        @logger.debug("[Fractor] #{message}")
+      else
+        puts "[DEBUG] #{message}"
+      end
+    end
+
+    # Log info message
+    def info(message)
+      if @logger
+        @logger.info("[Fractor] #{message}")
+      else
+        puts "[INFO] #{message}"
+      end
+    end
+
+    # Log warning message
+    def warn(message)
+      if @logger
+        @logger.warn("[Fractor] #{message}")
+      else
+        Kernel.warn "[WARN] #{message}"
+      end
+    end
+
+    # Log error message
+    def error(message)
+      if @logger
+        @logger.error("[Fractor] #{message}")
+      else
+        Kernel.warn "[ERROR] #{message}"
+      end
+    end
+
+    # Log work item status
+    def log_work_added(work, total_count, queue_size)
+      debug "Work item added: #{work.inspect}"
+      debug "Initial work count: #{total_count}, Queue size: #{queue_size}"
+    end
+
+    # Log worker status
+    def log_worker_status(total:, idle:, busy:)
+      debug "Workers: #{total} total, #{idle} idle, #{busy} busy"
+    end
+
+    # Log processing status
+    def log_processing_status(processed:, total:, queue_size:)
+      debug "Processing: #{processed}/#{total}, Queue size: #{queue_size}"
+    end
+
+    # Log result received
+    def log_result_received(result)
+      debug "Result received: #{result.inspect}"
+    end
+
+    # Log error received
+    def log_error_received(error_result)
+      error "Error in worker: #{error_result.error}"
+      error "Work item: #{error_result.work.inspect}"
+    end
+
+    # Enable or disable debug mode
+    def debug=(enabled)
+      @debug_enabled = enabled
+    end
+  end
+end

data/lib/fractor/version.rb

@@ -2,5 +2,5 @@
 
 module Fractor
   # Fractor version
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

data/lib/fractor/work.rb

@@ -13,5 +13,17 @@ module Fractor
     def to_s
       "Work: #{@input}"
     end
+
+    # Provide detailed inspection of work item for debugging
+    # @return [String] Detailed inspection string
+    def inspect
+      details = [
+        "#<#{self.class.name}",
+        "0x#{(object_id << 1).to_s(16)}",
+        "@input=#{@input.inspect}",
+        "@type=#{input.class.name}",
+      ]
+      details.join(" ")
+    end
   end
 end

data/lib/fractor/work_distribution_manager.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Manages work distribution to workers in a Supervisor.
+  # Responsible for tracking idle workers and assigning work from the queue.
+  #
+  # This class extracts work distribution logic from Supervisor to follow
+  # the Single Responsibility Principle.
+  class WorkDistributionManager
+    attr_reader :idle_workers
+
+    def initialize(work_queue, workers, ractors_map, debug: false,
+                   continuous_mode: false, performance_monitor: nil)
+      @work_queue = work_queue
+      @workers = workers
+      @ractors_map = ractors_map
+      @debug = debug
+      @continuous_mode = continuous_mode
+      @performance_monitor = performance_monitor
+      @idle_workers = []
+      @work_start_times = {}
+    end
+
+    # Update the workers reference after workers are created
+    # This is needed when @workers is reassigned in Supervisor.start_workers
+    #
+    # @param workers [Array<WrappedRactor>] The new workers array
+    def update_workers(workers)
+      @workers = workers
+    end
+
+    # Assign work to a specific worker if work is available.
+    #
+    # @param wrapped_ractor [WrappedRactor] The worker to assign work to
+    # @return [Boolean] true if work was sent, false otherwise
+    def assign_work_to_worker(wrapped_ractor)
+      # Ensure the wrapped_ractor instance is valid and its underlying ractor is not closed
+      if wrapped_ractor && !wrapped_ractor.closed?
+        if @work_queue.empty?
+          puts "Work queue empty. Not sending new work to Ractor #{wrapped_ractor.name}." if @debug
+          false
+        else
+          work_item = @work_queue.pop # Now directly a Work object
+
+          # Track start time for performance monitoring
+          if @performance_monitor
+            @work_start_times[work_item.object_id] = Time.now
+          end
+
+          puts "Sending next work #{work_item.inspect} to Ractor: #{wrapped_ractor.name}." if @debug
+          wrapped_ractor.send(work_item) # Send the Work object
+          puts "Work sent to #{wrapped_ractor.name}." if @debug
+
+          # Remove from idle workers list since it's now busy
+          @idle_workers.delete(wrapped_ractor)
+          true
+        end
+      else
+        puts "Attempted to send work to an invalid or closed Ractor: #{wrapped_ractor&.name || 'unknown'}." if @debug
+        # Remove from map if found but closed
+        if wrapped_ractor && @ractors_map.key?(wrapped_ractor.ractor)
+          @ractors_map.delete(wrapped_ractor.ractor)
+        end
+        false
+      end
+    end
+
+    # Mark a worker as idle (available for work).
+    #
+    # @param wrapped_ractor [WrappedRactor] The worker to mark as idle
+    def mark_worker_idle(wrapped_ractor)
+      @idle_workers << wrapped_ractor unless @idle_workers.include?(wrapped_ractor)
+      puts "Worker #{wrapped_ractor.name} marked as idle." if @debug
+    end
+
+    # Mark a worker as busy (not available for work).
+    #
+    # @param wrapped_ractor [WrappedRactor] The worker to mark as busy
+    def mark_worker_busy(wrapped_ractor)
+      @idle_workers.delete(wrapped_ractor)
+    end
+
+    # Distribute available work to idle workers.
+    # Useful when new work is added to the queue.
+    #
+    # @return [Integer] Number of workers that received work
+    def distribute_to_idle_workers
+      distributed = 0
+      while !@work_queue.empty? && !@idle_workers.empty?
+        worker = @idle_workers.shift
+        if assign_work_to_worker(worker)
+          puts "Sent work to idle worker #{worker.name}" if @debug
+          distributed += 1
+        end
+      end
+      distributed
+    end
+
+    # Get the list of idle (available) workers.
+    #
+    # @return [Array<WrappedRactor>] List of idle workers
+    def idle_workers_list
+      @idle_workers.dup
+    end
+
+    # Get the list of busy (processing) workers.
+    #
+    # @return [Array<WrappedRactor>] List of busy workers
+    def busy_workers_list
+      @workers.reject { |w| @idle_workers.include?(w) }
+    end
+
+    # Get the count of idle workers.
+    #
+    # @return [Integer] Number of idle workers
+    def idle_count
+      @idle_workers.size
+    end
+
+    # Get the count of busy workers.
+    #
+    # @return [Integer] Number of busy workers
+    def busy_count
+      @workers.size - @idle_workers.size
+    end
+
+    # Get the work start time for a specific work item.
+    #
+    # @param work_object_id [Integer] The object_id of the work item
+    # @return [Time, nil] The start time, or nil if not found
+    def get_work_start_time(work_object_id)
+      @work_start_times.delete(work_object_id)
+    end
+
+    # Clear all tracked work start times.
+    # Useful for cleanup or testing.
+    def clear_work_start_times
+      @work_start_times.clear
+    end
+
+    # Get current worker status summary.
+    #
+    # @return [Hash] Worker status summary with :idle and :busy counts
+    def status_summary
+      {
+        idle: @idle_workers.size,
+        busy: @workers.size - @idle_workers.size,
+      }
+    end
+  end
+end

data/lib/fractor/work_queue.rb

@@ -16,6 +16,13 @@ module Fractor
     # @param work_item [Fractor::Work] The work item to add
     # @return [void]
     def <<(work_item)
+      enqueue(work_item)
+    end
+
+    # Add a work item to the queue (standardized API)
+    # @param work_item [Fractor::Work] The work item to add
+    # @return [void]
+    def enqueue(work_item)
       unless work_item.is_a?(Fractor::Work)
         raise ArgumentError,
               "#{work_item.class} must be an instance of Fractor::Work"
@@ -28,6 +35,13 @@ module Fractor
     # @param max_items [Integer] Maximum number of items to retrieve
     # @return [Array<Fractor::Work>] Array of work items (may be empty)
     def pop_batch(max_items = 10)
+      dequeue_batch(max_items)
+    end
+
+    # Retrieve multiple work items from the queue in a single operation (standardized API)
+    # @param max_items [Integer] Maximum number of items to retrieve
+    # @return [Array<Fractor::Work>] Array of work items (may be empty)
+    def dequeue_batch(max_items = 10)
       items = []
       max_items.times do
         break if @queue.empty?
@@ -42,6 +56,12 @@ module Fractor
       items
     end
 
+    # Retrieve a single work item from the queue (blocking if empty)
+    # @return [Fractor::Work, nil] A work item or nil if queue is closed
+    def dequeue
+      @queue.pop
+    end
+
     # Check if the queue is empty
     # @return [Boolean] true if the queue is empty
     def empty?

data/lib/fractor/work_result.rb

@@ -2,34 +2,206 @@
 
 module Fractor
   # Represents the result of processing a Work item.
-  # Can hold either a successful result or an error.
+  # Can hold either a successful result or an error with rich metadata.
   class WorkResult
-    attr_reader :result, :error, :work
+    # Error severity levels
+    SEVERITY_CRITICAL = :critical  # System-breaking errors
+    SEVERITY_ERROR = :error        # Standard errors
+    SEVERITY_WARNING = :warning    # Non-fatal issues
+    SEVERITY_INFO = :info          # Informational
 
-    def initialize(result: nil, error: nil, work: nil)
+    # Error categories
+    CATEGORY_VALIDATION = :validation # Input validation errors
+    CATEGORY_TIMEOUT = :timeout          # Timeout errors
+    CATEGORY_NETWORK = :network          # Network-related errors
+    CATEGORY_RESOURCE = :resource        # Resource exhaustion
+    CATEGORY_BUSINESS = :business        # Business logic errors
+    CATEGORY_SYSTEM = :system            # System errors
+    CATEGORY_UNKNOWN = :unknown          # Unknown/uncategorized
+
+    attr_reader :result, :error, :work, :error_code, :error_context,
+                :error_category, :error_severity, :suggestion, :stack_trace
+
+    def initialize(
+      result: nil,
+      error: nil,
+      work: nil,
+      error_code: nil,
+      error_context: nil,
+      error_category: nil,
+      error_severity: nil,
+      suggestion: nil,
+      stack_trace: nil
+    )
       @result = result
       @error = error
       @work = work
+      @error_code = error_code
+      @error_context = error_context || {}
+      @error_category = error_category || infer_category(error)
+      @error_severity = error_severity || infer_severity(error)
+      @suggestion = suggestion || infer_suggestion(error)
+      @stack_trace = stack_trace || capture_stack_trace(error)
     end
 
     def success?
       !@error
     end
 
+    def failure?
+      !success?
+    end
+
+    # Check if error is critical
+    def critical?
+      @error_severity == SEVERITY_CRITICAL
+    end
+
+    # Check if error is retriable based on category
+    def retriable?
+      return false if success?
+
+      retriable_categories = [
+        CATEGORY_TIMEOUT,
+        CATEGORY_NETWORK,
+        CATEGORY_RESOURCE,
+      ]
+      retriable_categories.include?(@error_category)
+    end
+
+    # Get full error information as hash
+    def error_info
+      return nil if success?
+
+      {
+        error: @error,
+        error_class: @error&.class&.name,
+        error_message: @error&.message,
+        error_code: @error_code,
+        error_category: @error_category,
+        error_severity: @error_severity,
+        error_context: @error_context,
+        suggestion: @suggestion,
+        stack_trace: @stack_trace,
+      }
+    end
+
     def to_s
       if success?
         "Result: #{@result}"
       else
-        "Error: #{@error}, Work: #{@work}"
+        "Error: #{@error}, Code: #{@error_code}, Category: #{@error_category}, Severity: #{@error_severity}"
       end
     end
 
     def inspect
-      {
-        result: @result,
-        error: @error,
-        work: @work&.to_s, # Use safe navigation for work
-      }
+      if success?
+        {
+          result: @result,
+          work: @work&.to_s,
+        }
+      else
+        {
+          error: @error,
+          error_code: @error_code,
+          error_category: @error_category,
+          error_severity: @error_severity,
+          error_context: @error_context,
+          work: @work&.to_s,
+        }
+      end
+    end
+
+    private
+
+    # Infer error category from error type
+    def infer_category(error)
+      return nil unless error
+
+      case error
+      when ArgumentError, TypeError
+        CATEGORY_VALIDATION
+      when Timeout::Error
+        CATEGORY_TIMEOUT
+      when String
+        # Categorize string error messages by content
+        error_msg = error.downcase
+        if error_msg.include?("timeout") || error_msg.include?("timed out")
+          CATEGORY_TIMEOUT
+        elsif error_msg.include?("connection") || error_msg.include?("network") ||
+            error_msg.include?("socket") || error_msg.include?("refused")
+          CATEGORY_NETWORK
+        elsif error_msg.include?("memory") || error_msg.include?("space")
+          CATEGORY_RESOURCE
+        else
+          CATEGORY_UNKNOWN
+        end
+      when defined?(SocketError) ? SocketError : nil, Errno::ECONNREFUSED, Errno::ETIMEDOUT
+        CATEGORY_NETWORK
+      when Errno::ENOMEM, Errno::ENOSPC
+        CATEGORY_RESOURCE
+      when SystemCallError, SystemStackError
+        CATEGORY_SYSTEM
+      else
+        CATEGORY_UNKNOWN
+      end
+    end
+
+    # Infer error severity from error type
+    def infer_severity(error)
+      return nil unless error
+
+      case error
+      when SystemStackError, Errno::ENOMEM
+        SEVERITY_CRITICAL
+      when StandardError
+        SEVERITY_ERROR
+      else
+        SEVERITY_WARNING
+      end
+    end
+
+    # Infer suggestion from error type
+    def infer_suggestion(error)
+      return nil unless error
+
+      error_msg = error.to_s.downcase
+
+      case error_msg
+      when /negative number/i, /must be positive/i
+        "Ensure input values are positive. Consider using absolute value or validating input range."
+      when /timeout/i
+        "Consider increasing timeout duration or breaking work into smaller chunks."
+      when /memory/i, /out of memory/i
+        "Try processing smaller batches or increasing available memory."
+      when /connection/i, /network/i, /refused/i
+        "Verify network connectivity and service availability. Check firewall settings."
+      when /undefined method/i, /no method/i
+        "Ensure the Worker class implements all required methods for the Work type."
+      when /nil/i, /null/i
+        "Check if work items are being initialized with valid input data."
+      when /argument/i, /type/i
+        "Verify input data types match expected format. Check Work item initialization."
+      when /file/i, /not found/i
+        "Ensure file paths are correct and files exist before processing."
+      when /permission/i, /authorized/i
+        "Check file permissions and ensure proper access rights for the operation."
+      else
+        "Check the error message and ensure all requirements are met. Enable debug logging for more details."
+      end
+    end
+
+    # Capture stack trace from error if available
+    def capture_stack_trace(error)
+      return nil unless error
+
+      # If error is a string, return nil
+      return nil unless error.is_a?(Exception)
+
+      # Get backtrace from exception
+      error.backtrace
+    rescue StandardError
+      nil
     end
   end
 end

data/lib/fractor/worker.rb

@@ -1,17 +1,90 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Fractor
   # Base class for defining work processors.
   # Subclasses must implement the `process` method.
   class Worker
+    class << self
+      attr_reader :input_type_class, :output_type_class, :worker_timeout
+
+      # Declare the input type for this worker.
+      # Used by the workflow system to validate data flow.
+      #
+      # @param klass [Class] A Lutaml::Model::Serializable subclass
+      def input_type(klass)
+        validate_type_class!(klass, "input_type")
+        @input_type_class = klass
+      end
+
+      # Declare the output type for this worker.
+      # Used by the workflow system to validate data flow.
+      #
+      # @param klass [Class] A Lutaml::Model::Serializable subclass
+      def output_type(klass)
+        validate_type_class!(klass, "output_type")
+        @output_type_class = klass
+      end
+
+      # Set a timeout for this worker's process method.
+      # If the process method takes longer than this, a Timeout::Error will be raised.
+      #
+      # @param seconds [Numeric] Timeout in seconds
+      def timeout(seconds)
+        @worker_timeout = seconds
+      end
+
+      # Get the effective timeout for this worker.
+      # Returns the worker-specific timeout, or the global default if not set.
+      # Note: This method accesses Fractor.config and should be called from
+      # the main ractor context, not from within worker ractors.
+      #
+      # @return [Numeric, nil] Timeout in seconds, or nil if not configured
+      def effective_timeout
+        @worker_timeout || begin
+          # Access config safely - this must be called from main ractor
+          Fractor.config.default_worker_timeout
+        end
+      end
+
+      private
+
+      def validate_type_class!(klass, method_name)
+        # Allow any class for now, stricter validation can be added later
+        # In production, you'd want to check for Lutaml::Model::Serializable
+        return if klass.is_a?(Class)
+
+        raise ArgumentError, "#{method_name} must be a Class"
+      end
+    end
+
     def initialize(name: nil, **options)
       @name = name
       @options = options
+      # If timeout is not provided or is nil, fall back to class-level timeout
+      # Note: This must only be called from the main ractor, not from within worker ractors.
+      # In the ractor context, timeout should always be passed explicitly.
+      if !@options.key?(:timeout) || @options[:timeout].nil?
+        @options[:timeout] = self.class.worker_timeout
+      end
     end
 
     def process(work)
       raise NotImplementedError,
             "Subclasses must implement the 'process' method."
     end
+
+    # Get the timeout for this worker instance.
+    # Uses the class-level timeout if not overridden.
+    # Note: This method is safe to call from within ractors as it only
+    # accesses instance variables that were set at initialization time.
+    #
+    # @return [Numeric, nil] Timeout in seconds, or nil if not configured
+    def timeout
+      # The timeout is always set at initialization time via options,
+      # so we can safely access it from within the ractor
+      @options[:timeout]
+    end
   end
 end