activejob-temporal 0.1.0

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

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module Workflows
+      module WorkflowInteractions
+        HANDLER_NAME_PATTERN = /\A[a-zA-Z_]\w*\z/
+
+        private
+
+        def pause_workflow(args)
+          workflow_state["paused"] = true
+          workflow_state["pause_reason"] = args.first if args.any?
+          record_signal("pause", args)
+          nil
+        end
+
+        def resume_workflow(args)
+          workflow_state["paused"] = false
+          workflow_state.delete("pause_reason")
+          record_signal("resume", args)
+          nil
+        end
+
+        def dispatch_custom_signal(handler_name, args)
+          unless workflow_interactions_configured?
+            buffered_custom_signals << [handler_name, deep_copy(args)]
+            return nil
+          end
+
+          dispatch_configured_custom_signal(handler_name, args)
+        end
+
+        def dispatch_configured_custom_signal(handler_name, args)
+          handler = workflow_signal_handlers[handler_name]
+          raise ArgumentError, "Unknown workflow signal: #{handler_name}" unless handler
+
+          handler.call(workflow_state["custom"], *args)
+          record_signal(handler_name, args)
+          nil
+        end
+
+        def dispatch_custom_query(handler_name, args)
+          handler = workflow_query_handlers[handler_name]
+          raise ArgumentError, "Unknown workflow query: #{handler_name}" unless handler
+
+          handler.call(deep_copy(workflow_state["custom"]), *args)
+        end
+
+        def dispatch_custom_update(handler_name, args)
+          handler = workflow_update_handlers[handler_name]
+          raise ArgumentError, "Unknown workflow update: #{handler_name}" unless handler
+
+          result = handler.call(workflow_state["custom"], *args)
+          record_update(handler_name, args)
+          result
+        end
+
+        def record_signal(handler_name, args)
+          workflow_state["signals"][handler_name] = {
+            "args" => deep_copy(args),
+            "received_at" => Temporalio::Workflow.now.iso8601
+          }
+        end
+
+        def record_update(handler_name, args)
+          workflow_state["updates"][handler_name] = {
+            "args" => deep_copy(args),
+            "accepted_at" => Temporalio::Workflow.now.iso8601
+          }
+        end
+
+        def configure_workflow_state(payload)
+          restore_workflow_state(payload)
+          workflow_state["job_class"] = payload[:job_class] || payload["job_class"]
+          workflow_state["job_id"] = payload[:job_id] || payload["job_id"]
+          workflow_state["queue_name"] = payload[:queue_name] || payload["queue_name"]
+          workflow_state["phase"] = "initialized"
+        end
+
+        def restore_workflow_state(payload)
+          return unless workflow_patch_enabled?(:workflow_state)
+
+          state = payload[:workflow_state] || payload["workflow_state"]
+          return unless state.is_a?(Hash)
+
+          @workflow_state = deep_copy(state)
+          workflow_state["phase"] ||= "initialized"
+          workflow_state["paused"] = false unless workflow_state.key?("paused")
+          workflow_state["signals"] ||= {}
+          workflow_state["updates"] ||= {}
+          workflow_state["custom"] ||= {}
+        end
+
+        def configure_workflow_interactions(payload)
+          reset_workflow_interactions
+          load_workflow_interaction_handlers(payload)
+          @workflow_interactions_configured = true
+          flush_buffered_custom_signals
+        end
+
+        def reset_workflow_interactions
+          @workflow_signal_handlers = {}
+          @workflow_query_handlers = {}
+          @workflow_update_handlers = {}
+        end
+
+        def load_workflow_interaction_handlers(payload)
+          metadata = payload[:workflow_interactions] || payload["workflow_interactions"]
+          return unless metadata
+
+          job_class = constant_from_name(metadata[:job_class] || metadata["job_class"])
+          return unless job_class
+
+          @workflow_signal_handlers = filtered_handlers(
+            job_class,
+            :temporal_signal_handlers,
+            metadata[:signals] || metadata["signals"]
+          )
+          @workflow_query_handlers = filtered_handlers(
+            job_class,
+            :temporal_query_handlers,
+            metadata[:queries] || metadata["queries"]
+          )
+          @workflow_update_handlers = filtered_handlers(
+            job_class,
+            :temporal_update_handlers,
+            metadata[:updates] || metadata["updates"]
+          )
+        end
+
+        def workflow_state
+          @workflow_state ||= {
+            "phase" => "initialized",
+            "paused" => false,
+            "signals" => {},
+            "updates" => {},
+            "custom" => {}
+          }
+        end
+
+        def workflow_signal_handlers
+          @workflow_signal_handlers ||= {}
+        end
+
+        def workflow_query_handlers
+          @workflow_query_handlers ||= {}
+        end
+
+        def workflow_update_handlers
+          @workflow_update_handlers ||= {}
+        end
+
+        def workflow_interactions_configured?
+          @workflow_interactions_configured == true
+        end
+
+        def buffered_custom_signals
+          @buffered_custom_signals ||= []
+        end
+
+        def flush_buffered_custom_signals
+          buffered_custom_signals.shift(buffered_custom_signals.length).each do |handler_name, args|
+            dispatch_configured_custom_signal(handler_name, args)
+          end
+        end
+
+        def filtered_handlers(job_class, method_name, handler_names)
+          return {} unless job_class.respond_to?(method_name)
+
+          allowed_names = Array(handler_names).map(&:to_s)
+          job_class.public_send(method_name).each_with_object({}) do |(name, handler), handlers|
+            handler_name = name.to_s
+            handlers[handler_name] = handler if allowed_names.include?(handler_name)
+          end
+        end
+
+        def constant_from_name(class_name)
+          class_name.to_s.split("::").reject(&:empty?).reduce(Object) do |namespace, constant_name|
+            namespace.const_get(constant_name, false)
+          end
+        rescue NameError
+          nil
+        end
+
+        def normalize_handler_name!(name, handler_type)
+          handler_name = name.to_s
+          return handler_name if handler_name.match?(HANDLER_NAME_PATTERN)
+
+          raise ArgumentError, "#{handler_type} names must start with a letter or underscore and contain word chars"
+        end
+
+        def wait_while_paused
+          return unless workflow_state["paused"]
+
+          workflow_state["phase"] = "paused"
+          Temporalio::Workflow.wait_condition { !workflow_state["paused"] }
+        end
+
+        def deep_copy(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, entry_value), hash|
+              hash[key.to_s] = deep_copy(entry_value)
+            end
+          when Array
+            value.map { |entry_value| deep_copy(entry_value) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module Workflows
+      module WorkflowLocalActivities
+        private
+
+        def execute_helper_activity(payload, helper_name, activity, *, **)
+          if local_activity_helper?(payload, helper_name)
+            Temporalio::Workflow.execute_local_activity(activity, *, **)
+          else
+            Temporalio::Workflow.execute_activity(activity, *, **)
+          end
+        end
+
+        def local_activity_helper?(payload, helper_name)
+          return false unless workflow_patch_enabled?(:local_activity_helpers)
+
+          local_activity_helper_names(payload).include?(helper_name.to_s)
+        end
+
+        def local_activity_helper_names(payload)
+          Array(payload[:local_activity_helpers] || payload["local_activity_helpers"]).map(&:to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module Workflows
+      module WorkflowNexus
+        private
+
+        def nexus_client_for(endpoint:, service:)
+          Temporalio::Workflow.create_nexus_client(endpoint: endpoint, service: service)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module Workflows
+      module WorkflowVersioning
+        PATCHES = {
+          continue_as_new: "activejob-temporal.continue-as-new-v1",
+          local_activity_helpers: "activejob-temporal.local-activity-helpers-v1",
+          workflow_state: "activejob-temporal.workflow-state-v1"
+        }.freeze
+
+        private
+
+        def workflow_patch_enabled?(patch_name)
+          Temporalio::Workflow.patched(PATCHES.fetch(patch_name))
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require "logger"
+require "active_support/core_ext/numeric/time"
+
+require_relative "temporal/version"
+require_relative "temporal/configuration"
+require_relative "temporal/configurable"
+require_relative "temporal/client"
+require_relative "temporal/logger"
+require_relative "temporal/bind_policy"
+require_relative "temporal/rails_environment_loader"
+require_relative "temporal/tls_file"
+require_relative "temporal/certificate_watcher"
+require_relative "temporal/reload_signal_queue"
+require_relative "temporal/worker_client_reloader"
+require_relative "temporal/worker_pool"
+require_relative "temporal/audit_log"
+require_relative "temporal/metrics_server"
+require_relative "temporal/observability"
+require_relative "temporal/worker_health"
+require_relative "temporal/health_check_server"
+require_relative "temporal/middleware"
+require_relative "temporal/payload_serializers"
+require_relative "temporal/rate_limit_options"
+require_relative "temporal/rate_limiters/memory"
+require_relative "temporal/payload_encryption"
+require_relative "temporal/payload_storage"
+require_relative "temporal/payload"
+require_relative "temporal/search_attributes"
+require_relative "temporal/retry_mapper"
+require_relative "temporal/job_descriptor"
+require_relative "temporal/external_operation"
+require_relative "temporal/signal_query_options"
+require_relative "temporal/child_workflow_options"
+require_relative "temporal/chain_options"
+require_relative "temporal/dependency_options"
+require_relative "temporal/workflow_identity"
+require_relative "temporal/job_payload_builder"
+require_relative "temporal/schedule_options"
+require_relative "temporal/conditional_enqueue"
+require_relative "temporal/job_tags"
+require_relative "temporal/temporal_options"
+require_relative "temporal/schedule"
+require_relative "temporal/schedulable"
+require_relative "temporal/workflow_id_builder"
+require_relative "temporal/batch_enqueue_result"
+require_relative "temporal/batch_enqueuer"
+require_relative "temporal/workflow_enqueuer_batch"
+require_relative "temporal/workflow_enqueuer"
+require_relative "temporal/adapter"
+require_relative "temporal/transaction_safety"
+require_relative "temporal/workflows/aj_workflow"
+require_relative "temporal/workflows/dead_letter_workflow"
+require_relative "temporal/activities/rate_limit_activity"
+require_relative "temporal/activities/dependency_status_activity"
+require_relative "temporal/activities/aj_runner_activity"
+require_relative "temporal/cancel"
+require_relative "temporal/inspect"
+require_relative "temporal/signal_query"
+require_relative "temporal/dead_letter_queue"
+
+module ActiveJob
+  # ActiveJob adapter for Temporal workflow orchestration.
+  #
+  # This gem provides a durable, fault-tolerant execution backend for Rails ActiveJob
+  # by leveraging Temporal's workflow engine. Jobs are executed as Temporal workflows
+  # with automatic retries, scheduling, and observability.
+  #
+  # @example Basic configuration
+  #   ActiveJob::Temporal.configure do |config|
+  #     config.target = "temporal.example.com:7233"
+  #     config.namespace = "production"
+  #     config.task_queue_prefix = "my-app"
+  #   end
+  #
+  # @example Using the adapter in a job
+  #   class MyJob < ApplicationJob
+  #     self.queue_adapter = :temporal
+  #
+  #     def perform(arg1, arg2)
+  #       # Job logic here
+  #     end
+  #   end
+  #
+  # @example Complete configuration with error handling
+  #   begin
+  #     ActiveJob::Temporal.configure do |config|
+  #       config.target = "temporal.example.com:7233"
+  #       config.namespace = "production"
+  #       config.default_activity_timeout = 10.minutes
+  #       config.max_payload_size_kb = 250
+  #     end
+  #     ActiveJob::Temporal.config.validate!
+  #   rescue ActiveJob::Temporal::ConfigurationError => e
+  #     Rails.logger.error("Temporal configuration invalid: #{e.message}")
+  #     raise
+  #   end
+  #
+  # @see https://github.com/temporalio/sdk-ruby Temporal Ruby SDK
+  module Temporal
+    # Raised when attempting to cancel a job that does not exist.
+    #
+    # @see Cancel.cancel
+    class WorkflowNotFoundError < Error; end
+
+    # Raised when Temporal cluster is unreachable.
+    #
+    # @see Client.build
+    # @see Cancel.cancel
+    class TemporalConnectionError < Error; end
+
+    extend Configurable
+
+    class << self
+      # Returns the memoized Temporal client connection for the process.
+      #
+      # The client is connected to the Temporal server specified in the configuration.
+      # TLS options can be provided via configuration attributes or environment variables:
+      # - TEMPORAL_TLS_CERT: TLS certificate
+      # - TEMPORAL_TLS_KEY: TLS private key
+      # - TEMPORAL_TLS_SERVER_NAME: TLS server name
+      #
+      # @return [Temporalio::Client] the connected Temporal client
+      # @raise [ActiveJob::Temporal::Error] if connection fails due to network or authentication issues
+      # @raise [ActiveJob::Temporal::TemporalConnectionError] if Temporal cluster is unreachable
+      # @raise [Errno::ECONNREFUSED] if Temporal cluster is not accepting connections
+      # @raise [SocketError] if Temporal hostname cannot be resolved
+      # @raise [OpenSSL::SSL::SSLError] if TLS configuration is invalid
+      # @example Get the client
+      #   client = ActiveJob::Temporal.client
+      #   client.list_workflows("ajQueue='default'")
+      #
+      # @example Using client for workflow queries
+      #   client = ActiveJob::Temporal.client
+      #   workflows = client.list_workflows("ajClass='MyJob'")
+      #   workflows.each { |wf| puts wf.id }
+      #
+      # @example Accessing workflow handles
+      #   client = ActiveJob::Temporal.client
+      #   handle = client.workflow_handle("ajwf:MyJob:abc-123")
+      #   result = handle.result
+      #
+      # @see Client.build
+      def client
+        client_mutex.synchronize do
+          @client ||= Client.build(config)
+        end
+      end
+
+      def reload_client!
+        fresh_client = Client.build(config)
+        begin
+          yield fresh_client if block_given?
+        rescue StandardError
+          close_client(fresh_client)
+          raise
+        end
+
+        previous_client = nil
+
+        client_mutex.synchronize do
+          previous_client = @client
+          @client = fresh_client
+        end
+
+        close_client(previous_client) unless previous_client.equal?(fresh_client)
+        fresh_client
+      end
+
+      # Cancels a running or scheduled job by job ID.
+      #
+      # This method requests cancellation for the Temporal workflow associated with the job.
+      # Cancellation is asynchronous and best-effort: the job will stop only if it is actively
+      # heartbeating. See Cancel module documentation for details.
+      #
+      # @param job_class [Class] the ActiveJob class (used to determine task queue)
+      # @param job_id [String] the unique job identifier
+      # @return [Boolean, nil] false if workflow already completed, nil if cancellation requested
+      # @raise [ActiveJob::Temporal::WorkflowNotFoundError] if job never existed or already removed from history
+      # @raise [ActiveJob::Temporal::TemporalConnectionError] if Temporal cluster is unreachable
+      # @example Cancel a scheduled job
+      #   ActiveJob::Temporal.cancel(MyJob, "job-123-abc")
+      # @example Handle cancellation outcomes
+      #   result = ActiveJob::Temporal.cancel(MyJob, "abc-123")
+      #   case result
+      #   when false
+      #     puts "Job already completed"
+      #   when nil
+      #     puts "Cancellation requested"
+      #   end
+      #
+      # @example Cancel with error handling
+      #   begin
+      #     ActiveJob::Temporal.cancel(MyJob, "unknown-id")
+      #   rescue ActiveJob::Temporal::WorkflowNotFoundError
+      #     puts "Job does not exist"
+      #   end
+      #
+      # @note Cancellation Requires Heartbeating
+      #   For jobs to respond to cancellation, they must check for cancellation by heartbeating
+      #   or polling Temporalio::Activity::Context.current.cancelled?. Without heartbeating,
+      #   long-running activities will complete before they detect the cancellation signal.
+      #
+      # @see Cancel.cancel
+      def cancel(job_class, job_id)
+        Cancel.cancel(job_class, job_id)
+      end
+
+      def cancel_all(job_class)
+        Cancel.cancel_all(job_class)
+      end
+
+      def cancel_where(filters)
+        Cancel.cancel_where(filters)
+      end
+
+      def enqueue_batch(items, concurrency: 1)
+        WorkflowEnqueuer.new(
+          -> { client },
+          config,
+          config.logger
+        ).enqueue_batch(items, concurrency: concurrency)
+      end
+
+      def activity(temporal_type, **)
+        ExternalOperation.activity(temporal_type, **)
+      end
+
+      def workflow(temporal_type, **)
+        ExternalOperation.workflow(temporal_type, **)
+      end
+
+      def job(job_class, **options)
+        JobDescriptor.new(job_class, options)
+      end
+
+      def status(job_class, job_id)
+        Inspect.status(job_class, job_id)
+      end
+
+      def signal(job_class, job_id, signal_name, *)
+        SignalQuery.signal(job_class, job_id, signal_name, *)
+      end
+
+      def query(job_class, job_id, query_name, *, reject_condition: SignalQuery::DEFAULT_REJECT_CONDITION)
+        SignalQuery.query(job_class, job_id, query_name, *, reject_condition: reject_condition)
+      end
+
+      def update(job_class, job_id, update_name, *)
+        SignalQuery.update(job_class, job_id, update_name, *)
+      end
+
+      def running?(job_class, job_id)
+        Inspect.running?(job_class, job_id)
+      end
+
+      def completed?(job_class, job_id)
+        Inspect.completed?(job_class, job_id)
+      end
+
+      def failed?(job_class, job_id)
+        Inspect.failed?(job_class, job_id)
+      end
+
+      def dead_letter_entry(job_class, job_id)
+        DeadLetterQueue.entry(job_class, job_id)
+      end
+
+      def dead_letter_entries(queue: nil, limit: DeadLetterQueue::DEFAULT_ENTRIES_LIMIT)
+        DeadLetterQueue.entries(queue: queue, limit: limit)
+      end
+
+      def retry_dead_letter(job_class, job_id, queue: nil)
+        DeadLetterQueue.retry(job_class, job_id, queue: queue)
+      end
+
+      def discard_dead_letter(job_class, job_id, reason: nil)
+        DeadLetterQueue.discard(job_class, job_id, reason: reason)
+      end
+
+      private
+
+      def client_mutex
+        @client_mutex ||= Mutex.new
+      end
+
+      def close_client(client)
+        return unless client.respond_to?(:close)
+
+        client.close
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/activejob-temporal.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "activejob/temporal"