job-workflow 0.1.3

data/guides/WORKFLOW_STATUS_QUERY.md

@@ -0,0 +1,288 @@
+# Workflow Status Query
+
+JobWorkflow provides a robust API for querying the execution status of workflows. This allows you to monitor running workflows, inspect their state, and build observability dashboards.
+
+## Basic Usage
+
+### Finding a Workflow
+
+```ruby
+# Find by job_id (raises NotFoundError if not found)
+status = JobWorkflow::WorkflowStatus.find("job-123")
+
+# Find by job_id (returns nil if not found)
+status = JobWorkflow::WorkflowStatus.find_by(job_id: "job-123")
+return unless status
+
+# Check workflow status
+status.status  # => :pending, :running, :succeeded, or :failed
+```
+
+### Status Check Methods
+
+```ruby
+# Convenient predicate methods
+status.pending?    # => true if not yet started
+status.running?    # => true if currently executing
+status.completed?  # => true if finished successfully
+status.failed?     # => true if execution failed
+```
+
+## Accessing Workflow Information
+
+### Basic Information
+
+```ruby
+status = JobWorkflow::WorkflowStatus.find("job-123")
+
+# Job class name
+status.job_class_name  # => "OrderProcessingJob"
+
+# Current task being executed (nil if not running)
+status.current_task_name  # => :validate_payment
+
+# Workflow execution status
+status.status  # => :running
+```
+
+### Arguments
+
+Access the immutable input arguments that were passed to the workflow:
+
+```ruby
+# Get Arguments object
+args = status.arguments
+
+# Access argument values
+args.order_id    # => 12345
+args.user_id     # => 789
+args.to_h        # => { order_id: 12345, user_id: 789 }
+```
+
+### Output
+
+Access the accumulated outputs from completed tasks:
+
+```ruby
+# Get Output object
+output = status.output
+
+# Access outputs by task name
+validation_output = output[:validate_payment].first
+validation_output.data  # => { valid: true, amount: 1000 }
+
+# Iterate over all outputs
+output.flat_task_outputs.each do |task_output|
+  puts "#{task_output.task_name}: #{task_output.data}"
+end
+```
+
+### Job Status
+
+Access detailed information about individual task executions:
+
+```ruby
+# Get JobStatus object
+job_status = status.job_status
+
+# Access task statuses by name
+task_statuses = job_status[:validate_payment]
+task_statuses.each do |task_status|
+  puts "Job ID: #{task_status.job_id}"
+  puts "Status: #{task_status.status}"  # :pending, :running, :succeeded, :failed
+  puts "Finished: #{task_status.finished?}"
+end
+
+# Iterate over all task statuses
+job_status.flat_task_job_statuses.each do |task_status|
+  puts "Task: #{task_status.task_name}, Status: #{task_status.status}"
+end
+```
+
+## Hash Representation
+
+Convert workflow status to a hash for serialization or API responses:
+
+```ruby
+status_hash = status.to_h
+# => {
+#   status: :running,
+#   job_class_name: "OrderProcessingJob",
+#   current_task_name: :validate_payment,
+#   arguments: { order_id: 12345, user_id: 789 },
+#   output: [
+#     {
+#       task_name: :fetch_order,
+#       each_index: 0,
+#       data: { order: {...} }
+#     }
+#   ]
+# }
+```
+
+## Practical Examples
+
+### REST API Endpoint
+
+```ruby
+# app/controllers/api/workflows_controller.rb
+class Api::WorkflowsController < ApplicationController
+  def show
+    status = JobWorkflow::WorkflowStatus.find_by(job_id: params[:id])
+    
+    if status
+      render json: {
+        id: params[:id],
+        status: status.status,
+        job_class: status.job_class_name,
+        current_task: status.current_task_name,
+        completed: status.completed?,
+        failed: status.failed?,
+        arguments: status.arguments.to_h,
+        outputs: status.output.flat_task_outputs.map do |output|
+          {
+            task: output.task_name,
+            data: output.data
+          }
+        end
+      }
+    else
+      render json: { error: "Workflow not found" }, status: :not_found
+    end
+  end
+end
+```
+
+### Progress Tracking
+
+```ruby
+# Track workflow progress
+class WorkflowProgressTracker
+  def self.track(job_id)
+    status = JobWorkflow::WorkflowStatus.find(job_id)
+    
+    # Calculate progress based on completed tasks
+    total_tasks = count_total_tasks(status.job_class_name)
+    completed_tasks = status.job_status.flat_task_job_statuses.count do |task_status|
+      task_status.succeeded?
+    end
+    
+    progress = (completed_tasks.to_f / total_tasks * 100).round(2)
+    
+    {
+      job_id: job_id,
+      status: status.status,
+      progress_percentage: progress,
+      current_task: status.current_task_name,
+      completed_tasks: completed_tasks,
+      total_tasks: total_tasks
+    }
+  end
+  
+  def self.count_total_tasks(job_class_name)
+    job_class = job_class_name.constantize
+    job_class._workflow.tasks.count
+  end
+end
+
+# Usage
+progress = WorkflowProgressTracker.track("job-123")
+# => {
+#   job_id: "job-123",
+#   status: :running,
+#   progress_percentage: 60.0,
+#   current_task: :process_payment,
+#   completed_tasks: 3,
+#   total_tasks: 5
+# }
+```
+
+### Monitoring Dashboard
+
+```ruby
+# Monitor all running workflows
+class WorkflowMonitor
+  def self.running_workflows
+    # Get all running job IDs from your queue adapter
+    # (Implementation depends on your queue backend)
+    running_job_ids = fetch_running_job_ids
+    
+    running_job_ids.map do |job_id|
+      status = JobWorkflow::WorkflowStatus.find_by(job_id: job_id)
+      next unless status&.running?
+      
+      {
+        job_id: job_id,
+        workflow: status.job_class_name,
+        current_task: status.current_task_name,
+        started_at: extract_start_time(status)
+      }
+    end.compact
+  end
+  
+  def self.failed_workflows(since: 1.hour.ago)
+    # Implementation depends on your queue backend
+    # Query failed jobs and return their status
+  end
+end
+```
+
+### Retry Failed Workflows
+
+```ruby
+# Check if workflow failed and retry with same arguments
+def retry_workflow_if_failed(job_id)
+  status = JobWorkflow::WorkflowStatus.find(job_id)
+  
+  if status.failed?
+    # Get the original arguments
+    original_args = status.arguments.to_h
+    
+    # Re-enqueue with same arguments
+    job_class = status.job_class_name.constantize
+    job_class.perform_later(**original_args)
+    
+    puts "Retried workflow: #{status.job_class_name} with args: #{original_args}"
+  end
+end
+```
+
+## Error Handling
+
+### NotFoundError
+
+When using `find`, a `JobWorkflow::WorkflowStatus::NotFoundError` is raised if the job is not found:
+
+```ruby
+begin
+  status = JobWorkflow::WorkflowStatus.find("invalid-job-id")
+rescue JobWorkflow::WorkflowStatus::NotFoundError => e
+  Rails.logger.error "Workflow not found: #{e.message}"
+  # Handle the error appropriately
+end
+```
+
+### Safe Queries
+
+Use `find_by` for safe queries that return `nil` instead of raising:
+
+```ruby
+status = JobWorkflow::WorkflowStatus.find_by(job_id: params[:job_id])
+
+if status.nil?
+  render json: { error: "Workflow not found" }, status: :not_found
+  return
+end
+
+# Process status...
+```
+
+## Limitations and Considerations
+
+1. **Context Restoration**: Status information is restored from serialized job data. Only information stored in the job's context is available.
+
+2. **completed_tasks Not Included**: The `completed_tasks` field is not included in the status response as it can become stale due to dynamic updates during workflow execution. Use `job_status` to track task completion.
+
+3. **Queue Adapter Dependency**: The `find_job` functionality depends on the queue adapter implementation. Ensure your queue adapter supports job lookup by ID.
+
+4. **Performance**: Querying workflow status involves deserializing job data. For high-frequency status checks, consider caching or implementing a dedicated status tracking system.

