job-workflow 0.1.3

data/lib/job_workflow/semaphore.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class Semaphore
+    DEFAULT_POLLING_INTERVAL = 3.0 #: Float
+    private_constant :DEFAULT_POLLING_INTERVAL
+
+    attr_reader :concurrency_key #: String
+    attr_reader :concurrency_limit #: Integer
+    attr_reader :concurrency_duration #: ActiveSupport::Duration
+
+    class << self
+      #:  () -> bool
+      def available?
+        QueueAdapter.current.semaphore_available?
+      end
+    end
+
+    #:  (
+    #     concurrency_key: String,
+    #     concurrency_duration: ActiveSupport::Duration,
+    #     ?concurrency_limit: Integer,
+    #     ?polling_interval: Float
+    #   ) -> void
+    def initialize(
+      concurrency_key:,
+      concurrency_duration:,
+      concurrency_limit: 1,
+      polling_interval: DEFAULT_POLLING_INTERVAL
+    )
+      @concurrency_key = concurrency_key
+      @concurrency_duration = concurrency_duration
+      @concurrency_limit = concurrency_limit
+      @polling_interval = polling_interval
+    end
+
+    #:  () -> bool
+    def wait
+      return true unless self.class.available?
+
+      Instrumentation.instrument_throttle(self) do
+        loop do
+          return true if QueueAdapter.current.semaphore_wait(self)
+
+          sleep(polling_interval)
+        end
+      end
+    end
+
+    #:  () -> bool
+    def signal
+      return true unless self.class.available?
+
+      result = QueueAdapter.current.semaphore_signal(self)
+      Instrumentation.notify_throttle_release(self)
+      result
+    end
+
+    #: [T] () { () -> T } -> T
+    def with(&)
+      wait
+      yield
+    ensure
+      signal
+    end
+
+    private
+
+    attr_reader :polling_interval #: Float
+  end
+end

data/lib/job_workflow/task.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class Task
+    attr_reader :job_name #: String
+    attr_reader :namespace #: Namespace
+    attr_reader :block #: ^(untyped) -> void
+    attr_reader :each #: ^(Context) -> untyped
+    attr_reader :enqueue #: TaskEnqueue
+    attr_reader :output #: Array[OutputDef]
+    attr_reader :depends_on #: Array[Symbol]
+    attr_reader :condition #: ^(Context) -> bool
+    attr_reader :task_retry #: TaskRetry
+    attr_reader :throttle #: TaskThrottle
+    attr_reader :timeout #: Numeric?
+    attr_reader :dependency_wait #: TaskDependencyWait
+    attr_reader :dry_run_config #: DryRunConfig
+
+    # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength, Metrics/AbcSize
+    #:  (
+    #     job_name: String,
+    #     name: Symbol,
+    #     namespace: Namespace,
+    #     block: ^(untyped) -> void,
+    #     ?each: ^(Context) -> untyped,
+    #     ?enqueue: true | false | ^(Context) -> bool | Hash[Symbol, untyped],
+    #     ?output: Hash[Symbol, String],
+    #     ?depends_on: Array[Symbol],
+    #     condition: ^(Context) -> bool,
+    #     ?task_retry: Integer | Hash[Symbol, untyped],
+    #     ?throttle: Integer | Hash[Symbol, untyped],
+    #     ?timeout: Numeric?,
+    #     ?dependency_wait: Hash[Symbol, untyped],
+    #     ?dry_run: bool | ^(Context) -> bool
+    #   ) -> void
+    def initialize(
+      job_name:,
+      name:,
+      namespace:,
+      block:,
+      each: nil,
+      enqueue: nil,
+      output: {},
+      depends_on: [],
+      condition: ->(_ctx) { true },
+      task_retry: 0,
+      throttle: {},
+      timeout: nil,
+      dependency_wait: {},
+      dry_run: false
+    )
+      @job_name = job_name
+      @name = name
+      @namespace = namespace #: Namespace
+      @block = block
+      @each = each
+      @enqueue = TaskEnqueue.from_primitive_value(enqueue)
+      @output = output.map { |name, type| OutputDef.new(name:, type:) }
+      @depends_on = depends_on
+      @condition = condition
+      @task_retry = TaskRetry.from_primitive_value(task_retry)
+      @throttle = TaskThrottle.from_primitive_value_with_task(value: throttle, task: self)
+      @timeout = timeout
+      @dependency_wait = TaskDependencyWait.from_primitive_value(dependency_wait)
+      @dry_run_config = DryRunConfig.from_primitive_value(dry_run)
+    end
+    # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength, Metrics/AbcSize
+
+    #:  () -> Symbol
+    def task_name
+      [namespace.full_name.to_s, name.to_s].reject(&:empty?).join(":").to_sym
+    end
+
+    #:  () -> String
+    def throttle_prefix_key
+      "#{job_name}:#{task_name}"
+    end
+
+    private
+
+    attr_reader :name #: Symbol
+  end
+end

