activejob-temporal 0.1.0

data/lib/activejob/temporal/batch_enqueuer.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "batch_enqueue_result"
+
+module ActiveJob
+  module Temporal
+    class BatchEnqueuer
+      def initialize(enqueue:, validate_job:, validate_scheduled_at:)
+        @enqueue_job = enqueue
+        @validate_job = validate_job
+        @validate_scheduled_at = validate_scheduled_at
+      end
+
+      def enqueue(items, concurrency: 1)
+        entries = validate_entries!(items)
+        concurrency = validate_concurrency!(concurrency)
+        results = Array.new(entries.length)
+
+        enqueue_entries(entries, results, concurrency)
+
+        BatchEnqueueResult.new(results)
+      end
+
+      private
+
+      attr_reader :enqueue_job, :validate_job, :validate_scheduled_at
+
+      def validate_entries!(items)
+        raise ArgumentError, "batch enqueue jobs must be an Enumerable" unless items.respond_to?(:each)
+
+        errors = []
+        entries = items.each_with_index.map do |item, index|
+          validate_entry(item, index, errors)
+        end
+
+        raise ArgumentError, "batch enqueue jobs cannot be empty" if entries.empty?
+        raise BatchEnqueueValidationError, errors if errors.any?
+
+        entries
+      end
+
+      def validate_entry(item, index, errors)
+        entry = normalize_entry(item)
+        entry[:index] = index
+        validate_job.call(entry[:job])
+        entry[:scheduled_at] = validate_scheduled_at.call(entry[:scheduled_at])
+        entry
+      rescue StandardError => e
+        errors << {
+          index: index,
+          error: "#{e.class}: #{e.message}"
+        }
+        nil
+      end
+
+      def normalize_entry(item)
+        return { job: item, scheduled_at: nil } if active_job_instance?(item)
+
+        raise ArgumentError, "must be an ActiveJob instance or a Hash with :job" unless item.respond_to?(:to_hash)
+
+        hash = item.to_hash
+        job = hash[:job] || hash["job"]
+        scheduled_at = hash[:scheduled_at] || hash["scheduled_at"]
+        raise ArgumentError, "must include an ActiveJob instance in :job" unless active_job_instance?(job)
+
+        { job: job, scheduled_at: scheduled_at }
+      end
+
+      def active_job_instance?(value)
+        value.respond_to?(:job_id) && value.respond_to?(:queue_name)
+      end
+
+      def validate_concurrency!(concurrency)
+        concurrency = Integer(concurrency)
+        raise ArgumentError unless concurrency.positive?
+
+        concurrency
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "batch enqueue concurrency must be a positive integer"
+      end
+
+      def enqueue_entries(entries, results, concurrency)
+        return enqueue_sequentially(entries, results) if concurrency == 1
+
+        entry_queue = Queue.new
+        entries.each { |entry| entry_queue << entry }
+        worker_count = [concurrency, entries.length].min
+
+        Array.new(worker_count) do
+          Thread.new do
+            loop do
+              enqueue_entry(entry_queue.pop(true), results)
+            rescue ThreadError
+              break
+            end
+          end
+        end.each(&:value)
+      end
+
+      def enqueue_sequentially(entries, results)
+        entries.each { |entry| enqueue_entry(entry, results) }
+      end
+
+      def enqueue_entry(entry, results)
+        handle = enqueue_job.call(entry[:job], scheduled_at: entry[:scheduled_at])
+        results[entry[:index]] = success_result(entry, handle)
+      rescue DuplicateEnqueueError => e
+        results[entry[:index]] = duplicate_result(entry, e)
+      rescue StandardError => e
+        results[entry[:index]] = failed_result(entry, e)
+      end
+
+      def success_result(entry, handle)
+        BatchEnqueueItemResult.new(
+          index: entry[:index],
+          job: entry[:job],
+          status: :success,
+          handle: handle
+        )
+      end
+
+      def duplicate_result(entry, error)
+        BatchEnqueueItemResult.new(
+          index: entry[:index],
+          job: entry[:job],
+          status: :duplicate,
+          error: error
+        )
+      end
+
+      def failed_result(entry, error)
+        BatchEnqueueItemResult.new(
+          index: entry[:index],
+          job: entry[:job],
+          status: :failed,
+          error: error
+        )
+      end
+    end
+  end
+end

