activejob-temporal 0.1.0

data/lib/activejob/temporal/health_check_server.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+require "io/wait"
+require "socket"
+
+require_relative "connection_worker_pool"
+require_relative "bind_policy"
+require_relative "http_line_reader"
+
+module ActiveJob
+  module Temporal
+    class HealthCheckServer
+      include HttpLineReader
+
+      DEFAULT_BIND_ADDRESS = "127.0.0.1"
+      READ_TIMEOUT_SECONDS = 1
+      CONNECTION_WORKERS = 4
+      CONNECTION_QUEUE_SIZE = 16
+
+      attr_reader :port, :bind_address
+
+      def initialize(port:, state:, bind_address: DEFAULT_BIND_ADDRESS, allow_public_bind: false)
+        @requested_port = Integer(port)
+        @bind_address = bind_address
+        @allow_public_bind = allow_public_bind
+        @state = state
+        @running = false
+        @mutex = Mutex.new
+      end
+
+      def start
+        @mutex.synchronize do
+          return self if @running
+
+          BindPolicy.validate!(
+            endpoint: "health check", bind_address: bind_address, allow_public_bind: @allow_public_bind
+          )
+          @server = TCPServer.new(bind_address, @requested_port)
+          @port = @server.addr[1]
+          @connection_pool = ConnectionWorkerPool.new(
+            size: CONNECTION_WORKERS,
+            queue_size: CONNECTION_QUEUE_SIZE,
+            name: "activejob-temporal-health"
+          ) { |client| serve_client(client) }.start
+          @running = true
+          @thread = Thread.new { run }
+        end
+
+        self
+      end
+
+      def stop
+        server = nil
+        thread = nil
+        connection_pool = nil
+
+        @mutex.synchronize do
+          server = @server
+          thread = @thread
+          connection_pool = @connection_pool
+          @server = nil
+          @thread = nil
+          @connection_pool = nil
+          @running = false
+        end
+
+        server&.close
+        connection_pool&.stop(timeout: 2)
+        thread&.join(2)
+      end
+
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      private
+
+      def run
+        loop do
+          server, connection_pool = @mutex.synchronize { [@server, @connection_pool] }
+          break unless server && connection_pool
+
+          connection_pool.enqueue(server.accept)
+        rescue IOError, Errno::EBADF
+          break
+        end
+      ensure
+        @mutex.synchronize { @running = false if @server }
+      end
+
+      def serve_client(client)
+        handle_client(client)
+      rescue IOError, SystemCallError
+        nil
+      ensure
+        client&.close
+      end
+
+      def handle_client(client)
+        request_line = read_line(client)
+        return unless request_line
+
+        method, path = request_line.split.first(2)
+        drain_headers(client)
+
+        unless method && path
+          write_json(client, 400, { error: "bad_request" })
+          return
+        end
+
+        case [method, path]
+        in ["GET" | "HEAD", "/health"]
+          payload = health_payload
+          write_json(client, health_status(payload), payload, body: method == "GET")
+        in [_, "/health"]
+          write_json(client, 405, { error: "method_not_allowed" })
+        else
+          write_json(client, 404, { error: "not_found" })
+        end
+      end
+
+      def health_payload
+        @state.respond_to?(:snapshot) ? @state.snapshot : @state.call
+      end
+
+      def health_status(payload)
+        payload[:worker_running] ? 200 : 503
+      end
+
+      def drain_headers(client)
+        loop do
+          line = read_line(client)
+          break if line.nil? || line == "\r\n" || line == "\n"
+        end
+      end
+
+      def write_json(client, status, payload, body: true)
+        json = JSON.generate(payload)
+        response = "HTTP/1.1 #{status} #{reason_phrase(status)}\r\n"
+        response << "Content-Type: application/json\r\n"
+        response << "Content-Length: #{body ? json.bytesize : 0}\r\n"
+        response << "Connection: close\r\n\r\n"
+        response << json if body
+        client.write(response)
+      end
+
+      def reason_phrase(status)
+        {
+          200 => "OK",
+          400 => "Bad Request",
+          404 => "Not Found",
+          405 => "Method Not Allowed",
+          503 => "Service Unavailable"
+        }.fetch(status)
+      end
+    end
+  end
+end

