tasker-engine 1.0.0

data/app/models/tasker/named_tasks_named_step.rb

@@ -0,0 +1,82 @@
+# typed: false
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: named_tasks_named_steps
+#
+#  id                  :integer          not null, primary key
+#  default_retry_limit :integer          default(3), not null
+#  default_retryable   :boolean          default(TRUE), not null
+#  skippable           :boolean          default(FALSE), not null
+#  created_at          :datetime         not null
+#  updated_at          :datetime         not null
+#  named_step_id       :integer          not null
+#  named_task_id       :integer          not null
+#
+# Indexes
+#
+#  named_tasks_named_steps_named_step_id_index  (named_step_id)
+#  named_tasks_named_steps_named_task_id_index  (named_task_id)
+#  named_tasks_steps_ids_unique                 (named_task_id,named_step_id) UNIQUE
+#
+# Foreign Keys
+#
+#  named_tasks_named_steps_named_step_id_foreign  (named_step_id => named_steps.named_step_id)
+#  named_tasks_named_steps_named_task_id_foreign  (named_task_id => named_tasks.named_task_id)
+#
+module Tasker
+  class NamedTasksNamedStep < ApplicationRecord
+    belongs_to :named_task
+    belongs_to :named_step
+    validates :named_task_id, uniqueness: { scope: :named_step_id }
+    validates :named_step_id, uniqueness: { scope: :named_task_id }
+
+    scope :named_steps_for_named_task, lambda { |named_task_id|
+      where(named_task_id: named_task_id).includes(:named_task).includes(:named_step)
+    }
+
+    def self.find_or_create(
+      named_task,
+      named_step,
+      options = {
+        default_retry_limit: 3,
+        default_retryable: true,
+        skippable: false
+      }
+    )
+      inst = where(named_task_id: named_task.named_task_id, named_step_id: named_step.named_step_id).first
+
+      inst ||= create({ named_task_id: named_task.named_task_id,
+                        named_step_id: named_step.named_step_id }.merge(options))
+
+      inst
+    end
+
+    def self.associate_named_step_with_named_task(named_task, template, named_step)
+      ntns = named_steps_for_named_task(named_task.named_task_id).where(named_step: { name: named_step.name }).first
+      return ntns if ntns
+
+      dependent_system = Tasker::DependentSystem.find_or_create_by!(name: template.dependent_system)
+      named_step = Tasker::NamedStep.find_or_create_by!(name: template.name,
+                                                        dependent_system_id: dependent_system.dependent_system_id)
+      find_or_create(
+        named_task,
+        named_step,
+        {
+          default_retry_limit: template.default_retry_limit,
+          default_retryable: template.default_retryable,
+          skippable: template.skippable
+        }
+      )
+    end
+
+    def task_name
+      named_task.name
+    end
+
+    def step_name
+      named_step.name
+    end
+  end
+end

data/app/models/tasker/step_dag_relationship.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Tasker
+  class StepDagRelationship < ApplicationRecord
+    self.table_name = 'tasker_step_dag_relationships'
+    self.primary_key = 'workflow_step_id'
+
+    # Read-only model backed by database view
+    def readonly?
+      true
+    end
+
+    # Associations to actual models for additional data
+    belongs_to :workflow_step
+    belongs_to :task
+
+    # Scopes for common DAG queries
+    scope :for_task, ->(task_id) { where(task_id: task_id) }
+    scope :root_steps, -> { where(is_root_step: true) }
+    scope :leaf_steps, -> { where(is_leaf_step: true) }
+    scope :with_parents, -> { where('parent_count > 0') }
+    scope :with_children, -> { where('child_count > 0') }
+
+    # Efficient siblings scope leveraging existing WorkflowStepEdge logic
+    # Uses the sophisticated sibling_sql that finds steps with exactly the same parent set
+    scope :siblings_of, lambda { |workflow_step_id|
+      # Get sibling step IDs using the existing, well-tested WorkflowStepEdge logic
+      sibling_edges = WorkflowStepEdge.siblings_of(WorkflowStep.find(workflow_step_id))
+      sibling_step_ids = sibling_edges.pluck(:to_step_id).uniq
+
+      # Return StepDagRelationship records for these siblings
+      where(workflow_step_id: sibling_step_ids)
+    }
+
+    # Helper methods for DAG navigation
+    def root_step?
+      is_root_step
+    end
+
+    def leaf_step?
+      is_leaf_step
+    end
+
+    def has_parents?
+      parent_count.positive?
+    end
+
+    def has_children?
+      child_count.positive?
+    end
+
+    # Parse JSONB arrays for relationship access
+    def parent_step_ids_array
+      return [] if parent_step_ids.blank?
+
+      parent_step_ids.is_a?(Array) ? parent_step_ids : JSON.parse(parent_step_ids)
+    end
+
+    def child_step_ids_array
+      return [] if child_step_ids.blank?
+
+      child_step_ids.is_a?(Array) ? child_step_ids : JSON.parse(child_step_ids)
+    end
+  end
+end

