tasker-engine 0.1.0 → 1.0.0

data/app/models/tasker/task_diagram.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'pathname'
+
+module Tasker
+  class TaskDiagram
+    # Colors for different step statuses
+    STATUS_COLORS = {
+      Tasker::Constants::WorkflowStepStatuses::PENDING => 'lightblue',
+      Tasker::Constants::WorkflowStepStatuses::IN_PROGRESS => 'lightgreen',
+      Tasker::Constants::WorkflowStepStatuses::COMPLETE => 'green',
+      Tasker::Constants::WorkflowStepStatuses::ERROR => 'red',
+      Tasker::Constants::WorkflowStepStatuses::CANCELLED => 'gray'
+    }.freeze
+
+    # Create a new task diagram
+    #
+    # @param task [Tasker::Task] The task to create a diagram for
+    # @param base_url [String, nil] Optional base URL for REST endpoints
+    # @return [TaskDiagram] A new task diagram instance
+    def initialize(task, base_url = nil)
+      @task = task
+      @base_url = base_url
+    end
+
+    # Generate a Mermaid diagram string for the task
+    #
+    # @return [String] Mermaid flowchart diagram string
+    delegate :to_mermaid, to: :flowchart
+
+    # Generate a complete HTML document with embedded Mermaid diagram
+    #
+    # @return [String] HTML document with Mermaid diagram
+    def to_html
+      # Generate the mermaid diagram
+      @diagram = flowchart.to_mermaid
+
+      # Create binding with relevant variables
+      task = @task # Make task available to the template
+      diagram = @diagram # Make diagram available to the template
+
+      # Create a binding with the variables
+      b = binding
+
+      # Get the template path relative to this file
+      template_path = views_path.join('_diagram.html.erb')
+
+      # Load and render the template with ERB
+      begin
+        template = File.read(template_path)
+        ERB.new(template).result(b)
+      rescue Errno::ENOENT
+        raise TaskDiagramError, "Template file not found: #{template_path}"
+      rescue Errno::EACCES
+        raise TaskDiagramError, "Permission denied while accessing template file: #{template_path}"
+      end
+    end
+
+    def to_json(pretty: false)
+      flowchart.to_json(pretty: pretty)
+    end
+
+    private
+
+    def flowchart
+      return @flowchart if @flowchart
+
+      # Preload workflow steps with scenic view relationships for efficiency
+      workflow_steps = @task.workflow_steps.includes(:named_step, :step_dag_relationship)
+
+      # Create a new flowchart
+      @flowchart = Tasker::Diagram::Flowchart.new(
+        direction: 'TD',
+        title: "Task #{@task.task_id}: #{@task.name}"
+      )
+
+      # Add task info node
+      @flowchart.add_node(build_task_node)
+
+      # Build nodes for all workflow steps
+      workflow_steps.each do |step|
+        @flowchart.add_node(build_step_node(step))
+      end
+
+      # Build all edges efficiently using scenic view data
+      build_all_step_edges(workflow_steps).each do |edge|
+        @flowchart.add_edge(edge)
+      end
+
+      @flowchart
+    end
+
+    # Get the path to the view templates directory
+    #
+    # @return [Pathname] Path to view templates
+    def views_path
+      # Get the absolute path of the current file
+      current_file = Pathname.new(__FILE__)
+
+      # Navigate to the views directory relative to this file
+      # This file is in app/models/tasker/task_diagram.rb
+      # Views are in app/views/tasker/task/
+      current_file.dirname.parent.parent.parent.join('app', 'views', 'tasker', 'task')
+    end
+
+    # Build the task information node
+    #
+    # @return [Tasker::Diagram::Node] The task node
+    def build_task_node
+      Tasker::Diagram::Node.new(
+        id: "task_#{@task.task_id}",
+        label: "Task: #{@task.name}\nID: #{@task.task_id}\nStatus: #{@task.status}"
+      )
+    end
+
+    # Build a node for a workflow step
+    #
+    # @param step [Tasker::WorkflowStep] The workflow step
+    # @return [Tasker::Diagram::Node] The step node
+    def build_step_node(step)
+      node_id = "step_#{step.workflow_step_id}"
+      color = STATUS_COLORS[step.status] || 'lightgray'
+
+      # Create label with step details
+      label = build_step_label(step)
+
+      # Create clickable URL if base_url is provided
+      url = @base_url ? "#{@base_url}/tasks/#{@task.task_id}/workflow_steps/#{step.workflow_step_id}" : nil
+
+      # Create node with styling
+      Tasker::Diagram::Node.new(
+        id: node_id,
+        label: label.join("\n"),
+        shape: 'box',
+        style: "fill:#{color};",
+        url: url
+      )
+    end
+
+    # Build the label lines for a step node
+    #
+    # @param step [Tasker::WorkflowStep] The workflow step
+    # @return [Array<String>] Array of label lines
+    def build_step_label(step)
+      label = [
+        "Step: #{step.name}",
+        "Status: #{step.status}",
+        "Attempts: #{step.attempts || 0}"
+      ]
+
+      # Add error info if applicable
+      if step.status == Tasker::Constants::WorkflowStepStatuses::ERROR && step.results&.key?('error')
+        error_msg = step.results['error'].to_s
+        # Truncate long error messages
+        error_msg = "#{error_msg[0..27]}..." if error_msg.length > 30
+        label << "Error: #{error_msg}"
+      end
+
+      label
+    end
+
+    # Build an edge between two nodes
+    #
+    # @param source_id [String] The source node ID
+    # @param target_id [String] The target node ID
+    # @param label [String] The edge label
+    # @return [Tasker::Diagram::Edge] The edge
+    def build_edge(source_id, target_id, label = '')
+      Tasker::Diagram::Edge.new(
+        source_id: source_id,
+        target_id: target_id,
+        label: label
+      )
+    end
+
+    # Build all edges efficiently using scenic view data - eliminates N+1 queries
+    #
+    # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps for the task
+    # @return [Array<Tasker::Diagram::Edge>] All edges for the diagram
+    def build_all_step_edges(workflow_steps)
+      edges = []
+
+      # Add edges from task to root steps using dedicated builder
+      edges.concat(TaskToRootStepEdgeBuilder.build(@task, workflow_steps))
+
+      # Add edges between steps using dedicated builder
+      edges.concat(StepToStepEdgeBuilder.build(workflow_steps))
+
+      edges
+    end
+
+    # Service class to build edges from task to root steps
+    # Reduces complexity by organizing edge building logic
+    class TaskToRootStepEdgeBuilder
+      class << self
+        # Build edges from task node to root steps
+        #
+        # @param task [Tasker::Task] The task
+        # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps
+        # @return [Array<Tasker::Diagram::Edge>] Task to root step edges
+        def build(task, workflow_steps)
+          edges = []
+
+          workflow_steps.each do |step|
+            next unless step.step_dag_relationship&.is_root_step
+
+            edges << build_edge(
+              "task_#{task.task_id}",
+              "step_#{step.workflow_step_id}"
+            )
+          end
+
+          edges
+        end
+
+        private
+
+        # Build an edge between two nodes
+        #
+        # @param source_id [String] The source node ID
+        # @param target_id [String] The target node ID
+        # @param label [String] The edge label
+        # @return [Tasker::Diagram::Edge] The edge
+        def build_edge(source_id, target_id, label = '')
+          Tasker::Diagram::Edge.new(
+            source_id: source_id,
+            target_id: target_id,
+            label: label
+          )
+        end
+      end
+    end
+
+    # Service class to build edges between workflow steps
+    # Reduces complexity by organizing edge building logic
+    class StepToStepEdgeBuilder
+      class << self
+        # Build edges between workflow steps
+        #
+        # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps
+        # @return [Array<Tasker::Diagram::Edge>] Step to step edges
+        def build(workflow_steps)
+          edge_data = collect_edge_data(workflow_steps)
+          return [] if edge_data.empty?
+
+          edge_records = batch_load_edge_records(edge_data)
+          build_edges_from_data(edge_data, edge_records)
+        end
+
+        private
+
+        # Collect all edge relationships for efficient batch lookup
+        #
+        # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps
+        # @return [Array<Hash>] Edge data with from_step_id and to_step_id
+        def collect_edge_data(workflow_steps)
+          edge_data = []
+
+          workflow_steps.each do |step|
+            next unless step.step_dag_relationship
+
+            child_ids = step.step_dag_relationship.child_step_ids_array
+            child_ids.each do |child_id|
+              edge_data << {
+                from_step_id: step.workflow_step_id,
+                to_step_id: child_id
+              }
+            end
+          end
+
+          edge_data
+        end
+
+        # Batch load all WorkflowStepEdge records for edge labels
+        #
+        # @param edge_data [Array<Hash>] Edge data to load records for
+        # @return [Hash] Hash mapping edge keys to edge records
+        def batch_load_edge_records(edge_data)
+          edge_records = {}
+
+          conditions = edge_data.map do |data|
+            "(from_step_id = #{data[:from_step_id]} AND to_step_id = #{data[:to_step_id]})"
+          end
+
+          Tasker::WorkflowStepEdge.where(conditions.join(' OR ')).find_each do |edge_record|
+            key = "#{edge_record.from_step_id}_#{edge_record.to_step_id}"
+            edge_records[key] = edge_record
+          end
+
+          edge_records
+        end
+
+        # Build edges using pre-calculated data and records
+        #
+        # @param edge_data [Array<Hash>] Edge data with IDs
+        # @param edge_records [Hash] Loaded edge records for labels
+        # @return [Array<Tasker::Diagram::Edge>] Built edges
+        def build_edges_from_data(edge_data, edge_records)
+          edges = []
+
+          edge_data.each do |data|
+            source_id = "step_#{data[:from_step_id]}"
+            target_id = "step_#{data[:to_step_id]}"
+
+            # Find edge label from batch-loaded records
+            key = "#{data[:from_step_id]}_#{data[:to_step_id]}"
+            edge_label = edge_records[key]&.name || ''
+
+            edges << build_edge(source_id, target_id, edge_label)
+          end
+
+          edges
+        end
+
+        # Build an edge between two nodes
+        #
+        # @param source_id [String] The source node ID
+        # @param target_id [String] The target node ID
+        # @param label [String] The edge label
+        # @return [Tasker::Diagram::Edge] The edge
+        def build_edge(source_id, target_id, label = '')
+          Tasker::Diagram::Edge.new(
+            source_id: source_id,
+            target_id: target_id,
+            label: label
+          )
+        end
+      end
+    end
+  end
+end

