activejob-temporal 0.1.0 → 0.2.0

data/lib/activejob/temporal/cancel.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "temporalio/error"
+require_relative "job_id_validation"
 require_relative "visibility_query"
 require_relative "workflow_id_builder"
 
@@ -27,6 +29,48 @@ module ActiveJob
     # @see https://docs.temporal.io/activities#heartbeat Temporal Activity Heartbeating
     # @see https://docs.temporal.io/workflows#cancellation Temporal Cancellation Guide
     module Cancel
+      class CancellationRequest
+        def initialize(client:, job_id:, workflow_id:, run_id: nil)
+          @client = client
+          @job_id = job_id
+          @workflow_id = workflow_id
+          @run_id = run_id
+        end
+
+        def call
+          cancellation_handle.cancel
+        rescue StandardError => e
+          raise workflow_not_found_error, cause: e if rpc_not_found?(e)
+
+          raise ActiveJob::Temporal::TemporalConnectionError.new(
+            "Failed to cancel Temporal workflow for job_id #{@job_id}: #{e.message}"
+          ), cause: e
+        end
+
+        private
+
+        attr_reader :client, :workflow_id, :run_id
+
+        def cancellation_handle
+          return client.workflow_handle(workflow_id) unless run_id
+
+          client.workflow_handle(workflow_id, run_id: run_id)
+        end
+
+        def workflow_not_found_error
+          ActiveJob::Temporal::WorkflowNotFoundError.new(
+            "No workflow found for job_id #{@job_id}. The job may have completed or never existed."
+          )
+        end
+
+        def rpc_not_found?(error)
+          defined?(Temporalio::Error::RPCError) &&
+            error.is_a?(Temporalio::Error::RPCError) &&
+            error.code == Temporalio::Error::RPCError::Code::NOT_FOUND
+        end
+      end
+      private_constant :CancellationRequest
+
       class << self
         # Cancels a running Temporal workflow by sending a cancellation request.
         #
@@ -38,7 +82,7 @@ module ActiveJob
         # @return [Boolean, nil] Returns false if workflow already completed, nil if cancellation requested
         #
         # @raise [WorkflowNotFoundError] if no workflow exists for the given job_id
-        # @raise [TemporalConnectionError] if the Temporal cluster cannot be reached
+        # @raise [TemporalConnectionError] if Temporal lookup or cancellation RPCs fail
         #
         # @note Asynchronous Cancellation
         #   Cancellation requests are asynchronous. The method returns immediately after
@@ -67,6 +111,8 @@ module ActiveJob
         def cancel(job_class, job_id)
           validate_job_id!(job_id)
           client = ActiveJob::Temporal.client
+          return nil if cancel_schedule_execution(client, job_class, job_id)
+
           workflow_state = find_workflow(client, job_class, job_id)
           workflow_id = workflow_state[:workflow_id]
 
@@ -78,7 +124,7 @@ module ActiveJob
             raise ActiveJob::Temporal::WorkflowNotFoundError,
                   "No workflow found for job_id #{job_id}. The job may have never existed."
           when :running
-            client.workflow_handle(workflow_id).cancel
+            request_cancellation(client, job_id, workflow_id)
             log_cancellation_requested(job_class, job_id, workflow_id)
             log_audit_cancellation_requested(job_class, job_id, workflow_id)
             nil
@@ -95,11 +141,6 @@ module ActiveJob
           BatchCanceller.new(ActiveJob::Temporal.client).cancel_where(filters)
         end
 
-        # UUID format regex (compliant with RFC 4122).
-        # Matches standard UUID format: 8-4-4-4-12 hexadecimal characters.
-        # @api private
-        UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
-
         private
 
         def validate_job_class!(job_class)
@@ -108,22 +149,28 @@ module ActiveJob
           raise ArgumentError, "job_class must be a named class"
         end
 