data/app/models/tasker/step_readiness_status.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Tasker
+  # StepReadinessStatus now uses SQL functions for high-performance queries
+  # This class explicitly delegates to the function-based implementation for better maintainability
+  class StepReadinessStatus
+    # Explicit delegation of class methods to function-based implementation
+    def self.for_task(task_id, step_ids = nil)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.for_task(task_id, step_ids)
+    end
+
+    def self.for_steps(task_id, step_ids)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.for_steps(task_id, step_ids)
+    end
+
+    def self.for_tasks(task_ids)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.for_tasks(task_ids)
+    end
+
+    # Task-scoped methods that require task_id parameter
+    def self.ready_for_task(task_id)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.ready_for_task(task_id)
+    end
+
+    def self.blocked_by_dependencies_for_task(task_id)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.blocked_by_dependencies_for_task(task_id)
+    end
+
+    def self.blocked_by_retry_for_task(task_id)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.blocked_by_retry_for_task(task_id)
+    end
+
+    def self.pending_for_task(task_id)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.pending_for_task(task_id)
+    end
+
+    def self.failed_for_task(task_id)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.failed_for_task(task_id)
+    end
+
+    def self.in_progress_for_task(task_id)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.in_progress_for_task(task_id)
+    end
+
+    def self.complete_for_task(task_id)
+      Tasker::Functions::FunctionBasedStepReadinessStatus.complete_for_task(task_id)
+    end
+
+    # For backward compatibility, maintain the active method but point to function-based implementation
+    def self.active
+      Tasker::Functions::FunctionBasedStepReadinessStatus
+    end
+
+    def self.all_steps_complete_for_task?(task)
+      complete = Tasker::Functions::FunctionBasedStepReadinessStatus.complete_for_task(task.task_id)
+      complete.length == task.workflow_steps.count
+    end
+  end
+end

data/app/models/tasker/task.rb