data/lib/activejob/temporal/http_line_reader.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module HttpLineReader
+      private
+
+      def read_line(client)
+        deadline = monotonic_time + self.class.const_get(:READ_TIMEOUT_SECONDS)
+        buffer = +""
+
+        loop do
+          remaining = deadline - monotonic_time
+          return if remaining <= 0 || !client.wait_readable(remaining)
+
+          chunk = client.read_nonblock(1, exception: false)
+          case chunk
+          when :wait_readable
+            next
+          when nil
+            return buffer unless buffer.empty?
+
+            return
+          else
+            buffer << chunk
+            return buffer if chunk == "\n"
+          end
+        end
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/activejob/temporal/inspect.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "temporalio/client/workflow_execution_status"
+require "temporalio/error"
+require_relative "visibility_query"
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    module Inspect
+      UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+      JOB_CLASS_NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\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
+
+      class << self
+        def status(job_class, job_id)
+          validate_job_class!(job_class)
+          validate_job_id!(job_id)
+
+          client = ActiveJob::Temporal.client
+          describe_default_workflow(client, job_class, job_id) ||
+            describe_search_attribute_workflow(client, job_class, job_id)
+        rescue ArgumentError
+          raise
+        rescue StandardError => e
+          raise ActiveJob::Temporal::TemporalConnectionError,
+                "Failed to inspect Temporal workflow for job_id #{job_id}: #{e.message}"
+        end
+
+        def running?(job_class, job_id) = workflow_state?(job_class, job_id, :running)
+
+        def completed?(job_class, job_id) = workflow_state?(job_class, job_id, :completed)
+
+        def failed?(job_class, job_id) = workflow_state?(job_class, job_id, :failed)
+
+        private
+
+        def workflow_state?(job_class, job_id, state)
+          status(job_class, job_id)&.fetch(:state) == state
+        end
+
+        def validate_job_class!(job_class)
+          unless job_class.is_a?(Class) && !job_class.name.to_s.empty?
+            raise ArgumentError, "job_class must be a named class"
+          end
+
+          return if job_class.name.match?(JOB_CLASS_NAME_PATTERN)
+
+          raise ArgumentError, "job_class must have a valid constant name"
+        end
+
+        def validate_job_id!(job_id)
+          return if job_id.is_a?(String) && job_id.match?(UUID_REGEX)
+
+          raise ArgumentError,
+                "Invalid job_id format: expected UUID (e.g., '550e8400-e29b-41d4-a716-446655440000'), " \
+                "got: #{job_id.inspect}"
+        end
+
+        def describe_default_workflow(client, job_class, job_id)
+          describe_workflow(client, default_workflow_reference(job_class, job_id))
+        rescue StandardError => e
+          raise unless rpc_not_found?(e)
+
+          nil
+        end
+
+        def describe_search_attribute_workflow(client, job_class, job_id)
+          workflow_reference = find_workflow_reference(client, job_class, job_id)
+          return unless workflow_reference
+
+          describe_workflow(client, workflow_reference)
+        rescue StandardError => e
+          return nil if rpc_not_found?(e) || rpc_invalid_argument?(e)
+
+          raise
+        end
+
+        def find_workflow_reference(client, job_class, job_id)
+          workflow = client.list_workflows(workflow_search_query(job_class, job_id)).first
+          return unless workflow
+
+          {
+            workflow_id: workflow.id,
+            run_id: workflow.respond_to?(:run_id) ? workflow.run_id : nil
+          }
+        end
+
+        def workflow_search_query(job_class, job_id)
+          "ajClass=#{VisibilityQuery.quote(job_class.name)} AND ajJobId=#{VisibilityQuery.quote(job_id)}"
+        end
+
+        def default_workflow_reference(job_class, job_id)
+          {
+            workflow_id: WorkflowIdBuilder.new.build_from_job_class(job_class, job_id),
+            run_id: nil
+          }
+        end
+
+        def describe_workflow(client, workflow_reference)
+          handle = client.workflow_handle(
+            workflow_reference.fetch(:workflow_id),
+            run_id: workflow_reference[:run_id]
+          )
+          status_from_description(handle.describe)
+        end
+
+        def status_from_description(description)
+          pending_activity = pending_activity(description)
+
+          {
+            state: WORKFLOW_STATES.fetch(description.status, :unknown),
+            workflow_id: description.id,
+            run_id: description.run_id,
+            started_at: description.start_time,
+            closed_at: description.close_time,
+            attempt: activity_attempt(pending_activity),
+            last_failure: activity_last_failure(pending_activity)
+          }
+        end
+
+        def pending_activity(description)
+          return unless description.respond_to?(:raw_description)
+          return unless description.raw_description.respond_to?(:pending_activities)
+
+          activities = description.raw_description.pending_activities
+          return if activities.nil? || activities.empty?
+
+          activities.max_by { |activity| activity_attempt(activity).to_i }
+        end
+
+        def activity_attempt(activity)
+          return unless activity.respond_to?(:attempt)
+
+          activity.attempt
+        end
+
+        def activity_last_failure(activity)
+          return unless activity.respond_to?(:last_failure)
+
+          format_failure(activity.last_failure)
+        end
+
+        def format_failure(failure)
+          return unless failure
+
+          type = failure_type(failure)
+          message = failure.respond_to?(:message) ? failure.message.to_s : failure.to_s
+          failure_details = [type, message].compact.reject(&:empty?)
+          return if failure_details.empty?
+
+          failure_details.join(": ")
+        end
+
+        def failure_type(failure)
+          return unless failure.respond_to?(:application_failure_info)
+          return unless failure.application_failure_info.respond_to?(:type)
+
+          failure.application_failure_info.type.to_s
+        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/job_descriptor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module ActiveJob
+  module Temporal
+    class JobDescriptor
+      attr_reader :job_class, :options
+
+      def self.normalize(value)
+        return value.to_h if value.is_a?(self)
+
+        nil
+      end
+
+      def initialize(job_class, options = {})
+        @job_class = normalize_job_class(job_class)
+        @options = options.dup
+      end
+
+      def to_h
+        {
+          job_class: job_class.name,
+          options: options.dup
+        }
+      end
+
+      private
+
+      def normalize_job_class(job_class)
+        return job_class if job_class.is_a?(Class) && job_class < ActiveJob::Base && job_class.name
+
+        raise ArgumentError, "Temporal job descriptors require a named ActiveJob class"
+      end
+    end
+  end
+end