data/lib/job_workflow/task_callable.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskCallable
+    class NotCalledError < StandardError
+      #:  (Symbol) -> void
+      def initialize(task_name)
+        super("around hook for '#{task_name}' did not call task.call")
+      end
+    end
+
+    class AlreadyCalledError < StandardError
+      #:  () -> void
+      def initialize
+        super("task.call has already been called")
+      end
+    end
+
+    #:  () { () -> void } -> void
+    def initialize(&block)
+      @block = block #: () -> void
+      @called = false #: bool
+    end
+
+    #:  () -> void
+    def call
+      raise AlreadyCalledError if called
+
+      self.called = true
+      block.call
+    end
+
+    #:  () -> bool
+    def called?
+      called
+    end
+
+    private
+
+    attr_reader :block #: () -> void
+    attr_accessor :called #: bool
+  end
+end

data/lib/job_workflow/task_context.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskContext
+    NULL_VALUE = nil #: nil
+    public_constant :NULL_VALUE
+
+    attr_reader :task #: Task?
+    attr_reader :parent_job_id #: String?
+    attr_reader :index #: Integer
+    attr_reader :value #: untyped
+    attr_reader :retry_count #: Integer
+    attr_reader :dry_run #: bool
+
+    class << self
+      #:  (Hash[String, untyped]) -> TaskContext
+      def deserialize(hash)
+        new(
+          task: hash["task"],
+          parent_job_id: hash["parent_job_id"],
+          index: hash["index"],
+          value: ActiveJob::Arguments.deserialize([hash["value"]]).first,
+          retry_count: hash.fetch("retry_count", 0)
+        )
+      end
+    end
+
+    #:  (
+    #     ?task: Task?,
+    #     ?parent_job_id: String?,
+    #     ?index: Integer,
+    #     ?value: untyped,
+    #     ?retry_count: Integer,
+    #     ?dry_run: bool
+    #   ) -> void
+    def initialize(task: nil, parent_job_id: nil, index: 0, value: nil, retry_count: 0, dry_run: false) # rubocop:disable Metrics/ParameterLists
+      self.task = task
+      self.parent_job_id = parent_job_id
+      self.index = index
+      self.value = value
+      self.retry_count = retry_count
+      self.dry_run = dry_run
+    end
+
+    #:  () -> bool
+    def enabled?
+      !parent_job_id.nil?
+    end
+
+    #:  () -> Hash[String, untyped]
+    def serialize
+      {
+        "task_name" => task&.task_name,
+        "parent_job_id" => parent_job_id,
+        "index" => index,
+        "value" => ActiveJob::Arguments.serialize([value]).first,
+        "retry_count" => retry_count
+      }
+    end
+
+    private
+
+    attr_writer :task #: Task?
+    attr_writer :parent_job_id #: String?
+    attr_writer :index #: Integer
+    attr_writer :value #: untyped
+    attr_writer :retry_count #: Integer
+    attr_writer :dry_run #: bool
+  end
+end