-        # Validates that job_id is a valid UUID format.
-        #
-        # ActiveJob generates job IDs using SecureRandom.uuid, which produces RFC 4122
-        # compliant UUIDs. This validation prevents search query injection attacks by
-        # ensuring job_id contains only hexadecimal characters and hyphens, making it
-        # safe for direct use in Temporal queries.
-        #
         # @param job_id [String] The job identifier to validate
-        # @raise [ArgumentError] if job_id is not a valid UUID format
+        # @raise [ArgumentError] if job_id is not a safe string identifier
         # @api private
         def validate_job_id!(job_id)
-          return if job_id.is_a?(String) && job_id.match?(UUID_REGEX)
+          JobIdValidation.validate!(job_id)
+        end
 
-          raise ArgumentError,
-                "Invalid job_id format: expected UUID (e.g., '550e8400-e29b-41d4-a716-446655440000'), " \
-                "got: #{job_id.inspect}"
+        def cancel_schedule_execution(client, job_class, job_id)
+          schedule_reference = JobIdValidation.schedule_execution_reference(job_id)
+          return false unless schedule_reference
+
+          workflow_id = schedule_reference.fetch(:workflow_id)
+          request_cancellation(client, job_id, workflow_id, run_id: schedule_reference.fetch(:run_id))
+          log_cancellation_requested(job_class, job_id, workflow_id)
+          log_audit_cancellation_requested(job_class, job_id, workflow_id)
+          true
+        rescue ActiveJob::Temporal::WorkflowNotFoundError
+          false
+        end
+
+        def request_cancellation(client, job_id, workflow_id, run_id: nil)
+          CancellationRequest.new(client: client, job_id: job_id, workflow_id: workflow_id, run_id: run_id).call
         end
 
         # Builds deterministic workflow ID from job class and job ID.
@@ -167,21 +214,11 @@ module ActiveJob
           { status: status, workflow_id: workflow_id }
         end
 
-        # Builds Temporal query for running workflows by job class and job_id.
-        #
-        # Note: job_id is validated as a UUID before reaching this method, ensuring it
-        # contains only safe characters ([0-9a-fA-F-]) for direct query interpolation.
-        #
         # @api private
         def running_workflows_query(job_class, job_id)
           workflow_search_query(job_class, job_id, "ExecutionStatus='Running'")
         end
 
-        # Builds Temporal query for closed workflows by job class and job_id.
-        #
-        # Note: job_id is validated as a UUID before reaching this method, ensuring it
-        # contains only safe characters ([0-9a-fA-F-]) for direct query interpolation.
-        #
         # @api private
         def closed_workflows_query(job_class, job_id)
           workflow_search_query(

data/lib/activejob/temporal/certificate_watcher.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "listen"
-
 module ActiveJob
   module Temporal
     # Watches TLS certificate files and runs a reload callback when they change.
@@ -16,7 +14,7 @@ module ActiveJob
         ].compact.reject { |path| path.to_s.strip.empty? }
       end
 
-      def initialize(paths:, reload_callback:, listener_factory: Listen, debounce_seconds: DEFAULT_DEBOUNCE_SECONDS)
+      def initialize(paths:, reload_callback:, listener_factory: nil, debounce_seconds: DEFAULT_DEBOUNCE_SECONDS)
         @paths = paths.map { |path| File.expand_path(path) }.uniq
         @reload_callback = reload_callback
         @listener_factory = listener_factory
@@ -24,12 +22,13 @@ module ActiveJob
         @mutex = Mutex.new
         @last_reload_at = nil
         @listener = nil
+        @trailing_reload = nil
       end
 
       def start
         return self if @paths.empty? || @listener
 
-        @listener = @listener_factory.to(*directories) do |modified, added, removed|
+        @listener = listener_factory.to(*directories) do |modified, added, removed|
           handle_changes(modified + added + removed)
         end
         @listener.start
@@ -39,21 +38,57 @@ module ActiveJob
       def stop
         @listener&.stop
         @listener = nil
+        @mutex.synchronize { @trailing_reload }&.kill
       end
 
       def handle_changes(changed_paths)
         return unless relevant_change?(changed_paths)
-        return if debounced?
 
