activejob-temporal 0.1.0

data/lib/activejob/temporal/chain_options.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "active_job"
+require_relative "configured_job_compatibility"
+require_relative "external_operation"
+require_relative "job_descriptor"
+
+module ActiveJob
+  module Temporal
+    module ChainOptions
+      SUPPORTED_CONFIGURED_OPTIONS = %i[priority queue].freeze
+
+      attr_reader :temporal_chain
+
+      def self.normalize(chain)
+        return nil if chain.nil?
+
+        raise ArgumentError, "chain must be an Array of ActiveJob classes or configured jobs" unless chain.is_a?(Array)
+        raise ArgumentError, "chain must contain at least one ActiveJob class or configured job" if chain.empty?
+
+        chain.map { |job_class| normalize_job_class(job_class) }
+      end
+
+      def self.normalize_job_class(job_class)
+        ExternalOperation.normalize(job_class) ||
+          job_descriptor_payload(job_class) ||
+          active_job_class_payload(job_class) ||
+          configured_job_payload(job_class, feature: "chain") ||
+          raise(ArgumentError, "chain entries must be ActiveJob classes or configured jobs")
+      end
+      private_class_method :normalize_job_class
+
+      def self.job_descriptor_payload(job_class)
+        payload = JobDescriptor.normalize(job_class)
+        return unless payload
+
+        payload.merge(options: normalize_configured_options(payload.fetch(:options)))
+      end
+      private_class_method :job_descriptor_payload
+
+      def self.active_job_class_payload(job_class)
+        return unless job_class.is_a?(Class) && job_class < ActiveJob::Base && job_class.name
+
+        { job_class: job_class.name, options: {} }
+      end
+      private_class_method :active_job_class_payload
+
+      def self.configured_job_payload(job_class, feature:)
+        ConfiguredJobCompatibility.payload(
+          job_class,
+          feature: feature,
+          normalize_options: method(:normalize_configured_options)
+        )
+      end
+      private_class_method :configured_job_payload
+
+      def self.normalize_configured_options(options)
+        unsupported_options = options.keys.reject do |key|
+          SUPPORTED_CONFIGURED_OPTIONS.include?(key.to_sym)
+        end
+        unless unsupported_options.empty?
+          raise ArgumentError, "chain configured jobs only support queue and priority options"
+        end
+
+        options.each_with_object({}) do |(key, value), normalized|
+          normalized[key.to_sym] = value
+        end
+      end
+      private_class_method :normalize_configured_options
+
+      def set(options = {})
+        enqueue_options = options.dup
+        normalized_chain = ChainOptions.normalize(enqueue_options.delete(:chain)) if enqueue_options.key?(:chain)
+
+        super(enqueue_options).tap do
+          @temporal_chain = normalized_chain if options.key?(:chain)
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Base.prepend(ActiveJob::Temporal::ChainOptions) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/child_workflow_options.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "active_job"
+require_relative "configured_job_compatibility"
+require_relative "external_operation"
+require_relative "job_descriptor"
+require_relative "job_tags"
+
+module ActiveJob
+  module Temporal
+    module ChildWorkflowOptions
+      SUPPORTED_CONFIGURED_OPTIONS = %i[priority queue tags].freeze
+
+      attr_reader :temporal_child_workflows
+
+      def self.normalize(child_workflows)
+        return nil if child_workflows.nil?
+
+        unless child_workflows.is_a?(Array)
+          raise ArgumentError, "child_workflows must be an Array of ActiveJob classes or configured jobs"
+        end
+        if child_workflows.empty?
+          raise ArgumentError, "child_workflows must contain at least one ActiveJob class or configured job"
+        end
+
+        child_workflows.map { |child_workflow| normalize_job_class(child_workflow) }
+      end
+
+      def self.normalize_job_class(child_workflow)
+        external_operation = ExternalOperation.normalize(child_workflow)
+        return normalize_external_operation(external_operation) if external_operation
+
+        job_descriptor = job_descriptor_payload(child_workflow)
+        return job_descriptor if job_descriptor
+
+        active_job_class_payload(child_workflow) ||
+          configured_job_payload(child_workflow, feature: "child_workflows") ||
+          raise(ArgumentError, "child_workflows entries must be ActiveJob classes or configured jobs")
+      end
+      private_class_method :normalize_job_class
+
+      def self.job_descriptor_payload(child_workflow)
+        payload = JobDescriptor.normalize(child_workflow)
+        return unless payload
+
+        payload.merge(options: normalize_configured_options(payload.fetch(:options)))
+      end
+      private_class_method :job_descriptor_payload
+
+      def self.normalize_external_operation(external_operation)
+        return external_operation if external_operation[:temporal_operation] == ExternalOperation::WORKFLOW
+
+        raise ArgumentError, "child_workflows entries must be ActiveJob classes or configured jobs; " \
+                             "external refs must be workflows"
+      end
+      private_class_method :normalize_external_operation
+
+      def self.active_job_class_payload(job_class)
+        return unless job_class.is_a?(Class) && job_class < ActiveJob::Base && job_class.name
+
+        { job_class: job_class.name, options: {} }
+      end
+      private_class_method :active_job_class_payload
+
+      def self.configured_job_payload(child_workflow, feature:)
+        ConfiguredJobCompatibility.payload(
+          child_workflow,
+          feature: feature,
+          normalize_options: method(:normalize_configured_options)
+        )
+      end
+      private_class_method :configured_job_payload
+
+      def self.normalize_configured_options(options)
+        unsupported_options = options.keys.reject do |key|
+          SUPPORTED_CONFIGURED_OPTIONS.include?(key.to_sym)
+        end
+        unless unsupported_options.empty?
+          raise ArgumentError, "child_workflows configured jobs only support queue, priority, and tags options"
+        end
+
+        options.each_with_object({}) do |(key, value), normalized|
+          normalized[key.to_sym] = key.to_sym == :tags ? JobTags.normalize(value) : value
+        end
+      end
+      private_class_method :normalize_configured_options
+
+      def set(options = {})
+        enqueue_options = options.dup
+        normalized_children = if enqueue_options.key?(:child_workflows)
+                                ChildWorkflowOptions.normalize(enqueue_options.delete(:child_workflows))
+                              end
+
+        super(enqueue_options).tap do
+          @temporal_child_workflows = normalized_children if options.key?(:child_workflows)
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Base.prepend(ActiveJob::Temporal::ChildWorkflowOptions) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/client.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+begin
+  require "temporalio/client"
+rescue LoadError
+  # The Temporal Ruby SDK is not present in development/test by default.
+  # Tests stub Temporalio::Client, and production users must include the SDK.
+end
+
+require_relative "tls_file"
+
+module ActiveJob
+  module Temporal
+    # Builds Temporal client connections.
+    #
+    # This module encapsulates the logic for connecting to a Temporal cluster
+    # with optional TLS configuration. TLS options can be provided via configuration
+    # attributes or environment variables.
+    #
+    # @note TLS Configuration Precedence
+    #   `config.tls` takes precedence, followed by configured certificate file paths,
+    #   then legacy environment variables.
+    #
+    # @note Environment Variables
+    #   - TEMPORAL_TLS_CERT: TLS certificate (PEM format, full content)
+    #   - TEMPORAL_TLS_KEY: TLS private key (PEM format, full content)
+    #   - TEMPORAL_TLS_SERVER_NAME: TLS server name for verification
+    #
+    # @example Basic connection
+    #   config = ActiveJob::Temporal.config
+    #   client = Client.build(config)
+    #
+    # @example TLS via environment variables
+    #   ENV["TEMPORAL_TLS_CERT"] = File.read("cert.pem")
+    #   ENV["TEMPORAL_TLS_KEY"] = File.read("key.pem")
+    #   ENV["TEMPORAL_TLS_SERVER_NAME"] = "temporal.example.com"
+    #   client = Client.build(config)
+    #
+    # @example TLS via configuration object
+    #   ActiveJob::Temporal.configure do |config|
+    #     config.tls = {
+    #       client_cert: File.read("cert.pem"),
+    #       client_private_key: File.read("key.pem"),
+    #       domain: "temporal.example.com"
+    #     }
+    #   end
+    #   client = ActiveJob::Temporal.client
+    module Client
+      TLS_OPTIONS_CLASS = if defined?(Temporalio::Client::Connection::TLSOptions)
+                            Temporalio::Client::Connection::TLSOptions
+                          end
+
+      # Environment variable name for TLS certificate
+      TLS_CERT_ENV = "TEMPORAL_TLS_CERT"
+      # Environment variable name for TLS private key
+      TLS_KEY_ENV = "TEMPORAL_TLS_KEY"
+      # Environment variable name for TLS server name
+      TLS_SERVER_NAME_ENV = "TEMPORAL_TLS_SERVER_NAME"
+      # Environment variable name for TLS root CA certificate
+      TLS_SERVER_ROOT_CA_CERT_ENV = "TEMPORAL_TLS_SERVER_ROOT_CA_CERT"
+
+      module_function
+
+      # Builds and connects a Temporal client.
+      #
+      # Creates a new Temporalio::Client instance connected to the configured
+      # Temporal cluster. TLS options are automatically included if present in
+      # configuration or environment variables.
+      #
+      # @param configuration [Configuration] Gem configuration object with target/namespace
+      #
+      # @return [Temporalio::Client] Connected Temporal client
+      #
+      # @raise [ActiveJob::Temporal::Error] if connection fails (includes target, namespace, and error message)
+      # @raise [OpenSSL::SSL::SSLError] if TLS certificate validation fails
+      # @raise [OpenSSL::PKey::RSAError] if TLS private key is invalid
+      # @raise [OpenSSL::X509::CertificateError] if TLS certificate is malformed
+      # @raise [SocketError] if target hostname cannot be resolved
+      # @raise [Errno::ECONNREFUSED] if target port is not accepting connections
+      # @raise [Errno::ETIMEDOUT] if connection times out
+      #
+      # @example Basic usage
+      #   config = ActiveJob::Temporal::Configuration.new
+      #   config.target = "temporal.example.com:7233"
+      #   config.namespace = "production"
+      #   client = Client.build(config)
+      #
+      # @example With TLS via environment variables
+      #   ENV["TEMPORAL_TLS_CERT"] = File.read("client.pem")
+      #   ENV["TEMPORAL_TLS_KEY"] = File.read("client-key.pem")
+      #   ENV["TEMPORAL_TLS_SERVER_NAME"] = "temporal.prod.example.com"
+      #   client = Client.build(config)
+      #   # Client will connect using mutual TLS
+      #
+      # @example Handling connection failures
+      #   begin
+      #     client = Client.build(config)
+      #   rescue ActiveJob::Temporal::Error => e
+      #     Rails.logger.fatal("Cannot connect to Temporal: #{e.message}")
+      #     # Fall back to different adapter or alert operations team
+      #   end
+      def build(configuration)
+        Temporalio::Client.connect(
+          configuration.target,
+          configuration.namespace,
+          **connection_kwargs(configuration)
+        )
+      rescue StandardError => e
+        raise ActiveJob::Temporal::Error,
+              format(
+                "Unable to connect to Temporal at %<target>s (namespace: %<namespace>s): %<error>s",
+                target: configuration.target,
+                namespace: configuration.namespace,
+                error: e.message
+              )
+      end
+
+      # Builds connection keyword arguments (including TLS options).
+      # @api private
+      def connection_kwargs(configuration)
+        tls = tls_options(configuration)
+        return {} if tls.nil?
+
+        { tls: tls }
+      end
+      private_class_method :connection_kwargs
+
+      # Extracts TLS options from config or environment variables.
+      # @api private
+      def tls_options(configuration)
+        configured_tls = configuration.tls if configuration.respond_to?(:tls)
+        return normalize_tls_options(configured_tls) unless configured_tls.nil?
+
+        path_options = tls_path_options(configuration)
+        return path_options if path_options
+
+        cert = ENV.fetch(TLS_CERT_ENV, nil)
+        key = ENV.fetch(TLS_KEY_ENV, nil)
+        server_name = ENV.fetch(TLS_SERVER_NAME_ENV, nil)
+        server_root_ca_cert = ENV.fetch(TLS_SERVER_ROOT_CA_CERT_ENV, nil)
+        return nil unless cert || key || server_name || server_root_ca_cert
+
+        build_tls_options(
+          client_cert: cert,
+          client_private_key: key,
+          server_root_ca_cert: server_root_ca_cert,
+          domain: server_name
+        )
+      end
+      private_class_method :tls_options
+
+      def tls_path_options(configuration)
+        return unless configuration.respond_to?(:tls_cert_path)
+
+        cert = read_tls_file(configuration.tls_cert_path)
+        key = read_tls_file(configuration.tls_key_path)
+        server_root_ca_cert = read_tls_file(configuration.tls_server_root_ca_cert_path)
+        domain = configuration.tls_domain
+        return nil unless cert || key || server_root_ca_cert || domain
+
+        build_tls_options(
+          client_cert: cert,
+          client_private_key: key,
+          server_root_ca_cert: server_root_ca_cert,
+          domain: domain
+        )
+      end
+      private_class_method :tls_path_options
+
+      def read_tls_file(path)
+        TLSFile.read(path)
+      end
+      private_class_method :read_tls_file
+
+      def normalize_tls_options(tls)
+        return tls if [true, false].include?(tls)
+        return tls if TLS_OPTIONS_CLASS && tls.is_a?(TLS_OPTIONS_CLASS)
+        return normalize_tls_hash(tls) if tls.is_a?(Hash)
+
+        tls
+      end
+      private_class_method :normalize_tls_options
+
+      def normalize_tls_hash(tls)
+        build_tls_options(
+          client_cert: tls_hash_value(tls, :client_cert, :certificate),
+          client_private_key: tls_hash_value(tls, :client_private_key, :private_key),
+          server_root_ca_cert: tls_hash_value(tls, :server_root_ca_cert),
+          domain: tls_hash_value(tls, :domain, :server_name)
+        )
+      end
+      private_class_method :normalize_tls_hash
+
+      def tls_hash_value(hash, *keys)
+        keys.each do |key|
+          return hash[key] if hash.key?(key)
+
+          string_key = key.to_s
+          return hash[string_key] if hash.key?(string_key)
+        end
+
+        nil
+      end
+      private_class_method :tls_hash_value
+
+      def build_tls_options(**attributes)
+        attributes = attributes.compact
+        return attributes unless TLS_OPTIONS_CLASS
+
+        TLS_OPTIONS_CLASS.new(**attributes)
+      end
+      private_class_method :build_tls_options
+    end
+  end
+end