data/lib/job_workflow/task_dependency_wait.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  # TaskDependencyWait holds configuration for waiting on dependent tasks.
+  #
+  # When a task has dependencies (depends_on:), the runner waits for those tasks to complete.
+  # This class configures how long to poll before rescheduling the job.
+  #
+  # @example Default behavior (polling only, no reschedule)
+  #   task :process, depends_on: [:fetch]
+  #
+  # @example Wait up to 30 seconds with polling, then reschedule
+  #   task :process, depends_on: [:fetch], dependency_wait: { poll_timeout: 30 }
+  #
+  # @example Wait 60 seconds total, poll every 10 seconds, reschedule after 5 seconds
+  #   task :process, depends_on: [:fetch], dependency_wait: { poll_timeout: 60, poll_interval: 10, reschedule_delay: 5 }
+  class TaskDependencyWait
+    DEFAULT_POLL_TIMEOUT = 0 #: Integer
+    DEFAULT_POLL_INTERVAL = 5 #: Integer
+    DEFAULT_RESCHEDULE_DELAY = 5 #: Integer
+
+    attr_reader :poll_timeout #: Integer
+    attr_reader :poll_interval #: Integer
+    attr_reader :reschedule_delay #: Integer
+
+    class << self
+      #:  (Integer | Hash[Symbol, untyped] | nil) -> TaskDependencyWait
+      def from_primitive_value(value)
+        case value
+        when Integer
+          new(poll_timeout: value)
+        when Hash
+          new(
+            poll_timeout: value[:poll_timeout] || DEFAULT_POLL_TIMEOUT,
+            poll_interval: value[:poll_interval] || DEFAULT_POLL_INTERVAL,
+            reschedule_delay: value[:reschedule_delay] || DEFAULT_RESCHEDULE_DELAY
+          )
+        else
+          new
+        end
+      end
+    end
+
+    #:  (?poll_timeout: Integer, ?poll_interval: Integer, ?reschedule_delay: Integer) -> void
+    def initialize(
+      poll_timeout: DEFAULT_POLL_TIMEOUT,
+      poll_interval: DEFAULT_POLL_INTERVAL,
+      reschedule_delay: DEFAULT_RESCHEDULE_DELAY
+    )
+      @poll_timeout = poll_timeout #: Integer
+      @poll_interval = poll_interval #: Integer
+      @reschedule_delay = reschedule_delay #: Integer
+    end
+
+    #:  () -> bool
+    def polling_only?
+      poll_timeout <= 0
+    end
+
+    #:  (Time) -> bool
+    def polling_keep?(started_at)
+      elapsed = Time.current - started_at
+      elapsed < poll_timeout
+    end
+  end
+end

data/lib/job_workflow/task_enqueue.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskEnqueue
+    attr_reader :condition #: true | false | ^(Context) -> bool
+    attr_reader :queue #: String?
+    attr_reader :concurrency #: Integer?
+
+    class << self
+      #:  (true | false | ^(Context) -> bool | Hash[Symbol, untyped] | nil) -> TaskEnqueue
+      def from_primitive_value(value)
+        case value
+        when TrueClass, FalseClass, Proc
+          new(condition: value)
+        when Hash
+          new(
+            condition: value.fetch(:condition, !value.empty?),
+            queue: value[:queue],
+            concurrency: value[:concurrency]
+          )
+        else
+          new
+        end
+      end
+    end
+
+    #:  (
+    #     ?condition: true | false | ^(Context) -> bool,
+    #     ?queue: String?,
+    #     ?concurrency: Integer?
+    #   ) -> void
+    def initialize(condition: false, queue: nil, concurrency: nil)
+      @condition = condition
+      @queue = queue
+      @concurrency = concurrency
+    end
+
+    #:  (Context) -> bool
+    def should_enqueue?(context)
+      return condition.call(context) if condition.is_a?(Proc)
+
+      !!condition
+    end
+
+    #:  () -> bool
+    def should_limits_concurrency?
+      !!condition && !concurrency.nil? && QueueAdapter.current.supports_concurrency_limits?
+    end
+  end
+end

