activejob-temporal 0.1.0

data/lib/activejob/temporal/job_payload_chain_builder.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "adapter"
+require_relative "external_operation"
+require "active_support/core_ext/string/inflections"
+
+module ActiveJob
+  module Temporal
+    module JobPayloadChainBuilder
+      ChainStepRoutingJob = Struct.new(:queue_name, :priority)
+
+      private
+
+      def apply_chain(payload, job)
+        chain = chain_payloads_for(job)
+        payload[:chain] = chain if chain.any?
+      end
+
+      def chain_payloads_for(job)
+        Array(job.respond_to?(:temporal_chain) ? job.temporal_chain : nil).each_with_index.map do |chain_step, index|
+          chain_payload_for(job, chain_step, index + 1)
+        end
+      end
+
+      def chain_payload_for(root_job, chain_step, position)
+        external_operation = ExternalOperation.normalize(chain_step)
+        return external_chain_payload(external_operation) if external_operation
+
+        job_class = chain_step_job_class(chain_step)
+        options = chain_step_options(chain_step)
+        queue_name = chain_step_queue_name(job_class, options)
+        job_id = "#{root_job.job_id}:chain:#{position}"
+        payload = base_chain_payload(job_class, job_id, queue_name, options)
+
+        apply_chain_step_retry_policy(payload, job_class, job_id, queue_name)
+        apply_temporal_options(payload, job_class)
+        apply_rate_limits_for_class(payload, job_class)
+        apply_workflow_interactions(payload, job_class)
+        payload
+      end
+
+      def external_chain_payload(external_operation)
+        {
+          temporal_operation: external_operation.fetch(:temporal_operation),
+          temporal_type: external_operation.fetch(:temporal_type),
+          options: external_operation.fetch(:options)
+        }
+      end
+
+      def base_chain_payload(job_class, job_id, queue_name, options)
+        {
+          job_class: job_class.name,
+          job_id: job_id,
+          queue_name: queue_name,
+          arguments: [],
+          executions: 0,
+          exception_executions: {},
+          default_activity_options: default_activity_options,
+          activity_task_queue: chain_step_activity_task_queue(queue_name, options)
+        }
+      end
+
+      def chain_step_job_class(chain_step)
+        job_class_name = chain_step[:job_class] || chain_step["job_class"]
+        job_class = job_class_name.constantize
+        return job_class if job_class < ActiveJob::Base
+
+        raise ArgumentError, "chain entries must be ActiveJob classes or configured jobs"
+      end
+
+      def chain_step_options(chain_step)
+        chain_step[:options] || chain_step["options"] || {}
+      end
+
+      def chain_step_queue_name(job_class, options)
+        queue_name = options[:queue] || options["queue"] || job_class.queue_name
+        queue_name.to_s
+      end
+
+      def chain_step_activity_task_queue(queue_name, options)
+        priority = options[:priority] || options["priority"]
+        routing_job = ChainStepRoutingJob.new(queue_name, priority)
+        Adapter.resolve_task_queue(routing_job, config: @config)
+      end
+
+      def apply_chain_step_retry_policy(payload, job_class, job_id, queue_name)
+        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_id,
+          queue_name,
+          retry_policy,
+          task_queue: payload.fetch(:activity_task_queue)
+        )
+      end
+
+      def apply_rate_limits_for_class(payload, job_class)
+        rate_limits = rate_limits_for(job_class)
+        payload[:rate_limits] = rate_limits if rate_limits.any?
+      end
+    end
+  end
+end

