activejob-temporal 0.1.0

data/lib/activejob/temporal/schedulable.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module ActiveJob
+  module Temporal
+    module Schedulable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def schedule(options = nil, **kwargs)
+          schedule_options = normalize_schedule_options(options, kwargs)
+          @temporal_schedule = ActiveJob::Temporal::Schedule.new(self, schedule_options)
+        end
+
+        def temporal_schedule
+          @temporal_schedule
+        end
+
+        def create_temporal_schedule(options = nil, **kwargs)
+          if options || kwargs.any?
+            schedule_options = merged_schedule_options(normalize_schedule_options(options, kwargs))
+            return ActiveJob::Temporal::Schedule.new(self, schedule_options).create
+          end
+
+          raise ArgumentError, "No schedule defined for #{name}" unless temporal_schedule
+
+          temporal_schedule.create
+        end
+
+        def temporal_schedule_handle(id: nil, client: ActiveJob::Temporal.client)
+          client.schedule_handle(id || temporal_schedule&.id || "ajsch:#{name}")
+        end
+
+        private
+
+        def normalize_schedule_options(options, kwargs)
+          case options
+          when nil
+            kwargs
+          when Hash
+            options.merge(kwargs)
+          else
+            raise ArgumentError, "schedule options must be a Hash"
+          end
+        end
+
+        def merged_schedule_options(overrides)
+          return overrides unless temporal_schedule
+
+          temporal_schedule.options.merge(overrides)
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Base.include(ActiveJob::Temporal::Schedulable) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/schedule.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "temporalio/client/schedule"
+
+require_relative "adapter"
+require_relative "audit_log"
+require_relative "job_payload_builder"
+require_relative "logger"
+require_relative "schedule_options"
+require_relative "search_attributes"
+require_relative "workflows/aj_workflow"
+
+module ActiveJob
+  module Temporal
+    class Schedule
+      attr_reader :job_class
+
+      def initialize(job_class, options = {})
+        options = options.transform_keys(&:to_sym)
+        client = options.delete(:client)
+        config = options.delete(:config) || ActiveJob::Temporal.config
+        payload_builder = options.delete(:payload_builder)
+
+        @job_class = job_class
+        @options = ScheduleOptions.new(job_class, options)
+        @client = client
+        @config = config
+        @payload_builder = payload_builder || JobPayloadBuilder.new(config)
+      end
+
+      def id = @options.id
+
+      def cron_expressions = @options.cron_expressions
+
+      def timezone = @options.timezone
+
+      def overlap_policy = @options.overlap_policy
+
+      def args = @options.args
+
+      def queue = @options.queue
+
+      def paused = @options.paused
+
+      def trigger_immediately = @options.trigger_immediately
+
+      def cron
+        @options.cron
+      end
+
+      def create
+        temporal_schedule = to_temporal_schedule
+        handle = client.create_schedule(
+          id,
+          temporal_schedule,
+          trigger_immediately: trigger_immediately,
+          memo: nil,
+          search_attributes: nil
+        )
+        log_created(task_queue: temporal_schedule.action.task_queue, duplicate: false)
+        handle
+      rescue StandardError => e
+        raise unless schedule_already_running?(e)
+
+        handle_existing_schedule
+      end
+
+      def handle
+        client.schedule_handle(id)
+      end
+
+      def options
+        @options.to_h
+      end
+
+      def to_temporal_schedule
+        Temporalio::Client::Schedule.new(
+          action: schedule_action,
+          spec: schedule_spec,
+          policy: schedule_policy,
+          state: schedule_state
+        )
+      end
+
+      private
+
+      def client
+        @client || ActiveJob::Temporal.client
+      end
+
+      def schedule_action
+        job = build_job
+        workflow_id = workflow_id_prefix
+        payload = @payload_builder.build(job, encryption_context: encryption_context_for(workflow_id))
+        payload = annotate_scheduled_payload(payload, workflow_id)
+
+        Temporalio::Client::Schedule::Action::StartWorkflow.new(
+          Workflows::AjWorkflow,
+          payload,
+          id: workflow_id,
+          task_queue: Adapter.resolve_task_queue(job, config: @config),
+          search_attributes: search_attributes_for(job)
+        )
+      end
+
+      def schedule_spec
+        Temporalio::Client::Schedule::Spec.new(
+          cron_expressions: cron_expressions,
+          time_zone_name: timezone
+        )
+      end
+
+      def schedule_policy
+        Temporalio::Client::Schedule::Policy.new(overlap: @options.temporal_overlap_policy)
+      end
+
+      def schedule_state
+        Temporalio::Client::Schedule::State.new(
+          paused: paused,
+          note: "ActiveJob Temporal schedule for #{job_class.name}"
+        )
+      end
+
+      def build_job
+        job = job_class.new(*args)
+        job.job_id = id if job.respond_to?(:job_id=)
+        job.queue_name = queue if queue && job.respond_to?(:queue_name=)
+        job
+      end
+
+      def search_attributes_for(job)
+        return unless @config.respond_to?(:enable_search_attributes) && @config.enable_search_attributes
+
+        SearchAttributes.for(job)
+      end
+
+      def workflow_id_prefix
+        "ajschwf:#{id}"
+      end
+
+      def encryption_context_for(workflow_id)
+        { namespace: @config.namespace, workflow_id: workflow_id }
+      end
+
+      def annotate_scheduled_payload(payload, workflow_id)
+        payload.merge(
+          schedule_id: id,
+          schedule_workflow_id_prefix: workflow_id,
+          payload_encryption_context: encryption_context_for(workflow_id)
+        )
+      end
+
+      def schedule_already_running?(error)
+        defined?(Temporalio::Error::ScheduleAlreadyRunningError) &&
+          error.is_a?(Temporalio::Error::ScheduleAlreadyRunningError)
+      end
+
+      def handle_existing_schedule
+        existing_handle = handle
+        log_created(task_queue: Adapter.resolve_task_queue(build_job, config: @config), duplicate: true)
+        existing_handle
+      end
+
+      def log_created(task_queue:, duplicate:)
+        attributes = {
+          schedule_id: id,
+          job_class: job_class.name,
+          cron: cron,
+          timezone: timezone,
+          overlap_policy: overlap_policy,
+          task_queue: task_queue,
+          duplicate: duplicate
+        }
+
+        Logger.log_event("schedule_created", attributes)
+        AuditLog.record("schedule.created", attributes)
+      end
+    end
+  end
+end

