activejob-temporal 0.1.0 → 0.2.0

data/lib/activejob/temporal/retry_handler_extractor.rb

@@ -131,18 +131,33 @@ module ActiveJob
         handlers = job_class.rescue_handlers
         return [] unless handlers.respond_to?(:reverse_each)
 
-        signature = rescue_handlers_signature(handlers)
+        cached = cache[job_class]
+        return cached[:entries] if fresh_cache_entry?(cached, handlers)
 
         @cache_mutex.synchronize do
           cached = cache[job_class]
-          return cached[:entries] if cached && cached[:signature] == signature
+          return cached[:entries] if fresh_cache_entry?(cached, handlers)
 
           entries = yield(handlers).map(&:freeze).freeze
-          cache[job_class] = { signature: signature, entries: entries }.freeze
+          cache[job_class] = {
+            handlers: handlers,
+            signature: rescue_handlers_signature(handlers),
+            entries: entries
+          }.freeze
           entries
         end
       end
 
+      # ActiveJob replaces the rescue_handlers array on every declaration, so
+      # identity is a sound (and allocation-free) freshness check; the signature
+      # comparison stays as a fallback for in-place mutation.
+      def fresh_cache_entry?(cached, handlers)
+        return false unless cached
+        return true if cached[:handlers].equal?(handlers)
+
+        cached[:signature] == rescue_handlers_signature(handlers)
+      end
+
       def rescue_handlers_signature(handlers)
         handlers.reverse_each.map do |class_or_name, handler|
           [class_or_name, handler.object_id]

data/lib/activejob/temporal/schedulable.rb

@@ -10,22 +10,20 @@ module ActiveJob
       end
 
       module ClassMethods
-        def schedule(options = nil, **kwargs)
+        def temporal_schedule(options = nil, **kwargs)
+          return @temporal_schedule if options.nil? && kwargs.empty?
+
           schedule_options = normalize_schedule_options(options, kwargs)
           @temporal_schedule = ActiveJob::Temporal::Schedule.new(self, schedule_options)
         end
 
-        def temporal_schedule
-          @temporal_schedule
-        end
-
         def create_temporal_schedule(options = nil, **kwargs)
           if options || kwargs.any?
             schedule_options = merged_schedule_options(normalize_schedule_options(options, kwargs))
             return ActiveJob::Temporal::Schedule.new(self, schedule_options).create
           end
 
-          raise ArgumentError, "No schedule defined for #{name}" unless temporal_schedule
+          raise ArgumentError, "No temporal_schedule defined for #{name}" unless temporal_schedule
 
           temporal_schedule.create
         end
@@ -43,7 +41,7 @@ module ActiveJob
           when Hash
             options.merge(kwargs)
           else
-            raise ArgumentError, "schedule options must be a Hash"
+            raise ArgumentError, "temporal_schedule options must be a Hash"
           end
         end
 

data/lib/activejob/temporal/schedule.rb

@@ -9,7 +9,7 @@ require_relative "job_payload_builder"
 require_relative "logger"
 require_relative "schedule_options"
 require_relative "search_attributes"
-require_relative "workflows/aj_workflow"
+require_relative "workflow_types"
 
 module ActiveJob
   module Temporal