data/lib/job_workflow/task_graph.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskGraph
+    include TSort #[Task]
+    include Enumerable #[Task]
+
+    #:  () -> void
+    def initialize
+      @tasks = {} #: Hash[Symbol, Task]
+    end
+
+    #:  (Task) -> void
+    def add(task)
+      @tasks[task.task_name] = task
+    end
+
+    #:  (Symbol?) -> Task?
+    def fetch(task_name)
+      @tasks[task_name]
+    end
+
+    #:  () { (Task) -> void } -> void
+    def each(&)
+      tsort.each(&)
+    end
+
+    #:  () { (Task) -> void } -> void
+    def tsort_each_node(&)
+      @tasks.values.each(&)
+    end
+
+    #:  (Task task) { (Task) -> void } -> void
+    def tsort_each_child(task)
+      task.depends_on.each do |dep_task_name|
+        dep_task = @tasks[dep_task_name]
+        raise ArgumentError, "Task '#{task.task_name}' depends on missing task '#{dep_task_name}'" if dep_task.nil?
+
+        yield(dep_task)
+      end
+    end
+  end
+end

data/lib/job_workflow/task_job_status.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskJobStatus
+    attr_reader :task_name #: Symbol
+    attr_reader :job_id #: String
+    attr_reader :each_index #: Integer
+    attr_reader :status #: Symbol
+
+    class << self
+      #:  (Hash[Symbol, untyped]) -> TaskJobStatus
+      def from_hash(hash)
+        new(
+          task_name: hash[:task_name],
+          job_id: hash[:job_id],
+          each_index: hash[:each_index],
+          status: hash[:status]
+        )
+      end
+
+      #:  (Hash[String, untyped]) -> TaskJobStatus
+      def deserialize(hash)
+        new(
+          task_name: hash["task_name"].to_sym,
+          job_id: hash["job_id"],
+          each_index: hash["each_index"],
+          status: hash["status"].to_sym
+        )
+      end
+    end
+
+    #:  (
+    #      task_name: Symbol,
+    #      job_id: String,
+    #      each_index: Integer,
+    #      ?status: Symbol
+    #    ) -> void
+    def initialize(task_name:, job_id:, each_index:, status: :pending)
+      @task_name = task_name
+      @job_id = job_id
+      @each_index = each_index
+      @status = status
+    end
+
+    #:  (Symbol) -> void
+    def update_status(status)
+      @status = status
+    end
+
+    #:  () -> bool
+    def finished?
+      %i[succeeded failed].include?(status)
+    end
+
+    #:  () -> bool
+    def succeeded?
+      status == :succeeded
+    end
+
+    #:  () -> bool
+    def failed?
+      status == :failed
+    end
+
+    #:  () -> Hash[String, untyped]
+    def serialize
+      { "task_name" => task_name.to_s, "job_id" => job_id, "each_index" => each_index, "status" => status.to_s }
+    end
+  end
+end

data/lib/job_workflow/task_output.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskOutput
+    attr_reader :task_name #: Symbol
+    attr_reader :each_index #: Integer
+    attr_reader :data #: Hash[Symbol, untyped]
+
+    class << self
+      #:  (task: Task, each_index: Integer, data: Hash[Symbol, untyped]) -> TaskOutput
+      def from_task(task:, data:, each_index:)
+        normalized_data = task.output.to_h { |output_def| [output_def.name, nil] }
+        normalized_data.merge!(data.slice(*normalized_data.keys))
+        new(task_name: task.task_name, each_index:, data: normalized_data)
+      end
+
+      #:  (Hash[String, untyped]) -> TaskOutput
+      def deserialize(hash)
+        new(
+          task_name: hash["task_name"].to_sym,
+          each_index: hash["each_index"],
+          data: ActiveJob::Arguments.deserialize([hash["data"]]).first
+        )
+      end
+    end
+
+    #:  (task_name: Symbol, each_index: Integer, ?data: Hash[Symbol, untyped]) -> void
+    def initialize(task_name:, each_index:, data: {})
+      @task_name = task_name
+      @each_index = each_index
+      @data = data
+    end
+
+    #:  () -> Hash[String, untyped]
+    def serialize
+      { "task_name" => task_name.to_s, "each_index" => each_index, "data" => ActiveJob::Arguments.serialize([data]).first }
+    end
+
+    #:  ...
+    def method_missing(name, *args, **kwargs, &block)
+      return data[name.to_sym] if data.key?(name.to_sym) && args.empty? && kwargs.empty? && block.nil?
+
+      super
+    end
+
+    #:  (Symbol, bool) -> bool
+    def respond_to_missing?(sym, include_private)
+      data.key?(sym) || super
+    end
+  end
+end

