activejob-temporal 0.1.0

data/lib/activejob/temporal/workflow_id_builder.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+
+module ActiveJob
+  module Temporal
+    # Builds deterministic Temporal workflow IDs for ActiveJob jobs.
+    #
+    # The default format keeps workflow IDs stable across enqueue retries so
+    # Temporal can reject duplicate starts for the same ActiveJob job_id.
+    class WorkflowIdBuilder
+      DEFAULT_PREFIX = "ajwf"
+      MAX_WORKFLOW_ID_LENGTH = 255
+      CONTROL_CHARACTER_PATTERN = /[[:cntrl:]]/
+
+      # @param strategy [#call, nil] Optional callable that receives the job and returns a workflow ID
+      def initialize(strategy = nil)
+        @strategy = strategy
+      end
+
+      # Builds a workflow ID from an ActiveJob instance.
+      #
+      # @param job [ActiveJob::Base] ActiveJob instance being enqueued
+      # @return [String] Workflow ID in format "ajwf:<ClassName>:<job_id>"
+      def build(job)
+        workflow_id = class_configured_workflow_id(job) ||
+                      configured_workflow_id(job) ||
+                      self.class.default_for(job)
+        self.class.validate!(workflow_id)
+        workflow_id
+      end
+
+      # Builds a workflow ID from a job class and job ID.
+      #
+      # @param job_class [Class] ActiveJob class
+      # @param job_id [String] ActiveJob job_id
+      # @return [String] Workflow ID in format "ajwf:<ClassName>:<job_id>"
+      def build_from_job_class(job_class, job_id)
+        workflow_id = self.class.prefixed_from_job_class(job_class, job_id) ||
+                      self.class.default_from_job_class(job_class, job_id)
+        self.class.validate!(workflow_id)
+        workflow_id
+      end
+
+      class << self
+        # Builds the default workflow ID for a job.
+        #
+        # @param job [ActiveJob::Base] ActiveJob instance being enqueued
+        # @return [String] Workflow ID in format "ajwf:<ClassName>:<job_id>"
+        def default_for(job)
+          default_from_job_class(job.class, job.job_id)
+        end
+
+        # Builds the default workflow ID from a job class and job ID.
+        #
+        # @param job_class [Class] ActiveJob class
+        # @param job_id [String] ActiveJob job_id
+        # @return [String] Workflow ID in format "ajwf:<ClassName>:<job_id>"
+        def default_from_job_class(job_class, job_id)
+          "#{DEFAULT_PREFIX}:#{job_class.name}:#{job_id}"
+        end
+
+        def prefixed_from_job_class(job_class, job_id)
+          prefix = workflow_id_prefix_for(job_class)
+          return unless prefix
+
+          "#{prefix}:#{job_id}"
+        end
+
+        def workflow_id_prefix_for(job_class)
+          return unless job_class.respond_to?(:temporal_workflow_id_prefix)
+
+          job_class.temporal_workflow_id_prefix
+        end
+
+        # Validates generated workflow IDs before they reach Temporal.
+        #
+        # @param workflow_id [Object] generated workflow ID
+        # @return [void]
+        # @raise [ConfigurationError] when the generated ID is invalid
+        def validate!(workflow_id)
+          unless workflow_id.is_a?(String)
+            raise ConfigurationError,
+                  "workflow_id_generator must return a String, got #{workflow_id.class}: #{workflow_id.inspect}"
+          end
+
+          if workflow_id.empty?
+            raise ConfigurationError, "workflow_id_generator returned an invalid workflow ID: must not be blank"
+          end
+
+          unless utf8_compatible?(workflow_id)
+            raise ConfigurationError,
+                  "workflow_id_generator returned an invalid workflow ID: must be valid UTF-8"
+          end
+
+          if workflow_id.length > MAX_WORKFLOW_ID_LENGTH
+            raise ConfigurationError,
+                  "workflow_id_generator returned an invalid workflow ID: maximum length is " \
+                  "#{MAX_WORKFLOW_ID_LENGTH} characters (got #{workflow_id.length})"
+          end
+
+          return unless workflow_id.match?(CONTROL_CHARACTER_PATTERN)
+
+          raise ConfigurationError,
+                "workflow_id_generator returned an invalid workflow ID: control characters are not allowed " \
+                "(got #{workflow_id.inspect})"
+        end
+
+        private
+
+        def utf8_compatible?(workflow_id)
+          workflow_id.valid_encoding? && (workflow_id.encoding == Encoding::UTF_8 || workflow_id.ascii_only?)
+        end
+      end
+
+      private
+
+      def class_configured_workflow_id(job)
+        prefix = self.class.workflow_id_prefix_for(job.class)
+        return "#{prefix}:#{job.job_id}" if prefix
+
+        strategy = class_workflow_id_strategy(job.class)
+        return unless strategy
+
+        call_class_strategy(strategy, job)
+      end
+
+      def class_workflow_id_strategy(job_class)
+        return unless job_class.respond_to?(:temporal_workflow_id)
+
+        job_class.temporal_workflow_id
+      end
+
+      def call_class_strategy(strategy, job)
+        strategy.call(*Array(job.arguments))
+      rescue ArgumentError => e
+        raise ConfigurationError,
+              "temporal_workflow_id block must accept this job's perform arguments: #{e.message}"
+      end
+
+      def configured_workflow_id(job)
+        return unless @strategy
+
+        call_strategy(job)
+      end
+
+      def call_strategy(job)
+        @strategy.call(job)
+      rescue ArgumentError => e
+        raise ConfigurationError,
+              "workflow_id_generator must accept one positional ActiveJob argument: #{e.message}"
+      end
+    end
+  end
+end

