job-workflow 0.4.0 → 0.6.0

data/lib/job_workflow/instrumentation.rb

@@ -40,7 +40,7 @@ module JobWorkflow
     end
 
     class << self
-      #:  (DSL) { () -> untyped } -> untyped
+      #:  (_JobInterface) { () -> untyped } -> untyped
       def instrument_workflow(job, &)
         payload = build_workflow_payload(job)
         instrument(Events::WORKFLOW_START, payload)
@@ -49,7 +49,7 @@ module JobWorkflow
         instrument(Events::WORKFLOW_COMPLETE, payload)
       end
 
-      #:  (DSL, Task, Context) { () -> untyped } -> untyped
+      #:  (_JobInterface, Task, Context) { () -> untyped } -> untyped
       def instrument_task(job, task, ctx, &)
         payload = build_task_payload(job, task, ctx)
         instrument(Events::TASK_START, payload)
@@ -58,12 +58,12 @@ module JobWorkflow
         instrument(Events::TASK_COMPLETE, payload)
       end
 
-      #:  (DSL, Task, String) -> void
+      #:  (_JobInterface, Task, String) -> void
       def notify_task_skip(job, task, reason)
         instrument(Events::TASK_SKIP, build_task_skip_payload(job, task, reason))
       end
 
-      #:  (DSL, Task, Integer) -> void
+      #:  (_JobInterface, Task, Integer) -> void
       def notify_task_enqueue(job, task, sub_job_count)
         instrument(Events::TASK_ENQUEUE, build_task_enqueue_payload(job, task, sub_job_count))
       end
@@ -73,7 +73,7 @@ module JobWorkflow
         instrument(Events::TASK_RETRY, build_task_retry_payload(task, ctx, job_id, attempt, delay, error))
       end
 
-      #:  (DSL, Task) { () -> untyped } -> untyped
+      #:  (_JobInterface, Task) { () -> untyped } -> untyped
       def instrument_dependent_wait(job, task, &)
         payload = build_dependent_payload(job, task)
         instrument(Events::DEPENDENT_WAIT_START, payload)
@@ -82,7 +82,7 @@ module JobWorkflow
         instrument(Events::DEPENDENT_WAIT_COMPLETE, payload)
       end
 
