activejob-temporal 0.1.0

data/lib/activejob/temporal/worker_pool.rb

@@ -0,0 +1,408 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+require_relative "bind_policy"
+
+module ActiveJob
+  module Temporal
+    # rubocop:disable Metrics/ClassLength
+    class WorkerPool
+      Child = Data.define(:pid, :index, :restarts)
+
+      DEFAULT_RESTART_DELAY = 1.0
+      DEFAULT_SHUTDOWN_TIMEOUT = 10.0
+      MAX_RESTART_COUNT = 1_000
+      SHUTDOWN_SIGNALS = %w[INT TERM].freeze
+      VALID_OPTIONS = %i[
+        worker_command
+        process_adapter
+        health_check_port
+        health_check_bind
+        health_check_allow_public_bind
+        metrics_port
+        metrics_bind
+        metrics_allow_public_bind
+        max_concurrent_activities
+        max_concurrent_workflows
+        restart_delay
+        shutdown_timeout
+        install_signal_handlers
+      ].freeze
+
+      def initialize(size:, **options)
+        validate_options!(options)
+
+        @size = positive_integer(size, "pool size")
+        configure_process_options(options)
+        configure_runtime_options(options)
+        initialize_state
+        validate!
+      end
+
+      def self.default_worker_command
+        bundled_executable = File.expand_path("../../../bin/temporal-worker", __dir__)
+        return [RbConfig.ruby, bundled_executable] if File.exist?(bundled_executable)
+
+        ["temporal-worker"]
+      end
+
+      def start(supervise: true)
+        ensure_fork_supported!
+
+        @mutex.synchronize do
+          return self if @running
+
+          @running = true
+          @stopping = false
+        end
+
+        install_signal_handlers if @install_signal_handlers
+        @size.times { |index| start_worker(index) }
+        @supervisor_thread = Thread.new { supervise_workers } if supervise
+        self
+      end
+
+      def wait
+        @supervisor_thread&.join
+        self
+      end
+
+      def stop
+        children = @mutex.synchronize do
+          if @stopping
+            nil
+          else
+            @stopping = true
+            @running = false
+
+            @children.values
+          end
+        end
+        return self unless children
+
+        children.each { |child| terminate_worker(child) }
+        deadline = monotonic_time + @shutdown_timeout
+        children.each { |child| wait_for_worker(child, deadline) }
+        @mutex.synchronize { children.each { |child| @children.delete(child.pid) } }
+        restore_signal_handlers if @install_signal_handlers
+        self
+      end
+
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      private
+
+      def validate_options!(options)
+        unknown_options = options.keys - VALID_OPTIONS
+        return if unknown_options.empty?
+
+        raise ArgumentError, "unknown worker pool options: #{unknown_options.join(', ')}"
+      end
+
+      def configure_process_options(options)
+        worker_command = options.fetch(:worker_command, nil)
+        @worker_command = Array(worker_command || self.class.default_worker_command)
+        @process_adapter = options.fetch(:process_adapter) { ProcessAdapter.new }
+      end
+
+      def configure_runtime_options(options)
+        @health_check_port = optional_positive_integer(options.fetch(:health_check_port, nil), "health_check_port")
+        @health_check_bind = options.fetch(:health_check_bind, nil)
+        @health_check_allow_public_bind = options.fetch(:health_check_allow_public_bind, false)
+        @metrics_port = optional_positive_integer(options.fetch(:metrics_port, nil), "metrics_port")
+        @metrics_bind = options.fetch(:metrics_bind, nil)
+        @metrics_allow_public_bind = options.fetch(:metrics_allow_public_bind, false)
+        @max_concurrent_activities =
+          optional_positive_integer(options.fetch(:max_concurrent_activities, nil), "max_concurrent_activities")
+        @max_concurrent_workflows =
+          optional_positive_integer(options.fetch(:max_concurrent_workflows, nil), "max_concurrent_workflows")
+        @restart_delay = Float(options.fetch(:restart_delay, DEFAULT_RESTART_DELAY))
+        @shutdown_timeout = Float(options.fetch(:shutdown_timeout, DEFAULT_SHUTDOWN_TIMEOUT))
+        @install_signal_handlers = options.fetch(:install_signal_handlers, true)
+      end
+
+      def initialize_state
+        @children = {}
+        @mutex = Mutex.new
+        @running = false
+        @stopping = false
+        @previous_signal_handlers = {}
+      end
+
+      def validate!
+        raise ArgumentError, "worker_command must not be empty" if @worker_command.empty?
+        raise ArgumentError, "restart_delay must be finite and non-negative" unless finite_non_negative?(@restart_delay)
+        unless finite_non_negative?(@shutdown_timeout)
+          raise ArgumentError, "shutdown_timeout must be finite and non-negative"
+        end
+
+        validate_public_binds!
+      end
+
+      def positive_integer(value, name)
+        integer = Integer(value)
+        return integer if integer.positive?
+
+        raise ArgumentError, "#{name} must be a positive integer"
+      rescue TypeError, ArgumentError
+        raise ArgumentError, "#{name} must be a positive integer"
+      end
+
+      def optional_positive_integer(value, name)
+        return if value.nil?
+
+        positive_integer(value, name)
+      end
+
+      def finite_non_negative?(value)
+        value.finite? && !value.negative?
+      end
+
+      def validate_public_binds!
+        if @health_check_port
+          BindPolicy.validate!(
+            endpoint: "health check",
+            bind_address: @health_check_bind,
+            allow_public_bind: @health_check_allow_public_bind,
+            warn_on_allowed: false
+          )
+        end
+
+        return unless @metrics_port
+
+        BindPolicy.validate!(
+          endpoint: "metrics",
+          bind_address: @metrics_bind,
+          allow_public_bind: @metrics_allow_public_bind,
+          warn_on_allowed: false
+        )
+      end
+
+      def ensure_fork_supported!
+        return if @process_adapter.fork_supported?
+
+        raise ActiveJob::Temporal::ConfigurationError, "worker pools require Process.fork support"
+      end
+
+      def start_worker(index, restarts: 0)
+        environment = worker_environment(index)
+        pid = @process_adapter.fork(environment, @worker_command)
+        child = Child.new(pid: pid, index: index, restarts: restarts)
+
+        unless register_worker_if_running(child)
+          terminate_worker(child)
+          wait_for_worker(child, monotonic_time + @shutdown_timeout)
+          return
+        end
+
+        ActiveJob::Temporal::Logger.log_event(
+          "worker_pool_worker_started",
+          worker_index: index,
+          pid: pid,
+          restarts: restarts
+        )
+      end
+
+      def register_worker_if_running(child)
+        @mutex.synchronize do
+          if @stopping || !@running
+            false
+          else
+            @children[child.pid] = child
+
+            true
+          end
+        end
+      end
+
+      def worker_environment(index)
+        environment = {
+          "ACTIVEJOB_TEMPORAL_WORKER_POOL_INDEX" => index.to_s,
+          "ACTIVEJOB_TEMPORAL_WORKER_POOL_SIZE" => "1"
+        }
+
+        environment["ACTIVEJOB_TEMPORAL_HEALTH_CHECK_PORT"] = (@health_check_port + index).to_s if @health_check_port
+        environment["ACTIVEJOB_TEMPORAL_HEALTH_CHECK_BIND"] = @health_check_bind.to_s if @health_check_bind
+        environment["ACTIVEJOB_TEMPORAL_HEALTH_CHECK_ALLOW_PUBLIC_BIND"] = "true" if @health_check_allow_public_bind
+        environment["ACTIVEJOB_TEMPORAL_METRICS_PORT"] = (@metrics_port + index).to_s if @metrics_port
+        environment["ACTIVEJOB_TEMPORAL_METRICS_BIND"] = @metrics_bind.to_s if @metrics_bind
+        environment["ACTIVEJOB_TEMPORAL_METRICS_ALLOW_PUBLIC_BIND"] = "true" if @metrics_allow_public_bind
+        if @max_concurrent_activities
+          environment["ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_ACTIVITIES"] = @max_concurrent_activities.to_s
+        end
+        if @max_concurrent_workflows
+          environment["ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS"] = @max_concurrent_workflows.to_s
+        end
+
+        environment
+      end
+
+      def supervise_workers
+        loop do
+          pid, status = @process_adapter.wait(worker_pids)
+          handle_worker_exit(pid, status)
+          break unless running? || child_count.positive?
+        rescue Errno::ECHILD
+          break unless running?
+
+          @process_adapter.sleep(0.1)
+        end
+      ensure
+        stop if running?
+      end
+
+      def handle_worker_exit(pid, status)
+        child = @mutex.synchronize { @children.delete(pid) }
+        return unless child
+
+        ActiveJob::Temporal::Logger.log_event(
+          "worker_pool_worker_exited",
+          worker_index: child.index,
+          pid: pid,
+          success: status.respond_to?(:success?) ? status.success? : nil
+        )
+
+        return unless restart_allowed?
+
+        @process_adapter.sleep(@restart_delay) if @restart_delay.positive?
+        return unless restart_allowed?
+
+        start_worker(child.index, restarts: next_restart_count(child))
+      end
+
+      def next_restart_count(child)
+        [child.restarts + 1, MAX_RESTART_COUNT].min
+      end
+
+      def child_count
+        @mutex.synchronize { @children.size }
+      end
+
+      def worker_pids
+        @mutex.synchronize { @children.keys }
+      end
+
+      def restart_allowed?
+        @mutex.synchronize { @running && !@stopping }
+      end
+
+      def terminate_worker(child)
+        @process_adapter.kill("TERM", child.pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def wait_for_worker(child, deadline)
+        loop do
+          return if @process_adapter.wait_nonblock(child.pid)
+
+          break if monotonic_time >= deadline
+
+          @process_adapter.sleep(0.1)
+        end
+
+        @process_adapter.kill("KILL", child.pid)
+        @process_adapter.wait(child.pid)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+
+      def install_signal_handlers
+        @mutex.synchronize do
+          signal_queue = Queue.new
+          @signal_queue = signal_queue
+          SHUTDOWN_SIGNALS.each do |signal|
+            @previous_signal_handlers[signal] = Signal.trap(signal) { signal_queue << signal }
+          end
+          @signal_thread = Thread.new do
+            signal = signal_queue.pop
+            unless signal == :shutdown
+              ActiveJob::Temporal::Logger.log_event("worker_pool_shutdown_requested", signal: signal)
+              stop
+            end
+          end
+        end
+      end
+
+      def restore_signal_handlers
+        previous_signal_handlers, signal_queue, signal_thread = @mutex.synchronize do
+          [
+            @previous_signal_handlers.dup,
+            @signal_queue,
+            @signal_thread
+          ].tap do
+            @previous_signal_handlers.clear
+            @signal_queue = nil
+            @signal_thread = nil
+          end
+        end
+
+        previous_signal_handlers.each do |signal, handler|
+          Signal.trap(signal, handler)
+        end
+        signal_queue << :shutdown if signal_queue && !signal_queue.closed?
+        signal_thread&.join(1) if signal_thread&.alive? && signal_thread != Thread.current
+      rescue ArgumentError
+        nil
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      class ProcessAdapter
+        def fork(environment, command)
+          Process.fork do
+            environment.each { |key, value| ENV[key] = value }
+            exec(*command)
+          end
+        end
+
+        def wait(pids)
+          if pids.is_a?(Integer)
+            Process.wait2(pids)
+          else
+            wait_for_any(pids)
+          end
+        end
+
+        def wait_nonblock(pid)
+          Process.wait(pid, Process::WNOHANG)
+        end
+
+        def kill(signal, pid)
+          Process.kill(signal, pid)
+        end
+
+        def sleep(duration)
+          Kernel.sleep(duration)
+        end
+
+        def fork_supported?
+          Process.respond_to?(:fork)
+        end
+
+        private
+
+        def wait_for_any(pids)
+          raise Errno::ECHILD if pids.empty?
+
+          loop do
+            pids.each do |pid|
+              waited_pid, status = Process.wait2(pid, Process::WNOHANG)
+              return [waited_pid, status] if waited_pid
+            rescue Errno::ECHILD
+              return [pid, nil]
+            end
+
+            sleep(0.1)
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/activejob/temporal/workflow_enqueuer.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "time"
+
+require_relative "dead_letter_payload_validation"
+require_relative "job_payload_builder"
+require_relative "observability"
+require_relative "workflow_enqueuer_batch"
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    # Service object for enqueueing jobs as Temporal workflows.
+    #
+    # This class handles the mechanics of converting an ActiveJob into a Temporal workflow
+    # execution, including payload serialization, workflow ID generation, and options building.
+    #
+    # @example Using with a job
+    #   enqueuer = WorkflowEnqueuer.new(client, config)
+    #   workflow_id = enqueuer.enqueue(job, scheduled_at: 5.minutes.from_now)
+    #
+    # @example Direct usage
+    #   client = ActiveJob::Temporal.client
+    #   config = ActiveJob::Temporal.config
+    #   enqueuer = WorkflowEnqueuer.new(client, config)
+    #   enqueuer.enqueue(job)
+    # rubocop:disable Metrics/ClassLength
+    class WorkflowEnqueuer
+      include WorkflowEnqueuerBatch
+
+      # @param client [Temporalio::Client] Temporal client connection
+      # @param config [ActiveJob::Temporal::Configuration] Configuration object
+      # @param logger [Logger] Optional logger instance
+      # @param workflow_id_builder [WorkflowIdBuilder] Builder for Temporal workflow IDs
+      def initialize(client, config, logger = nil, workflow_id_builder: nil, payload_builder: nil)
+        @client_provider = client if client.respond_to?(:call)
+        @client = client unless @client_provider
+        @config = config
+        @logger = logger || config.logger
+        @workflow_id_builder = workflow_id_builder || WorkflowIdBuilder.new(configured_workflow_id_generator)
+        @payload_builder = payload_builder || JobPayloadBuilder.new(config)
+      end
+
+      # Enqueue a job as a Temporal workflow.
+      #
+      # Performs validation, builds the payload, generates a workflow ID, constructs
+      # workflow options, and starts the workflow via the Temporal client.
+      #
+      # @param job [ActiveJob::Base] The job to enqueue
+      # @param scheduled_at [Time, nil] Time to schedule job, nil for immediate execution
+      # @return [Object] Workflow run handle
+      #
+      # @raise [ActiveJob::SerializationError] If payload serialization fails or exceeds max size
+      # @raise [ActiveJob::EnqueueError] If workflow cannot be started
+      # @raise [ActiveJob::Temporal::ConfigurationError] If job configuration is invalid
+      #
+      # @example Immediate execution
+      #   enqueuer.enqueue(job) # => workflow handle
+      #
+      # @example Scheduled execution
+      #   enqueuer.enqueue(job, scheduled_at: 1.hour.from_now) # => workflow handle
+      #
+      # @example Duplicate job (FAIL conflict policy)
+      #   enqueuer.enqueue(job) # => handle
+      #   enqueuer.enqueue(job) # raises DuplicateEnqueueError
+      def enqueue(job, scheduled_at: nil)
+        validate_job_for_enqueueing(job)
+        scheduled_at = validate_scheduled_at!(scheduled_at)
+        workflow_id = @workflow_id_builder.build(job)
+        payload = build_payload(job, workflow_id: workflow_id, scheduled_at: scheduled_at)
+        enqueue_with_payload(job, payload, workflow_id)
+      end
+
+      private
+
+      def configured_workflow_id_generator
+        return unless @config.respond_to?(:workflow_id_generator)
+
+        @config.workflow_id_generator
+      end
+
+      # Enqueues a workflow with the given payload and options.
+      # @api private
+      def enqueue_with_payload(job, payload, workflow_id)
+        DeadLetterPayloadValidation.validate!(payload)
+
+        task_queue = Adapter.resolve_task_queue(job, config: @config)
+        add_dead_letter_task_queue(payload, task_queue)
+
+        options = {
+          id: workflow_id,
+          task_queue: task_queue,
+          id_conflict_policy: Temporalio::WorkflowIDConflictPolicy::FAIL
+        }
+
+        # Add search attributes if configured
+        if @config.respond_to?(:enable_search_attributes) && @config.enable_search_attributes
+          search_attributes = SearchAttributes.for(job)
+          options[:search_attributes] = search_attributes
+        end
+
+        start_workflow(job, payload, options)
+      end
+
+      def add_dead_letter_task_queue(payload, task_queue)
+        dead_letter = payload[:dead_letter] || payload["dead_letter"]
+        return unless dead_letter
+
+        dead_letter[:task_queue] = task_queue if dead_letter.key?(:queue)
+        dead_letter["task_queue"] = task_queue if dead_letter.key?("queue")
+      end
+
+      # Builds a payload hash from a job instance.
+      # Includes the job's retry policy and temporal timeout options for use in the workflow.
+      # @api private
+      def build_payload(job, workflow_id:, scheduled_at: nil)
+        @payload_builder.build(
+          job,
+          scheduled_at: scheduled_at,
+          encryption_context: encryption_context_for(workflow_id)
+        )
+      end
+
+      def encryption_context_for(workflow_id)
+        { namespace: @config.namespace, workflow_id: workflow_id }
+      end
+
+      # Starts the Temporal workflow with the given options.
+      # @api private
+      def start_workflow(job, payload, options)
+        workflow_class = Workflows::AjWorkflow
+        handle = start_temporal_workflow(workflow_class, job, payload, options)
+
+        log_enqueued(job, options, payload, duplicate: false)
+        handle
+      end
+
+      def start_temporal_workflow(workflow_class, job, payload, options)
+        client.start_workflow(workflow_class, payload, **options)
+      rescue StandardError => e
+        if workflow_already_started?(e)
+          log_enqueued(job, options, payload, duplicate: true)
+          raise DuplicateEnqueueError, build_duplicate_enqueue_error_message(job, options)
+        end
+
+        raise ActiveJob::EnqueueError.new(build_enqueue_error_message(job, e)), cause: e
+      end
+
+      # Checks if error indicates workflow was already started (duplicate job_id).
+      # @api private
+      def workflow_already_started?(error)
+        return true if defined?(Temporalio::Error::WorkflowAlreadyStartedError) &&
+                       error.is_a?(Temporalio::Error::WorkflowAlreadyStartedError)
+        return true if defined?(Temporalio::Client::WorkflowAlreadyStartedError) &&
+                       error.is_a?(Temporalio::Client::WorkflowAlreadyStartedError)
+
+        defined?(Temporalio::Error::RPCError::Code::ALREADY_EXISTS) &&
+          error.respond_to?(:code) &&
+          error.code == Temporalio::Error::RPCError::Code::ALREADY_EXISTS
+      end
+
+      # Logs enqueue event with structured metadata.
+      # @api private
+      def log_enqueued(job, options, payload, duplicate:)
+        attributes = enqueue_attributes(job, options, payload, duplicate: duplicate)
+
+        emit_enqueue_side_effect("log", attributes) do
+          Logger.log_event("workflow_enqueued", **attributes)
+        end
+        emit_enqueue_side_effect("audit", attributes) do
+          AuditLog.record("job.enqueued", attributes)
+        end
+        emit_enqueue_side_effect("observability", attributes) do
+          Observability.emit(
+            :enqueue,
+            Observability.attributes_from_job(
+              job,
+              workflow_id: options[:id],
+              task_queue: options[:task_queue],
+              duplicate: duplicate
+            )
+          )
+        end
+      end
+
+      def enqueue_attributes(job, options, payload, duplicate:)
+        attributes = {
+          workflow_id: options[:id],
+          job_class: job.class.name,
+          job_id: job.job_id,
+          queue: job.queue_name,
+          task_queue: options[:task_queue],
+          duplicate: duplicate
+        }
+        attributes[:scheduled_at] = payload[:scheduled_at] if payload[:scheduled_at]
+
+        attributes
+      end
+
+      def emit_enqueue_side_effect(side_effect, attributes)
+        yield
+      rescue StandardError => e
+        report_enqueue_side_effect_failure(side_effect, attributes, e)
+      end
+
+      def report_enqueue_side_effect_failure(side_effect, attributes, error)
+        Logger.warn(
+          "workflow_enqueue_side_effect_failed",
+          attributes.merge(side_effect: side_effect, error_class: error.class.name)
+        )
+      rescue StandardError
+        nil
+      end
+
+      # Builds error message for enqueue failures.
+      # @api private
+      def build_enqueue_error_message(job, error)
+        format(
+          "Failed to enqueue job %<job_class>s (%<job_id>s): %<error>s",
+          job_class: job.class.name,
+          job_id: job.job_id,
+          error: error.message
+        )
+      end
+
+      def build_duplicate_enqueue_error_message(job, options)
+        format(
+          "Job %<job_class>s (%<job_id>s) was already enqueued as workflow %<workflow_id>s",
+          job_class: job.class.name,
+          job_id: job.job_id,
+          workflow_id: options[:id]
+        )
+      end
+
+      def client
+        return @client_provider.call if @client_provider
+
+        @client
+      end
+
+      # Validate job before enqueueing.
+      #
+      # @param job [ActiveJob::Base]
+      # @raise [ActiveJob::Temporal::ConfigurationError] If job configuration is invalid
+      # @api private
+      def validate_job_for_enqueueing(job)
+        raise ConfigurationError, "Job queue name cannot be blank" if job.queue_name.blank?
+      end
+
+      def validate_scheduled_at!(scheduled_at)
+        return if scheduled_at.nil?
+
+        scheduled_time = coerce_scheduled_at!(scheduled_at)
+        return if scheduled_time <= Time.now
+
+        scheduled_time
+      end
+
+      def coerce_scheduled_at!(scheduled_at)
+        scheduled_time = scheduled_at.is_a?(String) ? Time.iso8601(scheduled_at) : scheduled_at
+        scheduled_time = scheduled_time.to_time if !scheduled_time.is_a?(Time) && scheduled_time.respond_to?(:to_time)
+        raise ArgumentError unless scheduled_time.is_a?(Time)
+
+        scheduled_time
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "scheduled_at must be an ISO8601 string or respond to to_time"
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/activejob/temporal/workflow_enqueuer_batch.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "batch_enqueuer"
+
+module ActiveJob
+  module Temporal
+    module WorkflowEnqueuerBatch
+      def enqueue_batch(items, concurrency: 1)
+        BatchEnqueuer.new(
+          enqueue: method(:enqueue),
+          validate_job: method(:validate_job_for_enqueueing),
+          validate_scheduled_at: method(:validate_scheduled_at!)
+        ).enqueue(items, concurrency: concurrency)
+      end
+    end
+  end
+end