activejob-temporal 0.1.0

data/lib/activejob/temporal/activities/dependency_status_activity.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "temporalio/activity"
+require "temporalio/client/workflow_execution_status"
+require "temporalio/error"
+
+require_relative "../workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    module Activities
+      class DependencyStatusActivity < Temporalio::Activity::Definition
+        SAFE_QUERY_VALUE_PATTERN = /\A[A-Za-z0-9_.:-]+\z/
+        WORKFLOW_STATES = {
+          Temporalio::Client::WorkflowExecutionStatus::RUNNING => "running",
+          Temporalio::Client::WorkflowExecutionStatus::COMPLETED => "completed",
+          Temporalio::Client::WorkflowExecutionStatus::FAILED => "failed",
+          Temporalio::Client::WorkflowExecutionStatus::CANCELED => "canceled",
+          Temporalio::Client::WorkflowExecutionStatus::TERMINATED => "terminated",
+          Temporalio::Client::WorkflowExecutionStatus::CONTINUED_AS_NEW => "continued_as_new",
+          Temporalio::Client::WorkflowExecutionStatus::TIMED_OUT => "timed_out"
+        }.freeze
+
+        def execute(dependencies)
+          Array(dependencies).map { |dependency| status_for(normalize_dependency(dependency)) }
+        end
+
+        private
+
+        def status_for(dependency)
+          workflow_reference = find_workflow_reference(dependency)
+          return status_payload(dependency, "not_found") unless workflow_reference
+
+          status_from_description(dependency, describe_workflow(workflow_reference))
+        rescue StandardError => e
+          fallback_description = describe_search_attribute_workflow(dependency) if rpc_not_found?(e)
+          return status_from_description(dependency, fallback_description) if fallback_description
+          return status_payload(dependency, "not_found") if rpc_not_found?(e) || rpc_invalid_argument?(e)
+
+          raise
+        end
+
+        def status_from_description(dependency, description)
+          status_payload(
+            dependency,
+            WORKFLOW_STATES.fetch(description.status, "unknown"),
+            workflow_id: description.id,
+            run_id: description.run_id
+          )
+        end
+
+        def normalize_dependency(dependency)
+          dependency.each_with_object({}) do |(key, value), normalized|
+            normalized[key.to_s] = value
+          end
+        end
+
+        def find_workflow_reference(dependency)
+          workflow_id = dependency["workflow_id"]
+          return { workflow_id: workflow_id, run_id: nil } if workflow_id
+
+          search_workflow_reference(dependency) || default_workflow_reference(dependency)
+        end
+
+        def search_workflow_reference(dependency)
+          job_id = dependency["job_id"]
+          return unless job_id
+
+          workflow = client.list_workflows(workflow_search_query(dependency)).first
+          return unless workflow
+
+          {
+            workflow_id: workflow.id,
+            run_id: workflow.respond_to?(:run_id) ? workflow.run_id : nil
+          }
+        rescue StandardError => e
+          return nil if rpc_invalid_argument?(e)
+
+          raise
+        end
+
+        def default_workflow_reference(dependency)
+          job_class = dependency["job_class"]
+          job_id = dependency["job_id"]
+          return unless job_class && job_id
+
+          workflow_id = "#{WorkflowIdBuilder::DEFAULT_PREFIX}:#{job_class}:#{job_id}"
+          WorkflowIdBuilder.validate!(workflow_id)
+          {
+            workflow_id: workflow_id,
+            run_id: nil
+          }
+        end
+
+        def workflow_search_query(dependency)
+          filters = ["ajJobId='#{safe_query_value(dependency.fetch('job_id'))}'"]
+          job_class = dependency["job_class"]
+          filters.unshift("ajClass='#{safe_query_value(job_class)}'") if job_class
+          filters.join(" AND ")
+        end
+
+        def safe_query_value(value)
+          string_value = value.to_s
+          return string_value if string_value.match?(SAFE_QUERY_VALUE_PATTERN)
+
+          raise ArgumentError,
+                "dependency query values may only contain letters, numbers, underscore, hyphen, period, and colon"
+        end
+
+        def describe_workflow(workflow_reference)
+          client.workflow_handle(
+            workflow_reference.fetch(:workflow_id),
+            run_id: workflow_reference[:run_id]
+          ).describe
+        end
+
+        def describe_search_attribute_workflow(dependency)
+          return unless dependency["workflow_id"] && dependency["job_id"]
+
+          fallback_dependency = dependency.dup
+          fallback_dependency.delete("workflow_id")
+          workflow_reference = search_workflow_reference(fallback_dependency)
+          return unless workflow_reference
+
+          describe_workflow(workflow_reference)
+        rescue StandardError => e
+          return nil if rpc_not_found?(e) || rpc_invalid_argument?(e)
+
+          raise
+        end
+
+        def status_payload(dependency, state, workflow_id: nil, run_id: nil)
+          {
+            "job_id" => dependency["job_id"],
+            "job_class" => dependency["job_class"],
+            "workflow_id" => workflow_id || dependency["workflow_id"],
+            "run_id" => run_id,
+            "state" => state
+          }.compact
+        end
+
+        def client
+          ActiveJob::Temporal.client
+        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
+
+        def rpc_invalid_argument?(error)
+          defined?(Temporalio::Error::RPCError) &&
+            error.is_a?(Temporalio::Error::RPCError) &&
+            error.code == Temporalio::Error::RPCError::Code::INVALID_ARGUMENT
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/activities/rate_limit_activity.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "temporalio/activity"
+
+module ActiveJob
+  module Temporal
+    module Activities
+      # Activity wrapper around user-configured rate limiter I/O.
+      class RateLimitActivity < Temporalio::Activity::Definition
+        def execute(payload)
+          rate_limits = payload[:rate_limits] || payload["rate_limits"]
+          return 0.0 if Array(rate_limits).empty?
+
+          limiter = ActiveJob::Temporal.config.rate_limiter
+          raise ConfigurationError, "rate_limiter is required when rate limits are configured" unless limiter
+
+          normalize_wait_time(call_limiter(limiter, rate_limits))
+        end
+
+        private
+
+        def call_limiter(limiter, rate_limits)
+          return limiter.wait_time_for(rate_limits) if limiter.respond_to?(:wait_time_for)
+          return limiter.call(rate_limits) if limiter.respond_to?(:call)
+
+          raise ConfigurationError, "rate_limiter must respond to #wait_time_for or #call"
+        end
+
+        def normalize_wait_time(value)
+          wait_time = Float(value)
+          raise ArgumentError, "rate limiter wait time must be finite" unless wait_time.finite?
+          raise ArgumentError, "rate limiter wait time must not be negative" if wait_time.negative?
+
+          wait_time
+        rescue TypeError
+          raise ArgumentError, "rate limiter wait time must be numeric"
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/adapter.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_job/queue_adapters/abstract_adapter"
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    # Helper methods for the TemporalAdapter.
+    #
+    # This module provides utility functions for building workflow IDs and resolving
+    # task queue names. Used internally by the adapter.
+    module Adapter
+      module_function
+
+      # Builds deterministic workflow ID used for Temporal workflows.
+      #
+      # Delegates ID construction to WorkflowIdBuilder while preserving the public
+      # helper used by integrations and tests. Creates a unique, reproducible
+      # workflow ID from the job class and job ID.
+      # This enables idempotent enqueuing: duplicate enqueue calls with the same job_id
+      # will be rejected by Temporal's FAIL conflict policy.
+      #
+      # @param job [ActiveJob::Base] ActiveJob instance being enqueued
+      # @return [String] Workflow ID in format "ajwf:<ClassName>:<job_id>"
+      #
+      # @note Idempotency Guarantee
+      #   The workflow ID format ensures that jobs with the same job_id will never
+      #   execute twice. This is critical for preventing duplicate processing in
+      #   distributed systems.
+      #
+      # @example Basic usage
+      #   job = MyJob.new
+      #   job.job_id # => "abc-123"
+      #   build_workflow_id(job) # => "ajwf:MyJob:abc-123"
+      #
+      # @example Duplicate enqueue
+      #   MyJob.set(job_id: "unique-id").perform_later("arg")  # First enqueue succeeds
+      #   MyJob.set(job_id: "unique-id").perform_later("arg")  # Second enqueue returns false
+      #
+      # @see TemporalAdapter#enqueue
+      def build_workflow_id(job)
+        WorkflowIdBuilder.new(configured_workflow_id_generator).build(job)
+      end
+
+      def configured_workflow_id_generator
+        ActiveJob::Temporal.config.workflow_id_generator if ActiveJob::Temporal.respond_to?(:config)
+      end
+      private_class_method :configured_workflow_id_generator
+
+      # Resolves the Temporal task queue name for a given job.
+      #
+      # Extracts the queue name from the job and applies the configured task_queue_prefix
+      # if present. Defaults to "default" if queue_name is blank.
+      #
+      # @param job [ActiveJob::Base] ActiveJob instance being enqueued
+      # @return [String] Task queue name, optionally prefixed
+      # @example Without prefix
+      #   job.queue_name # => "mailers"
+      #   resolve_task_queue(job) # => "mailers"
+      # @example With prefix
+      #   ActiveJob::Temporal.config.task_queue_prefix = "myapp-"
+      #   job.queue_name # => "mailers"
+      #   resolve_task_queue(job) # => "myapp-mailers"
+      def resolve_task_queue(job, config: ActiveJob::Temporal.config)
+        queue_name = priority_task_queue(job, config) || job.queue_name.to_s.strip
+        queue_name = "default" if queue_name.empty?
+
+        prefix = config.task_queue_prefix
+        return queue_name if prefix.nil? || prefix.to_s.strip.empty?
+
+        "#{prefix}#{queue_name}"
+      end
+
+      def priority_task_queue(job, config)
+        priority_task_queues = config.respond_to?(:priority_task_queues) ? config.priority_task_queues : {}
+        return unless priority_task_queues.is_a?(Hash) && priority_task_queues.any?
+
+        return unless job.respond_to?(:priority)
+
+        job_priority = job.priority
+        return unless job_priority.is_a?(Integer)
+
+        priority_task_queues[job_priority]&.to_s&.strip
+      end
+      private_class_method :priority_task_queue
+    end
+  end
+end
+
+module ActiveJob
+  module QueueAdapters
+    # ActiveJob queue adapter for Temporal workflows.
+    #
+    # This adapter integrates ActiveJob with Temporal by starting workflows for each
+    # enqueued job. It translates ActiveJob's `perform_later` and `set(wait:).perform_later`
+    # into Temporal workflow starts with the AjWorkflow.
+    #
+    # @note Idempotent Enqueuing
+    #   Jobs with the same job_id will not be enqueued twice. The adapter uses
+    #   FAIL conflict policy, so duplicate enqueue attempts surface as
+    #   DuplicateEnqueueError through ActiveJob's enqueue status.
+    #
+    # @note Transaction Safety
+    #   Jobs using the Temporal adapter are opted into ActiveJob's
+    #   `enqueue_after_transaction_commit` setting. This defers workflow starts
+    #   until the current database transaction commits and prevents workflows from
+    #   starting for rolled-back jobs.
+    #
+    # @example Basic usage
+    #   class MyJob < ApplicationJob
+    #     self.queue_adapter = :temporal
+    #     def perform(arg)
+    #       # job logic
+    #     end
+    #   end
+    #   MyJob.perform_later("arg")
+    #
+    # @example Scheduled job
+    #   MyJob.set(wait: 1.hour).perform_later("arg")
+    class TemporalAdapter < ActiveJob::QueueAdapters::AbstractAdapter
+      # @return [WorkflowEnqueuer] the enqueuer service
+      attr_reader :enqueuer
+
+      # Initialize the adapter with a WorkflowEnqueuer service instance.
+      def initialize
+        super
+
+        config = ActiveJob::Temporal.config
+        logger = config.logger
+
+        @enqueuer = ActiveJob::Temporal::WorkflowEnqueuer.new(
+          -> { ActiveJob::Temporal.client },
+          config,
+          logger
+        )
+      end
+
+      # Enqueues a job for immediate execution on Temporal by starting the AjWorkflow.
+      #
+      # Delegates to the WorkflowEnqueuer service to handle the mechanics of workflow
+      # creation and startup.
+      #
+      # @param job [ActiveJob::Base] the job instance provided by ActiveJob
+      # @return [Object] workflow run handle if provided by Temporal SDK
+      #
+      # @raise [ActiveJob::SerializationError] if payload serialization fails or exceeds max_payload_size_kb
+      # @raise [ActiveJob::EnqueueError] if the Temporal client cannot start the workflow
+      # @raise [ActiveJob::Temporal::ConfigurationError] if configuration is invalid
+      #
+      # @note FAIL Conflict Policy
+      #   Duplicate job_id values raise DuplicateEnqueueError. ActiveJob catches
+      #   this as an enqueue failure, so `perform_later` returns false and the
+      #   yielded job exposes the error through `enqueue_error`.
+      #
+      # @example Basic usage
+      #   adapter = TemporalAdapter.new
+      #   job = MyJob.new("arg1", "arg2")
+      #   adapter.enqueue(job)
+      #
+      # @example Handling serialization errors
+      #   begin
+      #     MyJob.perform_later(huge_object)
+      #   rescue ActiveJob::SerializationError => e
+      #     Rails.logger.error("Payload too large: #{e.message}")
+      #     MyJob.perform_later(huge_object.id)  # Pass ID instead
+      #   end
+      #
+      # @example Handling configuration errors
+      #   begin
+      #     MyJob.perform_later("arg")
+      #   rescue ActiveJob::Temporal::ConfigurationError => e
+      #     # Configuration validation failed
+      #     Rails.logger.fatal("Invalid Temporal configuration: #{e.message}")
+      #   end
+      #
+      # @example Handling enqueue errors (cluster unreachable)
+      #   begin
+      #     MyJob.perform_later("arg")
+      #   rescue ActiveJob::EnqueueError => e
+      #     # Temporal cluster is down or network issue
+      #     Rails.logger.error("Cannot enqueue job: #{e.message}")
+      #     # Consider queuing to fallback system or retrying later
+      #   end
+      #
+      # @see #enqueue_at
+      # @see https://docs.temporal.io/workflows#workflow-id-reuse-policy Temporal Workflow ID Policies
+      def enqueue(job)
+        @enqueuer.enqueue(job)
+      end
+
+      # Enqueues a job for execution at a specific time by starting the AjWorkflow immediately.
+      #
+      # The workflow starts immediately but sleeps (non-blockingly) until the scheduled time
+      # before executing the activity. This leverages Temporal's durable timers.
+      #
+      # @param job [ActiveJob::Base] the job instance provided by ActiveJob
+      # @param timestamp [Integer, Float] UNIX timestamp when the job should be executed
+      # @return [Object] workflow run handle if provided by Temporal SDK
+      #
+      # @raise [ActiveJob::SerializationError] if payload serialization fails or exceeds max_payload_size_kb
+      # @raise [ActiveJob::EnqueueError] if the Temporal client cannot start the workflow
+      # @raise [ActiveJob::Temporal::ConfigurationError] if configuration is invalid
+      #
+      # @note Non-Blocking Sleep
+      #   The workflow uses Temporal's durable timer mechanism, so scheduled jobs
+      #   do not consume worker resources while waiting.
+      #
+      # @example Basic usage
+      #   adapter = TemporalAdapter.new
+      #   job = MyJob.new("arg")
+      #   adapter.enqueue_at(job, 1.hour.from_now.to_i)
+      #
+      # @example Scheduling with ActiveJob DSL
+      #   MyJob.set(wait: 1.hour).perform_later("arg")
+      #
+      # @example Scheduling with wait_until
+      #   MyJob.set(wait_until: Date.tomorrow.noon).perform_later("arg")
+      #
+      # @example Far-future scheduling (durable timer benefits)
+      #   # Schedule a job 30 days in the future
+      #   MyJob.set(wait: 30.days).perform_later("reminder", user_id: 123)
+      #   # The workflow sleeps for 30 days without consuming resources
+      #
+      # @see #enqueue
+      # @see Workflows::AjWorkflow#sleep_until
+      def enqueue_at(job, timestamp)
+        scheduled_time = Time.at(timestamp)
+        @enqueuer.enqueue(job, scheduled_at: scheduled_time)
+      end
+
+      # Signals transaction-aware ActiveJob versions to defer enqueuing until after commit.
+      #
+      # Rails 8 uses the job class `enqueue_after_transaction_commit` setting instead. The
+      # TransactionSafety hook enables that setting when a job selects the Temporal adapter.
+      # This method remains for adapter-contract compatibility with older ActiveJob behavior.
+      #
+      # @return [Boolean] always returns true
+      # @example Transaction-safe enqueuing
+      #   ActiveRecord::Base.transaction do
+      #     user = User.create!(name: "Alice")
+      #     MyJob.perform_later(user) # Deferred until commit
+      #     raise ActiveRecord::Rollback # Job is NOT enqueued
+      #   end
+      #
+      # @example Ensuring job runs after DB commit
+      #   ActiveRecord::Base.transaction do
+      #     order = Order.create!(amount: 100)
+      #     PaymentJob.perform_later(order.id)
+      #     # Job will not start until transaction commits successfully
+      #   end
+      def enqueue_after_transaction_commit?
+        true
+      end
+    end
+  end
+end