data/app/models/tasker/workflow_step_edge.rb

@@ -11,27 +11,26 @@ module Tasker
 
     scope :children_of, ->(step) { where(from_step: step) }
     scope :parents_of, ->(step) { where(to_step: step) }
-    scope :siblings_of, ->(step) { find_by_sql(sibling_sql(step.workflow_step_id)) }
+    scope :siblings_of, ->(step) { find_by_sql(sibling_sql(step.id)) }
     scope :provides_edges, -> { where(name: WorkflowStep::PROVIDES_EDGE_NAME) }
-    scope :provides_to_children, ->(step) { where(name: WorkflowStep::PROVIDES_EDGE_NAME, to_step: children_of(step)) }
+    scope :provides_to_children, -> { where(name: WorkflowStep::PROVIDES_EDGE_NAME, to_step: children_of(from_step)) }
 
     def self.create_edge!(from_step, to_step, name)
       create!(from_step: from_step, to_step: to_step, name: name)
     end
 
     def self.sibling_sql(step_id)
-      sanitized_id = connection.quote(step_id)
       <<~SQL.squish
         WITH step_parents AS (
           SELECT from_step_id
           FROM tasker_workflow_step_edges
-          WHERE to_step_id = #{sanitized_id}
+          WHERE to_step_id = #{step_id}
         ),
         potential_siblings AS (
           SELECT to_step_id
           FROM tasker_workflow_step_edges
           WHERE from_step_id IN (SELECT from_step_id FROM step_parents)
-          AND to_step_id != #{sanitized_id}
+          AND to_step_id != #{step_id}
         ),
         siblings AS (
           SELECT to_step_id

data/app/views/tasker/task/_diagram.html.erb

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Task <%= task.task_id %> Workflow Diagram</title>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+  <script>
+    mermaid.initialize({
+      startOnLoad: true,
+      theme: 'default'
+    });
+  </script>
+  <style>
+    body { font-family: Arial, sans-serif; margin: 20px; }
+    .mermaid { margin: 20px 0; }
+    .header { margin-bottom: 20px; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>Task Workflow Diagram</h1>
+    <p>Task ID: <%= task.task_id %></p>
+    <p>Task Name: <%= task.name %></p>
+    <p>Status: <%= task.status %></p>
+    <p>Created: <%= task.created_at %></p>
+  </div>
+
+  <div class="tasker-diagram mermaid">
+    <%= diagram %>
+  </div>
+</body>
+</html>

data/config/routes.rb

@@ -24,11 +24,11 @@ Tasker::Engine.routes.draw do
   get '/handlers/:namespace', to: 'handlers#show_namespace' # List handlers in namespace
   get '/handlers/:namespace/:name', to: 'handlers#show'     # Show specific handler with dependency graph
 
-  # GraphQL endpoint
   post '/graphql', to: 'graphql#execute'
-
-  # Task endpoints
+  # mount Rswag::Ui::Engine => '/api-docs'
+  # mount Rswag::Api::Engine => '/api-docs'
   resources :tasks do
     resources :workflow_steps
+    resources :task_diagrams, only: %i[index]
   end
 end

data/db/init/schema.sql

@@ -1,3 +1,14 @@
+SET statement_timeout = 0;
+SET lock_timeout = 0;
+SET idle_in_transaction_session_timeout = 0;
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = on;
+SELECT pg_catalog.set_config('search_path', '', false);
+SET check_function_bodies = false;
+SET xmloption = content;
+SET client_min_messages = warning;
+SET row_security = off;
+
 --
 -- Name: calculate_dependency_levels(bigint); Type: FUNCTION; Schema: public; Owner: -
 --
@@ -824,6 +835,11 @@ BEGIN
 END;
 $$;
 
+
+SET default_tablespace = '';
+
+SET default_table_access_method = heap;
+
 --
 -- Name: tasker_annotation_types; Type: TABLE; Schema: public; Owner: -
 --
@@ -2252,3 +2268,10 @@ ALTER TABLE ONLY public.tasker_workflow_steps
 
 ALTER TABLE ONLY public.tasker_workflow_steps
     ADD CONSTRAINT workflow_steps_task_id_foreign FOREIGN KEY (task_id) REFERENCES public.tasker_tasks(task_id);
+
+
+--
+-- PostgreSQL database dump complete
+--
+
+SET search_path TO "$user", public;

data/docs/APPLICATION_GENERATOR.md

@@ -366,7 +366,7 @@ Once installed, developers can immediately:
 task = Tasker::HandlerFactory.instance.get(
   'order_processing',
   namespace_name: 'ecommerce',
-  version: '1.0.1'
+  version: '1.0.0'
 ).initialize_task!(
   Tasker::Types::TaskRequest.new(
     name: 'order_processing',

data/docs/AUTH.md

@@ -57,7 +57,7 @@ By default, Tasker requires no authentication:
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authentication_enabled = false  # Default - no configuration needed
   end
@@ -70,7 +70,7 @@ For any authentication system, enable authentication and specify your authentica
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authentication_enabled = true
     auth.authenticator_class = 'YourCustomAuthenticator'
@@ -85,7 +85,7 @@ Enable both authentication and authorization for complete security:
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authentication_enabled = true
     auth.authenticator_class = 'YourCustomAuthenticator'
@@ -104,7 +104,7 @@ Authorization in Tasker uses a **resource:action** permission model that works s
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authorization_enabled = true
     auth.authorization_coordinator_class = 'YourAuthorizationCoordinator'
@@ -126,6 +126,8 @@ class YourAuthorizationCoordinator < Tasker::Authorization::BaseCoordinator
       authorize_task_action(action, context)
     when Tasker::Authorization::ResourceConstants::RESOURCES::WORKFLOW_STEP
       authorize_step_action(action, context)
+    when Tasker::Authorization::ResourceConstants::RESOURCES::TASK_DIAGRAM
+      authorize_diagram_action(action, context)
     when Tasker::Authorization::ResourceConstants::RESOURCES::HEALTH_STATUS
       authorize_health_status_action(action, context)
     else
@@ -160,6 +162,15 @@ class YourAuthorizationCoordinator < Tasker::Authorization::BaseCoordinator
     end
   end
 
+  def authorize_diagram_action(action, context)
+    case action
+    when :index, :show
+      user.tasker_admin? || user.has_tasker_permission?("#{Tasker::Authorization::ResourceConstants::RESOURCES::TASK_DIAGRAM}:#{action}")
+    else
+      false
+    end
+  end
+
   def authorize_health_status_action(action, context)
     case action
     when :index
@@ -232,7 +243,7 @@ Enable health status authorization:
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authorization_enabled = true
     auth.authorization_coordinator_class = 'YourAuthorizationCoordinator'
@@ -464,7 +475,7 @@ rails generate tasker:authenticator CompanyJWT --type=jwt --user-class=User
 ### Authentication Configuration Block
 
 ```ruby
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     # Authentication settings
     auth.authentication_enabled = true | false  # Enable/disable authentication
@@ -543,11 +554,13 @@ All authorization revolves around the central resource registry:
 Resources:
   - tasker.task (index, show, create, update, destroy, retry, cancel)
   - tasker.workflow_step (index, show, update, destroy, retry, cancel)
+  - tasker.task_diagram (index, show)
 
 # Permission Examples:
 'tasker.task:index'           # List all tasks
 'tasker.task:create'          # Create new tasks
 'tasker.workflow_step:show'   # View individual workflow steps
+'tasker.task_diagram:index'   # List task diagrams
 ```
 
 ### Authorization Coordinator Interface
@@ -609,6 +622,10 @@ end
 - `retry` - Retry failed step
 - `cancel` - Cancel running step
 
+#### Task Diagrams (`tasker.task_diagram`)
+- `index` - List task diagrams
+- `show` - View specific diagram
+
 ## Building Authorization Coordinators
 
 Authorization coordinators provide the business logic for permission checking. Here's how to build effective coordinators:
@@ -626,6 +643,8 @@ class CompanyAuthorizationCoordinator < Tasker::Authorization::BaseCoordinator
       authorize_task(action, context)
     when Tasker::Authorization::ResourceConstants::RESOURCES::WORKFLOW_STEP
       authorize_workflow_step(action, context)
+    when Tasker::Authorization::ResourceConstants::RESOURCES::TASK_DIAGRAM
+      authorize_task_diagram(action, context)
     else
       false
     end
@@ -658,6 +677,16 @@ class CompanyAuthorizationCoordinator < Tasker::Authorization::BaseCoordinator
       false
     end
   end
+
+  def authorize_task_diagram(action, context)
+    case action
+    when :index, :show
+      # Diagram viewing
+      user.has_tasker_permission?("tasker.task_diagram:#{action}")
+    else
+      false
+    end
+  end
 end
 ```
 
@@ -840,7 +869,7 @@ Our `ExampleJWTAuthenticator` demonstrates a production-ready JWT implementation
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authentication_enabled = true
     auth.authenticator_class = 'ExampleJWTAuthenticator'
@@ -864,7 +893,7 @@ end
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authentication_enabled = true
     auth.authenticator_class = 'ExampleJWTAuthenticator'
@@ -1092,6 +1121,9 @@ DELETE /tasker/tasks/123      → tasker.task:destroy
 GET    /tasker/tasks/123/workflow_steps     → tasker.workflow_step:index
 GET    /tasker/workflow_steps/456           → tasker.workflow_step:show
 PATCH  /tasker/workflow_steps/456           → tasker.workflow_step:update
+
+GET    /tasker/tasks/123/task_diagrams      → tasker.task_diagram:index
+GET    /tasker/task_diagrams/789            → tasker.task_diagram:show
 ```
 
 ### GraphQL Integration
@@ -1284,7 +1316,7 @@ For authorization testing, use comprehensive integration tests:
 # spec/support/shared_contexts/configuration_test_isolation.rb
 RSpec.shared_context 'configuration test isolation' do
   around(:each) do |example|
-    original_config = Tasker::Configuration.configuration
+    original_config = Tasker.configuration
     example.run
   ensure
     # Reset to clean state
@@ -1313,7 +1345,8 @@ RSpec.describe 'Authorization Integration', type: :request do
       permissions: [
         'tasker.task:index',
         'tasker.task:show',
-        'tasker.workflow_step:index'
+        'tasker.workflow_step:index',
+        'tasker.task_diagram:index'
       ],
       roles: ['user'],
       admin: false
@@ -1443,7 +1476,7 @@ RSpec.configure do |config|
   config.after(:each) do
     # Automatic cleanup of authentication/authorization state
     if defined?(Tasker) && Tasker.respond_to?(:configuration)
-      current_config = Tasker::Configuration.configuration
+      current_config = Tasker.configuration
       if current_config&.auth&.authorization_enabled == true
         needs_reset = true
       end
@@ -1454,7 +1487,7 @@ RSpec.configure do |config|
       end
 
       if needs_reset
-        Tasker::Configuration.configuration do |config|
+        Tasker.configuration do |config|
           config.auth.authentication_enabled = false
           config.auth.authorization_enabled = false
           config.auth.authenticator_class = nil
@@ -1590,6 +1623,8 @@ class CompanyAuthorizationCoordinator < Tasker::Authorization::BaseCoordinator
       authorize_task(action, context)
     when ResourceConstants::RESOURCES::WORKFLOW_STEP
       authorize_workflow_step(action, context)
+    when ResourceConstants::RESOURCES::TASK_DIAGRAM
+      authorize_task_diagram(action, context)
     else
       false
     end
@@ -1605,6 +1640,10 @@ class CompanyAuthorizationCoordinator < Tasker::Authorization::BaseCoordinator
   def authorize_workflow_step(action, context)
     # Workflow step authorization logic
   end
+
+  def authorize_task_diagram(action, context)
+    # Diagram authorization logic
+  end
 end
 ```