-      #:  (DSL, Task, Numeric, Integer) -> void
+      #:  (_JobInterface, Task, Numeric, Integer) -> void
       def notify_dependent_reschedule(job, task, reschedule_delay, poll_count)
         instrument(
           Events::DEPENDENT_RESCHEDULE,
@@ -120,7 +120,7 @@ module JobWorkflow
         instrument(event_name, payload, &)
       end
 
-      #:  (DSL, Context, Symbol?, Integer, bool) { () -> untyped } -> untyped
+      #:  (_JobInterface, Context, Symbol?, Integer, bool) { () -> untyped } -> untyped
       def instrument_dry_run(job, ctx, dry_run_name, skip_in_dry_run_index, dry_run, &)
         start_event = dry_run ? Events::DRY_RUN_SKIP : Events::DRY_RUN_EXECUTE
         payload = build_skip_in_dry_run_payload(job, ctx, dry_run_name, skip_in_dry_run_index, dry_run)
@@ -135,7 +135,7 @@ module JobWorkflow
         ActiveSupport::Notifications.instrument(event_name, payload, &)
       end
 
-      #:  (DSL) -> Hash[Symbol, untyped]
+      #:  (_JobInterface) -> Hash[Symbol, untyped]
       def build_workflow_payload(job)
         {
           job:,
@@ -144,7 +144,7 @@ module JobWorkflow
         }
       end
 
-      #:  (DSL, Task, Context) -> Hash[Symbol, untyped]
+      #:  (_JobInterface, Task, Context) -> Hash[Symbol, untyped]
       def build_task_payload(job, task, ctx)
         task_ctx = ctx._task_context
         {
@@ -159,7 +159,7 @@ module JobWorkflow
         }
       end
 
-      #:  (DSL, Task, String) -> Hash[Symbol, untyped]
+      #:  (_JobInterface, Task, String) -> Hash[Symbol, untyped]
       def build_task_skip_payload(job, task, reason)
         {
           job:,
@@ -171,7 +171,7 @@ module JobWorkflow
         }
       end
 
-      #:  (DSL, Task, Integer) -> Hash[Symbol, untyped]
+      #:  (_JobInterface, Task, Integer) -> Hash[Symbol, untyped]
       def build_task_enqueue_payload(job, task, sub_job_count)
         {
           job:,
@@ -200,7 +200,7 @@ module JobWorkflow
         }
       end
 
-      #:  (DSL, Task) -> Hash[Symbol, untyped]
+      #:  (_JobInterface, Task) -> Hash[Symbol, untyped]
       def build_dependent_payload(job, task)
         {
           job:,
@@ -211,7 +211,7 @@ module JobWorkflow
         }
       end
 
-      #:  (DSL, Task, Numeric, Integer) -> Hash[Symbol, untyped]
+      #:  (_JobInterface, Task, Numeric, Integer) -> Hash[Symbol, untyped]
       def build_dependent_reschedule_payload(job, task, reschedule_delay, poll_count)
         {
           job:,
@@ -240,7 +240,7 @@ module JobWorkflow
         }
       end
 
-      #:  (DSL, Context, Symbol?, Integer, bool) -> Hash[Symbol, untyped]
+      #:  (_JobInterface, Context, Symbol?, Integer, bool) -> Hash[Symbol, untyped]
       def build_skip_in_dry_run_payload(job, ctx, dry_run_name, dry_run_index, dry_run)
         {
           job_id: job.job_id,

data/lib/job_workflow/job_status.rb

@@ -55,7 +55,7 @@ module JobWorkflow
       task_job_statuses[task_job_status.task_name][task_job_status.each_index] = task_job_status
     end
 
-    #:  (task_name: Symbol, jobs: Array[DSL]) -> void
+    #:  (task_name: Symbol, jobs: Array[_JobInterface]) -> void
     def update_task_job_statuses_from_jobs(task_name:, jobs:)
       jobs.each.with_index do |job, index|
         update_task_job_status(
@@ -85,6 +85,21 @@ module JobWorkflow
       end
     end
 
+    #:  () -> void
+    def refresh_from_db!
+      statuses = flat_task_job_statuses.reject(&:finished?).index_by(&:job_id)
+      return if statuses.empty?
+
+      task_jobs = QueueAdapter.current.fetch_job_statuses(statuses.keys)
+      statuses.each do |job_id, task_job_status|
+        task_job = task_jobs[job_id]
+        next if task_job.nil?
+
+        task_job_status.update_status(QueueAdapter.current.job_status(task_job))
+        update_task_job_status(task_job_status)
+      end
+    end
+
     private
 
     attr_accessor :task_job_statuses #: Hash[Symbol, Array[TaskJobStatus]]

data/lib/job_workflow/monitoring/dag_layout.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class DagLayout
+      NODE_WIDTH = 224
+      NODE_HEIGHT = 84
+      COLUMN_GAP = 56
+      ROW_GAP = 24
+      PADDING = 16
+      LABEL_LIMIT = 24
+
+      #:  (tasks: Array[Hash[Symbol, untyped]]) -> void
+      def initialize(tasks:)
+        validate_tasks!(tasks)
+        @tasks = tasks
+      end
+
+      #:  () -> Hash[Symbol, untyped]
+      def to_h
+        {
+          width: canvas_width,
+          height: canvas_height,
+          nodes:,
+          edges:
+        }
+      end
+
+      private
+
+      attr_reader :tasks #: Array[Hash[Symbol, untyped]]
+
+      #:  (Array[Hash[Symbol, untyped]]) -> void
+      def validate_tasks!(tasks)
+        seen_names = {} #: Hash[Symbol, bool]
+
+        tasks.each do |task|
+          validate_dependencies!(task, seen_names)
+          seen_names[task.fetch(:name)] = true
+        end
+      end
+
+      #:  (Hash[Symbol, untyped], Hash[Symbol, bool]) -> void
+      def validate_dependencies!(task, seen_names)
+        missing_dependencies = task.fetch(:depends_on).reject { |dependency_name| seen_names[dependency_name] }
+        return if missing_dependencies.empty?
+
+        task_name = task.fetch(:name)
+        dependency_names = missing_dependencies.join(", ")
+
+        raise(
+          ArgumentError,
+          "DagLayout tasks must be topologically sorted; " \
+          "#{task_name} depends on unavailable prior tasks: #{dependency_names}"
+        )
+      end
+
+      #:  () -> Array[Hash[Symbol, untyped]]
+      def nodes
+        @nodes ||= tasks.map do |task|
+          position = node_positions.fetch(task.fetch(:name))
+          task.merge(
+            x: x_for(position.fetch(:column)),
+            y: y_for(position.fetch(:row)),
+            width: NODE_WIDTH,
+            height: NODE_HEIGHT,
+            label: task.fetch(:name).to_s,
+            truncated_label: truncate_label(task.fetch(:name)),
+            meta_label: node_meta_label(task)
+          )
+        end
+      end
+
+      #:  () -> Array[Hash[Symbol, untyped]]
+      def edges
+        @edges ||= tasks.flat_map do |task|
+          task.fetch(:depends_on).map do |dependency_name|
+            edge_view(dependency_name, task.fetch(:name))
+          end
+        end
+      end
+
+      #:  () -> Hash[Symbol, Hash[Symbol, Integer]]
+      def node_positions
+        @node_positions ||= begin
+          column_rows = Hash.new(0) #: Hash[Integer, Integer]
+          positions = {} #: Hash[Symbol, Hash[Symbol, Integer]]
+
+          tasks.each_with_object(positions) do |task, current_positions|
+            column = dependency_column(task, current_positions)
+            row = column_rows[column]
+            column_rows[column] += 1
+            current_positions[task.fetch(:name)] = { column:, row: }
+          end
+        end
+      end
+
+      #:  (Hash[Symbol, untyped], Hash[Symbol, Hash[Symbol, Integer]]) -> Integer
+      def dependency_column(task, positions)
+        depends_on = task.fetch(:depends_on)
+        return 0 if depends_on.empty?
+
+        depends_on.map { |dependency_name| positions.fetch(dependency_name).fetch(:column) + 1 }.max || 0
+      end
+
+      #:  (Symbol, Symbol) -> Hash[Symbol, untyped]
+      def edge_view(from_name, to_name)
+        from_node = node_view(from_name)
+        to_node = node_view(to_name)
+        {
+          from: from_name,
+          to: to_name,
+          path: edge_path(from_node, to_node)
+        }
+      end
+
+      #:  (Hash[Symbol, untyped], Hash[Symbol, untyped]) -> String
+      def edge_path(from_node, to_node)
+        start_x = from_node.fetch(:x) + from_node.fetch(:width)
+        start_y = from_node.fetch(:y) + (from_node.fetch(:height) / 2)
+        end_x = to_node.fetch(:x)
+        end_y = to_node.fetch(:y) + (to_node.fetch(:height) / 2)
+        mid_x = ((start_x + end_x) / 2.0).round(2)
+
+        "M #{start_x} #{start_y} L #{mid_x} #{start_y} L #{mid_x} #{end_y} L #{end_x} #{end_y}"
+      end
+
+      #:  (Symbol) -> Hash[Symbol, untyped]
+      def node_view(task_name)
+        nodes.find { |task| task.fetch(:name) == task_name } || raise(KeyError, task_name.to_s)
+      end
+
+      #:  () -> Integer
+      def canvas_width
+        return 0 if nodes.empty?
+
+        max_column = node_positions.values.map { |position| position.fetch(:column) }.max || 0
+        (PADDING * 2) + ((max_column + 1) * NODE_WIDTH) + (max_column * COLUMN_GAP)
+      end
+
+      #:  () -> Integer
+      def canvas_height
+        return 0 if nodes.empty?
+
+        max_row = node_positions.values.map { |position| position.fetch(:row) }.max || 0
+        (PADDING * 2) + ((max_row + 1) * NODE_HEIGHT) + (max_row * ROW_GAP)
+      end
+
+      #:  (Integer) -> Integer
+      def x_for(column)
+        PADDING + (column * (NODE_WIDTH + COLUMN_GAP))
+      end
+
+      #:  (Integer) -> Integer
+      def y_for(row)
+        PADDING + (row * (NODE_HEIGHT + ROW_GAP))
+      end
+
+      #:  (Symbol) -> String
+      def truncate_label(task_name)
+        label = task_name.to_s
+        return label if label.length <= LABEL_LIMIT
+
+        "#{label[0, LABEL_LIMIT - 1]}…"
+      end
+
+      #:  (Hash[Symbol, untyped]) -> String?
+      def node_meta_label(task)
+        return root_task_label if task.fetch(:depends_on).empty?
+        return each_progress_label(task.fetch(:each_progress)) if task.fetch(:each)
+
+        nil
+      end
+
+      #:  () -> String
+      def root_task_label
+        "root task"
+      end
+
+      #:  (Hash[Symbol, Integer]) -> String
+      def each_progress_label(progress)
+        "each #{progress.fetch(:succeeded)}/#{progress.fetch(:total)}"
+      end
+    end
+  end
+end

data/lib/job_workflow/monitoring/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    # :nocov:
+    if defined?(Rails::Engine)
+      class Engine < ::Rails::Engine
+        isolate_namespace JobWorkflow::Monitoring
+
+        JobWorkflow::Monitoring.configure_engine_config(config) if respond_to?(:config)
+      end
+    end
+    # :nocov:
+  end
+end

data/lib/job_workflow/monitoring/execution_page.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class ExecutionPage
+      attr_reader :executions #: Array[ExecutionViewModel]
+      attr_reader :next_cursor #: String?
+
+      #:  (executions: Array[ExecutionViewModel], next_cursor: String?) -> void
+      def initialize(executions:, next_cursor:)
+        @executions = executions
+        @next_cursor = next_cursor
+      end
+    end
+  end
+end

data/lib/job_workflow/monitoring/execution_registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class ExecutionRegistry
+      DEFAULT_LIMIT = 25
+      private_constant :DEFAULT_LIMIT
+
+      class << self
+        #:  (job_class_name: String, ?limit: Integer, ?cursor: String?) -> ExecutionPage
+        def page_for(job_class_name:, limit: DEFAULT_LIMIT, cursor: nil)
+          page = QueueAdapter.current.fetch_root_workflow_job_page(job_class_name:, limit:, cursor:)
+          executions = page.fetch(:jobs).filter_map { |job_data| build_view_model(job_data) }
+          ExecutionPage.new(executions:, next_cursor: page[:next_cursor])
+        end
+
+        #:  (String) -> ExecutionViewModel?
+        def find(job_id)
+          job_data = QueueAdapter.current.find_job(job_id)
+          return if job_data.nil?
+
+          build_view_model(job_data, hydrate_sub_tasks: true)
+        end
+
+        private
+
+        #:  (Hash[String, untyped], ?hydrate_sub_tasks: bool) -> ExecutionViewModel?
+        def build_view_model(job_data, hydrate_sub_tasks: false)
+          return if job_data["class_name"] == JobWorkflow::SubTaskJob.name
+
+          status = WorkflowStatus.from_job_data(job_data)
+          hydrate_sub_task_state(status) if hydrate_sub_tasks
+          ExecutionViewModel.new(job_id: job_data.fetch("job_id"), queue_name: job_data["queue_name"], status:)
+        rescue NameError => e
+          raise e if e.is_a?(NoMethodError)
+
+          nil
+        end
+
+        #:  (WorkflowStatus) -> void
+        def hydrate_sub_task_state(status)
+          status.job_status.refresh_from_db!
+          sub_task_job_ids = status.job_status.flat_task_job_statuses.map(&:job_id)
+          sub_task_contexts = QueueAdapter.current.fetch_job_contexts(sub_task_job_ids)
+          status.output.update_task_outputs_from_contexts(sub_task_contexts, status.context.workflow)
+        end
+      end
+    end
+  end
+end

data/lib/job_workflow/monitoring/execution_view_model.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class ExecutionViewModel
+      attr_reader :job_id #: String
+      attr_reader :queue_name #: String?
+      attr_reader :status #: WorkflowStatus
+
+      #:  (job_id: String, queue_name: String?, status: WorkflowStatus) -> void
+      def initialize(job_id:, queue_name:, status:)
+        @job_id = job_id
+        @queue_name = queue_name
+        @status = status
+      end
+
+      #:  () -> String
+      def job_class_name
+        status.job_class_name
+      end
+
+      #:  () -> Symbol
+      def workflow_status
+        status.status
+      end
+
+      #:  () -> Symbol?
+      def current_task_name
+        status.current_task_name
+      end
+
+      #:  () -> Arguments
+      def arguments
+        status.arguments
+      end
+
+      #:  () -> Hash[untyped, untyped]
+      def filtered_arguments
+        ParameterFilter.filter(arguments.to_h)
+      end
+
+      #:  () -> Array[Hash[Symbol, untyped]]
+      def tasks
+        @tasks ||= status.context.workflow.tasks.map { |task| task_view_model(task) }
+      end
+
+      #:  () -> Symbol?
+      def failed_task_name
+        @failed_task_name ||= begin
+          failed_task = tasks.find { |task| task[:status] == :failed }
+          failed_task&.fetch(:name)
+        end
+      end
+
+      #:  () -> String?
+      def mission_control_job_path
+        JobWorkflow::Monitoring.mission_control_job_path(job_id, status: workflow_status)
+      end
+
+      #:  () -> Hash[Symbol, untyped]
+      def dag_layout
+        @dag_layout ||= DagLayout.new(tasks:).to_h
+      end
+
+      #:  () -> bool
+      def running?
+        workflow_status == :running
+      end
+
+      #:  () -> Hash[Symbol, untyped]
+      def to_h
+        {
+          job_id:,
+          queue_name:,
+          job_class_name:,
+          status: workflow_status,
+          current_task_name:,
+          failed_task_name:,
+          arguments: filtered_arguments,
+          tasks:,
+          mission_control_job_path:
+        }
+      end
+
+      private
+
+      #:  (Symbol, Array[TaskOutput], Array[TaskJobStatus]) -> Symbol
+      def task_status(task_name, task_outputs, task_job_statuses)
+        return :failed if task_job_statuses.any?(&:failed?)
+        return :succeeded if completed_task?(task_outputs, task_job_statuses)
+        return :running if task_running?(task_name, task_job_statuses)
+
+        :pending
+      end
+
+      #:  (Array[TaskOutput], Array[TaskJobStatus]) -> bool
+      def completed_task?(task_outputs, task_job_statuses)
+        return true if !running? && task_outputs.any?
+        return task_job_statuses.all?(&:succeeded?) if task_job_statuses.any?
+
+        task_outputs.any?
+      end
+
+      #:  (Symbol, Array[TaskJobStatus]) -> bool
+      def task_running?(task_name, task_job_statuses)
+        current_task_running?(task_name) ||
+          (!task_job_statuses.empty? && task_job_statuses.any? { |task_status| !task_status.finished? })
+      end
+
+      #:  (Symbol) -> bool
+      def current_task_running?(task_name) = running? && current_task_name == task_name
+
+      #:  (Task) -> Hash[Symbol, untyped]
+      def task_view_model(task)
+        task_name = task.task_name
+        task_outputs, task_job_statuses = task_state(task_name)
+
+        task_configuration_view(task).merge(
+          task_runtime_view(task_name, task_outputs, task_job_statuses)
+        )
+      end
+
+      #:  (Task) -> Hash[Symbol, untyped]
+      def task_configuration_view(task)
+        {
+          name: task.task_name,
+          depends_on: task.depends_on,
+          each: task.each?,
+          configuration: task_configuration(task)
+        }
+      end
+
+      #:  (Symbol, Array[TaskOutput], Array[TaskJobStatus]) -> Hash[Symbol, untyped]
+      def task_runtime_view(task_name, task_outputs, task_job_statuses)
+        {
+          status: task_status(task_name, task_outputs, task_job_statuses),
+          each_progress: each_progress(task_outputs, task_job_statuses),
+          outputs: task_outputs_view(task_outputs),
+          sub_task_jobs: sub_task_jobs_view(task_job_statuses)
+        }
+      end
+
+      #:  (Symbol) -> [Array[TaskOutput], Array[TaskJobStatus]]
+      def task_state(task_name)
+        [
+          status.output.fetch_all(task_name:),
+          status.job_status.fetch_all(task_name:)
+        ]
+      end
+
+      #:  (Task) -> Hash[Symbol, untyped]
+      def task_configuration(task)
+        {
+          job_name: task.job_name,
+          each: callable_summary(task.each),
+          condition: callable_summary(task.condition),
+          enqueue: enqueue_configuration(task),
+          outputs: output_configuration(task),
+          retry: retry_configuration(task),
+          throttle: throttle_configuration(task),
+          timeout: task.timeout,
+          dependency_wait: dependency_wait_configuration(task),
+          dry_run: callable_summary(task.dry_run_config.evaluator)
+        }
+      end
+
+      #:  (Task) -> Hash[Symbol, untyped]
+      def enqueue_configuration(task)
+        {
+          enabled: primitive_summary(task.enqueue.condition),
+          queue: task.enqueue.queue
+        }
+      end
+
+      #:  (Task) -> Array[Hash[Symbol, untyped]]
+      def output_configuration(task)
+        task.output.map { |output| { name: output.name, type: output.type } }
+      end
+
+      #:  (Task) -> Hash[Symbol, untyped]
+      def retry_configuration(task)
+        {
+          count: task.task_retry.count,
+          strategy: task.task_retry.strategy,
+          base_delay: task.task_retry.base_delay,
+          jitter: task.task_retry.jitter
+        }
+      end
+
+      #:  (Task) -> Hash[Symbol, untyped]
+      def throttle_configuration(task)
+        {
+          key: task.throttle.key,
+          limit: task.throttle.limit,
+          ttl: task.throttle.ttl
+        }
+      end
+
+      #:  (Task) -> Hash[Symbol, untyped]
+      def dependency_wait_configuration(task)
+        {
+          poll_timeout: task.dependency_wait.poll_timeout,
+          poll_interval: task.dependency_wait.poll_interval,
+          reschedule_delay: task.dependency_wait.reschedule_delay,
+          polling_only: task.dependency_wait.polling_only?
+        }
+      end
+
+      #:  (untyped) -> untyped
+      def callable_summary(value)
+        case value
+        when nil
+          nil
+        when Proc
+          "proc"
+        else
+          value
+        end
+      end
+
+      #:  (untyped) -> untyped
+      def primitive_summary(value)
+        value.is_a?(Proc) ? "proc" : value
+      end
+
+      #:  (Array[TaskOutput], Array[TaskJobStatus]) -> Hash[Symbol, Integer]
+      def each_progress(task_outputs, task_job_statuses)
+        {
+          total: [task_outputs.size, task_job_statuses.size].max,
+          succeeded: task_job_statuses.count(&:succeeded?),
+          failed: task_job_statuses.count(&:failed?),
+          pending: task_job_statuses.count { |task_status| task_status.status == :pending },
+          running: task_job_statuses.count { |task_status| task_status.status == :running }
+        }
+      end
+
+      #:  (Array[TaskOutput]) -> Array[Hash[Symbol, untyped]]
+      def task_outputs_view(task_outputs)
+        task_outputs.map do |output|
+          { each_index: output.each_index, data: ParameterFilter.filter(output.data) }
+        end
+      end
+
+      #:  (Array[TaskJobStatus]) -> Array[Hash[Symbol, untyped]]
+      def sub_task_jobs_view(task_job_statuses)
+        Array(task_job_statuses).map do |task_job_status|
+          {
+            job_id: task_job_status.job_id,
+            each_index: task_job_status.each_index,
+            status: task_job_status.status,
+            mission_control_job_path: mission_control_job_path_for(task_job_status.job_id, task_job_status.status)
+          }
+        end
+      end
+
+      #:  (String?, Symbol?) -> String?
+      def mission_control_job_path_for(job_id, status = nil)
+        JobWorkflow::Monitoring.mission_control_job_path(job_id, status:)
+      end
+    end
+  end
+end