-        @reload_callback.call
+        if debounced?
+          schedule_trailing_reload
+        else
+          reload(retry_on_failure: true)
+        end
       end
 
       private
 
+      # A failed reload clears the debounce stamp so the next change reloads
+      # immediately, and gets one retry in case no further change arrives.
+      def reload(retry_on_failure:)
+        @reload_callback.call
+      rescue StandardError
+        @mutex.synchronize { @last_reload_at = nil }
+        schedule_trailing_reload if retry_on_failure
+      end
+
+      # Cert and key rotate as separate writes, so the second one lands inside
+      # the debounce window. Flush it once the window closes instead of dropping it.
+      def schedule_trailing_reload
+        @mutex.synchronize do
+          return if @trailing_reload&.alive?
+
+          @trailing_reload = Thread.new do
+            sleep(@debounce_seconds)
+            @mutex.synchronize { @last_reload_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+            reload(retry_on_failure: false)
+          end
+        end
+      end
+
       def directories
         @directories ||= @paths.map { |path| File.dirname(path) }.uniq
       end
 
+      def listener_factory
+        @listener_factory ||= begin
+          require "listen"
+          Listen
+        rescue LoadError => e
+          raise LoadError, "listen gem is required when tls_cert_watch is enabled: #{e.message}"
+        end
+      end
+
       def relevant_change?(changed_paths)
         changed_paths.any? do |path|
           @paths.include?(File.expand_path(path))

data/lib/activejob/temporal/client.rb

@@ -71,7 +71,8 @@ module ActiveJob
       #
       # @return [Temporalio::Client] Connected Temporal client
       #
-      # @raise [ActiveJob::Temporal::Error] if connection fails (includes target, namespace, and error message)
+      # @raise [ActiveJob::Temporal::TemporalConnectionError] if connection fails
+      #   (includes target, namespace, and error message)
       # @raise [OpenSSL::SSL::SSLError] if TLS certificate validation fails
       # @raise [OpenSSL::PKey::RSAError] if TLS private key is invalid
       # @raise [OpenSSL::X509::CertificateError] if TLS certificate is malformed
@@ -95,7 +96,7 @@ module ActiveJob
       # @example Handling connection failures
       #   begin
       #     client = Client.build(config)
-      #   rescue ActiveJob::Temporal::Error => e
+      #   rescue ActiveJob::Temporal::TemporalConnectionError => e
       #     Rails.logger.fatal("Cannot connect to Temporal: #{e.message}")
       #     # Fall back to different adapter or alert operations team
       #   end
@@ -106,7 +107,7 @@ module ActiveJob
           **connection_kwargs(configuration)
         )
       rescue StandardError => e