data/lib/activejob/temporal/workflow_identity.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_support/concern"
+
+module ActiveJob
+  module Temporal
+    module WorkflowIdentity
+      extend ActiveSupport::Concern
+
+      UNSET = Object.new.freeze
+      CONTROL_CHARACTER_PATTERN = /[[:cntrl:]]/
+
+      def self.normalize_identity_value(value, label)
+        raise ArgumentError, "#{label} must be a String" unless value.is_a?(String)
+
+        normalized = value.strip
+        raise ArgumentError, "#{label} must be present" if normalized.empty?
+        raise ArgumentError, "#{label} must be valid UTF-8" unless normalized.valid_encoding?
+
+        if normalized.match?(CONTROL_CHARACTER_PATTERN)
+          raise ArgumentError, "#{label} cannot contain control characters"
+        end
+
+        normalized
+      end
+
+      class_methods do
+        def temporal_workflow_name(name = UNSET)
+          unless name.equal?(UNSET)
+            @temporal_workflow_name = WorkflowIdentity.normalize_identity_value(name, "temporal_workflow_name")
+          end
+
+          @temporal_workflow_name
+        end
+
+        def temporal_workflow_id(&block)
+          if block
+            @temporal_workflow_id_strategy = block
+            @temporal_workflow_id_prefix = nil
+          end
+
+          @temporal_workflow_id_strategy
+        end
+
+        def temporal_workflow_id_prefix(prefix = UNSET)
+          unless prefix.equal?(UNSET)
+            @temporal_workflow_id_prefix = WorkflowIdentity.normalize_identity_value(
+              prefix,
+              "temporal_workflow_id_prefix"
+            )
+            @temporal_workflow_id_strategy = nil
+          end
+
+          @temporal_workflow_id_prefix
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Base.include(ActiveJob::Temporal::WorkflowIdentity) if defined?(ActiveJob::Base)

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

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "time"
+require "active_support/core_ext/hash/keys"
+require "temporalio/error"
+require "temporalio/retry_policy"
+require "temporalio/workflow"
+
+require_relative "../activities/rate_limit_activity"
+require_relative "dead_letter_support"
+require_relative "workflow_continue_as_new"
+require_relative "workflow_child_workflows"
+require_relative "workflow_chaining"
+require_relative "workflow_dependencies"
+require_relative "workflow_execution_steps"
+require_relative "workflow_interactions"
+require_relative "workflow_local_activities"
+require_relative "workflow_nexus"
+require_relative "workflow_versioning"
+
+module ActiveJob
+  module Temporal
+    module Workflows
+      RETRY_POLICY_MAX_ATTEMPT_KEYS = [:maximum_attempts, "maximum_attempts", :max_attempts, "max_attempts"].freeze
+
+      # Deterministic orchestration workflow for ActiveJob execution.
+      #
+      # This workflow serves as the durable scheduling and orchestration layer for ActiveJob.
+      # It handles delayed execution (via `Workflow.sleep`) and invokes the activity that
+      # executes the actual job logic.
+      #
+      # @note Workflow Determinism
+      #   This workflow MUST remain deterministic. It contains no I/O operations,
+      #   no random number generation, no system time calls (only `Workflow.now`),
+      #   and no direct method calls to external services. All side effects occur
+      #   in the activity layer. Temporal replays workflow code on every restart,
+      #   so non-deterministic changes will cause workflow execution errors.
+      #
+      # @note Non-Blocking Sleep
+      #   The `Workflow.sleep` method uses Temporal's durable timer mechanism. This means
+      #   scheduled jobs do not consume worker resources while waiting. The workflow is
+      #   persisted, and Temporal wakes it up at the scheduled time.
+      #
+      # @example Workflow execution flow
+      #   1. Extract scheduled_at timestamp from payload
+      #   2. If scheduled_at is in the future, sleep until that time (non-blocking)
+      #   3. Execute AjRunnerActivity with the payload and retry policy
+      #   4. Return activity result
+      #
+      # @example Replay behavior
+      #   # If a worker crashes during step 3, Temporal will replay the workflow:
+      #   # - Step 1: Re-reads scheduled_at (deterministic)
+      #   # - Step 2: Skips sleep (already elapsed, replayed from history)
+      #   # - Step 3: Continues from last checkpoint
+      #
+      # @see https://docs.temporal.io/workflows#deterministic-constraints Temporal Determinism Guide
+      # @see https://docs.temporal.io/workflows#timers Temporal Durable Timers
+      class AjWorkflow < Temporalio::Workflow::Definition
+        include DeadLetterSupport
+        include WorkflowContinueAsNew
+        include WorkflowChildWorkflows
+        include WorkflowChaining
+        include WorkflowDependencies
+        include WorkflowExecutionSteps
+        include WorkflowInteractions
+        include WorkflowLocalActivities
+        include WorkflowNexus
+        include WorkflowVersioning
+
+        DEFAULT_START_TO_CLOSE_TIMEOUT = 900.0
+        RATE_LIMIT_ACTIVITY_TIMEOUT = 30.0
+        RATE_LIMIT_RETRY_POLICY = Temporalio::RetryPolicy.new(max_attempts: 1)
+
+        workflow_signal dynamic: true
+        def handle_dynamic_signal(signal_name, *args)
+          handler_name = normalize_handler_name!(signal_name, "signal")
+
+          case handler_name
+          when "pause" then pause_workflow(args)
+          when "resume" then resume_workflow(args)
+          else dispatch_custom_signal(handler_name, args)
+          end
+        end
+
+        workflow_query dynamic: true
+        def handle_dynamic_query(query_name, *args)
+          handler_name = normalize_handler_name!(query_name, "query")
+
+          case handler_name
+          when "state" then deep_copy(workflow_state)
+          when "paused" then workflow_state["paused"]
+          when "pause_reason" then workflow_state["pause_reason"]
+          when "phase" then workflow_state["phase"]
+          when "signals" then deep_copy(workflow_state["signals"])
+          else dispatch_custom_query(handler_name, args)
+          end
+        end
+
+        workflow_update dynamic: true
+        def handle_dynamic_update(update_name, *args)
+          handler_name = normalize_handler_name!(update_name, "update")
+
+          dispatch_custom_update(handler_name, args)
+        end
+
+        # Executes the workflow: optionally sleeps until scheduled time, then runs the activity.
+        #
+        # @param payload [Hash] Job payload containing execution metadata
+        # @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] :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)
+        # @option payload [String] :scheduled_at ISO8601 timestamp for delayed execution (optional)
+        # @option payload [Integer] :executions Current execution count (default: 0)
+        # @option payload [Hash] :exception_executions Exception execution counts (default: {})
+        #
+        # @return [Object, nil] Result from the activity execution
+        #
+        # @raise [Temporalio::Error::ActivityError] if activity execution fails (propagates from activity)
+        # @raise [Temporalio::Error::TimeoutError] if activity exceeds start_to_close_timeout
+        #
+        # @note Durable Timers
+        #   If scheduled_at is in the future, the workflow creates a durable timer.
+        #   The timer persists across worker restarts and does not block worker threads.
+        #
+        # @example Immediate execution
+        #   execute({ job_class: "MyJob", job_id: "123", arguments: ["arg1"] })
+        #
+        # @example Scheduled execution (non-blocking sleep)
+        #   execute({
+        #     job_class: "MyJob",
+        #     job_id: "123",
+        #     scheduled_at: "2025-10-31T12:00:00Z",
+        #     arguments: []
+        #   })
+        #   # Workflow sleeps until scheduled time without consuming worker resources
+        #
+        # @example Replay behavior on worker restart
+        #   # Initial execution: Workflow sleeps for 1 hour
+        #   # Worker crashes after 30 minutes
+        #   # Workflow is replayed: Sleep is skipped (already elapsed), activity executes immediately
+        #
+        # @note Durable Timer Guarantees
+        #   Temporal's durable timers persist across worker restarts and cluster outages.
+        #   Even if all workers are down, the scheduled job will execute once workers
+        #   are back online. The timer is stored in Temporal's event history, making it
+        #   highly reliable for long-term scheduling.
+        #
+        # @see Activities::AjRunnerActivity#execute
+        def execute(payload)
+          payload = schedule_execution_payload(payload)
+          current_activity_payload = payload
+          configure_workflow_state(payload)
+          configure_workflow_interactions(payload)
+
+          result = execute_workflow_steps(payload) do |chain_payload|
+            current_activity_payload = chain_payload
+          end
+
+          workflow_state["phase"] = "completed"
+          result
+        rescue Temporalio::Error::ActivityError => e
+          workflow_state["phase"] = "failed"
+          if dead_letterable_failure?(current_activity_payload, e)
+            start_dead_letter_workflow(current_activity_payload, e)
+          end
+          raise
+        end
+
+        private
+
+        def schedule_execution_payload(payload)
+          return payload unless payload_value(payload, :schedule_id)
+
+          execution_job_id = Temporalio::Workflow.info.workflow_id
+          payload.merge(
+            "job_id" => execution_job_id,
+            "schedule_execution_job_id" => execution_job_id
+          )
+        end
+
+        # Extracts scheduled execution time from payload.
+        # @api private
+        def extract_scheduled_time(payload)
+          timestamp = payload[:scheduled_at] || payload["scheduled_at"]
+          return unless timestamp
+
+          Time.iso8601(timestamp)
+        end
+
+        def wait_until_scheduled(payload)
+          scheduled_time = extract_scheduled_time(payload)
+          workflow_state["phase"] = "scheduled" if scheduled_time
+          sleep_until(scheduled_time) if scheduled_time
+          wait_while_paused
+        end
+
+        # Sleeps until target time using Temporal's durable timer.
+        # @api private
+        def sleep_until(target_time)
+          now = Temporalio::Workflow.now
+          delay = target_time - now
+          return unless delay.positive?
+
+          Temporalio::Workflow.sleep(delay)
+        end
+
+        def wait_for_rate_limit(payload)
+          return unless rate_limits?(payload)
+
+          workflow_state["phase"] = "waiting_rate_limit"
+          loop do
+            wait_while_paused
+            wait_time = execute_helper_activity(
+              payload,
+              :rate_limit,
+              ActiveJob::Temporal::Activities::RateLimitActivity,
+              payload,
+              schedule_to_close_timeout: RATE_LIMIT_ACTIVITY_TIMEOUT,
+              start_to_close_timeout: RATE_LIMIT_ACTIVITY_TIMEOUT,
+              retry_policy: RATE_LIMIT_RETRY_POLICY
+            ).to_f
+            break unless wait_time.positive?
+
+            Temporalio::Workflow.sleep(wait_time)
+          end
+        end
+
+        def rate_limits?(payload)
+          Array(payload[:rate_limits] || payload["rate_limits"]).any?
+        end
+
+        # Builds activity execution options with timeout configuration and retry policy.
+        #
+        # Merges timeout options from deterministic payload values only.
+        #
+        # @api private
+        def activity_options(payload)
+          options = default_activity_options(payload)
+
+          temporal_opts = payload[:temporal_options] || payload["temporal_options"]
+          options.merge!(temporal_opts.symbolize_keys) if temporal_opts
+
+          retry_policy_hash = payload[:retry_policy] || payload["retry_policy"]
+          options[:retry_policy] = build_retry_policy(retry_policy_hash) if retry_policy_hash
+          task_queue = payload[:activity_task_queue] || payload["activity_task_queue"]
+          options[:task_queue] = task_queue if task_queue
+
+          options
+        end
+
+        # Builds activity timeout defaults from workflow input.
+        # @api private
+        def default_activity_options(payload)
+          options = payload[:default_activity_options] || payload["default_activity_options"]
+          return options.symbolize_keys if options
+
+          { start_to_close_timeout: DEFAULT_START_TO_CLOSE_TIMEOUT }
+        end
+
+        # Builds Temporalio::RetryPolicy from hash.
+        # @api private
+        def build_retry_policy(hash)
+          # RetryMapper returns maximum_attempts, but Temporalio::RetryPolicy expects max_attempts
+          max_attempts_value = RETRY_POLICY_MAX_ATTEMPT_KEYS.filter_map { |key| hash[key] }.first
+          retry_policy_options = {
+            initial_interval: hash[:initial_interval] || hash["initial_interval"],
+            backoff_coefficient: hash[:backoff_coefficient] || hash["backoff_coefficient"],
+            max_interval: hash[:max_interval] || hash["max_interval"],
+            max_attempts: max_attempts_value,
+            non_retryable_error_types: hash[:non_retryable_error_types] || hash["non_retryable_error_types"]
+          }.compact
+
+          Temporalio::RetryPolicy.new(**retry_policy_options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "digest"
+require "temporalio/error"
+require "temporalio/workflow"
+
+module ActiveJob
+  module Temporal
+    module Workflows
+      module DeadLetterSupport
+        private
+
+        def dead_letterable_failure?(payload, error)
+          metadata = dead_letter_metadata(payload)
+          return false unless metadata
+          return false unless job_execution_activity_failure?(error)
+
+          return false unless error.retry_state == Temporalio::Error::RetryState::MAXIMUM_ATTEMPTS_REACHED
+          return true if dead_letter_queue_present?(metadata)
+
+          log_dead_letter_skipped(metadata, error)
+          false
+        end
+
+        def start_dead_letter_workflow(payload, error)
+          metadata = dead_letter_metadata(payload)
+          entry = dead_letter_entry(payload, error, metadata)
+
+          Temporalio::Workflow.start_child_workflow(
+            ActiveJob::Temporal::Workflows::DeadLetterWorkflow,
+            entry,
+            id: entry.fetch("id"),
+            task_queue: metadata_value(metadata, :queue),
+            parent_close_policy: Temporalio::Workflow::ParentClosePolicy::ABANDON
+          )
+        end
+
+        def dead_letter_entry(payload, error, metadata)
+          {
+            "id" => dead_letter_workflow_id(metadata),
+            "state" => "pending",
+            "payload" => payload,
+            "failure" => failure_metadata(error),
+            "metadata" => dead_letter_failure_metadata(metadata)
+          }
+        end
+
+        def dead_letter_failure_metadata(metadata)
+          job_class = metadata_value(metadata, :job_class)
+          job_id = metadata_value(metadata, :job_id)
+          {
+            "job_class" => job_class,
+            "job_id" => job_id,
+            "original_queue_name" => metadata_value(metadata, :queue_name),
+            "original_task_queue" => metadata_value(metadata, :task_queue) || metadata_value(metadata, :queue_name),
+            "workflow_id" => workflow_id(job_class, job_id),
+            "workflow_run_id" => workflow_run_id,
+            "attempt" => metadata_value(metadata, :after_attempts),
+            "max_attempts" => metadata_value(metadata, :after_attempts),
+            "auto_discard_after_seconds" => metadata_value(metadata, :auto_discard_after_seconds),
+            "failed_at" => Temporalio::Workflow.now.iso8601
+          }.compact
+        end
+
+        def failure_metadata(error)
+          source_error = error.cause || error
+          class_name = failure_class_name(source_error)
+          {
+            "class" => class_name,
+            "message" => source_error.message.to_s,
+            "retry_state" => error.retry_state,
+            "fingerprint" => Digest::SHA256.hexdigest("#{class_name}:#{source_error.message}")
+          }
+        end
+
+        def failure_class_name(error)
+          type = error.type if error.is_a?(Temporalio::Error::ApplicationError)
+          return type unless type.to_s.strip.empty?
+
+          error.class.name
+        end
+
+        def dead_letter_workflow_id(metadata)
+          "ajdlq:#{metadata_value(metadata, :job_class)}:#{metadata_value(metadata, :job_id)}"
+        end
+
+        def workflow_id(job_class, job_id)
+          info = Temporalio::Workflow.info
+          info.workflow_id if info.respond_to?(:workflow_id)
+        rescue StandardError
+          "ajwf:#{job_class}:#{job_id}"
+        end
+
+        def workflow_run_id
+          info = Temporalio::Workflow.info
+          info.run_id if info.respond_to?(:run_id)
+        rescue StandardError
+          nil
+        end
+
+        def dead_letter_metadata(payload)
+          payload[:dead_letter] || payload["dead_letter"]
+        end
+
+        def job_execution_activity_failure?(error)
+          error.respond_to?(:activity_type) && error.activity_type == "AjRunnerActivity"
+        end
+
+        def dead_letter_queue_present?(metadata)
+          metadata_value(metadata, :queue).to_s.strip.present?
+        end
+
+        def log_dead_letter_skipped(metadata, error)
+          Temporalio::Workflow.logger.warn(
+            event: "dead_letter_skipped",
+            reason: "blank_queue",
+            job_class: metadata_value(metadata, :job_class),
+            job_id: metadata_value(metadata, :job_id),
+            queue_name: metadata_value(metadata, :queue_name),
+            retry_state: error.retry_state
+          )
+        end
+
+        def metadata_value(metadata, key)
+          return unless metadata.respond_to?(:[])
+
+          metadata[key] || metadata[key.to_s]
+        rescue TypeError
+          nil
+        end
+      end
+    end
+  end
+end