activejob-temporal 0.1.0

data/lib/activejob/temporal/reload_signal_queue.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    class ReloadSignalQueue
+      POLL_INTERVAL_SECONDS = 0.05
+
+      def initialize
+        @pending_signal = nil
+        @closed = false
+      end
+
+      def push(signal)
+        return if @closed || @pending_signal
+
+        @pending_signal = signal
+        signal
+      end
+
+      def pop
+        loop do
+          return nil if @closed
+
+          if @pending_signal
+            signal = @pending_signal
+            @pending_signal = nil
+            return signal
+          end
+
+          sleep(POLL_INTERVAL_SECONDS)
+        end
+      end
+
+      def close
+        @closed = true
+        @pending_signal = nil
+      end
+    end
+  end
+end

data/lib/activejob/temporal/retry_handler_extractor.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require_relative "active_job_handler_source"
+require_relative "logger"
+
+module ActiveJob
+  module Temporal
+    # Extracts ActiveJob retry_on and discard_on handler declarations.
+    #
+    # This class introspects an ActiveJob class to find all retry_on and
+    # discard_on declarations, converting them into structured handler objects.
+    # It handles the complexity of ActiveJob's internal rescue_handlers mechanism,
+    # including binding inspection and exception class constantization.
+    #
+    # The extractor is used by RetryMapper to separate handler extraction logic
+    # from retry policy building logic, improving testability and maintainability.
+    #
+    # @note ActiveJob Compatibility
+    #   ActiveJob does not expose retry_on or discard_on metadata through a
+    #   public API. If retry metadata cannot be read, the extractor logs a warning
+    #   and returns nil retry values so RetryMapper can use configured defaults
+    #   instead of failing during enqueue.
+    #
+    # @example Extracting retry handlers
+    #   extractor = RetryHandlerExtractor.new
+    #   retry_handlers = extractor.retry_handlers(MyJob)
+    #   # => [{ exception: StandardError, wait: 5.seconds, attempts: 3, handler: ... }]
+    #
+    # @example Extracting discard handlers
+    #   discard_handlers = extractor.discard_handlers(MyJob)
+    #   # => [{ exception: ActiveRecord::RecordNotFound, handler: ... }]
+    # rubocop:disable Metrics/ClassLength
+    class RetryHandlerExtractor
+      def initialize
+        @cache_mutex = Mutex.new
+        @retry_handlers_by_job_class = ObjectSpace::WeakMap.new
+        @discard_handlers_by_job_class = ObjectSpace::WeakMap.new
+      end
+
+      # Extracts retry handler entries from a job class's rescue_handlers.
+      #
+      # Iterates through the job class's rescue_handlers and filters for retry_on
+      # declarations. Binding metadata is used when available; source-location
+      # fallback keeps enqueue working if ActiveJob changes closure locals.
+      #
+      # @param job_class [Class] ActiveJob class with retry_on declarations
+      #
+      # @return [Array<Hash>] Array of retry handler entries, each containing:
+      #   - :exception [Class] Exception class to match
+      #   - :wait [Numeric, Symbol, Proc] Wait strategy (duration, :exponentially_longer, etc.)
+      #   - :attempts [Integer, Symbol] Max attempts (number or :unlimited)
+      #   - :handler [Proc] The raw handler proc from ActiveJob
+      #
+      # @example Basic retry handler
+      #   class MyJob < ActiveJob::Base
+      #     retry_on StandardError, wait: 5.seconds, attempts: 3
+      #   end
+      #
+      #   extractor = RetryHandlerExtractor.new
+      #   handlers = extractor.retry_handlers(MyJob)
+      #   # => [{ exception: StandardError, wait: 5.0, attempts: 3, handler: #<Proc> }]
+      def retry_handlers(job_class)
+        cached_handler_entries(@retry_handlers_by_job_class, job_class) do |handlers|
+          handler_entries(job_class, handlers) do |class_or_name, handler|
+            retry_handler_payload(job_class, class_or_name, handler)
+          end
+        end
+      end
+
+      # Extracts discard handler entries from a job class's rescue_handlers.
+      #
+      # Iterates through the job class's rescue_handlers and filters for discard_on
+      # declarations. Returns structured handler entries with exception classes
+      # that should not be retried.
+      #
+      # @param job_class [Class] ActiveJob class with discard_on declarations
+      #
+      # @return [Array<Hash>] Array of discard handler entries, each containing:
+      #   - :exception [Class] Exception class to discard (not retry)
+      #   - :handler [Proc] The raw handler proc from ActiveJob
+      #
+      # @example Basic discard handler
+      #   class MyJob < ActiveJob::Base
+      #     discard_on ActiveRecord::RecordNotFound
+      #   end
+      #
+      #   extractor = RetryHandlerExtractor.new
+      #   handlers = extractor.discard_handlers(MyJob)
+      #   # => [{ exception: ActiveRecord::RecordNotFound, handler: #<Proc> }]
+      def discard_handlers(job_class)
+        cached_handler_entries(@discard_handlers_by_job_class, job_class) do |handlers|
+          handler_entries(job_class, handlers) do |class_or_name, handler|
+            discard_handler_payload(job_class, class_or_name, handler)
+          end
+        end
+      end
+
+      # Checks if an exception should be discarded based on job class handlers.
+      #
+      # Inspects the job class's discard_on declarations to determine if the given
+      # exception matches any discard handler. This is used to determine if an
+      # activity should raise a non-retryable error in Temporal.
+      #
+      # @param job_class [Class] ActiveJob class with discard_on declarations
+      # @param exception [Exception] Exception instance to check
+      #
+      # @return [Boolean] true if exception should be discarded, false otherwise
+      #
+      # @example Check if exception is discardable
+      #   class MyJob < ApplicationJob
+      #     discard_on ActiveRecord::RecordNotFound
+      #   end
+      #
+      #   extractor = RetryHandlerExtractor.new
+      #   extractor.discard_exception?(MyJob, ActiveRecord::RecordNotFound.new)
+      #   # => true
+      def discard_exception?(job_class, exception)
+        return false unless job_class && exception
+
+        discard_handlers(job_class).any? do |handler|
+          handles_exception?(handler[:exception], exception)
+        end
+      end
+
+      private
+
+      def cached_handler_entries(cache, job_class)
+        return [] unless job_class.respond_to?(:rescue_handlers)
+
+        handlers = job_class.rescue_handlers
+        return [] unless handlers.respond_to?(:reverse_each)
+
+        signature = rescue_handlers_signature(handlers)
+
+        @cache_mutex.synchronize do
+          cached = cache[job_class]
+          return cached[:entries] if cached && cached[:signature] == signature
+
+          entries = yield(handlers).map(&:freeze).freeze
+          cache[job_class] = { signature: signature, entries: entries }.freeze
+          entries
+        end
+      end
+
+      def rescue_handlers_signature(handlers)
+        handlers.reverse_each.map do |class_or_name, handler|
+          [class_or_name, handler.object_id]
+        end
+      end
+
+      # Generic handler entry extractor (used by retry_handlers and discard_handlers).
+      #
+      # Walks through the job class's rescue_handlers in reverse order (ActiveJob's
+      # precedence order: last declared = first matched) and yields each handler to
+      # the provided block for filtering and transformation.
+      #
+      # @api private
+      # @param job_class [Class] ActiveJob class
+      # @yield [handler] Block that filters and transforms each handler
+      # @return [Array<Hash>] Filtered and transformed handler entries
+      def handler_entries(job_class, handlers)
+        entries = []
+        handlers.reverse_each do |class_or_name, handler|
+          payload = yield(class_or_name, handler)
+          next unless payload
+
+          exception_class = constantize_handler_class(job_class, class_or_name)
+          next unless exception_class
+
+          entries << payload.merge(exception: exception_class)
+        end
+        entries
+      end
+
+      def retry_handler_payload(job_class, class_or_name, handler)
+        unless ActiveJobHandlerSource.supported?(:retry_on)
+          log_handler_source_unavailable("retry", job_class)
+          return nil
+        end
+
+        return nil unless retry_handler_source?(job_class, handler)
+
+        binding = handler_binding(handler)
+        payload = retry_payload_from_binding(binding)
+        return payload.merge(handler: handler) if payload.is_a?(Hash)
+
+        log_metadata_fallback("retry", job_class, class_or_name, "retry_on_metadata_unavailable")
+
+        {
+          handler: handler,
+          wait: fallback_binding_value(binding, :wait),
+          attempts: fallback_binding_value(binding, :attempts)
+        }
+      end
+
+      def discard_handler_payload(job_class, class_or_name, handler)
+        unless ActiveJobHandlerSource.supported?(:discard_on)
+          log_handler_source_unavailable("discard", job_class)
+          return nil
+        end
+
+        return nil unless discard_handler_source?(job_class, handler)
+
+        binding = handler_binding(handler)
+        return { handler: handler } if discard_handler_binding?(binding)
+
+        log_metadata_fallback("discard", job_class, class_or_name, "discard_on_metadata_unavailable")
+
+        { handler: handler }
+      end
+
+      def handler_binding(handler)
+        return nil unless handler.respond_to?(:binding)
+
+        handler.binding
+      rescue StandardError
+        nil
+      end
+
+      def retry_payload_from_binding(binding)
+        return nil unless binding
+        return nil unless local_variable_defined?(binding, :attempts)
+
+        {
+          wait: binding.local_variable_get(:wait),
+          attempts: binding.local_variable_get(:attempts)
+        }.merge(exception_execution_key_from_binding(binding))
+      rescue StandardError
+        nil
+      end
+
+      def exception_execution_key_from_binding(binding)
+        return {} unless local_variable_defined?(binding, :exceptions)
+
+        { exception_execution_key: binding.local_variable_get(:exceptions).to_s }
+      rescue StandardError
+        {}
+      end
+
+      def fallback_binding_value(binding, name)
+        return nil unless binding
+        return nil unless local_variable_defined?(binding, name)
+
+        binding.local_variable_get(name)
+      rescue StandardError
+        nil
+      end
+
+      def retry_handler_source?(job_class, handler)
+        handler_source_match?("retry", job_class, handler, :retry_on)
+      end
+
+      def discard_handler_source?(job_class, handler)
+        handler_source_match?("discard", job_class, handler, :discard_on)
+      end
+
+      def handler_source_match?(handler_type, job_class, handler, method_name)
+        case ActiveJobHandlerSource.match_status(handler, method_name)
+        when :match
+          true
+        when :unsupported
+          log_handler_source_unavailable(handler_type, job_class)
+          false
+        else
+          false
+        end
+      end
+
+      def log_metadata_fallback(handler_type, job_class, class_or_name, reason)
+        warning_key = [handler_type, job_class.name, class_or_name.to_s, reason]
+        @metadata_fallback_warnings ||= {}
+        return if @metadata_fallback_warnings[warning_key]
+
+        @metadata_fallback_warnings[warning_key] = true
+        ActiveJob::Temporal::Logger.warn(
+          "active_job_handler_metadata_fallback",
+          handler_type: handler_type,
+          job_class: job_class.name,
+          exception: class_or_name.to_s,
+          reason: reason
+        )
+      rescue StandardError
+        nil
+      end
+
+      def log_handler_source_unavailable(handler_type, job_class)
+        warning_key = [handler_type, job_class.name, "handler_source_unavailable"]
+        @metadata_fallback_warnings ||= {}
+        return if @metadata_fallback_warnings[warning_key]
+
+        @metadata_fallback_warnings[warning_key] = true
+        ActiveJob::Temporal::Logger.warn(
+          "active_job_handler_source_unavailable",
+          handler_type: handler_type,
+          job_class: job_class.name,
+          reason: "active_job_handler_source_unavailable"
+        )
+      rescue StandardError
+        nil
+      end
+
+      # Checks if a binding represents a discard handler.
+      #
+      # Current ActiveJob exposes :report in discard_on handler bindings. Older
+      # versions did not, so source-location fallback handles those declarations.
+      #
+      # @api private
+      # @param binding [Binding] Handler proc's binding
+      # @return [Boolean] true if binding represents a discard handler
+      def discard_handler_binding?(binding)
+        local_variable_defined?(binding, :report) && !local_variable_defined?(binding, :attempts)
+      end
+
+      def local_variable_defined?(binding, name)
+        binding&.local_variable_defined?(name)
+      rescue StandardError
+        false
+      end
+
+      # Constantizes exception class from symbol/string/module.
+      #
+      # ActiveJob stores exception handlers with various types (Module, String, Symbol).
+      # This method normalizes them to actual exception classes, handling both
+      # relative constants (defined in job class) and global constants.
+      #
+      # @api private
+      # @param job_class [Class] Job class for relative constant lookup
+      # @param class_or_name [Module, String, Symbol] Exception class or name
+      # @return [Class, nil] Constantized exception class, or nil if not found
+      def constantize_handler_class(job_class, class_or_name)
+        case class_or_name
+        when Module
+          class_or_name
+        when String, Symbol
+          job_class.const_get(class_or_name)
+        end
+      rescue NameError
+        class_or_name.to_s.safe_constantize
+      end
+
+      # Checks if handler_class handles the given exception.
+      #
+      # Uses Ruby's inheritance mechanism to check if the exception is an instance
+      # of (or subclass of) the handler's exception class. Supports both exception
+      # instances and exception classes.
+      #
+      # @api private
+      # @param handler_class [Class] Exception class from handler
+      # @param exception [Exception, Class] Exception to check
+      # @return [Boolean] true if handler_class handles the exception
+      def handles_exception?(handler_class, exception)
+        return false unless handler_class && exception
+
+        candidate_class = exception.is_a?(Module) ? exception : exception.class
+        candidate_class <= handler_class
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/activejob/temporal/retry_mapper.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require_relative "retry_handler_extractor"
+
+module ActiveJob
+  module Temporal
+    # Translates ActiveJob retry DSL to Temporal RetryPolicy.
+    #
+    # This module introspects a job class's `retry_on` and `discard_on` declarations
+    # and converts them into a Temporal-compatible retry policy hash. It handles:
+    # - Retry intervals (wait durations)
+    # - Retry attempt limits
+    # - Non-retryable error types (from discard_on)
+    #
+    # The mapper uses Ruby's internal `rescue_handlers` mechanism to extract retry
+    # configuration at runtime, ensuring compatibility with ActiveJob's DSL.
+    #
+    # @note Algorithmic Wait Values
+    #   If `retry_on` uses a Proc or Symbol for `:wait` (e.g., `:exponentially_longer`),
+    #   it falls back to the configured `default_retry_initial_interval` because Temporal
+    #   only accepts static numeric intervals. Temporal's built-in exponential backoff
+    #   (via `backoff_coefficient`) is used instead.
+    #
+    # @note Multiple retry_on Declarations
+    #   If a job class has multiple `retry_on` declarations, the first matching handler
+    #   (based on exception type) is used. Handlers are evaluated in reverse order of
+    #   declaration (last declared = first matched).
+    #
+    # @note Exponential Backoff
+    #   Temporal automatically applies exponential backoff using backoff_coefficient.
+    #   For example, with initial_interval=30s and backoff_coefficient=2.0, retries occur
+    #   at 30s, 60s, 120s, 240s intervals (exponentially increasing).
+    #
+    # @note Unlimited Retries
+    #   Setting attempts: :unlimited translates to maximum_attempts: 0 in Temporal,
+    #   which means the activity will retry indefinitely until it succeeds or is cancelled.
+    #   Use this carefully to avoid infinite retry loops.
+    #
+    # @note Exception Inheritance
+    #   Exception matching respects inheritance. A retry_on StandardError declaration
+    #   will match all StandardError subclasses (RuntimeError, ArgumentError, etc.).
+    #   More specific exceptions should be declared last to take precedence.
+    #
+    # @example Retry policy structure
+    #   {
+    #     initial_interval: 30.0,              # seconds (Float)
+    #     backoff_coefficient: 2.0,            # exponential backoff multiplier
+    #     maximum_attempts: 5,                 # max retry count (0 = unlimited)
+    #     non_retryable_error_types: ["MyError::ClassName"]
+    #   }
+    #
+    # @see https://docs.temporal.io/retry-policies Temporal Retry Policies
+    # @see https://edgeguides.rubyonrails.org/active_job_basics.html#retrying-or-discarding-failed-jobs
+    #   ActiveJob Retry Guide
+    module RetryMapper
+      module_function
+
+      # Builds a Temporal retry policy hash from a job class's retry configuration.
+      #
+      # Inspects the job class's `retry_on` declarations and constructs a retry policy.
+      # If an exception is provided, selects the matching retry handler; otherwise uses
+      # the first retry handler found.
+      #
+      # @param job_class [Class] ActiveJob class with retry_on/discard_on declarations
+      # @param exception [Exception, nil] Optional exception to match against handlers
+      #
+      # @return [Hash] Retry policy with keys:
+      #   - :initial_interval [Float] Initial retry delay in seconds
+      #   - :backoff_coefficient [Float] Exponential backoff multiplier
+      #   - :maximum_attempts [Integer] Max retry attempts (0 = unlimited)
+      #   - :non_retryable_error_types [Array<String>] Exception class names to not retry
+      #
+      # @raise [TypeError] if attempts value cannot be converted to Integer
+      #
+      # @example Basic retry policy
+      #   class MyJob < ApplicationJob
+      #     retry_on StandardError, wait: 5.seconds, attempts: 3
+      #   end
+      #   RetryMapper.for(MyJob)
+      #   # => { initial_interval: 5.0, backoff_coefficient: 2.0, maximum_attempts: 3, ... }
+      #
+      # @example Unlimited retries
+      #   class MyJob < ApplicationJob
+      #     retry_on NetworkError, wait: 30.seconds, attempts: :unlimited
+      #   end
+      #   RetryMapper.for(MyJob)
+      #   # => { ..., maximum_attempts: 0 }
+      #
+      # @example Multiple retry_on declarations (precedence)
+      #   class MyJob < ApplicationJob
+      #     retry_on StandardError, wait: 10.seconds, attempts: 5
+      #     retry_on Timeout::Error, wait: 1.second, attempts: 10
+      #   end
+      #   RetryMapper.for(MyJob, Timeout::Error.new)
+      #   # => { initial_interval: 1.0, maximum_attempts: 10, ... }
+      #
+      # @example With discard_on (non-retryable errors)
+      #   class MyJob < ApplicationJob
+      #     retry_on StandardError, wait: 5.seconds, attempts: 3
+      #     discard_on ActiveRecord::RecordNotFound
+      #   end
+      #   RetryMapper.for(MyJob)
+      #   # => { ..., non_retryable_error_types: ["ActiveRecord::RecordNotFound"] }
+      #
+      # @example Algorithmic wait (falls back to default)
+      #   class MyJob < ApplicationJob
+      #     retry_on NetworkError, wait: :exponentially_longer, attempts: 5
+      #   end
+      #   RetryMapper.for(MyJob)
+      #   # => { initial_interval: 30.0, backoff_coefficient: 2.0, maximum_attempts: 5, ... }
+      #   # (Uses config.default_retry_initial_interval because :exponentially_longer is not a static value)
+      #
+      # @note Precedence of Multiple retry_on Declarations
+      #   When a job class has multiple retry_on declarations, ActiveJob's rescue_handlers
+      #   are evaluated in reverse order (last declared = first matched). If you provide an
+      #   exception argument, the first matching handler is used. Without an exception, the
+      #   first handler in the list is used.
+      def for(job_class, exception = nil)
+        config = ActiveJob::Temporal.config
+        retry_entries = extractor.retry_handlers(job_class)
+        retry_entry = select_retry_entry(job_class, exception, retry_entries)
+
+        {
+          initial_interval: interval_from(retry_entry&.fetch(:wait, nil), config),
+          backoff_coefficient: config.default_retry_backoff,
+          maximum_attempts: maximum_attempts_from(retry_entries, retry_entry, exception, config, job_class),
+          non_retryable_error_types: discard_exception_names(job_class)
+        }
+      end
+
+      def retry_handler(job_class, exception)
+        select_retry_entry(job_class, exception)
+      end
+
+      def exception_execution_keys(job_class)
+        extractor.retry_handlers(job_class).filter_map { |handler| handler[:exception_execution_key] }.uniq
+      end
+
+      # Checks if an exception should be discarded (not retried).
+      #
+      # Inspects the job class's `discard_on` declarations to determine if the given
+      # exception matches any discard handler. If true, the activity should raise
+      # a non-retryable error to stop Temporal from retrying.
+      #
+      # @param job_class [Class] ActiveJob class with discard_on declarations
+      # @param exception [Exception] Exception instance to check
+      #
+      # @return [Boolean] true if exception should be discarded, false otherwise
+      #
+      # @example Check if exception is discardable
+      #   class MyJob < ApplicationJob
+      #     discard_on ActiveRecord::RecordNotFound
+      #   end
+      #   RetryMapper.discard_exception?(MyJob, ActiveRecord::RecordNotFound.new)
+      #   # => true
+      def discard_exception?(job_class, exception)
+        extractor.discard_exception?(job_class, exception)
+      end
+
+      # -- helpers ----------------------------------------------------------------
+
+      # Returns the handler extractor instance (memoized).
+      # @api private
+      def extractor
+        @extractor ||= RetryHandlerExtractor.new
+      end
+      private_class_method :extractor
+
+      # Selects the matching retry handler entry for the given exception.
+      # @api private
+      def select_retry_entry(job_class, exception, handlers = extractor.retry_handlers(job_class))
+        return nil if handlers.empty?
+
+        return handlers.find { |handler| handles_exception?(handler[:exception], exception) } if exception
+
+        handlers.first
+      end
+      private_class_method :select_retry_entry
+
+      # Extracts discard handler exception class names.
+      # @api private
+      def discard_exception_names(job_class)
+        extractor.discard_handlers(job_class).each_with_object([]) do |handler, names|
+          next unless handler[:exception]
+
+          name = handler[:exception].name
+          next unless name
+          next if names.include?(name)
+
+          names << name
+        end
+      end
+      private_class_method :discard_exception_names
+
+      # Extracts initial interval from retry_on wait value.
+      # @api private
+      def interval_from(value, config)
+        # Temporal only accepts numeric intervals, so algorithmic waits (Proc/Symbol)
+        # fall back to the configured default for now.
+        case value
+        when Numeric, ActiveSupport::Duration
+          value.to_f
+        else
+          config.default_retry_initial_interval.to_f
+        end
+      end
+      private_class_method :interval_from
+
+      # Extracts maximum attempts from retry_on attempts value.
+      # @api private
+      def attempts_from(value, config, job_class)
+        case value
+        when nil
+          config.default_retry_max_attempts
+        when :unlimited
+          0
+        else
+          Integer(value)
+        end
+      rescue ArgumentError, TypeError => e
+        log_attempts_fallback(job_class, value, config.default_retry_max_attempts, e)
+        config.default_retry_max_attempts
+      end
+      private_class_method :attempts_from
+
+      def maximum_attempts_from(retry_entries, retry_entry, exception, config, job_class)
+        return attempts_from(retry_entry&.fetch(:attempts, nil), config, job_class) if exception || retry_entries.empty?
+
+        attempts = retry_entries.map do |entry|
+          attempts_from(entry.fetch(:attempts, nil), config, job_class)
+        end
+        return 0 if attempts.include?(0)
+
+        attempts.max || config.default_retry_max_attempts
+      end
+      private_class_method :maximum_attempts_from
+
+      def log_attempts_fallback(job_class, value, default_attempts, error)
+        ActiveJob::Temporal::Logger.warn(
+          "retry_attempts_fallback",
+          job_class: job_class&.name,
+          attempts: value.inspect,
+          default_attempts: default_attempts,
+          error_class: error.class.name
+        )
+      rescue StandardError
+        nil
+      end
+      private_class_method :log_attempts_fallback
+
+      # Checks if handler_class handles the given exception.
+      # Delegates to the extractor's private method via duck typing.
+      # @api private
+      def handles_exception?(handler_class, exception)
+        return false unless handler_class && exception
+
+        candidate_class = exception.is_a?(Module) ? exception : exception.class
+        candidate_class <= handler_class
+      end
+      private_class_method :handles_exception?
+    end
+  end
+end