activejob-temporal 0.1.0

data/lib/activejob/temporal/signal_query_options.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_support/concern"
+
+module ActiveJob
+  module Temporal
+    module SignalQueryOptions
+      extend ActiveSupport::Concern
+
+      HANDLER_NAME_PATTERN = /\A[a-zA-Z_]\w*\z/
+      BUILT_IN_SIGNAL_NAMES = %w[pause resume].freeze
+      BUILT_IN_QUERY_NAMES = %w[pause_reason paused phase signals state].freeze
+      BUILT_IN_UPDATE_NAMES = [].freeze
+
+      module ClassMethods
+        def temporal_signal(name, &block)
+          handler_name = normalize_handler_name(name)
+          validate_custom_handler_name!(handler_name, "signal", BUILT_IN_SIGNAL_NAMES)
+          local_temporal_signal_handlers[handler_name] = block || default_signal_handler(handler_name)
+        end
+
+        def temporal_query(name, &block)
+          raise ArgumentError, "temporal_query requires a block" unless block
+
+          handler_name = normalize_handler_name(name)
+          validate_custom_handler_name!(handler_name, "query", BUILT_IN_QUERY_NAMES)
+          local_temporal_query_handlers[handler_name] = block
+        end
+
+        def temporal_update(name, &block)
+          raise ArgumentError, "temporal_update requires a block" unless block
+
+          handler_name = normalize_handler_name(name)
+          validate_custom_handler_name!(handler_name, "update", BUILT_IN_UPDATE_NAMES)
+          local_temporal_update_handlers[handler_name] = block
+        end
+
+        def temporal_signal_handlers
+          inherited_temporal_handlers(:temporal_signal_handlers).merge(local_temporal_signal_handlers)
+        end
+
+        def temporal_query_handlers
+          inherited_temporal_handlers(:temporal_query_handlers).merge(local_temporal_query_handlers)
+        end
+
+        def temporal_update_handlers
+          inherited_temporal_handlers(:temporal_update_handlers).merge(local_temporal_update_handlers)
+        end
+
+        def temporal_signal_handler_names
+          temporal_signal_handlers.keys
+        end
+
+        def temporal_query_handler_names
+          temporal_query_handlers.keys
+        end
+
+        def temporal_update_handler_names
+          temporal_update_handlers.keys
+        end
+
+        private
+
+        def local_temporal_signal_handlers
+          @local_temporal_signal_handlers ||= {}
+        end
+
+        def local_temporal_query_handlers
+          @local_temporal_query_handlers ||= {}
+        end
+
+        def local_temporal_update_handlers
+          @local_temporal_update_handlers ||= {}
+        end
+
+        def normalize_handler_name(name)
+          handler_name = name.to_s
+          return handler_name if handler_name.match?(HANDLER_NAME_PATTERN)
+
+          raise ArgumentError, "signal and query names must start with a letter or underscore and contain word chars"
+        end
+
+        def validate_custom_handler_name!(handler_name, handler_type, built_in_names)
+          return unless built_in_names.include?(handler_name)
+
+          raise ArgumentError, "#{handler_type} name #{handler_name.inspect} is reserved by ActiveJob::Temporal"
+        end
+
+        def inherited_temporal_handlers(method_name)
+          return {} unless superclass.respond_to?(method_name)
+
+          superclass.public_send(method_name)
+        end
+
+        def default_signal_handler(handler_name)
+          lambda do |state, *args|
+            state[handler_name] = args.length == 1 ? args.first : args
+          end
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Base.include(ActiveJob::Temporal::SignalQueryOptions) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/temporal_options.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module ActiveJob
+  module Temporal
+    # Provides per-job timeout configuration via the +temporal_options+ class method.
+    #
+    # @example Basic timeout override
+    #   class QuickJob < ApplicationJob
+    #     temporal_options start_to_close_timeout: 30.seconds
+    #   end
+    #
+    # @example Long-running job with heartbeat
+    #   class DataProcessingJob < ApplicationJob
+    #     temporal_options(
+    #       start_to_close_timeout: 2.hours,
+    #       heartbeat_timeout: 30.seconds
+    #     )
+    #   end
+    #
+    # @example All timeout types configured
+    #   class CriticalJob < ApplicationJob
+    #     temporal_options(
+    #       start_to_close_timeout: 10.minutes,
+    #       schedule_to_start_timeout: 1.minute,
+    #       schedule_to_close_timeout: 15.minutes,
+    #       heartbeat_timeout: 10.seconds
+    #     )
+    #   end
+    module TemporalOptions
+      extend ActiveSupport::Concern
+
+      VALID_TIMEOUT_KEYS = %i[
+        start_to_close_timeout
+        schedule_to_close_timeout
+        schedule_to_start_timeout
+        heartbeat_timeout
+      ].freeze
+
+      # rubocop:disable Metrics/BlockLength
+      class_methods do
+        # Define Temporal activity timeout options for this job class.
+        #
+        # @param options [Hash] Timeout configuration options
+        # @option options [Integer, ActiveSupport::Duration] :start_to_close_timeout
+        #   Maximum execution time for a single activity attempt
+        # @option options [Integer, ActiveSupport::Duration] :schedule_to_close_timeout
+        #   Total time including all retries from schedule to completion
+        # @option options [Integer, ActiveSupport::Duration] :schedule_to_start_timeout
+        #   Maximum wait time before activity starts after scheduling
+        # @option options [Integer, ActiveSupport::Duration] :heartbeat_timeout
+        #   Maximum interval between heartbeats before activity is considered failed
+        #
+        # @return [Hash] The stored timeout options (when called without arguments)
+        #
+        # @note At least one of +start_to_close_timeout+ or +schedule_to_close_timeout+
+        #   must be specified. Temporal SDK will validate this requirement.
+        #
+        # @note Timeout values can be specified as either integers (seconds) or
+        #   ActiveSupport::Duration objects (e.g., 2.hours, 30.seconds)
+        def temporal_options(options = nil)
+          if options
+            validate_timeout_keys!(options)
+            @temporal_options = normalize_timeout_values(options)
+          end
+          @temporal_options || {}
+        end
+
+        private
+
+        # Validates that only recognized timeout keys are provided
+        #
+        # @param options [Hash] The options hash to validate
+        # @raise [ArgumentError] If invalid keys are present
+        # @api private
+        def validate_timeout_keys!(options)
+          invalid_keys = options.keys - VALID_TIMEOUT_KEYS
+          return if invalid_keys.empty?
+
+          raise ArgumentError,
+                "Invalid temporal_options keys: #{invalid_keys.join(', ')}. " \
+                "Valid keys are: #{VALID_TIMEOUT_KEYS.join(', ')}"
+        end
+
+        # Normalizes timeout values to numeric seconds
+        #
+        # Converts ActiveSupport::Duration objects to their numeric second values
+        # while preserving integer/float values as-is.
+        #
+        # @param options [Hash] Raw timeout options with mixed value types
+        # @return [Hash] Normalized options with all values as numbers
+        # @api private
+        def normalize_timeout_values(options)
+          options.transform_values do |value|
+            case value
+            when ActiveSupport::Duration
+              value.to_f
+            when Numeric
+              value
+            else
+              raise ArgumentError,
+                    "Timeout values must be numeric or ActiveSupport::Duration, got: #{value.class}"
+            end
+          end
+        end
+      end
+      # rubocop:enable Metrics/BlockLength
+    end
+  end
+end
+
+# Automatically include TemporalOptions into ActiveJob::Base when this file is loaded
+ActiveJob::Base.include(ActiveJob::Temporal::TemporalOptions) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/tls_file.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module TLSFile
+      class Error < StandardError; end
+      OPEN_FLAGS = File::RDONLY | (File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0)
+      USES_NOFOLLOW = File.const_defined?(:NOFOLLOW)
+
+      module_function
+
+      def readable_regular_file?(path)
+        expanded_path = File.expand_path(path)
+        stat = File.lstat(expanded_path)
+        return false if stat.symlink?
+
+        stat.file? && File.readable?(expanded_path)
+      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+        false
+      end
+
+      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|
+          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}"
+      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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "active_support/lazy_load_hooks"
+
+module ActiveJob
+  module Temporal
+    module TransactionSafety
+      module QueueAdapterSetter
+        def queue_adapter=(adapter)
+          super.tap do
+            self.enqueue_after_transaction_commit = true if temporal_queue_adapter?(adapter)
+          end
+        end
+
+        private
+
+        def temporal_queue_adapter?(adapter)
+          case adapter
+          when Symbol, String
+            adapter.to_s == "temporal"
+          else
+            defined?(ActiveJob::QueueAdapters::TemporalAdapter) &&
+              adapter.is_a?(ActiveJob::QueueAdapters::TemporalAdapter)
+          end
+        end
+      end
+
+      module_function
+
+      def install!
+        ActiveSupport.on_load(:active_job) do
+          singleton_class.prepend(QueueAdapterSetter) unless singleton_class < QueueAdapterSetter
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Temporal::TransactionSafety.install!