data/lib/activejob/temporal/job_payload_builder.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "payload"
+require_relative "job_payload_child_workflows"
+require_relative "job_payload_chain_builder"
+require_relative "job_payload_dependencies"
+require_relative "job_payload_rate_limits"
+require_relative "job_payload_workflow_interactions"
+require_relative "observability"
+require_relative "retry_mapper"
+
+module ActiveJob
+  module Temporal
+    # rubocop:disable Metrics/ClassLength
+    class JobPayloadBuilder
+      include JobPayloadChildWorkflows
+      include JobPayloadChainBuilder
+      include JobPayloadDependencies
+      include JobPayloadRateLimits
+      include JobPayloadWorkflowInteractions
+
+      TIMEOUT_CONFIG_ATTRIBUTES = {
+        default_activity_timeout: :start_to_close_timeout,
+        default_schedule_to_close_timeout: :schedule_to_close_timeout,
+        default_schedule_to_start_timeout: :schedule_to_start_timeout,
+        default_heartbeat_timeout: :heartbeat_timeout
+      }.freeze
+
+      def initialize(config)
+        @config = config
+      end
+
+      def build(job, scheduled_at: nil, encryption_context: nil)
+        payload = base_payload_for(job, scheduled_at)
+        payload[:default_activity_options] = default_activity_options
+        Observability.inject_trace_context(payload, observability_attributes_for(job, encryption_context))
+
+        apply_retry_policy(payload, job)
+        apply_temporal_options(payload, job.class)
+        apply_workflow_identity(payload, job.class)
+        apply_rate_limits(payload, job)
+        apply_workflow_interactions(payload, job.class)
+        apply_child_workflows(payload, job)
+        apply_chain(payload, job)
+        apply_dependencies(payload, job)
+        apply_continue_as_new(payload)
+        apply_local_activity_helpers(payload)
+
+        payload = transport_payload(payload, job, scheduled_at, encryption_context)
+        Payload.enforce_size!(payload, metrics_payload: metrics_payload_for(job), config: @config)
+        payload
+      end
+
+      private
+
+      def base_payload_for(job, scheduled_at)
+        Payload.from_job(
+          job,
+          scheduled_at:,
+          enforce_size: false,
+          encrypt: false,
+          offload: false,
+          config: @config
+        )
+      end
+
+      def apply_retry_policy(payload, job)
+        retry_policy = retry_policy_for(job.class)
+        payload[:retry_policy] = retry_policy
+        return unless dead_letter_enabled?
+
+        payload[:dead_letter] = dead_letter_metadata(job.class.name, job.job_id, job.queue_name, retry_policy)
+      end
+
+      def apply_temporal_options(payload, job_class)
+        temporal_options = extract_temporal_options(job_class)
+        payload[:temporal_options] = temporal_options if temporal_options.any?
+      end
+
+      def apply_workflow_identity(payload, job_class)
+        workflow_name = extract_temporal_workflow_name(job_class)
+        return unless workflow_name
+
+        identity = { workflow_name: workflow_name }
+        workflow_id_prefix = extract_temporal_workflow_id_prefix(job_class)
+        identity[:workflow_id_prefix] = workflow_id_prefix if workflow_id_prefix
+        payload[:workflow_identity] = identity
+      end
+
+      def metrics_payload_for(job)
+        {
+          job_class: job.class.name,
+          job_id: job.job_id,
+          queue_name: job.queue_name
+        }
+      end
+
+      def observability_attributes_for(job, encryption_context)
+        Observability.attributes_from_job(
+          job,
+          workflow_id: encryption_context&.fetch(:workflow_id, nil),
+          namespace: @config.namespace,
+          task_queue: Adapter.resolve_task_queue(job, config: @config)
+        )
+      end
+
+      def transport_payload(payload, job, scheduled_at, encryption_context)
+        encrypted_payload = Payload.encrypt_payload(payload, config: @config, encryption_context: encryption_context)
+        Payload.offload_payload(
+          encrypted_payload,
+          metadata: storage_metadata_for(job, scheduled_at, encryption_context),
+          config: @config
+        )
+      end
+
+      def storage_metadata_for(job, scheduled_at, encryption_context)
+        metrics_payload_for(job).merge(
+          namespace: @config.namespace,
+          workflow_id: encryption_context&.fetch(:workflow_id, nil),
+          scheduled_at: scheduled_at.respond_to?(:iso8601) ? scheduled_at.iso8601 : scheduled_at
+        )
+      end
+
+      def apply_continue_as_new(payload)
+        threshold = @config.continue_as_new_history_event_threshold
+        return unless threshold
+
+        payload[:continue_as_new] = { history_event_threshold: threshold }
+      end
+
+      def apply_local_activity_helpers(payload)
+        helpers = Array(@config.local_activity_helpers).filter_map do |helper|
+          helper_name = helper.to_s.strip
+          helper_name unless helper_name.empty?
+        end.uniq
+        payload[:local_activity_helpers] = helpers if helpers.any?
+      end
+
+      def extract_temporal_options(job_class)
+        return {} unless job_class.respond_to?(:temporal_options)
+
+        job_class.temporal_options
+      end
+
+      def extract_temporal_workflow_name(job_class)
+        return unless job_class.respond_to?(:temporal_workflow_name)
+
+        job_class.temporal_workflow_name
+      end
+
+      def extract_temporal_workflow_id_prefix(job_class)
+        return unless job_class.respond_to?(:temporal_workflow_id_prefix)
+
+        job_class.temporal_workflow_id_prefix
+      end
+
+      def dead_letter_enabled?
+        @config.respond_to?(:dead_letter_queue) && @config.dead_letter_queue.to_s.strip.present?
+      end
+
+      def apply_dead_letter_attempt_limit(retry_policy)
+        return unless dead_letter_enabled?
+        return unless @config.dead_letter_after_attempts
+
+        retry_policy[:maximum_attempts] = @config.dead_letter_after_attempts
+      end
+
+      def dead_letter_metadata(job_class_name, job_id, queue_name, retry_policy, task_queue: nil)
+        {
+          queue: @config.dead_letter_queue,
+          job_class: job_class_name,
+          job_id: job_id,
+          queue_name: queue_name,
+          task_queue: task_queue,
+          after_attempts: dead_letter_attempt_limit(retry_policy),
+          auto_discard_after_seconds: @config.dead_letter_auto_discard_after&.to_f
+        }.compact
+      end
+
+      def dead_letter_attempt_limit(retry_policy)
+        configured_limit = @config.dead_letter_after_attempts
+        return configured_limit if configured_limit
+
+        attempts = retry_policy[:maximum_attempts] || retry_policy["maximum_attempts"]
+        attempts if attempts.respond_to?(:positive?) && attempts.positive?
+      end
+
+      def retry_policy_for(job_class)
+        retry_policy = RetryMapper.for(job_class)
+        apply_dead_letter_attempt_limit(retry_policy)
+        retry_policy
+      end
+
+      def default_activity_options
+        TIMEOUT_CONFIG_ATTRIBUTES.each_with_object({}) do |(config_attribute, option_name), options|
+          value = @config.public_send(config_attribute)
+          options[option_name] = normalize_duration(value) if value
+        end
+      end
+
+      def normalize_duration(value)
+        return value.to_f if value.respond_to?(:to_f)
+
+        value
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end