data/lib/activejob/temporal/schedule_options.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "temporalio/client/schedule"
+
+module ActiveJob
+  module Temporal
+    class ScheduleOptions
+      OVERLAP_POLICIES = {
+        skip: Temporalio::Client::Schedule::OverlapPolicy::SKIP,
+        buffer: Temporalio::Client::Schedule::OverlapPolicy::BUFFER_ONE,
+        buffer_one: Temporalio::Client::Schedule::OverlapPolicy::BUFFER_ONE,
+        buffer_all: Temporalio::Client::Schedule::OverlapPolicy::BUFFER_ALL,
+        allow_all: Temporalio::Client::Schedule::OverlapPolicy::ALLOW_ALL,
+        cancel_other: Temporalio::Client::Schedule::OverlapPolicy::CANCEL_OTHER,
+        terminate_other: Temporalio::Client::Schedule::OverlapPolicy::TERMINATE_OTHER
+      }.freeze
+
+      attr_reader :job_class, :id, :cron_expressions, :timezone, :overlap_policy, :args, :queue,
+                  :paused, :trigger_immediately
+
+      def initialize(job_class, options)
+        options = options.transform_keys(&:to_sym)
+
+        @job_class = job_class
+        @id = normalize_id(options.fetch(:id, default_id))
+        @cron_expressions = normalize_cron(options.fetch(:cron))
+        @timezone = normalize_timezone(options.fetch(:timezone, "UTC"))
+        @overlap_policy = normalize_overlap_policy(options.fetch(:overlap_policy, :skip))
+        @args = normalize_args(options.fetch(:args, []))
+        @queue = options[:queue]&.to_s
+        @paused = options.fetch(:paused, false)
+        @trigger_immediately = options.fetch(:trigger_immediately, false)
+      end
+
+      def cron
+        return cron_expressions.first if cron_expressions.one?
+
+        cron_expressions
+      end
+
+      def temporal_overlap_policy
+        OVERLAP_POLICIES.fetch(overlap_policy)
+      end
+
+      def to_h
+        {
+          id: id,
+          cron: cron,
+          timezone: timezone,
+          overlap_policy: overlap_policy,
+          args: args,
+          queue: queue,
+          paused: paused,
+          trigger_immediately: trigger_immediately
+        }
+      end
+
+      private
+
+      def default_id
+        "ajsch:#{job_class.name}"
+      end
+
+      def normalize_id(value)
+        value = value.to_s.strip
+        raise ArgumentError, "schedule id must be present" if value.empty?
+
+        value
+      end
+
+      def normalize_cron(value)
+        expressions = value.is_a?(Array) ? value : [value]
+        expressions.map do |expression|
+          expression = expression.to_s.strip
+          raise ArgumentError, "cron must be present" if expression.empty?
+
+          expression
+        end
+      end
+
+      def normalize_timezone(value)
+        value = value.to_s.strip
+        raise ArgumentError, "timezone must be present" if value.empty?
+
+        value
+      end
+
+      def normalize_overlap_policy(value)
+        policy = value.to_sym
+        return policy if OVERLAP_POLICIES.key?(policy)
+
+        raise ArgumentError,
+              "Unsupported overlap_policy #{value.inspect}. " \
+              "Supported policies are: #{OVERLAP_POLICIES.keys.join(', ')}"
+      end
+
+      def normalize_args(value)
+        return [] if value.nil?
+        return value if value.is_a?(Array)
+
+        raise ArgumentError, "args must be an Array"
+      end
+    end
+  end
+end