data/lib/activejob/temporal/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    VERSION = "0.1.0"
+  end
+end

data/lib/activejob/temporal/visibility_query.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module VisibilityQuery
+      module_function
+
+      def quote(value)
+        "'#{value.to_s.gsub("'", "''")}'"
+      end
+    end
+  end
+end

data/lib/activejob/temporal/worker_client_reloader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    # Rebuilds the Temporal client and swaps it into a running worker.
+    class WorkerClientReloader
+      def initialize(worker:, logger: ActiveJob::Temporal::Logger, reload_client: ActiveJob::Temporal.method(:reload_client!))
+        @worker = worker
+        @logger = logger
+        @reload_client = reload_client
+        @mutex = Mutex.new
+      end
+
+      def reload(source:)
+        @mutex.synchronize do
+          @logger.log_event("certificate_reload_started", source: source)
+          new_client = @reload_client.call do |fresh_client|
+            @worker.client = fresh_client
+          end
+          @logger.log_event("certificate_reload_succeeded", source: source)
+          new_client
+        rescue StandardError => e
+          @logger.error(
+            "certificate_reload_failed",
+            source: source,
+            error_class: e.class.name,
+            message: e.message
+          )
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/worker_health.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "time"
+require "temporalio/worker/interceptor"
+
+require_relative "observability"
+
+module ActiveJob
+  module Temporal
+    class WorkerHealth
+      include Temporalio::Worker::Interceptor::Activity
+
+      def initialize(task_queue:, namespace:, target:, max_concurrent_activities:, max_concurrent_workflows:)
+        @task_queue = task_queue
+        @namespace = namespace
+        @target = target
+        @max_concurrent_activities = max_concurrent_activities
+        @max_concurrent_workflows = max_concurrent_workflows
+        @mutex = Mutex.new
+        @started_at = nil
+        @worker_running = false
+        @active_tasks = 0
+        @last_poll = nil
+      end
+
+      def mark_started!
+        @mutex.synchronize do
+          @started_at ||= Time.now
+          @worker_running = true
+        end
+        Observability.emit(:worker_start, observability_attributes)
+      end
+
+      def mark_stopped!
+        @mutex.synchronize do
+          @worker_running = false
+        end
+        Observability.emit(:worker_stop, observability_attributes)
+      end
+
+      def record_task_started!(now: Time.now)
+        active_tasks = @mutex.synchronize do
+          @active_tasks += 1
+          @last_poll = now
+          @active_tasks
+        end
+        Observability.emit(:active_tasks, observability_attributes(count: active_tasks))
+      end
+
+      def record_task_finished!
+        active_tasks = @mutex.synchronize do
+          @active_tasks = [@active_tasks - 1, 0].max
+          @active_tasks
+        end
+        Observability.emit(:active_tasks, observability_attributes(count: active_tasks))
+      end
+
+      def snapshot(now: Time.now)
+        @mutex.synchronize do
+          {
+            status: @worker_running ? "ok" : "stopped",
+            worker_running: @worker_running,
+            started_at: iso8601(@started_at),
+            last_poll: iso8601(@last_poll),
+            active_tasks: @active_tasks,
+            uptime_seconds: uptime_seconds(now),
+            task_queue: @task_queue,
+            namespace: @namespace,
+            target: @target,
+            max_concurrent_activities: @max_concurrent_activities,
+            max_concurrent_workflows: @max_concurrent_workflows,
+            pid: Process.pid
+          }
+        end
+      end
+
+      def intercept_activity(next_interceptor)
+        ActivityInbound.new(self, next_interceptor)
+      end
+
+      private
+
+      def iso8601(time)
+        time&.utc&.iso8601
+      end
+
+      def uptime_seconds(now)
+        return 0 unless @started_at
+
+        [now - @started_at, 0].max.round
+      end
+
+      def observability_attributes(**attributes)
+        {
+          task_queue: @task_queue,
+          namespace: @namespace,
+          target: @target,
+          worker_id: Process.pid
+        }.merge(attributes)
+      end
+
+      class ActivityInbound < Temporalio::Worker::Interceptor::Activity::Inbound
+        def initialize(worker_health, next_interceptor)
+          super(next_interceptor)
+          @worker_health = worker_health
+        end
+
+        def execute(input)
+          @worker_health.record_task_started!
+          super
+        ensure
+          @worker_health.record_task_finished!
+        end
+      end
+    end
+  end
+end