@@ -96,7 +96,7 @@ module ActiveJob
         payload = annotate_scheduled_payload(payload, workflow_id)
 
         Temporalio::Client::Schedule::Action::StartWorkflow.new(
-          Workflows::AjWorkflow,
+          WorkflowTypes::ACTIVE_JOB,
           payload,
           id: workflow_id,
           task_queue: Adapter.resolve_task_queue(job, config: @config),

data/lib/activejob/temporal/signal_query.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 require "temporalio/error"
+require_relative "job_id_validation"
 require_relative "visibility_query"
 require_relative "workflow_id_builder"
 
 module ActiveJob
   module Temporal
     module SignalQuery
-      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
       JOB_CLASS_NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
       HANDLER_NAME_PATTERN = /\A[a-zA-Z_]\w*\z/
       DEFAULT_REJECT_CONDITION = Object.new.freeze
+      WORKFLOW_NOT_FOUND = Object.new.freeze
 
       class << self
         def signal(job_class, job_id, signal_name, *)
@@ -57,33 +58,48 @@ module ActiveJob
           raise ActiveJob::Temporal::TemporalConnectionError,
                 "Failed to update Temporal workflow for job_id #{job_id}: #{e.message}"
         end
+      end
 
+      class << self
         private
 
-        def with_running_workflow_handle(job_class, job_id)
+        def with_running_workflow_handle(job_class, job_id, &)
           client = ActiveJob::Temporal.client
-          default_handle = client.workflow_handle(default_workflow_id(job_class, job_id), run_id: nil)
+          result = yield_schedule_execution_handle(client, job_id, &)
+          return result unless result.equal?(WORKFLOW_NOT_FOUND)
 
-          begin
-            return yield(default_handle)
-          rescue Temporalio::Error::RPCError => e
-            raise unless rpc_not_found?(e)
-          end
+          result = yield_handle(client.workflow_handle(default_workflow_id(job_class, job_id), run_id: nil), &)
+          return result unless result.equal?(WORKFLOW_NOT_FOUND)
 
           workflow_reference = find_running_workflow_reference(client, job_class, job_id)
           raise workflow_not_found(job_id) unless workflow_reference
 
-          fallback_handle = client.workflow_handle(
+          result = yield_handle(workflow_handle(client, workflow_reference), &)
+          raise workflow_not_found(job_id) if result.equal?(WORKFLOW_NOT_FOUND)
+
+          result
+        end
+
+        def yield_schedule_execution_handle(client, job_id, &)
+          workflow_reference = JobIdValidation.schedule_execution_reference(job_id)
+          return WORKFLOW_NOT_FOUND unless workflow_reference
+
+          yield_handle(workflow_handle(client, workflow_reference), &)
+        end
+
+        def yield_handle(handle, &block)
+          block.call(handle)
+        rescue Temporalio::Error::RPCError => e
+          raise unless rpc_not_found?(e)
+
+          WORKFLOW_NOT_FOUND
+        end
+
+        def workflow_handle(client, workflow_reference)
+          client.workflow_handle(
             workflow_reference.fetch(:workflow_id),
             run_id: workflow_reference[:run_id]
           )
-          begin
-            yield(fallback_handle)
-          rescue Temporalio::Error::RPCError => e
-            raise workflow_not_found(job_id) if rpc_not_found?(e)
-
-            raise
-          end
         end
 
         def query_workflow(handle, handler_name, args, reject_condition)
@@ -119,11 +135,7 @@ module ActiveJob
         end
 
         def validate_job_id!(job_id)
-          return if job_id.is_a?(String) && job_id.match?(UUID_REGEX)
-
-          raise ArgumentError,
-                "Invalid job_id format: expected UUID (e.g., '550e8400-e29b-41d4-a716-446655440000'), " \
-                "got: #{job_id.inspect}"
+          JobIdValidation.validate!(job_id)
         end
 
         def normalize_handler_name!(name, handler_type)
@@ -149,11 +161,11 @@ module ActiveJob
         end
 
         def rpc_not_found?(error)
-          error.code == Temporalio::Error::RPCError::Code::NOT_FOUND
+          error.respond_to?(:code) && error.code == Temporalio::Error::RPCError::Code::NOT_FOUND
         end
 
         def rpc_invalid_argument?(error)
-          error.code == Temporalio::Error::RPCError::Code::INVALID_ARGUMENT
+          error.respond_to?(:code) && error.code == Temporalio::Error::RPCError::Code::INVALID_ARGUMENT
         end
       end
     end

data/lib/activejob/temporal/temporal_options.rb

@@ -11,6 +11,21 @@ module ActiveJob
     #     temporal_options start_to_close_timeout: 30.seconds
     #   end
     #
+    # @example ApplicationJob defaults inherited by subclasses
+    #   class ApplicationJob < ActiveJob::Base
+    #     temporal_options start_to_close_timeout: 2.minutes
+    #   end
+    #
+    #   class QuickJob < ApplicationJob
+    #   end
+    #
+    # @example Merge inherited defaults intentionally
+    #   class DataProcessingJob < ApplicationJob
+    #     temporal_options ApplicationJob.temporal_options.merge(
+    #       heartbeat_timeout: 30.seconds
+    #     )
+    #   end
+    #
     # @example Long-running job with heartbeat
     #   class DataProcessingJob < ApplicationJob
     #     temporal_options(
@@ -59,16 +74,26 @@ module ActiveJob
         #
         # @note Timeout values can be specified as either integers (seconds) or
         #   ActiveSupport::Duration objects (e.g., 2.hours, 30.seconds)
+        #
+        # @note Subclasses inherit parent options unless they declare their own.
+        #   A subclass declaration replaces the inherited hash. Use +merge+ to
+        #   keep inherited keys while overriding selected values.
         def temporal_options(options = nil)
           if options
             validate_timeout_keys!(options)
             @temporal_options = normalize_timeout_values(options)
           end
-          @temporal_options || {}
+          @temporal_options || inherited_temporal_options || {}
         end
 
         private
 
+        def inherited_temporal_options
+          return unless superclass.respond_to?(:temporal_options)
+
+          superclass.temporal_options
+        end
+
         # Validates that only recognized timeout keys are provided
         #
         # @param options [Hash] The options hash to validate

data/lib/activejob/temporal/tls_file.rb

@@ -4,42 +4,42 @@ module ActiveJob
   module Temporal
     module TLSFile
       class Error < StandardError; end
+      # Symlinks are resolved before opening, so NOFOLLOW only trips when the
+      # resolved path is swapped for a symlink between resolution and open.
       OPEN_FLAGS = File::RDONLY | (File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0)
-      USES_NOFOLLOW = File.const_defined?(:NOFOLLOW)
 
       module_function
 
+      # @param path [String, nil] path to a TLS file, symlinks allowed
+      # @return [Boolean] true when the path resolves to a readable regular file
       def readable_regular_file?(path)
-        expanded_path = File.expand_path(path)
-        stat = File.lstat(expanded_path)
-        return false if stat.symlink?
+        resolved_path = File.realpath(File.expand_path(path))
 
-        stat.file? && File.readable?(expanded_path)
-      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+        File.stat(resolved_path).file? && File.readable?(resolved_path)
+      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES, Errno::ELOOP
         false
       end
 
+      # Reads a TLS file, resolving symlinks first so Kubernetes secret mounts
+      # (path -> ..data/path -> timestamped directory) work.
+      #
+      # @param path [String, nil] path to a TLS file
+      # @return [String, nil] file contents, or nil when path is blank
+      # @raise [Error] when the path does not resolve to a readable regular file
       def read(path)
         return nil if path.nil? || path.to_s.empty?
 
-        expanded_path = File.expand_path(path)
-        reject_symlink!(expanded_path) unless USES_NOFOLLOW
-        File.open(expanded_path, OPEN_FLAGS) do |file|
+        resolved_path = File.realpath(File.expand_path(path))
+        File.open(resolved_path, OPEN_FLAGS) do |file|
           raise Error, "TLS file path must point to a regular file: #{path}" unless file.stat.file?
 
           file.read
         end
       rescue Errno::ELOOP
-        raise Error, "TLS file path must not be a symlink: #{path}"
+        raise Error, "TLS file path could not be resolved: #{path}"
       rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
         raise Error, "TLS file path is not readable: #{path}"
       end
-
-      def reject_symlink!(path)
-        return unless File.lstat(path).symlink?
-
-        raise Error, "TLS file path must not be a symlink: #{path}"
-      end
     end
   end
 end

data/lib/activejob/temporal/transaction_safety.rb

@@ -6,14 +6,115 @@ module ActiveJob
   module Temporal
     module TransactionSafety
       module QueueAdapterSetter
+        INHERITED_TRANSACTION_SETTING_MISSING = Object.new.freeze
+
         def queue_adapter=(adapter)
+          previous_transaction_setting = enqueue_after_transaction_commit
+
           super.tap do
-            self.enqueue_after_transaction_commit = true if temporal_queue_adapter?(adapter)
+            if temporal_queue_adapter?(adapter)
+              apply_temporal_transaction_safety(previous_transaction_setting)
+            else
+              restore_temporal_transaction_safety
+            end
+          end
+        end
+
+        def enqueue_after_transaction_commit=(value)
+          super.tap do
+            next if setting_temporal_transaction_safety?
+
+            @activejob_temporal_transaction_setting_explicit = true
+            @activejob_temporal_transaction_setting_changed_after_safety = true if temporal_transaction_safety_applied?
           end
         end
 
         private
 
+        def apply_temporal_transaction_safety(previous_transaction_setting)
+          return if temporal_transaction_safety_applied?
+          return if temporal_transaction_setting_explicit?
+
+          @activejob_temporal_previous_transaction_setting =
+            transaction_setting_before_temporal_safety(previous_transaction_setting)
+          apply_enqueue_after_transaction_commit_for_temporal(true)
+          @activejob_temporal_transaction_safety_applied = true
+          @activejob_temporal_transaction_setting_changed_after_safety = false
+        end
+
+        def restore_temporal_transaction_safety
+          unless temporal_transaction_safety_applied?
+            restore_inherited_temporal_transaction_safety
+            return
+          end
+
+          unless @activejob_temporal_transaction_setting_changed_after_safety
+            apply_enqueue_after_transaction_commit_for_temporal(@activejob_temporal_previous_transaction_setting)
+          end
+
+          remove_instance_variable(:@activejob_temporal_previous_transaction_setting)
+          @activejob_temporal_transaction_safety_applied = false
+          @activejob_temporal_transaction_setting_changed_after_safety = false
+        end
+
+        def restore_inherited_temporal_transaction_safety
+          return if temporal_transaction_setting_explicit_locally?
+
+          inherited_setting = inherited_temporal_transaction_previous_setting
+          return if inherited_setting.equal?(INHERITED_TRANSACTION_SETTING_MISSING)
+
+          apply_enqueue_after_transaction_commit_for_temporal(inherited_setting)
+        end
+
+        def apply_enqueue_after_transaction_commit_for_temporal(value)
+          @activejob_temporal_setting_transaction_safety = true
+          self.enqueue_after_transaction_commit = value
+        ensure
+          @activejob_temporal_setting_transaction_safety = false
+        end
+
+        def transaction_setting_before_temporal_safety(current_setting)
+          inherited_setting = inherited_temporal_transaction_previous_setting
+          return current_setting if inherited_setting.equal?(INHERITED_TRANSACTION_SETTING_MISSING)
+
+          inherited_setting
+        end
+
+        def inherited_temporal_transaction_previous_setting
+          return INHERITED_TRANSACTION_SETTING_MISSING unless superclass.respond_to?(
+            :temporal_transaction_safety_applied?, true
+          )
+
+          if superclass.send(:temporal_transaction_safety_applied?)
+            superclass.send(:temporal_previous_transaction_setting)
+          else
+            superclass.send(:inherited_temporal_transaction_previous_setting)
+          end
+        end
+
+        def temporal_previous_transaction_setting
+          @activejob_temporal_previous_transaction_setting
+        end
+
+        def temporal_transaction_setting_explicit?
+          return true if temporal_transaction_setting_explicit_locally?
+          return false unless superclass.respond_to?(:temporal_transaction_setting_explicit?, true)
+
+          superclass.send(:temporal_transaction_setting_explicit?)
+        end
+
+        def temporal_transaction_setting_explicit_locally?
+          @activejob_temporal_transaction_setting_explicit == true
+        end
+
+        def temporal_transaction_safety_applied?
+          @activejob_temporal_transaction_safety_applied == true
+        end
+
+        def setting_temporal_transaction_safety?
+          @activejob_temporal_setting_transaction_safety == true
+        end
+
         def temporal_queue_adapter?(adapter)
           case adapter
           when Symbol, String

data/lib/activejob/temporal/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveJob
   module Temporal
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/activejob/temporal/visibility_query.rb

@@ -3,10 +3,25 @@
 module ActiveJob
   module Temporal
     module VisibilityQuery
+      SAFE_VALUE_PATTERN = /\A[A-Za-z0-9_.:-]+\z/
+
       module_function
 
+      # Quotes a value for use in a Temporal visibility list filter.
+      #
+      # Escaping alone is not enough: Temporal's list filter grammar also treats
+      # backslashes as escapes, so a value containing one can break out of the
+      # quoted literal. Values are restricted to an allowlist instead.
+      #
+      # @param value [#to_s] Value to embed in a list filter
+      # @return [String] Single-quoted literal
+      # @raise [ArgumentError] if the value contains characters outside the allowlist
       def quote(value)
-        "'#{value.to_s.gsub("'", "''")}'"
+        string_value = value.to_s
+        return "'#{string_value}'" if string_value.match?(SAFE_VALUE_PATTERN)
+
+        raise ArgumentError,
+              "visibility query values may only contain letters, numbers, underscore, hyphen, period, and colon"
       end
     end
   end

data/lib/activejob/temporal/worker_pool.rb

@@ -140,6 +140,19 @@ module ActiveJob
         end
 
         validate_public_binds!
+        validate_port_ranges!
+      end
+
+      # Each worker binds base_port + index, so overlapping ranges would make
+      # workers fight over the same port and crash-loop.
+      def validate_port_ranges!
+        return unless @health_check_port && @metrics_port
+        return unless @health_check_port < @metrics_port + @size && @metrics_port < @health_check_port + @size
+
+        raise ArgumentError,
+              "health_check_port and metrics_port ranges overlap for #{@size} workers: " \
+              "health check #{@health_check_port}-#{@health_check_port + @size - 1}, " \
+              "metrics #{@metrics_port}-#{@metrics_port + @size - 1}"
       end
 
       def positive_integer(value, name)

data/lib/activejob/temporal/worker_runtime.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../temporal"
+require_relative "rails_environment_loader"
+require_relative "certificate_watcher"
+require_relative "reload_signal_queue"
+require_relative "worker_client_reloader"
+require_relative "worker_pool"
+require_relative "metrics_server"
+require_relative "worker_health"
+require_relative "health_check_server"
+require_relative "workflows/aj_workflow"
+require_relative "workflows/dead_letter_workflow"
+require_relative "activities/rate_limit_activity"
+require_relative "activities/dependency_status_activity"
+require_relative "activities/aj_runner_activity"

data/lib/activejob/temporal/workflow_enqueuer.rb

@@ -7,6 +7,7 @@ require_relative "job_payload_builder"
 require_relative "observability"
 require_relative "workflow_enqueuer_batch"
 require_relative "workflow_id_builder"
+require_relative "workflow_types"
 
 module ActiveJob
   module Temporal
@@ -128,7 +129,7 @@ module ActiveJob
       # Starts the Temporal workflow with the given options.
       # @api private
       def start_workflow(job, payload, options)
-        workflow_class = Workflows::AjWorkflow
+        workflow_class = WorkflowTypes::ACTIVE_JOB
         handle = start_temporal_workflow(workflow_class, job, payload, options)
 
         log_enqueued(job, options, payload, duplicate: false)

data/lib/activejob/temporal/workflow_types.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module WorkflowTypes
+      ACTIVE_JOB = "AjWorkflow"
+      DEAD_LETTER = "ActiveJobTemporalDeadLetterWorkflow"
+    end
+  end
+end

data/lib/activejob/temporal/workflows/aj_workflow.rb

@@ -8,6 +8,7 @@ require "temporalio/workflow"
 
 require_relative "../activities/rate_limit_activity"
 require_relative "dead_letter_support"
+require_relative "dead_letter_workflow"
 require_relative "workflow_continue_as_new"
 require_relative "workflow_child_workflows"
 require_relative "workflow_chaining"
@@ -109,7 +110,8 @@ module ActiveJob
         # @option payload [String] :job_class Fully-qualified job class name (required)
         # @option payload [String] :job_id Unique job identifier (required)
         # @option payload [String] :queue_name Target queue name (required)
-        # @option payload [Array] :arguments Serialized job arguments (required)
+        # @option payload [Hash] :active_job Full ActiveJob serialized payload
+        # @option payload [Array] :arguments Legacy serialized job arguments
         # @option payload [Hash] :default_activity_options Global activity timeout defaults (required)
         # @option payload [Hash] :retry_policy Retry policy for activity execution (required)
         # @option payload [Hash] :temporal_options Per-job timeout configuration (optional)
@@ -127,14 +129,14 @@ module ActiveJob
         #   The timer persists across worker restarts and does not block worker threads.
         #
         # @example Immediate execution
-        #   execute({ job_class: "MyJob", job_id: "123", arguments: ["arg1"] })
+        #   execute({ job_class: "MyJob", job_id: "123", active_job: { "arguments" => ["arg1"] } })
         #
         # @example Scheduled execution (non-blocking sleep)
         #   execute({
         #     job_class: "MyJob",
         #     job_id: "123",
         #     scheduled_at: "2025-10-31T12:00:00Z",
-        #     arguments: []
+        #     active_job: { "arguments" => [] }
         #   })
         #   # Workflow sleeps until scheduled time without consuming worker resources
         #
@@ -175,13 +177,24 @@ module ActiveJob
         def schedule_execution_payload(payload)
           return payload unless payload_value(payload, :schedule_id)
 
-          execution_job_id = Temporalio::Workflow.info.workflow_id
+          execution_job_id = schedule_execution_identity
           payload.merge(
             "job_id" => execution_job_id,
             "schedule_execution_job_id" => execution_job_id
           )
         end
 
+        def schedule_execution_identity
+          info = Temporalio::Workflow.info
+          run_id = if info.respond_to?(:first_execution_run_id)
+                     info.first_execution_run_id
+                   elsif info.respond_to?(:run_id)
+                     info.run_id
+                   end
+
+          [info.workflow_id, run_id].compact.join(":")
+        end
+
         # Extracts scheduled execution time from payload.
         # @api private
         def extract_scheduled_time(payload)