@@ -0,0 +1,424 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'digest'
+require_relative '../../../lib/tasker/state_machine/task_state_machine'
+
+# == Schema Information
+#
+# Table name: tasks
+#
+#  bypass_steps  :json
+#  complete      :boolean          default(FALSE), not null
+#  context       :jsonb
+#  identity_hash :string(128)      not null
+#  initiator     :string(128)
+#  reason        :string(128)
+#  requested_at  :datetime         not null
+#  source_system :string(128)
+#  tags          :jsonb
+#  created_at    :datetime         not null
+#  updated_at    :datetime         not null
+#  named_task_id :integer          not null
+#  task_id       :bigint           not null, primary key
+#
+# Indexes
+#
+#  index_tasks_on_identity_hash  (identity_hash) UNIQUE
+#  tasks_context_idx             (context) USING gin
+#  tasks_context_idx1            (context) USING gin
+#  tasks_identity_hash_index     (identity_hash)
+#  tasks_named_task_id_index     (named_task_id)
+#  tasks_requested_at_index      (requested_at)
+#  tasks_source_system_index     (source_system)
+#  tasks_tags_idx                (tags) USING gin
+#  tasks_tags_idx1               (tags) USING gin
+#
+# Foreign Keys
+#
+#  tasks_named_task_id_foreign  (named_task_id => named_tasks.named_task_id)
+#
+module Tasker
+  # Task represents a workflow process that contains multiple workflow steps.
+  # Each Task is identified by a name and has a context which defines the parameters for the task.
+  # Tasks track their status via state machine transitions, initiator, source system, and other metadata.
+  #
+  # @example Creating a task from a task request
+  #   task_request = Tasker::Types::TaskRequest.new(name: 'process_order', context: { order_id: 123 })
+  #   task = Tasker::Task.create_with_defaults!(task_request)
+  #
+  class Task < ApplicationRecord
+    # Regular expression to sanitize strings for database operations
+    ALPHANUM_PLUS_HYPHEN_DASH = /[^0-9a-z\-_]/i
+
+    self.primary_key = :task_id
+    after_initialize :init_defaults, if: :new_record?
+    belongs_to :named_task
+    has_many :workflow_steps, dependent: :destroy
+    has_many :task_annotations, dependent: :destroy
+    has_many :annotation_types, through: :task_annotations
+    has_many :task_transitions, inverse_of: :task, dependent: :destroy
+
+    validates :context, presence: true
+    validates :requested_at, presence: true
+    validate :unique_identity_hash, on: :create
+
+    delegate :name, to: :named_task
+    delegate :to_mermaid, to: :diagram
+    delegate :workflow_summary, to: :task_execution_context
+
+    # State machine integration
+    def state_machine
+      @state_machine ||= Tasker::StateMachine::TaskStateMachine.new(
+        self,
+        transition_class: Tasker::TaskTransition,
+        association_name: :task_transitions
+      )
+    end
+
+    # Status is now entirely managed by the state machine
+    def status
+      if new_record?
+        # For new records, return the initial state
+        Tasker::Constants::TaskStatuses::PENDING
+      else
+        # For persisted records, use state machine
+        state_machine.current_state
+      end
+    end
+
+    # Scopes a query to find tasks with a specific annotation value
+    #
+    # @scope class
+    # @param name [String] The annotation type name
+    # @param key [String, Symbol] The key within the annotation to match
+    # @param value [String] The value to match against
+    # @return [ActiveRecord::Relation] Tasks matching the annotation criteria
+    scope :by_annotation,
+          lambda { |name, key, value|
+            clean_key = key.to_s.gsub(ALPHANUM_PLUS_HYPHEN_DASH, '')
+            joins(:task_annotations, :annotation_types)
+              .where({ annotation_types: { name: name.to_s.strip } })
+              .where("tasker_task_annotations.annotation->>'#{clean_key}' = :value", value: value)
+          }
+
+    # Scopes a query to find tasks by their current state using state machine transitions
+    #
+    # @scope class
+    # @param state [String, nil] The state to filter by. If nil, returns all tasks with current state information
+    # @return [ActiveRecord::Relation] Tasks with current state, optionally filtered by specific state
+    scope :by_current_state,
+          lambda { |state = nil|
+            relation = joins(<<-SQL.squish)
+              INNER JOIN (
+                SELECT DISTINCT ON (task_id) task_id, to_state
+                FROM tasker_task_transitions
+                ORDER BY task_id, sort_key DESC
+              ) current_transitions ON current_transitions.task_id = tasker_tasks.task_id
+            SQL
+
+            if state.present?
+              relation.where(current_transitions: { to_state: state })
+            else
+              relation
+            end
+          }
+
+    # Includes all associated models for efficient querying
+    #
+    # @return [ActiveRecord::Relation] Tasks with all associated records preloaded
+    scope :with_all_associated, lambda {
+      includes(named_task: [:task_namespace])
+        .includes(workflow_steps: %i[named_step parents children])
+        .includes(task_annotations: %i[annotation_type])
+        .includes(:task_transitions)
+    }
+
+    # Analytics scopes for performance metrics
+
+    # Scopes tasks created within a specific time period
+    #
+    # @scope class
+    # @param since_time [Time] The earliest creation time to include
+    # @return [ActiveRecord::Relation] Tasks created since the specified time
+    scope :created_since, lambda { |since_time|
+      where('tasker_tasks.created_at > ?', since_time)
+    }
+
+    # Scopes tasks completed within a specific time period
+    #
+    # @scope class
+    # @param since_time [Time] The earliest completion time to include
+    # @return [ActiveRecord::Relation] Tasks completed since the specified time
+    scope :completed_since, lambda { |since_time|
+      joins(workflow_steps: :workflow_step_transitions)
+        .where('tasker_workflow_step_transitions.to_state = ? AND tasker_workflow_step_transitions.most_recent = ?', 'complete', true)
+        .where('tasker_workflow_step_transitions.created_at > ?', since_time)
+        .distinct
+    }
+
+    # Scopes tasks that have failed within a specific time period
+    # This scope identifies tasks that are actually in a failed state (task status = 'error'),
+    # not just tasks that have some failed steps but may still be progressing.
+    #
+    # @scope class
+    # @param since_time [Time] The earliest failure time to include
+    # @return [ActiveRecord::Relation] Tasks that have transitioned to error state since the specified time
+    scope :failed_since, lambda { |since_time|
+      joins(<<-SQL.squish)
+        INNER JOIN (
+          SELECT DISTINCT ON (task_id) task_id, to_state, created_at
+          FROM tasker_task_transitions
+          ORDER BY task_id, sort_key DESC
+        ) current_transitions ON current_transitions.task_id = tasker_tasks.task_id
+      SQL
+        .where(current_transitions: { to_state: Tasker::Constants::TaskStatuses::ERROR })
+        .where('current_transitions.created_at > ?', since_time)
+    }
+
+    # Scopes tasks that are currently active (not in terminal states)
+    #
+    # @scope class
+    # @return [ActiveRecord::Relation] Tasks that are not complete, error, or cancelled
+    scope :active, lambda {
+      # Active tasks are those with at least one workflow step whose most recent transition
+      # is NOT in a terminal state. Using EXISTS subquery for clarity and performance.
+      where(<<-SQL.squish)
+        EXISTS (
+          SELECT 1
+          FROM tasker_workflow_steps ws
+          INNER JOIN tasker_workflow_step_transitions wst ON wst.workflow_step_id = ws.workflow_step_id
+          WHERE ws.task_id = tasker_tasks.task_id
+            AND wst.most_recent = true
+            AND wst.to_state NOT IN ('complete', 'error', 'skipped', 'resolved_manually')
+        )
+      SQL
+    }
+
+    # Scopes tasks by namespace name through the named_task association
+    #
+    # @scope class
+    # @param namespace_name [String] The namespace name to filter by
+    # @return [ActiveRecord::Relation] Tasks in the specified namespace
+    scope :in_namespace, lambda { |namespace_name|
+      joins(named_task: :task_namespace)
+        .where(tasker_task_namespaces: { name: namespace_name })
+    }
+
+    # Scopes tasks by task name through the named_task association
+    #
+    # @scope class
+    # @param task_name [String] The task name to filter by
+    # @return [ActiveRecord::Relation] Tasks with the specified name
+    scope :with_task_name, lambda { |task_name|
+      joins(:named_task)
+        .where(tasker_named_tasks: { name: task_name })
+    }
+
+    # Scopes tasks by version through the named_task association
+    #
+    # @scope class
+    # @param version [String] The version to filter by
+    # @return [ActiveRecord::Relation] Tasks with the specified version
+    scope :with_version, lambda { |version|
+      joins(:named_task)
+        .where(tasker_named_tasks: { version: version })
+    }
+
+    # Class method for counting unique task types
+    #
+    # @return [Integer] Count of unique task names
+    def self.unique_task_types_count
+      joins(:named_task).distinct.count('tasker_named_tasks.name')
+    end
+
+    # Creates a task with default values from a task request and saves it to the database
+    #
+    # @param task_request [Tasker::Types::TaskRequest] The task request containing task parameters
+    # @return [Tasker::Task] The created and saved task
+    # @raise [ActiveRecord::RecordInvalid] If the task is invalid
+    def self.create_with_defaults!(task_request)
+      task = from_task_request(task_request)
+      task.save!
+      task
+    end
+
+    # Creates a new unsaved task instance from a task request
+    #
+    # @param task_request [Tasker::Types::TaskRequest] The task request containing task parameters
+    # @return [Tasker::Task] A new unsaved task instance
+    def self.from_task_request(task_request)
+      named_task = Tasker::NamedTask.find_or_create_by_full_name!(name: task_request.name,
+                                                                  namespace_name: task_request.namespace, version: task_request.version)
+      # Extract values from task_request, removing nils
+      request_values = get_request_options(task_request)
+      # Merge defaults with request values
+      options = get_default_task_request_options(named_task).merge(request_values)
+
+      task = new(options)
+      task.named_task = named_task
+      task
+    end
+
+    # Extracts and compacts options from a task request
+    #
+    # @param task_request [Tasker::Types::TaskRequest] The task request to extract options from
+    # @return [Hash] Hash of non-nil task options from the request
+    def self.get_request_options(task_request)
+      {
+        initiator: task_request.initiator,
+        source_system: task_request.source_system,
+        reason: task_request.reason,
+        tags: task_request.tags,
+        bypass_steps: task_request.bypass_steps,
+        requested_at: task_request.requested_at,
+        context: task_request.context
+      }.compact
+    end
+
+    # Provides default options for a task
+    #
+    # @param named_task [Tasker::NamedTask] The named task to associate with the task
+    # @return [Hash] Hash of default task options
+    def self.get_default_task_request_options(named_task)
+      {
+        initiator: Tasker::Constants::UNKNOWN,
+        source_system: Constants::UNKNOWN,
+        reason: Tasker::Constants::UNKNOWN,
+        complete: false,
+        tags: [],
+        bypass_steps: [],
+        requested_at: Time.zone.now,
+        named_task_id: named_task.named_task_id
+      }
+    end
+
+    # Finds a workflow step by its name
+    #
+    # @param name [String] The name of the step to find
+    # @return [Tasker::WorkflowStep, nil] The workflow step with the given name, or nil if not found
+    def get_step_by_name(name)
+      workflow_steps.includes(:named_step).where(named_step: { name: name }).first
+    end
+
+    # Gets or creates a diagram representation of this task
+    #
+    # @param base_url [String, nil] The base URL to use for links in the diagram, defaults to nil
+    # @return [Tasker::TaskDiagram] The diagram representation of this task
+    def diagram(base_url = nil)
+      @diagram ||= Tasker::TaskDiagram.new(self, base_url)
+    end
+
+    def runtime_analyzer
+      @runtime_analyzer ||= Tasker::Analysis::RuntimeGraphAnalyzer.new(task: self)
+    end
+
+    # Provides runtime dependency graph analysis
+    # Delegates to RuntimeGraphAnalyzer for graph-based analysis
+    #
+    # @return [Hash] Runtime dependency graph analysis
+    def dependency_graph
+      runtime_analyzer.analyze
+    end
+
+    # Checks if all steps in the task are complete
+    #
+    # @return [Boolean] True if all steps are complete, false otherwise
+    def all_steps_complete?
+      Tasker::StepReadinessStatus.all_steps_complete_for_task?(self)
+    end
+
+    def task_execution_context
+      @task_execution_context ||= Tasker::TaskExecutionContext.new(task_id)
+    end
+
+    def reload
+      super
+      @task_execution_context = nil
+      @diagram = nil
+    end
+
+    delegate :namespace_name, to: :named_task
+
+    delegate :version, to: :named_task
+
+    private
+
+    # Validates that the task has a unique identity hash
+    # Sets the identity hash and checks if a task with the same hash exists
+    #
+    # @return [void]
+    def unique_identity_hash
+      return errors.add(:named_task_id, 'no task name found') unless named_task
+
+      set_identity_hash
+      inst = self.class.where(identity_hash: identity_hash).where.not(task_id: task_id).first
+      errors.add(:identity_hash, 'is identical to a request made in the last minute') if inst
+    end
+
+    # Returns a hash of values that uniquely identify this task
+    #
+    # @return [Hash] Hash of identifying values
+    def identity_options
+      # a task can be described as identical to a prior request if
+      # it has the same name, initiator, source system, reason
+      # bypass steps, and critically, the same identical context for the request
+      # if all of these are the same, and it was requested within the same minute
+      # then we can assume some client side or queue side duplication is happening
+      {
+        name: name,
+        initiator: initiator,
+        source_system: source_system,
+        context: context,
+        reason: reason,
+        bypass_steps: bypass_steps || [],
+        # not allowing structurally identical requests within the same minute
+        # this is a fuzzy match of course, at the 59 / 00 mark there could be overlap
+        # but this feels like a pretty good level of identity checking
+        # without being exhaustive
+        requested_at: requested_at.strftime('%Y-%m-%d %H:%M')
+      }
+    end
+
+    # Initializes default values for a new task
+    #
+    # @return [void]
+    def init_defaults
+      return unless new_record?
+
+      # Apply defaults only for attributes that haven't been set
+      task_defaults.each do |attribute, default_value|
+        self[attribute] = default_value if self[attribute].nil?
+      end
+    end
+
+    # Returns a hash of default values for a task
+    #
+    # @return [Hash] Hash of default values
+    def task_defaults
+      @task_defaults ||= {
+        requested_at: Time.zone.now,
+        initiator: Tasker::Constants::UNKNOWN,
+        source_system: Tasker::Constants::UNKNOWN,
+        reason: Tasker::Constants::UNKNOWN,
+        complete: false,
+        tags: [],
+        bypass_steps: []
+      }
+    end
+
+    # Gets the identity strategy instance from configuration
+    #
+    # @return [Object] The identity strategy instance
+    def identity_strategy
+      @identity_strategy ||= Tasker.configuration.engine.identity_strategy_instance
+    end
+
+    # Sets the identity hash for this task using the configured identity strategy
+    #
+    # @return [String] The generated identity hash
+    def set_identity_hash
+      self.identity_hash = identity_strategy.generate_identity_hash(self, identity_options)
+    end
+  end
+end

data/app/models/tasker/task_annotation.rb

@@ -0,0 +1,36 @@
+# typed: false
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: task_annotations
+#
+#  annotation         :jsonb
+#  created_at         :datetime         not null
+#  updated_at         :datetime         not null
+#  annotation_type_id :integer          not null
+#  task_annotation_id :bigint           not null, primary key
+#  task_id            :bigint           not null
+#
+# Indexes
+#
+#  task_annotations_annotation_idx            (annotation) USING gin
+#  task_annotations_annotation_idx1           (annotation) USING gin
+#  task_annotations_annotation_type_id_index  (annotation_type_id)
+#  task_annotations_task_id_index             (task_id)
+#
+# Foreign Keys
+#
+#  task_annotations_annotation_type_id_foreign  (annotation_type_id => annotation_types.annotation_type_id)
+#  task_annotations_task_id_foreign             (task_id => tasks.task_id)
+#
+
+module Tasker
+  class TaskAnnotation < ApplicationRecord
+    self.primary_key = :task_annotation_id
+    belongs_to :task
+    belongs_to :annotation_type
+
+    delegate :name, to: :annotation_type, prefix: true
+  end
+end