data/lib/activejob/temporal/job_payload_child_workflows.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "time"
+
+require_relative "adapter"
+require_relative "external_operation"
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    module JobPayloadChildWorkflows
+      ChildWorkflowRoutingJob = Struct.new(:queue_name, :priority)
+
+      private
+
+      def apply_child_workflows(payload, job)
+        child_workflows = child_workflow_payloads_for(job)
+        payload[:child_workflows] = child_workflows if child_workflows.any?
+      end
+
+      def child_workflow_payloads_for(job)
+        child_workflows = job.respond_to?(:temporal_child_workflows) ? job.temporal_child_workflows : nil
+        Array(child_workflows).each_with_index.map do |child_workflow, index|
+          child_workflow_payload_for(job, child_workflow, index + 1)
+        end
+      end
+
+      def child_workflow_payload_for(root_job, child_workflow, position)
+        external_operation = ExternalOperation.normalize(child_workflow)
+        return external_child_workflow_payload(external_operation) if external_operation
+
+        job_class = child_workflow_job_class(child_workflow)
+        options = child_workflow_options(child_workflow)
+        queue_name = child_workflow_queue_name(job_class, options)
+        job_id = "#{root_job.job_id}:child:#{position}"
+        payload = base_child_workflow_payload(job_class, job_id, queue_name, options)
+
+        apply_child_workflow_retry_policy(payload, job_class, job_id, queue_name)
+        apply_temporal_options(payload, job_class)
+        apply_workflow_identity(payload, job_class)
+        apply_rate_limits_for_class(payload, job_class)
+        apply_workflow_interactions(payload, job_class)
+        apply_child_workflow_search_attributes(payload, job_class, job_id, queue_name, options)
+        payload
+      end
+
+      def external_child_workflow_payload(external_operation)
+        {
+          temporal_operation: external_operation.fetch(:temporal_operation),
+          temporal_type: external_operation.fetch(:temporal_type),
+          options: external_operation.fetch(:options)
+        }
+      end
+
+      def base_child_workflow_payload(job_class, job_id, queue_name, options)
+        task_queue = child_workflow_task_queue(queue_name, options)
+        {
+          job_class: job_class.name,
+          job_id: job_id,
+          workflow_id: child_workflow_id(job_class, job_id),
+          queue_name: queue_name,
+          arguments: [],
+          executions: 0,
+          exception_executions: {},
+          default_activity_options: default_activity_options,
+          activity_task_queue: task_queue,
+          workflow_task_queue: task_queue
+        }
+      end
+
+      def child_workflow_job_class(child_workflow)
+        job_class_name = child_workflow[:job_class] || child_workflow["job_class"]
+        job_class = job_class_name.constantize
+        return job_class if job_class < ActiveJob::Base
+
+        raise ArgumentError, "child_workflows entries must be ActiveJob classes or configured jobs"
+      end
+
+      def child_workflow_options(child_workflow)
+        child_workflow[:options] || child_workflow["options"] || {}
+      end
+
+      def child_workflow_queue_name(job_class, options)
+        queue_name = options[:queue] || options["queue"] || job_class.queue_name
+        queue_name.to_s
+      end
+
+      def child_workflow_task_queue(queue_name, options)
+        priority = options[:priority] || options["priority"]
+        routing_job = ChildWorkflowRoutingJob.new(queue_name, priority)
+        Adapter.resolve_task_queue(routing_job, config: @config)
+      end
+
+      def child_workflow_id(job_class, job_id)
+        WorkflowIdBuilder.new.build_from_job_class(job_class, job_id)
+      end
+
+      def apply_child_workflow_retry_policy(payload, job_class, job_id, queue_name)
+        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_id,
+          queue_name,
+          retry_policy,
+          task_queue: payload.fetch(:activity_task_queue)
+        )
+      end
+
+      def apply_child_workflow_search_attributes(payload, job_class, job_id, queue_name, options)
+        return unless @config.respond_to?(:enable_search_attributes) && @config.enable_search_attributes
+
+        tags = options[:tags] || options["tags"] || []
+        payload[:search_attributes] = {
+          job_class: job_class.name,
+          job_id: job_id,
+          queue_name: queue_name,
+          enqueued_at: Time.now.utc.iso8601,
+          tags: tags
+        }
+      end
+    end
+  end
+end

data/lib/activejob/temporal/job_payload_dependencies.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    module JobPayloadDependencies
+      private
+
+      def apply_dependencies(payload, job)
+        return unless job.respond_to?(:temporal_dependencies)
+
+        dependencies = Array(job.temporal_dependencies)
+        return if dependencies.empty?
+
+        payload[:dependencies] = dependencies.map { |dependency| enrich_dependency(dependency) }
+        policy = job.respond_to?(:temporal_dependency_failure_policy) ? job.temporal_dependency_failure_policy : :fail
+        payload[:dependency_failure_policy] = policy.to_s
+      end
+
+      def enrich_dependency(dependency)
+        normalized = dependency.each_with_object({}) do |(key, value), enriched_dependency|
+          enriched_dependency[key.to_sym] = value
+        end
+        normalized[:workflow_id] ||= default_dependency_workflow_id(normalized)
+        normalized.compact
+      end
+
+      def default_dependency_workflow_id(dependency)
+        job_class = dependency[:job_class]
+        job_id = dependency[:job_id]
+        return unless job_class && job_id
+
+        workflow_id = "#{WorkflowIdBuilder::DEFAULT_PREFIX}:#{job_class}:#{job_id}"
+        WorkflowIdBuilder.validate!(workflow_id)
+        workflow_id
+      end
+    end
+  end
+end