data/lib/activejob/temporal/search_attributes.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    # Builds Temporal search attributes for job metadata.
+    #
+    # This module constructs typed search attributes that enable filtering and searching
+    # workflows in the Temporal UI and via the Temporal API. Attributes include job class,
+    # queue name, job ID, enqueued timestamp, and optionally tenant ID.
+    #
+    # @note Pre-Registration Required
+    #   Search attributes MUST be pre-registered in the Temporal cluster with the correct
+    #   type (KEYWORD, TIME, INTEGER, etc.) before use. Unregistered attributes will cause
+    #   workflow start failures. Use the Temporal CLI to register attributes:
+    #
+    #     tctl admin cluster add-search-attributes --name ajClass --type Keyword
+    #     tctl admin cluster add-search-attributes --name ajQueue --type Keyword
+    #     tctl admin cluster add-search-attributes --name ajJobId --type Keyword
+    #     tctl admin cluster add-search-attributes --name ajEnqueuedAt --type Datetime
+    #     tctl admin cluster add-search-attributes --name ajTenantId --type Int
+    #     tctl admin cluster add-search-attributes --name ajTags --type KeywordList
+    #
+    # @note Tenant ID Extraction
+    #   The module automatically extracts tenant_id from the first job argument if it
+    #   responds to the `tenant_id` method. This supports multi-tenant architectures
+    #   where jobs operate on tenant-specific data.
+    #
+    # @example Created attributes
+    #   - ajClass: KEYWORD (job class name)
+    #   - ajQueue: KEYWORD (queue name)
+    #   - ajJobId: KEYWORD (unique job ID)
+    #   - ajEnqueuedAt: TIME (enqueue timestamp)
+    #   - ajTenantId: INTEGER (optional, if first argument responds to :tenant_id)
+    #   - ajTags: KEYWORD_LIST (optional, if tags are configured)
+    #
+    # @example Querying with search attributes (Temporal CLI)
+    #   # Find all jobs in the "mailers" queue
+    #   tctl workflow list --query "ajQueue='mailers'"
+    #
+    #   # Find specific job by ID
+    #   tctl workflow list --query "ajJobId='abc-123'"
+    #
+    #   # Find all tenant jobs enqueued today
+    #   tctl workflow list --query "ajTenantId=42 AND ajEnqueuedAt > '2025-10-31T00:00:00Z'"
+    #
+    #   # Find jobs tagged as urgent
+    #   tctl workflow list --query "ajTags='urgent'"
+    #
+    # @see https://docs.temporal.io/visibility Search Attributes documentation
+    module SearchAttributes
+      extend self
+
+      SEARCH_ATTRIBUTE_KEY_DEFINITIONS = {
+        aj_class: ["ajClass", :KEYWORD],
+        aj_queue: ["ajQueue", :KEYWORD],
+        aj_job_id: ["ajJobId", :KEYWORD],
+        aj_enqueued_at: ["ajEnqueuedAt", :TIME],
+        aj_tenant_id: ["ajTenantId", :INTEGER],
+        aj_tags: ["ajTags", :KEYWORD_LIST]
+      }.freeze
+
+      # Builds a Temporalio::SearchAttributes object for a job.
+      #
+      # Creates typed search attribute keys and populates them with job metadata.
+      # If `enable_search_attributes` is disabled in configuration, this should
+      # still be called but may return an empty attributes object (handled by caller).
+      #
+      # @param job [ActiveJob::Base] The job instance to extract metadata from
+      #
+      # @return [Temporalio::SearchAttributes] Typed search attributes for Temporal
+      #
+      # @raise [Temporalio::Error::WorkflowUpdateFailedError] if attributes are not pre-registered in Temporal
+      # @raise [ArgumentError] if job is nil
+      # @raise [TypeError] if job does not respond to required methods
+      # @raise [NameError] if Temporalio::SearchAttributes is not defined
+      #
+      # @example Basic usage
+      #   job = MyJob.new
+      #   attributes = SearchAttributes.for(job)
+      #   # attributes contains ajClass, ajQueue, ajJobId, ajEnqueuedAt
+      #
+      # @example With tenant ID (automatic extraction)
+      #   class TenantJob < ApplicationJob
+      #     def perform(tenant)
+      #       # tenant.tenant_id is extracted automatically
+      #     end
+      #   end
+      #   tenant = Tenant.find(42)
+      #   job = TenantJob.new(tenant)
+      #   attributes = SearchAttributes.for(job)
+      #   # attributes also contains ajTenantId: 42
+      #
+      # @example Without tenant ID
+      #   job = MyJob.new("plain_string_arg")
+      #   attributes = SearchAttributes.for(job)
+      #   # attributes does NOT contain ajTenantId (first arg doesn't respond to tenant_id)
+      def for(job)
+        # Create Temporal search attributes with typed keys
+        attributes = Temporalio::SearchAttributes.new
+
+        # Define and set core attributes
+        set_core_attributes(attributes, job)
+
+        # Add tenant ID if available
+        add_tenant_attribute(attributes, job)
+
+        # Add job tags if available
+        add_tags_attribute(attributes, job)
+
+        attributes
+      end
+
+      private
+
+      # Sets core search attributes (ajClass, ajQueue, ajJobId, ajEnqueuedAt).
+      # @api private
+      def set_core_attributes(attributes, job)
+        attributes[search_attribute_key(:aj_class)] = job.class.name
+        attributes[search_attribute_key(:aj_queue)] = job.queue_name || "default"
+        attributes[search_attribute_key(:aj_job_id)] = job.job_id
+        attributes[search_attribute_key(:aj_enqueued_at)] = Time.now
+      end
+
+      # Adds tenant ID attribute if first argument responds to tenant_id.
+      # @api private
+      def add_tenant_attribute(attributes, job)
+        tenant_id = extract_tenant_id(job.arguments)
+        return unless tenant_id
+
+        attributes[search_attribute_key(:aj_tenant_id)] = tenant_id
+      end
+
+      def add_tags_attribute(attributes, job)
+        tags = extract_tags(job)
+        return if tags.empty?
+
+        attributes[search_attribute_key(:aj_tags)] = tags
+      end
+
+      def search_attribute_key(key)
+        search_attribute_keys.fetch(key)
+      end
+
+      def search_attribute_keys
+        @search_attribute_keys ||= SEARCH_ATTRIBUTE_KEY_DEFINITIONS.each_with_object({}) do |(key, (name, type)), keys|
+          keys[key] = create_key(name, type).freeze
+        end.freeze
+      end
+
+      # Creates a typed Temporal search attribute key.
+      # @api private
+      def create_key(name, type)
+        type_constant = Temporalio::SearchAttributes::IndexedValueType.const_get(type)
+        Temporalio::SearchAttributes::Key.new(name, type_constant)
+      end
+
+      # Extracts tenant_id from first argument if it responds to tenant_id method.
+      # @api private
+      def extract_tenant_id(arguments)
+        first_argument = arguments&.first
+        return unless first_argument.respond_to?(:tenant_id)
+
+        first_argument.tenant_id
+      end
+
+      def extract_tags(job)
+        return [] unless job.respond_to?(:temporal_tags)
+
+        job.temporal_tags || []
+      end
+    end
+  end
+end