data/lib/activejob/temporal/bind_policy.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module ActiveJob
+  module Temporal
+    module BindPolicy
+      LOOPBACK_HOSTNAMES = %w[localhost].freeze
+      TRUE_VALUES = %w[1 true yes].freeze
+
+      module_function
+
+      def public_bind?(bind_address)
+        normalized = bind_address.to_s.strip
+        return false if normalized.empty? || LOOPBACK_HOSTNAMES.include?(normalized.downcase)
+
+        !IPAddr.new(normalized).loopback?
+      rescue IPAddr::InvalidAddressError
+        true
+      end
+
+      def allow_public_bind?(value)
+        TRUE_VALUES.include?(value.to_s.strip.downcase)
+      end
+
+      def validate!(endpoint:, bind_address:, allow_public_bind:, warn_on_allowed: true)
+        return unless public_bind?(bind_address)
+
+        unless allow_public_bind
+          raise ArgumentError,
+                "refusing to expose unauthenticated #{endpoint} endpoint on non-loopback address " \
+                "#{bind_address.inspect} without explicit public bind opt-in"
+        end
+
+        return unless warn_on_allowed
+
+        warn(
+          "Warning: exposing unauthenticated #{endpoint} endpoint on non-loopback address " \
+          "#{bind_address.inspect}. Protect it with network policy, a firewall, or an internal-only listener."
+        )
+      end
+    end
+  end
+end