data/lib/activejob/temporal/conditional_enqueue.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_support/concern"
+
+module ActiveJob
+  module Temporal
+    # Adds conditional enqueue helpers to ActiveJob classes.
+    module ConditionalEnqueue
+      extend ActiveSupport::Concern
+
+      def self.job_arguments(arguments, keyword_arguments)
+        return arguments if keyword_arguments.empty?
+
+        arguments + [keyword_arguments]
+      end
+
+      def self.condition_allows_enqueue?(receiver, condition, arguments)
+        !!evaluate_condition(receiver, condition, arguments)
+      end
+
+      def self.evaluate_condition(receiver, condition, arguments)
+        return receiver.public_send(condition, arguments) if condition.is_a?(Symbol) || condition.is_a?(String)
+        return condition.call(arguments) if condition.respond_to?(:call)
+
+        raise ArgumentError, "condition must be a Symbol, String, or respond to #call"
+      end
+
+      class_methods do
+        def perform_later_if(condition, *arguments, **keyword_arguments, &)
+          condition_arguments = ConditionalEnqueue.job_arguments(arguments, keyword_arguments)
+          return nil unless ConditionalEnqueue.condition_allows_enqueue?(self, condition, condition_arguments)
+
+          perform_later(*arguments, **keyword_arguments, &)
+        end
+      end
+    end
+
+    # Adds conditional enqueue helpers to ActiveJob configured jobs.
+    module ConfiguredConditionalEnqueue
+      def perform_later_if(condition, *arguments, **keyword_arguments, &)
+        job_class = instance_variable_get(:@job_class)
+        condition_arguments = ConditionalEnqueue.job_arguments(arguments, keyword_arguments)
+        return nil unless ConditionalEnqueue.condition_allows_enqueue?(job_class, condition, condition_arguments)
+
+        perform_later(*arguments, **keyword_arguments, &)
+      end
+    end
+  end
+end
+
+ActiveJob::Base.include(ActiveJob::Temporal::ConditionalEnqueue) if defined?(ActiveJob::Base)
+
+if defined?(ActiveJob::ConfiguredJob)
+  ActiveJob::ConfiguredJob.include(ActiveJob::Temporal::ConfiguredConditionalEnqueue)
+end