data/lib/activejob/temporal/job_payload_rate_limits.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "rate_limit_options"
+
+module ActiveJob
+  module Temporal
+    module JobPayloadRateLimits
+      private
+
+      def apply_rate_limits(payload, job)
+        rate_limits = rate_limits_for(job.class)
+        payload[:rate_limits] = rate_limits if rate_limits.any?
+      end
+
+      def rate_limits_for(job_class)
+        rate_limits = [
+          configured_global_rate_limit,
+          configured_job_rate_limit(job_class)
+        ].compact
+        validate_rate_limiter!(rate_limits)
+        rate_limits
+      end
+
+      def configured_global_rate_limit
+        return unless @config.respond_to?(:global_rate_limit) && @config.global_rate_limit
+
+        normalize_rate_limit(@config.global_rate_limit, default_key: "activejob-temporal:global")
+      end
+
+      def configured_job_rate_limit(job_class)
+        return unless job_class.respond_to?(:rate_limit)
+
+        rate_limit = job_class.rate_limit
+        return if rate_limit.empty?
+
+        normalize_rate_limit(rate_limit, default_key: "activejob-temporal:job:#{job_class.name}")
+      end
+
+      def normalize_rate_limit(rate_limit, default_key:)
+        normalized = RateLimitOptions.normalize_hash(rate_limit)
+        normalized[:key] ||= default_key
+        normalized
+      end
+
+      def validate_rate_limiter!(rate_limits)
+        return if rate_limits.empty?
+        return if @config.respond_to?(:rate_limiter) && @config.rate_limiter
+
+        raise ConfigurationError, "rate_limiter is required when rate limits are configured"
+      end
+    end
+  end
+end

data/lib/activejob/temporal/job_payload_workflow_interactions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module JobPayloadWorkflowInteractions
+      private
+
+      def apply_workflow_interactions(payload, job_class)
+        workflow_interactions = workflow_interactions_for(job_class)
+        payload[:workflow_interactions] = workflow_interactions if workflow_interactions
+      end
+
+      def workflow_interactions_for(job_class)
+        handlers = {
+          signals: handler_names_for(job_class, :temporal_signal_handler_names),
+          queries: handler_names_for(job_class, :temporal_query_handler_names),
+          updates: handler_names_for(job_class, :temporal_update_handler_names)
+        }
+        return if handlers.values.all?(&:empty?)
+
+        { job_class: job_class.name, **handlers }
+      end
+
+      def handler_names_for(job_class, method_name)
+        return [] unless job_class.respond_to?(method_name)
+
+        job_class.public_send(method_name).map(&:to_s).sort
+      end
+    end
+  end
+end

data/lib/activejob/temporal/job_tags.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module ActiveJob
+  module Temporal
+    # Captures Temporal search tags passed through ActiveJob's set options.
+    module JobTags
+      attr_reader :temporal_tags
+
+      def self.normalize(tags)
+        return [] if tags.nil?
+
+        raise ArgumentError, "tags must be an Array of Strings or Symbols" unless tags.is_a?(Array)
+
+        tags.map do |tag|
+          normalize_tag(tag)
+        end.uniq
+      end
+
+      def self.normalize_tag(tag)
+        return tag if tag.is_a?(String)
+        return tag.to_s if tag.is_a?(Symbol)
+
+        raise ArgumentError, "tags must contain only Strings or Symbols"
+      end
+
+      def set(options = {})
+        enqueue_options = options.dup
+        normalized_tags = JobTags.normalize(enqueue_options.delete(:tags)) if enqueue_options.key?(:tags)
+
+        super(enqueue_options).tap do
+          @temporal_tags = normalized_tags if options.key?(:tags)
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Base.prepend(ActiveJob::Temporal::JobTags) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/locales/en.yml

