activejob-temporal 0.1.0

data/lib/activejob/temporal/configured_job_compatibility.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "active_job"
+require_relative "logger"
+
+module ActiveJob
+  module Temporal
+    module ConfiguredJobCompatibility
+      module_function
+
+      def payload(value, feature:, normalize_options:)
+        return unless configured_job?(value)
+
+        log_private_api(feature)
+
+        job_class = value.instance_variable_get(:@job_class)
+        return unless active_job_class?(job_class)
+
+        {
+          job_class: job_class.name,
+          options: normalize_options.call(value.instance_variable_get(:@options) || {})
+        }
+      end
+
+      def configured_job?(value)
+        defined?(ActiveJob::ConfiguredJob) && value.is_a?(ActiveJob::ConfiguredJob)
+      end
+
+      def active_job_class?(job_class)
+        job_class.is_a?(Class) && job_class < ActiveJob::Base && job_class.name
+      end
+
+      def log_private_api(feature)
+        ActiveJob::Temporal::Logger.warn(
+          "active_job_configured_job_private_api",
+          feature: feature,
+          replacement: "ActiveJob::Temporal.job"
+        )
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/activejob/temporal/connection_worker_pool.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    class ConnectionWorkerPool
+      def initialize(size:, queue_size:, name:, &handler)
+        @size = Integer(size)
+        @queue_size = Integer(queue_size)
+        @name = name
+        @handler = handler
+        @mutex = Mutex.new
+        @started = false
+
+        raise ArgumentError, "size must be positive" unless @size.positive?
+        raise ArgumentError, "queue_size must be positive" unless @queue_size.positive?
+        raise ArgumentError, "handler is required" unless @handler
+      end
+
+      def start
+        @mutex.synchronize do
+          return self if @started
+
+          @queue = SizedQueue.new(@queue_size)
+          queue = @queue
+          @workers = Array.new(@size) do |index|
+            Thread.new(queue, index) { |worker_queue, worker_index| run_worker(worker_queue, worker_index) }
+          end
+          @started = true
+        end
+
+        self
+      end
+
+      def enqueue(connection)
+        queue = @mutex.synchronize { @queue if @started }
+        unless queue
+          close_connection(connection)
+          return false
+        end
+
+        queue.push(connection, true)
+        true
+      rescue ClosedQueueError, ThreadError
+        close_connection(connection)
+        false
+      end
+
+      def stop(timeout:)
+        queue = nil
+        workers = nil
+
+        @mutex.synchronize do
+          return unless @started
+
+          queue = @queue
+          workers = @workers
+          @queue = nil
+          @workers = []
+          @started = false
+        end
+
+        queue.close
+        workers.each { |worker| worker.join(timeout) }
+      end
+
+      private
+
+      def run_worker(queue, index)
+        Thread.current.name = "#{@name}-#{index}" if Thread.current.respond_to?(:name=)
+
+        loop do
+          connection = queue.pop
+          break unless connection
+
+          @handler.call(connection)
+        end
+      rescue ClosedQueueError
+        nil
+      end
+
+      def close_connection(connection)
+        connection.close
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/activejob/temporal/dead_letter_payload_validation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module DeadLetterPayloadValidation
+      extend self
+
+      def validate!(payload)
+        validate_metadata!(payload_value(payload, :dead_letter), "dead_letter.queue")
+
+        Array(payload_value(payload, :chain)).each do |chain_step|
+          validate_metadata!(payload_value(chain_step, :dead_letter), "chain.dead_letter.queue")
+        end
+      end
+
+      private
+
+      def validate_metadata!(metadata, queue_path)
+        return unless metadata
+        return if payload_value(metadata, :queue).to_s.strip.present?
+
+        raise ConfigurationError, "#{queue_path} cannot be blank"
+      end
+
+      def payload_value(payload, key)
+        return unless payload.respond_to?(:[])
+
+        payload[key] || payload[key.to_s]
+      rescue TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/activejob/temporal/dead_letter_queue.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "temporalio/client"
+
+module ActiveJob
+  module Temporal
+    module DeadLetterQueue
+      WORKFLOW_TYPE = "ActiveJobTemporalDeadLetterWorkflow"
+      DEFAULT_ENTRIES_LIMIT = 100
+
+      module_function
+
+      def entry(job_class, job_id, run_id: nil, client: ActiveJob::Temporal.client)
+        handle_for(job_class, job_id, run_id: run_id, client: client).query(:entry)
+      end
+
+      def entries(queue: nil, limit: DEFAULT_ENTRIES_LIMIT, client: ActiveJob::Temporal.client)
+        validate_limit!(limit)
+
+        client.list_workflows(entries_query(queue)).each_with_object([]) do |workflow, entries|
+          entry = query_workflow_entry(client, workflow)
+          entries << entry if entry
+          break entries if entries.size >= limit
+        end
+      end
+
+      def retry(job_class, job_id, queue: nil, client: ActiveJob::Temporal.client)
+        handle = handle_for(job_class, job_id, client: client)
+        entry = handle.query(:entry)
+        return entry.fetch("retry_workflow_id") if retried_entry?(entry)
+
+        ensure_pending_entry!(entry)
+
+        workflow_id = retry_workflow_id(entry)
+        start_retry_workflow(client, entry, workflow_id, queue)
+        mark_retried_entry(handle, workflow_id)
+        workflow_id
+      end
+
+      # rubocop:disable Naming/PredicateMethod
+      def discard(job_class, job_id, reason: nil, client: ActiveJob::Temporal.client)
+        handle_for(job_class, job_id, client: client).signal(:discard, reason)
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      def workflow_id(job_class, job_id)
+        class_name = job_class.is_a?(Class) ? job_class.name : job_class.to_s
+        "ajdlq:#{class_name}:#{job_id}"
+      end
+
+      def handle_for(job_class, job_id, run_id: nil, client: ActiveJob::Temporal.client)
+        client.workflow_handle(workflow_id(job_class, job_id), run_id: run_id)
+      end
+      private_class_method :handle_for
+
+      def entries_query(queue)
+        query = ["WorkflowType='#{WORKFLOW_TYPE}'", "ExecutionStatus='Running'"]
+        query << "TaskQueue='#{escape_query_value(queue)}'" if queue.to_s.strip.present?
+        query.join(" AND ")
+      end
+      private_class_method :entries_query
+
+      def query_workflow_entry(client, workflow)
+        client.workflow_handle(workflow.id, run_id: workflow_run_id(workflow)).query(:entry)
+      rescue Temporalio::Error
+        nil
+      end
+      private_class_method :query_workflow_entry
+
+      def start_retry_workflow(client, entry, workflow_id, queue)
+        client.start_workflow(
+          ActiveJob::Temporal::Workflows::AjWorkflow,
+          retry_payload(entry),
+          id: workflow_id,
+          task_queue: retry_task_queue(entry, queue),
+          id_conflict_policy: Temporalio::WorkflowIDConflictPolicy::FAIL
+        )
+      rescue StandardError => e
+        raise unless workflow_already_started?(e)
+      end
+      private_class_method :start_retry_workflow
+
+      def mark_retried_entry(handle, workflow_id)
+        handle.signal(:mark_retried, workflow_id)
+      rescue StandardError => e
+        return if entry_retried_with_workflow_id?(query_entry_after_mark_failure(handle), workflow_id)
+
+        message = "Retry workflow #{workflow_id} may be running, but could not mark dead letter entry retried"
+        raise ActiveJob::Temporal::Error.new(message), cause: e
+      end
+      private_class_method :mark_retried_entry
+
+      def query_entry_after_mark_failure(handle)
+        handle.query(:entry)
+      rescue StandardError
+        nil
+      end
+      private_class_method :query_entry_after_mark_failure
+
+      def ensure_pending_entry!(entry)
+        state = entry.fetch("state", "pending")
+        return if state == "pending"
+
+        message = "Cannot retry dead letter entry #{entry.fetch('id')} with state #{state.inspect}"
+        raise ActiveJob::Temporal::Error, message
+      end
+      private_class_method :ensure_pending_entry!
+
+      def retried_entry?(entry)
+        entry["state"] == "retried" && entry["retry_workflow_id"].to_s.strip.present?
+      end
+      private_class_method :retried_entry?
+
+      def entry_retried_with_workflow_id?(entry, workflow_id)
+        return false unless entry
+
+        entry["state"] == "retried" && entry["retry_workflow_id"] == workflow_id
+      end
+      private_class_method :entry_retried_with_workflow_id?
+
+      def retry_workflow_id(entry)
+        "ajdlq-retry:#{entry.fetch('id')}"
+      end
+      private_class_method :retry_workflow_id
+
+      def retry_payload(entry)
+        entry.fetch("payload").reject { |key, _value| key.to_s == "scheduled_at" }
+      end
+      private_class_method :retry_payload
+
+      def retry_task_queue(entry, queue)
+        queue || entry.dig("metadata", "original_task_queue") || entry.dig("metadata", "original_queue_name")
+      end
+      private_class_method :retry_task_queue
+
+      def workflow_run_id(workflow)
+        workflow.respond_to?(:run_id) ? workflow.run_id : nil
+      end
+      private_class_method :workflow_run_id
+
+      def validate_limit!(limit)
+        return if limit.is_a?(Integer) && limit.positive?
+
+        raise ArgumentError, "limit must be a positive integer"
+      end
+      private_class_method :validate_limit!
+
+      def escape_query_value(value)
+        value.to_s.gsub("'", "''")
+      end
+      private_class_method :escape_query_value
+
+      def workflow_already_started?(error)
+        (defined?(Temporalio::Error::WorkflowAlreadyStartedError) &&
+          error.is_a?(Temporalio::Error::WorkflowAlreadyStartedError)) ||
+          (defined?(Temporalio::Client::WorkflowAlreadyStartedError) &&
+            error.is_a?(Temporalio::Client::WorkflowAlreadyStartedError))
+      end
+      private_class_method :workflow_already_started?
+    end
+  end
+end