data/lib/activejob/temporal/audit_log.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module ActiveJob
+  module Temporal
+    module AuditLog
+      extend self
+
+      SENSITIVE_ATTRIBUTE_NAMES = %w[
+        arguments
+        args
+        cause
+        error
+        error_message
+        exception
+        message
+        payload
+        result
+        target
+      ].freeze
+
+      def record(event_name, attributes = {})
+        config = ActiveJob::Temporal.config
+        return unless config.audit_log
+
+        logger = config.audit_logger || config.logger
+        Logger.log_to(logger, :info, event_name, sanitized_attributes(attributes))
+      end
+
+      def job_attributes_from_payload(payload)
+        payload = payload.to_h
+        attributes = {
+          job_class: value_from(payload, :job_class),
+          job_id: value_from(payload, :job_id),
+          queue: value_from(payload, :queue_name),
+          executions: value_from(payload, :executions),
+          scheduled_at: value_from(payload, :scheduled_at)
+        }
+
+        attributes.compact
+      end
+
+      def activity_attributes_from_payload(payload)
+        job_attributes_from_payload(payload)
+          .merge(activity_context_attributes)
+          .merge(worker_id: ActiveJob::Temporal.config.identity)
+          .compact
+      end
+
+      def error_attributes(error)
+        {
+          error_class: error.class.name,
+          error_fingerprint: error_fingerprint(error)
+        }.compact
+      end
+
+      def cancelled_error?(error)
+        defined?(Temporalio::Error::CanceledError) && error.is_a?(Temporalio::Error::CanceledError)
+      end
+
+      def elapsed_milliseconds(started_at)
+        ((monotonic_time - started_at) * 1000).round(2)
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      private
+
+      def sanitized_attributes(attributes)
+        attributes.to_h.each_with_object({}) do |(key, value), result|
+          next if SENSITIVE_ATTRIBUTE_NAMES.include?(key.to_s)
+          next if value.nil?
+
+          result[key] = value
+        end
+      end
+
+      def value_from(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+
+      def activity_context_attributes
+        return {} unless defined?(Temporalio::Activity::Context)
+        return {} unless Temporalio::Activity::Context.exist?
+
+        activity_info = Temporalio::Activity::Context.current.info
+        {
+          workflow_id: context_value(activity_info, :workflow_id),
+          run_id: context_value(activity_info, :workflow_run_id, :run_id),
+          attempt: context_value(activity_info, :attempt)
+        }.compact
+      rescue StandardError
+        {}
+      end
+
+      def context_value(object, *methods)
+        methods.each do |method_name|
+          return object.public_send(method_name) if object.respond_to?(method_name)
+        end
+
+        nil
+      end
+
+      def error_fingerprint(error)
+        source = [
+          error.class.name,
+          error.message,
+          *Array(error.backtrace).first(20)
+        ].compact.join("\n")
+
+        Digest::SHA256.hexdigest(source)
+      end
+    end
+  end
+end

data/lib/activejob/temporal/batch_enqueue_result.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+
+module ActiveJob
+  module Temporal
+    class BatchEnqueueValidationError < Error
+      attr_reader :errors
+
+      def initialize(errors)
+        @errors = errors
+        super("Invalid batch enqueue jobs: #{format_errors(errors)}")
+      end
+
+      private
+
+      def format_errors(errors)
+        errors.map { |error| "item #{error[:index]} #{error[:error]}" }.join(", ")
+      end
+    end
+
+    class BatchEnqueueItemResult
+      attr_reader :index, :job, :status, :handle, :error
+
+      def initialize(index:, job:, status:, handle: nil, error: nil)
+        @index = index
+        @job = job
+        @status = status
+        @handle = handle
+        @error = error
+      end
+
+      def success?
+        status == :success
+      end
+
+      def duplicate?
+        status == :duplicate
+      end
+
+      def failure?
+        status == :failed
+      end
+
+      def to_h
+        {
+          index: index,
+          job_class: job.class.name,
+          job_id: job.job_id,
+          status: status,
+          handle: handle,
+          error: formatted_error
+        }.compact
+      end
+
+      private
+
+      def formatted_error
+        return unless error
+
+        "#{error.class}: #{error.message}"
+      end
+    end
+
+    class BatchEnqueueResult
+      attr_reader :results
+
+      def initialize(results)
+        @results = results
+      end
+
+      def success?
+        failures.empty?
+      end
+
+      def successes
+        results.select(&:success?)
+      end
+
+      def duplicates
+        results.select(&:duplicate?)
+      end
+
+      def failures
+        results.select(&:failure?)
+      end
+
+      def success_count
+        successes.length
+      end
+
+      def duplicate_count
+        duplicates.length
+      end
+
+      def failure_count
+        failures.length
+      end
+
+      def to_h
+        {
+          success_count: success_count,
+          duplicate_count: duplicate_count,
+          failure_count: failure_count,
+          results: results.map(&:to_h)
+        }
+      end
+    end
+  end
+end