data/lib/job-workflow.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "job_workflow"

data/lib/job_workflow/argument_def.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class ArgumentDef
+    attr_reader :name #: Symbol
+    attr_reader :type #: String
+    attr_reader :default #: untyped
+
+    #:  (name: Symbol, type: String, default: untyped) -> void
+    def initialize(name:, type:, default:)
+      @name = name
+      @type = type
+      @default = default
+    end
+  end
+end

data/lib/job_workflow/arguments.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class Arguments
+    #: (data: Hash[Symbol, untyped]) -> void
+    def initialize(data:)
+      @data = data.freeze
+      @reader_names = data.keys.to_set
+    end
+
+    #: (Hash[Symbol, untyped] other_data) -> Arguments
+    def merge(other_data)
+      merged = data.merge(other_data.slice(*reader_names.to_a))
+      self.class.new(data: merged)
+    end
+
+    #: (Symbol name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> untyped
+    def method_missing(name, *args, **kwargs, &block)
+      return super unless args.empty? && kwargs.empty? && block.nil?
+      return super unless reader_names.include?(name.to_sym)
+
+      data[name.to_sym]
+    end
+
+    #: (Symbol sym, bool include_private) -> bool
+    def respond_to_missing?(sym, include_private)
+      reader_names.include?(sym.to_sym) || super
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      data
+    end
+
+    private
+
+    attr_reader :data #: Hash[Symbol, untyped]
+    attr_reader :reader_names #: Set[Symbol]
+  end
+end