@@ -0,0 +1,126 @@
+en:
+  activemodel:
+    errors:
+      models:
+        active_job/temporal/config_validator:
+          attributes:
+            target:
+              target_required: "Target host is required (set ACTIVEJOB_TEMPORAL_TARGET or config.target)"
+              invalid_format: "must be in format 'host:port' with DNS-style host labels and TCP port 1-65535 (e.g., 'localhost:7233' or 'temporal.example.com:7233'), got: %{target}"
+
+            namespace:
+              namespace_required: "Namespace is required (set ACTIVEJOB_TEMPORAL_NAMESPACE or config.namespace)"
+              invalid_format: "must be 1-1000 characters, start and end with an alphanumeric character, and contain only alphanumeric characters, hyphens, and underscores (got: %{namespace})"
+
+            default_activity_timeout:
+              not_a_duration: "must be a duration (e.g., 10.minutes or 30.seconds), got: %{value}"
+              duration_not_positive: "must be positive (got: %{seconds} seconds). Use values like 1.second or 10.minutes"
+
+            default_retry_initial_interval:
+              not_a_duration: "must be a duration (e.g., 10.minutes or 30.seconds), got: %{value}"
+              duration_not_positive: "must be positive (got: %{seconds} seconds). Use values like 1.second or 10.minutes"
+
+            default_retry_backoff:
+              retry_backoff_too_small: "must be >= 1.0 (got: %{value}). Use 2.0 for exponential backoff"
+
+            default_retry_max_attempts:
+              retry_max_attempts_negative: "must be >= 0 (got: %{value}). Use 0 for unlimited retries, or positive number for max attempts"
+
+            max_payload_size_kb:
+              payload_size_invalid: "must be between 1 and 2,097,152 KB (got: %{value}). Typical values: 250 KB (default), 500 KB (large), or 1000 KB (very large)"
+
+            payload_serializer:
+              unsupported_serializer: "is not supported. Use one of: json, message_pack, msgpack, marshal"
+
+            payload_storage_adapter:
+              invalid: "must respond to #dump and #load, got: %{value}"
+
+            payload_storage_threshold_kb:
+              required: "is required when payload_storage_adapter is configured"
+              requires_adapter: "requires payload_storage_adapter"
+              invalid: "must be a positive integer, got: %{value}"
+
+            max_concurrent_activities:
+              concurrent_activities_invalid: "must be positive (got: %{value}). Typical values: 50 (low), 100 (default), 200+ (high throughput)"
+
+            max_concurrent_workflow_tasks:
+              concurrent_workflow_tasks_invalid: "must be positive (got: %{value}). Typical values: 5 (default), 10-50 (medium), 100+ (high throughput)"
+
+            validation_level:
+              invalid_level: "must be one of: strict, warn, none (got: %{value})"
+
+            observability:
+              invalid: "must be an observability configuration, got: %{value}"
+
+            audit_log:
+              not_boolean: "must be true or false, got: %{value}"
+
+            audit_logger:
+              invalid: "must respond to #info, got: %{value}"
+
+            encrypt_payload:
+              not_boolean: "must be true or false, got: %{value}"
+
+            encryption_key:
+              required: "is required when payload encryption is enabled"
+              invalid: "must be a Base64-encoded %{bytes}-byte AES-256-GCM key or key metadata with a safe id"
+
+            encryption_old_keys:
+              not_an_array: "must be an array of Base64-encoded keys or key metadata, got: %{value}"
+              invalid: "must contain only Base64-encoded %{bytes}-byte AES-256-GCM keys or key metadata with safe ids"
+
+            workflow_id_generator:
+              not_callable: "must respond to #call (for example, ->(job) { \"custom-#{job.job_id}\" }), got: %{value}"
+              wrong_arity: "must accept one positional ActiveJob argument (for example, ->(job) { \"custom-#{job.job_id}\" }), got: %{value}"
+
+            middleware_chain:
+              invalid: "must respond to #add and #call, got: %{value}"
+
+            priority_task_queues:
+              not_a_hash: "must be a hash mapping ActiveJob priority values to task queue names, got: %{value}"
+              non_integer_priority: "priority keys must be integers because ActiveJob priorities are numeric, got: %{value}"
+              blank_queue: "task queue names must be present, got: %{value}"
+
+            rate_limiter:
+              invalid: "must respond to #wait_time_for or #call, got: %{value}"
+              wrong_arity: "must accept one rate_limits argument, got: %{value}"
+
+            global_rate_limit:
+              requires_rate_limiter: "requires rate_limiter"
+              invalid: "must be a hash like { limit: 100, per: :second }, got: %{value}"
+
+            dead_letter_queue:
+              blank: "must be present when configured"
+
+            dead_letter_after_attempts:
+              requires_queue: "requires dead_letter_queue"
+              invalid: "must be greater than 0, got: %{value}"
+
+            dead_letter_auto_discard_after:
+              requires_queue: "requires dead_letter_queue"
+              not_a_duration: "must be a duration (e.g., 1.day or 6.hours), got: %{value}"
+              duration_not_positive: "must be positive (got: %{seconds} seconds). Use values like 1.hour or 7.days"
+
+            tls_cert_path:
+              requires_key_path: "requires tls_key_path so the client certificate and private key rotate together"
+              invalid_path: "must be a non-empty file path, got: %{value}"
+              unreadable_path: "must point to a readable, non-symlink file, got: %{value}"
+
+            tls_key_path:
+              invalid_path: "must be a non-empty file path, got: %{value}"
+              unreadable_path: "must point to a readable, non-symlink file, got: %{value}"
+
+            tls_server_root_ca_cert_path:
+              invalid_path: "must be a non-empty file path, got: %{value}"
+              unreadable_path: "must point to a readable, non-symlink file, got: %{value}"
+
+            tls_domain:
+              blank: "must be present when configured"
+
+            tls_cert_watch:
+              not_boolean: "must be true or false, got: %{value}"
+              requires_paths: "requires at least one TLS certificate path to watch"
+
+            tls_reload_signal:
+              blank: "must be present when configured"
+              invalid: "must be a signal name like HUP or USR1, got: %{value}"