data/lib/activejob/temporal/dependency_options.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "active_job"
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    module DependencyOptions
+      JOB_CLASS_NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+      SAFE_ID_PATTERN = /\A[A-Za-z0-9_.:-]+\z/
+      FAILURE_POLICIES = %i[fail ignore].freeze
+
+      attr_reader :temporal_dependencies, :temporal_dependency_failure_policy
+
+      def self.normalize(depends_on)
+        dependencies = depends_on.is_a?(Array) ? depends_on : [depends_on]
+        raise ArgumentError, "depends_on must contain at least one job dependency" if dependencies.empty?
+
+        dependencies.map { |dependency| normalize_dependency(dependency) }
+      end
+
+      def self.normalize_failure_policy(policy)
+        normalized_policy = policy.to_sym
+        return normalized_policy if FAILURE_POLICIES.include?(normalized_policy)
+
+        raise ArgumentError, "on_dependency_failure must be :fail or :ignore"
+      rescue NoMethodError
+        raise ArgumentError, "on_dependency_failure must be :fail or :ignore"
+      end
+
+      def self.normalize_dependency(dependency)
+        return normalize_job_dependency(dependency) if dependency.is_a?(ActiveJob::Base)
+        return normalize_hash_dependency(dependency) if dependency.is_a?(Hash)
+        return { job_id: normalize_id(dependency, "job_id") } if dependency.is_a?(String)
+
+        raise ArgumentError, "depends_on entries must be ActiveJob instances, job IDs, or dependency hashes"
+      end
+      private_class_method :normalize_dependency
+
+      def self.normalize_job_dependency(job)
+        {
+          job_class: normalize_job_class(job.class),
+          job_id: normalize_id(job.job_id, "job_id"),
+          workflow_id: WorkflowIdBuilder.new(configured_workflow_id_generator).build(job)
+        }
+      end
+      private_class_method :normalize_job_dependency
+
+      def self.configured_workflow_id_generator
+        ActiveJob::Temporal.config.workflow_id_generator if ActiveJob::Temporal.respond_to?(:config)
+      end
+      private_class_method :configured_workflow_id_generator
+
+      def self.normalize_hash_dependency(dependency)
+        normalized = {}
+        job_id = hash_value(dependency, :job_id)
+        workflow_id = hash_value(dependency, :workflow_id)
+        job_class = hash_value(dependency, :job_class)
+
+        normalized[:job_id] = normalize_id(job_id, "job_id") if job_id
+        normalized[:workflow_id] = normalize_id(workflow_id, "workflow_id") if workflow_id
+        normalized[:job_class] = normalize_job_class(job_class) if job_class
+
+        if normalized[:job_id].nil? && normalized[:workflow_id].nil?
+          raise ArgumentError, "dependency hashes must include job_id or workflow_id"
+        end
+
+        normalized
+      end
+      private_class_method :normalize_hash_dependency
+
+      def self.normalize_job_class(job_class)
+        name = if job_class.is_a?(Class) && job_class < ActiveJob::Base
+                 job_class.name
+               else
+                 job_class.to_s
+               end
+        unless name.match?(JOB_CLASS_NAME_PATTERN)
+          raise ArgumentError, "dependency job_class must be a named ActiveJob class or valid class name"
+        end
+
+        name
+      end
+      private_class_method :normalize_job_class
+
+      def self.normalize_id(value, name)
+        id = value.to_s
+        raise ArgumentError, "dependency #{name} must not be blank" if id.strip.empty?
+        raise ArgumentError, "dependency #{name} contains unsupported characters" unless id.match?(SAFE_ID_PATTERN)
+
+        id
+      end
+      private_class_method :normalize_id
+
+      def self.hash_value(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+      private_class_method :hash_value
+
+      def set(options = {})
+        enqueue_options = options.dup
+        dependencies_configured = enqueue_options.key?(:depends_on)
+        failure_policy_configured = enqueue_options.key?(:on_dependency_failure)
+
+        normalized_dependencies = if dependencies_configured
+                                    DependencyOptions.normalize(enqueue_options.delete(:depends_on))
+                                  end
+        normalized_failure_policy = normalize_dependency_failure_policy(
+          enqueue_options.delete(:on_dependency_failure),
+          failure_policy_configured
+        )
+
+        if failure_policy_configured && !dependencies_configured && normalized_dependencies.nil?
+          raise ArgumentError, "on_dependency_failure requires depends_on"
+        end
+
+        super(enqueue_options).tap do
+          @temporal_dependencies = normalized_dependencies if dependencies_configured
+          @temporal_dependency_failure_policy = normalized_failure_policy || :fail if dependencies_configured
+        end
+      end
+
+      private
+
+      def normalize_dependency_failure_policy(policy, configured)
+        return unless configured
+
+        DependencyOptions.normalize_failure_policy(policy)
+      end
+    end
+  end
+end
+
+ActiveJob::Base.prepend(ActiveJob::Temporal::DependencyOptions) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/external_operation.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "active_support/duration"
+
+module ActiveJob
+  module Temporal
+    class ExternalOperation
+      ACTIVITY = "activity"
+      WORKFLOW = "workflow"
+
+      attr_reader :operation, :temporal_type, :options
+
+      def self.activity(temporal_type, **options)
+        new(ACTIVITY, temporal_type, options)
+      end
+
+      def self.workflow(temporal_type, **options)
+        new(WORKFLOW, temporal_type, options)
+      end
+
+      def self.normalize(value)
+        return value.to_h if value.is_a?(self)
+        return normalize_hash(value) if external_operation_hash?(value)
+
+        nil
+      end
+
+      def self.external_operation_hash?(value)
+        value.respond_to?(:[]) &&
+          !payload_value(value, :temporal_operation).nil? &&
+          !payload_value(value, :temporal_type).nil?
+      end
+
+      def initialize(operation, temporal_type, options)
+        @operation = normalize_operation(operation)
+        @temporal_type = normalize_temporal_type(temporal_type)
+        @options = ExternalOperationOptions.normalize(@operation, options)
+      end
+
+      def to_h
+        {
+          temporal_operation: operation,
+          temporal_type: temporal_type,
+          options: options.dup
+        }
+      end
+
+      class << self
+        def normalize_hash(value)
+          operation = payload_value(value, :temporal_operation)
+          temporal_type = payload_value(value, :temporal_type)
+          options = payload_value(value, :options) || {}
+
+          new(operation, temporal_type, options).to_h
+        end
+
+        def payload_value(payload, key)
+          payload[key] || payload[key.to_s]
+        end
+      end
+
+      private
+
+      def normalize_operation(operation)
+        case operation.to_s
+        when ACTIVITY then ACTIVITY
+        when WORKFLOW then WORKFLOW
+        else raise ArgumentError, "external Temporal operation must be activity or workflow"
+        end
+      end
+
+      def normalize_temporal_type(value)
+        unless value.is_a?(String) && !value.strip.empty?
+          raise ArgumentError, "external Temporal type name must be a non-empty String"
+        end
+
+        value
+      end
+    end
+
+    class ExternalOperationOptions
+      ACTIVITY_OPTION_KEYS = %i[
+        activity_id
+        heartbeat_timeout
+        retry_policy
+        schedule_to_close_timeout
+        schedule_to_start_timeout
+        start_to_close_timeout
+        summary
+        task_queue
+      ].freeze
+
+      WORKFLOW_OPTION_KEYS = %i[
+        cron_schedule
+        execution_timeout
+        id
+        memo
+        retry_policy
+        run_timeout
+        static_details
+        static_summary
+        task_queue
+        task_timeout
+      ].freeze
+
+      DURATION_OPTION_KEYS = %i[
+        execution_timeout
+        heartbeat_timeout
+        run_timeout
+        schedule_to_close_timeout
+        schedule_to_start_timeout
+        start_to_close_timeout
+        task_timeout
+      ].freeze
+
+      RETRY_POLICY_DURATION_KEYS = %i[initial_interval max_interval].freeze
+
+      def self.normalize(operation, options)
+        supported_keys = option_keys_for(operation)
+        normalized_options = options.each_with_object({}) do |(key, value), normalized|
+          normalized_key = key.to_sym
+          unless supported_keys.include?(normalized_key)
+            raise ArgumentError, external_options_error(operation, supported_keys)
+          end
+
+          normalized[normalized_key] = normalize_option_value(normalized_key, value)
+        end
+        normalize_task_queue!(normalized_options)
+        normalized_options
+      end
+
+      class << self
+        private
+
+        def option_keys_for(operation)
+          case operation.to_s
+          when ExternalOperation::ACTIVITY then ACTIVITY_OPTION_KEYS
+          when ExternalOperation::WORKFLOW then WORKFLOW_OPTION_KEYS
+          else raise ArgumentError, "external Temporal operation must be activity or workflow"
+          end
+        end
+
+        def external_options_error(operation, supported_keys)
+          "external Temporal #{operation} options only support #{supported_keys.join(', ')}"
+        end
+
+        def normalize_option_value(key, value)
+          return normalize_duration(value) if DURATION_OPTION_KEYS.include?(key)
+          return normalize_retry_policy(value) if key == :retry_policy
+          return normalize_task_queue(value) if key == :task_queue
+
+          value
+        end
+
+        def normalize_retry_policy(value)
+          value = value.to_h if value.respond_to?(:to_h) && !value.is_a?(Hash)
+          return value unless value.is_a?(Hash)
+
+          value.each_with_object({}) do |(key, retry_value), normalized|
+            normalized_key = key.to_sym
+            normalized[normalized_key] = retry_policy_value(normalized_key, retry_value)
+          end
+        end
+
+        def retry_policy_value(key, value)
+          return normalize_duration(value) if RETRY_POLICY_DURATION_KEYS.include?(key)
+
+          value
+        end
+
+        def normalize_duration(value)
+          case value
+          when ActiveSupport::Duration, Numeric
+            value.to_f
+          else
+            raise ArgumentError, "Temporal timeout values must be numeric or ActiveSupport::Duration"
+          end
+        end
+
+        def normalize_task_queue!(options)
+          options[:task_queue] = normalize_task_queue(options[:task_queue])
+        end
+
+        def normalize_task_queue(value)
+          task_queue = value.to_s
+          return task_queue unless task_queue.strip.empty?
+
+          raise ArgumentError, "external Temporal steps require task_queue"
+        end
+      end
+    end
+  end
+end