data/lib/activejob/temporal/signal_query.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "temporalio/error"
+require_relative "visibility_query"
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    module SignalQuery
+      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/
+      HANDLER_NAME_PATTERN = /\A[a-zA-Z_]\w*\z/
+      DEFAULT_REJECT_CONDITION = Object.new.freeze
+
+      class << self
+        def signal(job_class, job_id, signal_name, *)
+          validate_job_class!(job_class)
+          validate_job_id!(job_id)
+          handler_name = normalize_handler_name!(signal_name, "signal")
+
+          with_running_workflow_handle(job_class, job_id) do |handle|
+            handle.signal(handler_name, *)
+          end
+        rescue ArgumentError, ActiveJob::Temporal::WorkflowNotFoundError
+          raise
+        rescue Temporalio::Error::RPCError => e
+          raise ActiveJob::Temporal::TemporalConnectionError,
+                "Failed to signal Temporal workflow for job_id #{job_id}: #{e.message}"
+        end
+
+        def query(job_class, job_id, query_name, *args, reject_condition: DEFAULT_REJECT_CONDITION)
+          validate_job_class!(job_class)
+          validate_job_id!(job_id)
+          handler_name = normalize_handler_name!(query_name, "query")
+
+          with_running_workflow_handle(job_class, job_id) do |handle|
+            query_workflow(handle, handler_name, args, reject_condition)
+          end
+        rescue ArgumentError, ActiveJob::Temporal::WorkflowNotFoundError
+          raise
+        rescue Temporalio::Error::RPCError => e
+          raise ActiveJob::Temporal::TemporalConnectionError,
+                "Failed to query Temporal workflow for job_id #{job_id}: #{e.message}"
+        end
+
+        def update(job_class, job_id, update_name, *)
+          validate_job_class!(job_class)
+          validate_job_id!(job_id)
+          handler_name = normalize_handler_name!(update_name, "update")
+
+          with_running_workflow_handle(job_class, job_id) do |handle|
+            handle.execute_update(handler_name, *)
+          end
+        rescue ArgumentError, ActiveJob::Temporal::WorkflowNotFoundError
+          raise
+        rescue Temporalio::Error::RPCError => e
+          raise ActiveJob::Temporal::TemporalConnectionError,
+                "Failed to update Temporal workflow for job_id #{job_id}: #{e.message}"
+        end
+
+        private
+
+        def with_running_workflow_handle(job_class, job_id)
+          client = ActiveJob::Temporal.client
+          default_handle = client.workflow_handle(default_workflow_id(job_class, job_id), run_id: nil)
+
+          begin
+            return yield(default_handle)
+          rescue Temporalio::Error::RPCError => e
+            raise unless rpc_not_found?(e)
+          end
+
+          workflow_reference = find_running_workflow_reference(client, job_class, job_id)
+          raise workflow_not_found(job_id) unless workflow_reference
+
+          fallback_handle = client.workflow_handle(
+            workflow_reference.fetch(:workflow_id),
+            run_id: workflow_reference[:run_id]
+          )
+          begin
+            yield(fallback_handle)
+          rescue Temporalio::Error::RPCError => e
+            raise workflow_not_found(job_id) if rpc_not_found?(e)
+
+            raise
+          end
+        end
+
+        def query_workflow(handle, handler_name, args, reject_condition)
+          if reject_condition.equal?(DEFAULT_REJECT_CONDITION)
+            handle.query(handler_name, *args)
+          else
+            handle.query(handler_name, *args, reject_condition: reject_condition)
+          end
+        end
+
+        def find_running_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
+          }
+        rescue StandardError => e
+          return nil if rpc_invalid_argument?(e)
+
+          raise
+        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 normalize_handler_name!(name, handler_type)
+          handler_name = name.to_s
+          return handler_name if handler_name.match?(HANDLER_NAME_PATTERN)
+
+          raise ArgumentError, "#{handler_type} names must start with a letter or underscore and contain word chars"
+        end
+
+        def workflow_search_query(job_class, job_id)
+          "ajClass=#{VisibilityQuery.quote(job_class.name)} AND ajJobId=#{VisibilityQuery.quote(job_id)} " \
+            "AND ExecutionStatus='Running'"
+        end
+
+        def default_workflow_id(job_class, job_id)
+          WorkflowIdBuilder.new.build_from_job_class(job_class, job_id)
+        end
+
+        def workflow_not_found(job_id)
+          ActiveJob::Temporal::WorkflowNotFoundError.new(
+            "No running workflow found for job_id #{job_id}. The job may have completed or never existed."
+          )
+        end
+
+        def rpc_not_found?(error)
+          error.code == Temporalio::Error::RPCError::Code::NOT_FOUND
+        end
+
+        def rpc_invalid_argument?(error)
+          error.code == Temporalio::Error::RPCError::Code::INVALID_ARGUMENT
+        end
+      end
+    end
+  end
+end