data/lib/job_workflow/task_retry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskRetry
+    attr_reader :count #: Integer
+    attr_reader :strategy #: Symbol
+    attr_reader :base_delay #: Integer
+    attr_reader :jitter #: bool
+
+    class << self
+      #:  (Integer | Hash[Symbol, untyped]) -> TaskRetry
+      def from_primitive_value(value)
+        case value
+        when Integer
+          new(count: value)
+        when Hash
+          new(
+            count: value.fetch(:count, 3),
+            strategy: value.fetch(:strategy, :exponential),
+            base_delay: value.fetch(:base_delay, 1),
+            jitter: value.fetch(:jitter, false)
+          )
+        else
+          raise ArgumentError, "retry must be Integer or Hash"
+        end
+      end
+    end
+
+    #:  (?count: Integer, ?strategy: Symbol, ?base_delay: Integer, ?jitter: bool) -> void
+    def initialize(count: 0, strategy: :exponential, base_delay: 1, jitter: false)
+      @count = count
+      @strategy = strategy
+      @base_delay = base_delay
+      @jitter = jitter
+    end
+
+    #:  (Integer) -> Float
+    def delay_for(retry_attempt)
+      delay = calculate_base_delay(retry_attempt)
+      apply_jitter(delay)
+    end
+
+    private
+
+    #:  (Integer) -> Integer
+    def calculate_base_delay(retry_attempt)
+      case strategy
+      when :exponential
+        exponent = retry_attempt - 1 #: Integer
+        base_delay * (1 << exponent)
+      else
+        base_delay
+      end
+    end
+
+    #:  (Integer) -> Float
+    def apply_jitter(delay)
+      return delay.to_f unless jitter
+
+      randomness = delay * 0.5
+      delay + (rand * randomness) - (randomness / 2)
+    end
+  end
+end

data/lib/job_workflow/task_throttle.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class TaskThrottle
+    attr_reader :key #: String
+    attr_reader :limit #: Integer?
+    attr_reader :ttl #: Integer
+
+    class << self
+      #:  (value: Integer | Hash[Symbol, untyped], task: Task) -> TaskThrottle
+      def from_primitive_value_with_task(value:, task:)
+        case value
+        when Integer
+          new(key: task.throttle_prefix_key, limit: value)
+        when Hash
+          new(
+            key: value[:key] || task.throttle_prefix_key,
+            limit: value[:limit],
+            ttl: value[:ttl] || 180
+          )
+        else
+          raise ArgumentError, "throttle must be Integer or Hash"
+        end
+      end
+    end
+
+    #:  (key: String, ?limit: Integer?, ?ttl: Integer) -> void
+    def initialize(key:, limit: nil, ttl: 180)
+      @key = key
+      @limit = limit
+      @ttl = ttl
+    end
+
+    #:  () -> Semaphore?
+    def semaphore
+      local_limit = limit
+      return if local_limit.nil?
+
+      Semaphore.new(
+        concurrency_key: key,
+        concurrency_duration: ttl.seconds,
+        concurrency_limit: local_limit
+      )
+    end
+  end
+end

data/lib/job_workflow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  VERSION = "0.1.3" # : String
+end