data/lib/activejob/temporal/configurable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "concurrent/mvar"
+
+require_relative "configuration"
+
+module ActiveJob
+  module Temporal
+    # Module-level configuration API for ActiveJob::Temporal.
+    #
+    # @api private
+    module Configurable
+      # Returns the global configuration object.
+      #
+      # @return [Configuration] the gem configuration
+      def config
+        @config_mvar ||= Concurrent::MVar.new(Configuration.new)
+        @config_mvar.value
+      end
+      alias configuration config
+
+      # Configures the gem with a block and validates after mutation.
+      #
+      # @yield [config] Gives the configuration object to the block
+      # @yieldparam config [Configuration] the configuration to modify
+      # @return [Configuration] the configuration object
+      # @raise [ConfigurationError] if validation fails after configuration
+      def configure
+        return config unless block_given?
+
+        @config_mvar ||= Concurrent::MVar.new(Configuration.new)
+        @config_mvar.borrow do |configuration|
+          configuration.in_configure_block = true
+
+          begin
+            yield(configuration)
+          ensure
+            configuration.in_configure_block = false
+          end
+
+          configuration.validate!
+          configuration
+        end
+      end
+
+      # Validates the current configuration.
+      #
+      # @return [void]
+      # @raise [ConfigurationError] if validation fails
+      def validate!
+        config.validate!
+      end
+    end
+  end
+end