-        raise ActiveJob::Temporal::Error,
+        raise ActiveJob::Temporal::TemporalConnectionError,
               format(
                 "Unable to connect to Temporal at %<target>s (namespace: %<namespace>s): %<error>s",
                 target: configuration.target,

data/lib/activejob/temporal/conditional_enqueue.rb

@@ -2,6 +2,7 @@
 
 require "active_job"
 require "active_support/concern"
+require_relative "configured_job_compatibility"
 
 module ActiveJob
   module Temporal
@@ -39,7 +40,7 @@ module ActiveJob
     # Adds conditional enqueue helpers to ActiveJob configured jobs.
     module ConfiguredConditionalEnqueue
       def perform_later_if(condition, *arguments, **keyword_arguments, &)
-        job_class = instance_variable_get(:@job_class)
+        job_class = ConfiguredJobCompatibility.job_class(self, feature: "conditional_enqueue")
         condition_arguments = ConditionalEnqueue.job_arguments(arguments, keyword_arguments)
         return nil unless ConditionalEnqueue.condition_allows_enqueue?(job_class, condition, condition_arguments)
 

data/lib/activejob/temporal/configurable.rb

@@ -19,28 +19,23 @@ module ActiveJob
       end
       alias configuration config
 
-      # Configures the gem with a block and validates after mutation.
+      # Configures the gem with a block and validates before publishing changes.
       #
       # @yield [config] Gives the configuration object to the block
       # @yieldparam config [Configuration] the configuration to modify
       # @return [Configuration] the configuration object
       # @raise [ConfigurationError] if validation fails after configuration
-      def configure
-        return config unless block_given?
+      def configure(&block)
+        return config unless block
 
         @config_mvar ||= Concurrent::MVar.new(Configuration.new)
-        @config_mvar.borrow do |configuration|
-          configuration.in_configure_block = true
+        applied_configuration = nil
 
-          begin
-            yield(configuration)
-          ensure
-            configuration.in_configure_block = false
-          end
-
-          configuration.validate!
-          configuration
+        @config_mvar.modify do |current_configuration|
+          applied_configuration = build_configuration_candidate(current_configuration, &block)
         end
+
+        applied_configuration
       end
 
       # Validates the current configuration.
@@ -50,6 +45,54 @@ module ActiveJob
       def validate!
         config.validate!
       end
+
+      private
+
+      def build_configuration_candidate(current_configuration)
+        candidate_configuration = current_configuration.dup
+        begin
+          candidate_configuration.in_configure_block = true
+          yield(candidate_configuration)
+        ensure
+          candidate_configuration.in_configure_block = false
+        end
+
+        candidate_configuration.validate!
+        deactivate_replaced_observability_adapters(current_configuration, candidate_configuration)
+        publish_configuration_candidate(current_configuration, candidate_configuration)
+      rescue StandardError
+        discard_configuration_candidate(current_configuration, candidate_configuration)
+        raise
+      end
+
+      def publish_configuration_candidate(current_configuration, candidate_configuration)
+        current_configuration.instance_variable_set(
+          :@attributes,
+          candidate_configuration.instance_variable_get(:@attributes)
+        )
+        current_configuration.in_configure_block = false
+        current_configuration.finalize_configuration_copy!
+      end
+
+      def deactivate_replaced_observability_adapters(previous_configuration, current_configuration)
+        previous_adapters = previous_configuration.observability.adapters
+        current_adapters = current_configuration.observability.adapters
+
+        previous_adapters.each do |adapter|
+          adapter.stop! unless current_adapters.include?(adapter)
+        end
+      end
+
+      def discard_configuration_candidate(previous_configuration, candidate_configuration)
+        previous_adapters = previous_configuration.observability.adapters
+        candidate_adapters = candidate_configuration.observability.adapters
+
+        candidate_adapters.each do |adapter|
+          adapter.stop! unless previous_adapters.include?(adapter)
+        end
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/activejob/temporal/configuration.rb

@@ -38,6 +38,8 @@ module ActiveJob
     TARGET_HOST_LABEL_PATTERN = /\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\z/
     TARGET_PORT_PATTERN = /\A[1-9]\d{0,4}\z/
     NAMESPACE_PATTERN = /\A[A-Za-z0-9](?:[A-Za-z0-9_-]*[A-Za-z0-9])?\z/
+    ENV_BOOLEAN_TRUE_VALUES = %w[1 true yes on].freeze
+    ENV_BOOLEAN_FALSE_VALUES = %w[0 false no off].freeze
 
     # Central registry of all configuration attributes.
     #
@@ -311,6 +313,13 @@ module ActiveJob
         description: "Base64-encoded 32-byte AES-256-GCM payload encryption key or key metadata"
       },
 
+      allow_legacy_encrypted_payloads: {
+        default: false,
+        env_var: "ACTIVEJOB_TEMPORAL_ALLOW_LEGACY_ENCRYPTED_PAYLOADS",
+        type: :boolean,
+        description: "Accept version 1 encrypted payloads, which are not bound to a namespace/workflow context"
+      },
+
       encryption_old_keys: {
         default: -> { [] },
         type: :array,
@@ -330,6 +339,34 @@ module ActiveJob
         description: "Optional workflow history event threshold for continuing ActiveJob workflows as new"
       },
 