data/lib/job_workflow/auto_scaling/adapter/aws_adapter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module JobWorkflow
+  module AutoScaling
+    module Adapter
+      class AwsAdapter
+        #:  (?ecs_client: Aws::ECS::Client?) -> void
+        def initialize(ecs_client: nil)
+          unless defined?(Aws::ECS::Client)
+            raise Error, "aws-sdk-ecs is required for JobWorkflow::AutoScaling::Adapter::AwsAdapter"
+          end
+
+          metadata_uri = ENV.fetch("ECS_CONTAINER_METADATA_URI_V4", nil)
+          raise Error, "ECS_CONTAINER_METADATA_URI_V4 is required on ECS" if metadata_uri.nil?
+
+          task_meta = JSON.parse(Net::HTTP.get(URI.parse("#{metadata_uri}/task")))
+
+          @ecs_client = ecs_client || Aws::ECS::Client.new
+          @cluster = task_meta.fetch("Cluster")
+          @task_arn = task_meta.fetch("TaskARN")
+        end
+
+        #:  (Integer) -> Integer?
+        def update_desired_count(desired_count)
+          service = describe_service
+          return if service.desired_count == desired_count
+
+          update_service(service: service, desired_count: desired_count)
+          desired_count
+        end
+
+        private
+
+        attr_reader :ecs_client #: Aws::ECS::Client
+        attr_reader :cluster #: String
+        attr_reader :task_arn #: String
+
+        #:  () -> String
+        def describe_service_name
+          task = ecs_client.describe_tasks({ cluster: cluster, tasks: [task_arn] }).tasks.first
+          raise Error, "Task(#{task_arn}) does not exist in cluster!" if task.nil?
+
+          task.group.delete_prefix("service:")
+        end
+
+        #:  () -> Aws::ECS::Types::Service
+        def describe_service
+          service_name = describe_service_name
+          response = ecs_client.describe_services({ cluster: cluster, services: [service_name] })
+          response.services.first || (raise Error, "Service(#{service_name}) does not exist in cluster!")
+        end
+
+        #:  (service: Aws::ECS::Types::Service, desired_count: Integer) -> Aws::ECS::Types::UpdateServiceResponse
+        def update_service(service:, desired_count:)
+          ecs_client.update_service(
+            { cluster: service.cluster_arn, service: service.service_name, desired_count: desired_count }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/job_workflow/auto_scaling/adapter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "adapter/aws_adapter"
+
+module JobWorkflow
+  module AutoScaling
+    module Adapter
+      # @rbs!
+      #   interface _ClassMethods
+      #     def new: () -> _InstanceMethods
+      #   end
+      #
+      #   interface _InstanceMethods
+      #     def class: () -> _ClassMethods
+      #     def update_desired_count: (Integer) -> Integer?
+      #   end
+
+      ADAPTERS = {
+        aws: AwsAdapter
+      }.freeze #: Hash[Symbol, _ClassMethods]
+      private_constant :ADAPTERS
+
+      class << self
+        #:  (Symbol) -> _ClassMethods
+        def fetch(adapter_name)
+          ADAPTERS.fetch(adapter_name)
+        end
+      end
+    end
+  end
+end

data/lib/job_workflow/auto_scaling/configuration.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module AutoScaling
+    class Configuration
+      attr_reader :queue_name #: String
+      attr_reader :min_count #: Integer
+      attr_reader :max_count #: Integer
+      attr_reader :step_count #: Integer
+      attr_reader :max_latency #: Integer
+
+      #
+      #:  (
+      #     ?queue_name: String,
+      #     ?min_count: Integer,
+      #     ?max_count: Integer,
+      #     ?step_count: Integer,
+      #     ?max_latency: Integer
+      #   ) -> void
+      def initialize(
+        queue_name: "default",
+        min_count: 1,
+        max_count: 1,
+        step_count: 1,
+        max_latency: 3_600
+      )
+        self.queue_name = queue_name
+        self.min_count = min_count
+        self.max_count = max_count
+        self.step_count = step_count
+        self.max_latency = max_latency
+      end
+
+      #:  () -> Integer
+      def latency_per_step_count
+        (max_latency / ((1 + max_count - min_count).to_f / step_count).ceil).tap do |value|
+          value.positive? || (raise Error, "latency per count isn't positive!")
+        end
+      end
+
+      #:  (String) -> void
+      def queue_name=(queue_name)
+        raise ArgumentError unless queue_name.instance_of?(String)
+
+        @queue_name = queue_name
+      end
+
+      #:  (Integer) -> void
+      def min_count=(min_count)
+        assert_positive_number!(min_count)
+
+        @min_count = min_count
+      end
+
+      #:  (Integer) -> void
+      def max_count=(max_count)
+        assert_positive_number!(max_count)
+
+        @max_count = max_count
+        @min_count = max_count if max_count < min_count
+      end
+
+      #:  (Integer) -> void
+      def step_count=(step_count)
+        assert_positive_number!(step_count)
+
+        @step_count = step_count
+      end
+
+      #:  (Integer) -> void
+      def max_latency=(max_latency)
+        assert_positive_number!(max_latency)
+
+        @max_latency = max_latency
+      end
+
+      private
+
+      #:  (Integer) -> void
+      def assert_positive_number!(number)
+        raise ArgumentError unless number.positive?
+      end
+    end
+  end
+end

data/lib/job_workflow/auto_scaling/executor.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module AutoScaling
+    class Executor
+      #:  (Configuration) -> void
+      def initialize(config)
+        @config = config
+      end
+
+      #:  () -> Integer?
+      def update_desired_count
+        adapter.update_desired_count(desired_count_by_latency)
+      end
+
+      private
+
+      attr_reader :config #: Configuration
+
+      #:  () -> Adapter::_InstanceMethods
+      def adapter
+        @adapter ||= Adapter.fetch(:aws).new
+      end
+
+      #:  () -> Integer?
+      def queue_latency
+        Queue.latency(config.queue_name)
+      end
+
+      #:  () -> Integer
+      def desired_count_by_latency
+        latency = queue_latency || 0
+
+        desired_count_list.at((latency.to_f / config.latency_per_step_count).floor.to_i) || config.max_count
+      end
+
+      #:  () -> Array[Integer]
+      def desired_count_list
+        config.min_count.step(config.max_count, config.step_count).to_a
+      end
+    end
+  end
+end

data/lib/job_workflow/auto_scaling.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "auto_scaling/adapter"
+require_relative "auto_scaling/configuration"
+require_relative "auto_scaling/executor"
+
+module JobWorkflow
+  # @example
+  #   ```ruby
+  #   class AutoScalingJob < ApplicationJob
+  #     include JobWorkflow::AutoScaling
+  #
+  #     target_queue_name "my_queue"
+  #     min_count 2
+  #     max_count 10
+  #     step_count 2
+  #     max_latency 1800
+  #   end
+  #   ```
+  module AutoScaling
+    extend ActiveSupport::Concern
+
+    # @rbs! extend ClassMethods
+
+    # @rbs!
+    #   def class: () -> ClassMethods
+
+    included do
+      class_attribute :_config, instance_writer: false, default: Configuration.new
+    end
+
+    #:  () -> void
+    def perform
+      Executor.new(self.class._config).update_desired_count
+    end
+
+    module ClassMethods
+      # @rbs!
+      #   def class_attribute: (Symbol, ?instance_writer: bool, default: untyped) -> void
+      #
+      #   def _config: () -> Configuration
+
+      #:  (String) -> void
+      def target_queue_name(queue_name)
+        _config.queue_name = queue_name
+      end
+
+      #:  (Integer) -> void
+      def min_count(min_count)
+        _config.min_count = min_count
+      end
+
+      #:  (Integer) -> void
+      def max_count(max_count)
+        _config.max_count = max_count
+      end
+
+      #:  (Integer) -> void
+      def step_count(step_count)
+        _config.step_count = step_count
+      end
+
+      #:  (Integer) -> void
+      def max_latency(max_latency)
+        _config.max_latency = max_latency
+      end
+    end
+  end
+end

data/lib/job_workflow/cache_store_adapters.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module CacheStoreAdapters
+    NAMESPACE = "job_workflow" #: String
+    private_constant :NAMESPACE
+
+    DEFAULT_OPTIONS = { namespace: NAMESPACE }.freeze #: Hash[Symbol, untyped]
+    private_constant :DEFAULT_OPTIONS
+
+    # @rbs!
+    #   def self._current: () -> ActiveSupport::Cache::Store
+    #   def self._current=: (ActiveSupport::Cache::Store?) -> void
+
+    mattr_accessor :_current
+
+    class << self
+      #:  () -> ActiveSupport::Cache::Store
+      def current
+        self._current ||= detect_adapter
+      end
+
+      #:  () -> void
+      def reset!
+        self._current = nil
+      end
+
+      private
+
+      # @note
+      #   - Rails.cache is NOT used directly because JobWorkflow requires namespace isolation from the Rails application's cache store.
+      #   - JobWorkflow caches are namespaced with "job_workflow" prefix to prevent key collisions with application-level caches.
+      #   - Using Rails.cache would share namespace configuration with the Rails app, which could lead to conflicts or unintended cache invalidations.
+      #   - Instead, JobWorkflow creates dedicated ActiveSupport::Cache::Store instances with explicit namespace options.
+      #
+      #:  () -> ActiveSupport::Cache::Store
+      def detect_adapter
+        if defined?(ActiveSupport::Cache::SolidCacheStore)
+          return ActiveSupport::Cache::SolidCacheStore.new(DEFAULT_OPTIONS.dup)
+        end
+
+        ActiveSupport::Cache::MemoryStore.new(DEFAULT_OPTIONS.dup)
+      end
+    end
+  end
+end