data/lib/activejob/temporal/cancel/batch_canceller.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "batch_summary"
+
+module ActiveJob
+  module Temporal
+    module Cancel
+      class BatchCanceller
+        PAGE_SIZE = 100
+        TERMINATION_CONCURRENCY = 5
+        MAX_REPORTED_ERRORS = BatchSummary::MAX_REPORTED_ERRORS
+        TERMINATION_REASON = "ActiveJob::Temporal.cancel_where"
+        SEARCH_ATTRIBUTE_TYPES = {
+          "ajClass" => :keyword,
+          "ajQueue" => :keyword,
+          "ajJobId" => :keyword,
+          "ajEnqueuedAt" => :datetime,
+          "ajTenantId" => :integer
+        }.freeze
+
+        def initialize(client)
+          @client = client
+        end
+
+        def cancel_where(filters)
+          query = workflows_query(normalize_filters(filters))
+          summary = BatchSummary.new
+
+          each_workflow_page(query) do |workflow_executions|
+            terminate_workflows(workflow_executions, summary)
+          end
+
+          summary.to_h
+        rescue ArgumentError
+          raise
+        rescue StandardError => e
+          raise ActiveJob::Temporal::TemporalConnectionError,
+                "Failed to query Temporal workflows for batch cancellation: #{e.message}"
+        end
+
+        private
+
+        attr_reader :client
+
+        def normalize_filters(filters)
+          unless filters.respond_to?(:to_hash)
+            raise ArgumentError, "cancel_where filters must be a Hash of search attributes"
+          end
+
+          normalized_filters = filters.to_hash.transform_keys(&:to_s)
+          raise ArgumentError, "cancel_where requires at least one search attribute" if normalized_filters.empty?
+
+          normalized_filters.each_with_object({}) do |(name, value), result|
+            result[validate_search_attribute_name!(name)] = format_search_attribute_value(name, value)
+          end
+        end
+
+        def validate_search_attribute_name!(name)
+          return name if SEARCH_ATTRIBUTE_TYPES.key?(name)
+
+          supported_attributes = SEARCH_ATTRIBUTE_TYPES.keys.join(", ")
+          raise ArgumentError,
+                "Unsupported search attribute #{name.inspect}. Supported attributes: #{supported_attributes}"
+        end
+
+        def format_search_attribute_value(name, value)
+          case SEARCH_ATTRIBUTE_TYPES.fetch(name)
+          when :integer
+            format_integer_search_attribute_value(name, value)
+          when :keyword
+            format_keyword_search_attribute_value(name, value)
+          when :datetime
+            format_datetime_search_attribute_value(name, value)
+          end
+        end
+
+        def format_integer_search_attribute_value(name, value)
+          return value.to_s if value.is_a?(Integer)
+
+          raise ArgumentError, "#{name} must be an Integer"
+        end
+
+        def format_keyword_search_attribute_value(name, value)
+          valid_value = value.is_a?(String) || value.is_a?(Symbol)
+          raise ArgumentError, "#{name} must be a String or Symbol" unless valid_value
+
+          quote_search_attribute_string(value.to_s)
+        end
+
+        def format_datetime_search_attribute_value(name, value)
+          value = value.iso8601 if value.respond_to?(:iso8601)
+          raise ArgumentError, "#{name} must be a String or ISO8601-compatible time value" unless value.is_a?(String)
+
+          quote_search_attribute_string(value)
+        end
+
+        def quote_search_attribute_string(value)
+          raise ArgumentError, "search attribute values cannot be empty" if value.empty?
+
+          "'#{value.gsub("'", "''")}'"
+        end
+
+        def workflows_query(filters)
+          (filters.map { |name, value| "#{name}=#{value}" } + ["ExecutionStatus='Running'"]).join(" AND ")
+        end
+
+        def each_workflow_page(query, &)
+          next_page_token = nil
+
+          loop do
+            page = client.list_workflow_page(query, page_size: PAGE_SIZE, next_page_token: next_page_token)
+            yield page.executions
+            next_page_token = page.next_page_token
+            break if next_page_token.to_s.empty?
+          end
+        end
+
+        def terminate_workflows(workflow_executions, summary)
+          workflow_executions = workflow_executions.to_a
+          worker_count = [workflow_executions.length, TERMINATION_CONCURRENCY].min
+          workflow_queue = Queue.new
+
+          workflow_executions.each { |workflow_execution| workflow_queue << workflow_execution }
+          Array.new(worker_count) do
+            Thread.new do
+              loop do
+                terminate_workflow(workflow_queue.pop(true), summary)
+              rescue ThreadError
+                break
+              end
+            end
+          end.each(&:value)
+        end
+
+        def terminate_workflow(workflow_execution, summary)
+          workflow_id = workflow_execution.id
+          run_id = workflow_execution.respond_to?(:run_id) ? workflow_execution.run_id : nil
+
+          client.workflow_handle(workflow_id, run_id: run_id).terminate(TERMINATION_REASON)
+          ActiveJob::Temporal::AuditLog.record(
+            "job.cancelled",
+            workflow_id: workflow_id,
+            run_id: run_id,
+            status: "terminated",
+            reason: TERMINATION_REASON
+          )
+          summary.record_terminated
+        rescue StandardError => e
+          summary.record_failure(workflow_id, run_id, e)
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/cancel/batch_summary.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module Cancel
+      class BatchSummary
+        MAX_REPORTED_ERRORS = 100
+
+        def initialize
+          @mutex = Mutex.new
+          @value = { terminated: 0, failed: 0, errors: [] }
+        end
+
+        def record_terminated
+          mutex.synchronize { value[:terminated] += 1 }
+        end
+
+        def record_failure(workflow_id, run_id, error)
+          mutex.synchronize do
+            value[:failed] += 1
+            if value[:errors].length < MAX_REPORTED_ERRORS
+              value[:errors] << cancellation_error(workflow_id, run_id, error)
+            end
+          end
+        end
+
+        def to_h
+          value
+        end
+
+        private
+
+        attr_reader :mutex, :value
+
+        def cancellation_error(workflow_id, run_id, error)
+          {
+            workflow_id: workflow_id,
+            run_id: run_id,
+            error: "#{error.class}: #{error.message}"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/cancel.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative "visibility_query"
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    # Job cancellation with query-based workflow discovery.
+    #
+    # This module provides cancellation capabilities for ActiveJob workflows running on Temporal.
+    # Cancellation is asynchronous and best-effort: workflows will stop only if they are actively
+    # checking for cancellation signals (via heartbeating or cancellation checks).
+    #
+    # @note Best-Effort Semantics
+    #   Temporal cancellation is cooperative, not forceful. Activities must check for cancellation
+    #   by heartbeating or polling `Temporalio::Activity::Context.current.cancelled?`. Activities
+    #   that do not check for cancellation will run to completion even after a cancel request.
+    #
+    # @note Query Strategy
+    #   This module queries running workflows first, then closed workflows (completed, failed,
+    #   cancelled, etc.) to determine the workflow state before issuing a cancellation request.
+    #   This ensures idempotent cancellation behavior.
+    #
+    # @example Cancel a running job
+    #   ActiveJob::Temporal.cancel(SendInvoiceJob, "550e8400-e29b-41d4-a716-446655440000")
+    #
+    # @see https://docs.temporal.io/activities#heartbeat Temporal Activity Heartbeating
+    # @see https://docs.temporal.io/workflows#cancellation Temporal Cancellation Guide
+    module Cancel
+      class << self
+        # Cancels a running Temporal workflow by sending a cancellation request.
+        #
+        # This method first queries Temporal to determine the workflow state before
+        # attempting cancellation. It will not cancel already-completed workflows.
+        #
+        # @param job_class [Class] The ActiveJob class for the job to cancel.
+        # @param job_id [String] Identifier of the job to cancel.
+        # @return [Boolean, nil] Returns false if workflow already completed, nil if cancellation requested
+        #
+        # @raise [WorkflowNotFoundError] if no workflow exists for the given job_id
+        # @raise [TemporalConnectionError] if the Temporal cluster cannot be reached
+        #
+        # @note Asynchronous Cancellation
+        #   Cancellation requests are asynchronous. The method returns immediately after
+        #   sending the request. The workflow will stop only if it checks for cancellation.
+        #
+        # @example Cancel a running job
+        #   result = ActiveJob::Temporal.cancel(SendInvoiceJob, "550e8400-e29b-41d4-a716-446655440000")
+        #   puts "Cancellation requested" if result.nil?
+        #
+        # @example Handle all outcomes
+        #   begin
+        #     result = ActiveJob::Temporal.cancel(MyJob, "abc-123")
+        #     case result
+        #     when false
+        #       puts "Job already completed, cannot cancel"
+        #     when nil
+        #       puts "Cancellation sent to Temporal"
+        #     end
+        #   rescue ActiveJob::Temporal::WorkflowNotFoundError
+        #     puts "Job never existed or already removed from history"
+        #   rescue ActiveJob::Temporal::TemporalConnectionError => e
+        #     puts "Cannot reach Temporal: #{e.message}"
+        #   end
+        #
+        # @see #find_workflow
+        def cancel(job_class, job_id)
+          validate_job_id!(job_id)
+          client = ActiveJob::Temporal.client
+          workflow_state = find_workflow(client, job_class, job_id)
+          workflow_id = workflow_state[:workflow_id]
+
+          case workflow_state[:status]
+          when :closed
+            log_workflow_already_completed(job_class, job_id, workflow_id)
+            false
+          when :not_found
+            raise ActiveJob::Temporal::WorkflowNotFoundError,
+                  "No workflow found for job_id #{job_id}. The job may have never existed."
+          when :running
+            client.workflow_handle(workflow_id).cancel
+            log_cancellation_requested(job_class, job_id, workflow_id)
+            log_audit_cancellation_requested(job_class, job_id, workflow_id)
+            nil
+          end
+        end
+
+        def cancel_all(job_class)
+          validate_job_class!(job_class)
+
+          cancel_where(ajClass: job_class.name)
+        end
+
+        def cancel_where(filters)
+          BatchCanceller.new(ActiveJob::Temporal.client).cancel_where(filters)
+        end
+
+        # UUID format regex (compliant with RFC 4122).
+        # Matches standard UUID format: 8-4-4-4-12 hexadecimal characters.
+        # @api private
+        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
+
+        private
+
+        def validate_job_class!(job_class)
+          return if job_class.respond_to?(:name) && !job_class.name.to_s.empty?
+
+          raise ArgumentError, "job_class must be a named class"
+        end
+
+        # Validates that job_id is a valid UUID format.
+        #
+        # ActiveJob generates job IDs using SecureRandom.uuid, which produces RFC 4122
+        # compliant UUIDs. This validation prevents search query injection attacks by
+        # ensuring job_id contains only hexadecimal characters and hyphens, making it
+        # safe for direct use in Temporal queries.
+        #
+        # @param job_id [String] The job identifier to validate
+        # @raise [ArgumentError] if job_id is not a valid UUID format
+        # @api private
+        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
+
+        # Builds deterministic workflow ID from job class and job ID.
+        # @api private
+        def build_workflow_id(job_class, job_id)
+          WorkflowIdBuilder.new.build_from_job_class(job_class, job_id)
+        end
+
+        # Queries Temporal to determine the current state of the workflow.
+        # Checks running workflows first, then closed workflows.
+        #
+        # @param client [Temporalio::Client] The Temporal client instance
+        # @param job_class [Class] The ActiveJob class for fallback workflow ID generation
+        # @param job_id [String] The job identifier
+        # @return [Symbol] :running, :closed, or :not_found
+        # @raise [TemporalConnectionError] if connection to Temporal fails
+        def find_workflow(client, job_class, job_id)
+          # Query running workflows first
+          running_query = running_workflows_query(job_class, job_id)
+          running = client.list_workflows(running_query).first
+          return workflow_state(:running, running, job_class, job_id) if running
+
+          # Query closed workflows (completed, failed, cancelled, etc.)
+          closed_query = closed_workflows_query(job_class, job_id)
+          closed = client.list_workflows(closed_query).first
+          return workflow_state(:closed, closed, job_class, job_id) if closed
+
+          { status: :not_found, workflow_id: build_workflow_id(job_class, job_id) }
+        rescue StandardError => e
+          raise ActiveJob::Temporal::TemporalConnectionError,
+                "Failed to query Temporal workflows for job_id #{job_id}: #{e.message}"
+        end
+
+        def workflow_state(status, workflow_info, job_class, job_id)
+          workflow_id = if workflow_info.respond_to?(:id) && workflow_info.id
+                          workflow_info.id
+                        else
+                          build_workflow_id(job_class, job_id)
+                        end
+
+          { status: status, workflow_id: workflow_id }
+        end
+
+        # Builds Temporal query for running workflows by job class and job_id.
+        #
+        # Note: job_id is validated as a UUID before reaching this method, ensuring it
+        # contains only safe characters ([0-9a-fA-F-]) for direct query interpolation.
+        #
+        # @api private
+        def running_workflows_query(job_class, job_id)
+          workflow_search_query(job_class, job_id, "ExecutionStatus='Running'")
+        end
+
+        # Builds Temporal query for closed workflows by job class and job_id.
+        #
+        # Note: job_id is validated as a UUID before reaching this method, ensuring it
+        # contains only safe characters ([0-9a-fA-F-]) for direct query interpolation.
+        #
+        # @api private
+        def closed_workflows_query(job_class, job_id)
+          workflow_search_query(
+            job_class,
+            job_id,
+            "ExecutionStatus IN ('Completed', 'Failed', 'Cancelled', 'Terminated', 'TimedOut', 'ContinuedAsNew')"
+          )
+        end
+
+        def workflow_search_query(job_class, job_id, status_query)
+          "ajClass=#{VisibilityQuery.quote(job_class.name)} AND ajJobId=#{VisibilityQuery.quote(job_id)} " \
+            "AND #{status_query}"
+        end
+
+        # Logs cancellation request event.
+        # @api private
+        def log_cancellation_requested(job_class, job_id, workflow_id)
+          ActiveJob::Temporal::Logger.info(
+            "cancellation_requested",
+            workflow_id: workflow_id,
+            job_class: job_class.name,
+            job_id: job_id
+          )
+        end
+
+        # Logs event when attempting to cancel an already-completed workflow.
+        # @api private
+        def log_workflow_already_completed(job_class, job_id, workflow_id)
+          ActiveJob::Temporal::Logger.warn(
+            "cancellation_workflow_already_completed",
+            workflow_id: workflow_id,
+            job_class: job_class.name,
+            job_id: job_id,
+            status: "completed"
+          )
+        end
+
+        def log_audit_cancellation_requested(job_class, job_id, workflow_id)
+          ActiveJob::Temporal::AuditLog.record(
+            "job.cancelled",
+            workflow_id: workflow_id,
+            job_class: job_class.name,
+            job_id: job_id,
+            status: "requested"
+          )
+        end
+      end
+    end
+  end
+end
+
+require_relative "cancel/batch_canceller"

data/lib/activejob/temporal/certificate_watcher.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "listen"
+
+module ActiveJob
+  module Temporal
+    # Watches TLS certificate files and runs a reload callback when they change.
+    class CertificateWatcher
+      DEFAULT_DEBOUNCE_SECONDS = 1.0
+
+      def self.paths_from_config(configuration)
+        [
+          configuration.tls_cert_path,
+          configuration.tls_key_path,
+          configuration.tls_server_root_ca_cert_path
+        ].compact.reject { |path| path.to_s.strip.empty? }
+      end
+
+      def initialize(paths:, reload_callback:, listener_factory: Listen, debounce_seconds: DEFAULT_DEBOUNCE_SECONDS)
+        @paths = paths.map { |path| File.expand_path(path) }.uniq
+        @reload_callback = reload_callback
+        @listener_factory = listener_factory
+        @debounce_seconds = debounce_seconds
+        @mutex = Mutex.new
+        @last_reload_at = nil
+        @listener = nil
+      end
+
+      def start
+        return self if @paths.empty? || @listener
+
+        @listener = @listener_factory.to(*directories) do |modified, added, removed|
+          handle_changes(modified + added + removed)
+        end
+        @listener.start
+        self
+      end
+
+      def stop
+        @listener&.stop
+        @listener = nil
+      end
+
+      def handle_changes(changed_paths)
+        return unless relevant_change?(changed_paths)
+        return if debounced?
+
+        @reload_callback.call
+      end
+
+      private
+
+      def directories
+        @directories ||= @paths.map { |path| File.dirname(path) }.uniq
+      end
+
+      def relevant_change?(changed_paths)
+        changed_paths.any? do |path|
+          @paths.include?(File.expand_path(path))
+        end
+      end
+
+      def debounced?
+        return false unless @debounce_seconds.positive?
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @mutex.synchronize do
+          return true if @last_reload_at && (now - @last_reload_at) < @debounce_seconds
+
+          @last_reload_at = now
+          false
+        end
+      end
+    end
+  end
+end