+      dependency_wait_timeout: {
+        default: -> { 1.day },
+        env_var: "ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_TIMEOUT_SECONDS",
+        type: :duration,
+        description: "Maximum time a workflow waits for dependencies before timing out"
+      },
+
+      dependency_wait_initial_interval: {
+        default: -> { 10.seconds },
+        env_var: "ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_INITIAL_INTERVAL_SECONDS",
+        type: :duration,
+        description: "Initial durable sleep interval between dependency checks"
+      },
+
+      dependency_wait_max_interval: {
+        default: -> { 1.minute },
+        env_var: "ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_MAX_INTERVAL_SECONDS",
+        type: :duration,
+        description: "Maximum durable sleep interval between dependency checks"
+      },
+
+      dependency_wait_backoff: {
+        default: 2.0,
+        env_var: "ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_BACKOFF",
+        type: :float,
+        description: "Backoff coefficient for dependency polling intervals"
+      },
+
       local_activity_helpers: {
         default: -> { [] },
         type: :array,
@@ -357,13 +394,18 @@ module ActiveJob
     # Use {ActiveJob::Temporal.configure} to set values with automatic validation.
     #
     # @note Thread Safety
-    #   The global configuration object is synchronized by {Configurable} while
-    #   configure blocks mutate it. Complete configuration during application boot.
+    #   The global configuration object is synchronized by {Configurable}.
+    #   Configure blocks mutate a candidate copy that replaces the active
+    #   configuration only after validation succeeds.
     #
     # @note Environment Variable Defaults
     #   ACTIVEJOB_TEMPORAL_TARGET, ACTIVEJOB_TEMPORAL_NAMESPACE,
     #   ACTIVEJOB_TEMPORAL_TASK_QUEUE_PREFIX, ACTIVEJOB_TEMPORAL_TASK_QUEUE,
     #   ACTIVEJOB_TEMPORAL_MAX_PAYLOAD_SIZE_KB,
+    #   ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_TIMEOUT_SECONDS,
+    #   ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_INITIAL_INTERVAL_SECONDS,
+    #   ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_MAX_INTERVAL_SECONDS,
+    #   ACTIVEJOB_TEMPORAL_DEPENDENCY_WAIT_BACKOFF,
     #   ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_ACTIVITIES,
     #   ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS,
     #   can provide defaults.
@@ -394,6 +436,14 @@ module ActiveJob
         end
       end
 
+      def initialize_copy(original)
+        super
+        @attributes = original.instance_variable_get(:@attributes).transform_values do |value|
+          duplicate_configuration_value(value)
+        end
+        @in_configure_block = false
+      end
+
       def [](key)
         @attributes[key]
       end
@@ -406,6 +456,26 @@ module ActiveJob
         middleware_chain.add(middleware, ...)
       end
 
+      # Attributes holding secrets, redacted by {#inspect}.
+      REDACTED_ATTRIBUTES = %i[encryption_key encryption_old_keys tls].freeze
+      REDACTED_PLACEHOLDER = "[FILTERED]"
+
+      # Returns the configuration with secret attributes redacted.
+      #
+      # The default `Object#inspect` dumps `@attributes`, which exposes the payload
+      # encryption keys and the inline TLS private key in logs and exception output.
+      #
+      # @return [String] inspect output with encryption keys and TLS settings filtered
+      def inspect
+        pairs = @attributes.map do |attribute, value|
+          value = REDACTED_PLACEHOLDER if REDACTED_ATTRIBUTES.include?(attribute) && value.present?
+
+          "#{attribute}=#{value.inspect}"
+        end
+
+        "#<#{self.class.name} #{pairs.join(', ')}>"
+      end
+
       def validate!
         return if validation_level == :none
 
@@ -415,6 +485,11 @@ module ActiveJob
         handle_validation_errors(validator.errors)
       end
 
+      def finalize_configuration_copy!
+        observability.finalize_configuration_copy! if observability.respond_to?(:finalize_configuration_copy!)
+        self
+      end
+
       def self.format_validation_errors(errors)
         messages = errors.full_messages
         return messages.first if messages.size == 1
@@ -429,6 +504,19 @@ module ActiveJob
 
       private
 
+      def duplicate_configuration_value(value)
+        case value
+        when Hash
+          value.transform_values { |entry| duplicate_configuration_value(entry) }
+        when Array
+          value.map { |entry| duplicate_configuration_value(entry) }
+        when String, Middleware::Chain, Observability::Configuration
+          value.dup
+        else
+          value
+        end
+      end
+
       def build_validator
         validator = ConfigValidator.new
 
@@ -448,24 +536,37 @@ module ActiveJob
       end
 
       def resolve_default_value(metadata)
-        if metadata[:env_var] && ENV[metadata[:env_var]]
-          value = ENV[metadata[:env_var]]
-          return convert_env_value(value, metadata[:type])
+        env_var = metadata[:env_var]
+        if env_var && ENV[env_var]
+          value = ENV[env_var]
+          return convert_env_value(value, metadata[:type], env_var)
         end
 
         default = metadata[:default]
         default.is_a?(Proc) ? default.call : default
       end
 
-      def convert_env_value(value, type)
+      def convert_env_value(value, type, env_var)
         case type
         when :integer then value.to_i
         when :float, :duration then value.to_f
-        when :boolean then value == "true"
+        when :boolean then convert_env_boolean(value, env_var)
         when :symbol then value.to_sym
         else value
         end
       end
+
+      def convert_env_boolean(value, env_var)
+        normalized = value.to_s.strip.downcase
+
+        return true if ENV_BOOLEAN_TRUE_VALUES.include?(normalized)
+        return false if ENV_BOOLEAN_FALSE_VALUES.include?(normalized)
+
+        raise ConfigurationError,
+              "Invalid boolean value for #{env_var}: #{value.inspect}. " \
+              "Accepted true values: #{ENV_BOOLEAN_TRUE_VALUES.join(', ')}. " \
+              "Accepted false values: #{ENV_BOOLEAN_FALSE_VALUES.join(', ')}."
+      end
     end
 
     # Validates ActiveJob::Temporal configuration.
@@ -598,6 +699,7 @@ module ActiveJob
       validate :validate_payload_storage_settings
       validate :validate_tls_settings
       validate :validate_local_activity_helpers
+      validate :validate_dependency_wait_settings
 
       private
 
@@ -645,6 +747,30 @@ module ActiveJob
         validate_duration_attribute(:default_schedule_to_start_timeout, required: false)
         validate_duration_attribute(:default_schedule_to_close_timeout, required: false)
         validate_duration_attribute(:dead_letter_auto_discard_after, required: false)
+        validate_duration_attribute(:dependency_wait_timeout, required: true)
+        validate_duration_attribute(:dependency_wait_initial_interval, required: true)
+        validate_duration_attribute(:dependency_wait_max_interval, required: true)
+      end
+
+      def validate_dependency_wait_settings
+        validate_dependency_wait_backoff
+        validate_dependency_wait_interval_order
+      end
+
+      def validate_dependency_wait_backoff
+        value = dependency_wait_backoff
+        return if value.is_a?(Numeric) && value >= 1.0
+
+        errors.add(:dependency_wait_backoff, "must be greater than or equal to 1")
+      end
+
+      def validate_dependency_wait_interval_order
+        initial_interval = duration_seconds(dependency_wait_initial_interval)
+        max_interval = duration_seconds(dependency_wait_max_interval)
+        return unless initial_interval && max_interval
+        return if max_interval >= initial_interval
+
+        errors.add(:dependency_wait_max_interval, "must be greater than or equal to initial interval")
       end
 
       def validate_workflow_id_generator
@@ -974,6 +1100,12 @@ module ActiveJob
                    seconds: seconds,
                    attribute: attr_name.to_s.humanize.downcase)
       end
+
+      def duration_seconds(value)
+        return value.to_f if value.is_a?(Numeric) || value.is_a?(ActiveSupport::Duration)
+
+        nil
+      end
     end
     # rubocop:enable Metrics/ClassLength
   end