standard_procedure_operations 0.6.0 → 0.7.0

data/app/models/operations/{agent → task/plan}/wait_handler.rb

@@ -1,4 +1,4 @@
-class Operations::Agent::WaitHandler
+class Operations::Task::Plan::WaitHandler
   def initialize name, &config
     @name = name.to_sym
     @conditions = []
@@ -19,10 +19,10 @@ class Operations::Agent::WaitHandler
 
   def condition_labels = @condition_labels ||= {}
 
-  def call(task, data)
-    Rails.logger.debug { "#{task}: waiting until #{@name} with #{data}" }
-    condition = @conditions.find { |condition| data.instance_eval(&condition) }
-    next_state = (condition.nil? || @conditions.index(condition).nil?) ? task.state : @destinations[@conditions.index(condition)]
-    data.go_to next_state
+  def call(task)
+    Rails.logger.debug { "#{task}: waiting until #{@name}" }
+    condition = @conditions.find { |condition| task.instance_eval(&condition) }
+    next_state = (condition.nil? || @conditions.index(condition).nil?) ? task.current_state : @destinations[@conditions.index(condition)]
+    task.go_to next_state
   end
 end

data/app/models/operations/task/plan.rb

@@ -2,20 +2,21 @@ module Operations::Task::Plan
   extend ActiveSupport::Concern
 
   included do
-    attribute :state, :string
-    validate :state_is_valid
+    validate :current_state_is_legal
   end
 
   class_methods do
-    def starts_with(value) = @initial_state = value.to_sym
+    def starts_with(value) = @initial_state = value.to_s
 
-    def initial_state = @initial_state
+    def action(name, &handler) = state_handlers[name.to_s] = ActionHandler.new(name, &handler)
 
-    def decision(name, &config) = state_handlers[name.to_sym] = DecisionHandler.new(name, &config)
+    def decision(name, &config) = state_handlers[name.to_s] = DecisionHandler.new(name, &config)
 
-    def action(name, &handler) = state_handlers[name.to_sym] = ActionHandler.new(name, &handler)
+    def wait_until(name, &config) = state_handlers[name.to_s] = WaitHandler.new(name, &config)
 
-    def result(name, inputs: [], optional: [], &results) = state_handlers[name.to_sym] = ResultHandler.new(name, inputs, optional, &results)
+    def interaction(name, &implementation) = interaction_handlers[name.to_s] = InteractionHandler.new(name, self, &implementation)
+
+    def result(name) = state_handlers[name.to_s] = ResultHandler.new(name)
 
     def go_to(state)
       # Get the most recently defined action handler
@@ -25,13 +26,45 @@ module Operations::Task::Plan
       last_action.next_state = state.to_sym
     end
 
+    def initial_state = @initial_state || "start"
+
+    def delay(value) = @background_delay = value
+
+    def timeout(value) = @execution_timeout = value
+
+    def delete_after(value) = @deletion_time = value
+
+    def on_timeout(&handler) = @on_timeout = handler
+
+    def background_delay = @background_delay ||= 1.minute
+
+    def execution_timeout = @execution_timeout ||= 24.hours
+
+    def timeout_handler = @on_timeout
+
+    def deletion_time = @deletion_time ||= 90.days
+
     def state_handlers = @state_handlers ||= {}
 
-    def handler_for(state) = state_handlers[state.to_sym]
+    def handler_for(state) = state_handlers[state.to_s]
+
+    def interaction_handlers = @interaction_handlers ||= {}
+
+    def interaction_handler_for(name) = interaction_handlers[name.to_s]
+
+    def default_times = {wakes_at: background_delay.from_now, expires_at: execution_timeout.from_now, delete_at: deletion_time.from_now}
   end
 
-  private def handler_for(state) = self.class.handler_for(state.to_sym)
-  private def state_is_valid
-    errors.add :state, :invalid if state.blank? || handler_for(state.to_sym).nil?
+  def in?(state) = current_state == state.to_s
+  alias_method :waiting_until?, :in?
+
+  private def handler_for(state) = self.class.handler_for(state)
+  private def default_times = self.class.default_times
+  private def background_delay = self.class.background_delay
+  private def execution_timeout = self.class.execution_timeout
+  private def timeout_handler = self.class.timeout_handler
+  private def timeout_expired? = expires_at.present? && expires_at < Time.now.utc
+  private def current_state_is_legal
+    errors.add :current_state, :invalid if current_state.blank? || handler_for(current_state).nil?
   end
 end

data/app/models/operations/{agent → task}/runner.rb

@@ -1,5 +1,5 @@
 module Operations
-  class Agent::Runner
+  class Task::Runner
     def initialize
       @stopped = false
     end
@@ -9,8 +9,9 @@ module Operations
       register_signal_handlers
       puts "...signal handlers registered"
       until @stopped
-        process_timed_out_agents
-        process_waiting_agents
+        Rails.application.eager_load! if Rails.env.development? # Ensure all sub-classes are loaded in dev mode
+        Task.wake_sleeping
+        Task.delete_old
         sleep 30
       end
       puts "...stopping"
@@ -22,10 +23,6 @@ module Operations
 
     def self.start = new.start
 
-    private def process_timed_out_agents = Agent::FindTimeoutsJob.perform_later
-
-    private def process_waiting_agents = Agent::WakeAgentsJob.perform_later
-
     private def register_signal_handlers
       %w[INT TERM].each do |signal|
         trap(signal) { @stopped = true }

data/app/models/operations/task.rb

@@ -1,104 +1,70 @@
 module Operations
   class Task < ApplicationRecord
+    include HasAttributes
     include Plan
-    include Deletion
-    include Testing
-    include Exports
-    include HasDataAttributes
-    extend InputValidation
-
-    enum :status, in_progress: 0, waiting: 10, completed: 100, failed: -1
-    scope :active, -> { where(status: %w[in_progress waiting]) }
+    include Index
+    scope :ready_to_wake, -> { ready_to_wake_at(Time.current) }
+    scope :ready_to_wake_at, ->(time) { where(wakes_at: ..time) }
+    scope :expired, -> { expires_at(Time.current) }
+    scope :expired_at, ->(time) { where(expires_at: ..time) }
+    scope :ready_to_delete, -> { ready_to_delete_at(Time.current) }
+    scope :ready_to_delete_at, ->(time) { where(delete_at: ..time) }
+
+    # Task hierarchy relationships
+    belongs_to :parent, class_name: "Operations::Task", optional: true
+    has_many :sub_tasks, class_name: "Operations::Task", foreign_key: "parent_id", dependent: :nullify
+    has_many :active_sub_tasks, -> { where(status: ["active", "waiting"]) }, class_name: "Operations::Task", foreign_key: "parent_id"
+    has_many :failed_sub_tasks, -> { failed }, class_name: "Operations::Task", foreign_key: "parent_id"
+    has_many :completed_sub_tasks, -> { completed }, class_name: "Operations::Task", foreign_key: "parent_id"
+
+    enum :task_status, active: 0, waiting: 10, completed: 100, failed: -1
+    serialize :data, coder: JSON, type: Hash, default: {}
+    has_attribute :exception_class, :string
+    has_attribute :exception_message, :string
+    has_attribute :exception_backtrace, :string
+
+    def call(immediate: false)
+      while active?
+        Rails.logger.debug { "--- #{self}: #{current_state}" }
+        (handler_for(current_state).immediate? || immediate) ? handler_for(current_state).call(self) : go_to_sleep!
+      end
+    rescue => ex
+      record_error! ex
+      raise ex
+    end
 
-    serialize :data, coder: GlobalIdSerialiser, type: Hash, default: {}
-    serialize :results, coder: GlobalIdSerialiser, type: Hash, default: {}
+    def go_to(next_state) = update! current_state: next_state
 
-    has_many :task_participants, class_name: "Operations::TaskParticipant", dependent: :destroy
-    after_save :record_participants
+    def wake_up! = timeout_expired? ? call_timeout_handler : activate_and_call
 
-    def to_s = "#{model_name.human}:#{id}"
+    def start(task_class, **attributes) = task_class.later(**attributes.merge(parent: self))
 
-    def is?(state) = self.state.to_s == state.to_s
+    def record_error!(exception) = update!(task_status: "failed", exception_class: exception.class.to_s, exception_message: exception.message.to_s, exception_backtrace: exception.backtrace)
 
-    def active? = in_progress? || waiting?
+    private def go_to_sleep! = update!(default_times.merge(task_status: "waiting"))
 
-    def call sub_task_class, **data, &result_handler
-      Rails.logger.debug { "#{self}: call #{sub_task_class}" }
-      sub_task = sub_task_class.call(**data)
-      result_handler&.call(sub_task.results)
-      sub_task
+    private def activate_and_call
+      active!
+      call(immediate: true)
     end
 
-    def perform
-      return if failed?
-      in_progress!
-      Rails.logger.debug { "#{self}: performing #{state} with #{data}" }
-      handler_for(state).call(self, carrier_for(data))
+    private def call_timeout_handler
+      timeout_handler.nil? ? raise(Operations::Timeout.new("Timeout expired", self)) : timeout_handler.call
     rescue => ex
-      record_exception(ex)
+      record_error! ex
       raise ex
     end
 
-    class << self
-      def call(**data)
-        validate_inputs! data
-        create!(state: initial_state, status: "in_progress", data: data, status_message: "").tap do |task|
-          task.perform
-        end
-      end
-      alias_method :start, :call
-
-      def inputs(*names)
-        super
-        data_attributes(*names)
-      end
-
-      def optional(*names)
-        super
-        data_attributes(*names)
-      end
-    end
-
-    def go_to(state, data = {}, message: nil)
-      record_state_transition! state: state, data: data.to_h.except(:task), status_message: (message || state).to_s.truncate(240)
-      perform
-    end
+    def self.call(task_status: "active", **attributes) = create!(attributes.merge(task_status: task_status, current_state: initial_state).merge(default_times)).tap { |t| t.call }
 
-    def fail_with(message)
-      Rails.logger.error { "#{self}: failed #{message}" }
-      raise Operations::Failure.new(message, self)
-    end
+    def self.later(**attributes) = call(task_status: "waiting", **attributes)
 
-    def complete(results)
-      Rails.logger.debug { "#{self}: completed #{results}" }
-      update!(status: "completed", status_message: "completed", results: results.to_h)
-    end
+    def self.perform_now(...) = call(...)
 
-    protected def record_state_transition! **params
-      Rails.logger.debug { "#{self}: state transition to #{state}" }
-      params[:data] = params[:data].to_h.except(:task)
-      update! params
-    end
+    def self.perform_later(...) = later(...)
 
-    private def carrier_for(data) = data.is_a?(DataCarrier) ? data : DataCarrier.new(data.merge(task: self))
+    def self.wake_sleeping = Task.ready_to_wake.find_each { |t| Operations::WakeTaskJob.perform_later(t) }
 
-    private def record_exception(ex)
-      Rails.logger.error { "Exception in #{self} - #{ex.inspect}" }
-      update!(status: "failed", status_message: ex.message.to_s.truncate(240), results: {failure_message: ex.message, exception_class: ex.class.name, exception_backtrace: ex.backtrace})
-    end
-
-    private def record_participants
-      record_participants_in :data, data.select { |key, value| value.is_a? Participant }
-      record_participants_in :results, results.select { |key, value| value.is_a? Participant }
-    end
-
-    private def record_participants_in context, participants
-      task_participants.where(context: context).where.not(role: participants.keys).delete_all
-      participants.each do |role, participant|
-        task_participants.where(context: context, role: role).first_or_initialize.tap do |task_participant|
-          task_participant.update! participant: participant
-        end
-      end
-    end
+    def self.delete_old = Task.ready_to_delete.find_each { |t| Operations::DeleteOldTaskJob.perform_later(t) }
   end
 end

data/app/models/operations/task_participant.rb

@@ -1,14 +1,9 @@
 module Operations
   class TaskParticipant < ApplicationRecord
-    scope :as, ->(role) { where(role: role) }
-    scope :context, ->(context) { where(context: context) }
     belongs_to :task
     belongs_to :participant, polymorphic: true
 
-    validates :role, presence: true
-    validates :context, presence: true
-    validates :task_id, uniqueness: {scope: [:participant_type, :participant_id, :role, :context]}
-
-    scope :in, ->(context) { where(context: context) }
+    validates :attribute_name, presence: true
+    normalizes :attribute_name, with: ->(n) { n.to_s.strip }
   end
 end

data/db/migrate/20250701190516_rename_existing_operations_tables.rb

@@ -0,0 +1,19 @@
+class RenameExistingOperationsTables < ActiveRecord::Migration[8.0]
+  def up
+    remove_foreign_key :operations_task_participants, :operations_tasks, if_exists: true if table_exists?("operations_task_participants")
+
+    rename_table :operations_tasks, :operations_tasks_legacy if table_exists?("operations_tasks")
+    rename_table :operations_task_participants, :operations_task_participants_legacy if table_exists?("operations_task_participants")
+
+    add_foreign_key :operations_task_participants_legacy, :operations_tasks_legacy, column: :task_id if table_exists?("operations_task_participants_legacy")
+  end
+
+  def down
+    remove_foreign_key :operations_task_participants_legacy, :operations_tasks_legacy if table_exists?("operations_task_participants_legacy")
+
+    rename_table :operations_tasks_legacy, :operations_tasks if table_exists?("operations_task_legacy")
+    rename_table :operations_task_participants_legacy, :operations_task_participants if table_exists?("operations_task_participants_legacy")
+
+    add_foreign_key :operations_task_participants, :operations_tasks, column: :task_id if table_exists?("operations_task_participants")
+  end
+end

data/db/migrate/20250701190716_create_new_operations_tasks.rb

@@ -0,0 +1,20 @@
+class CreateNewOperationsTasks < ActiveRecord::Migration[8.0]
+  def change
+    create_table :operations_tasks do |t|
+      t.belongs_to :parent, foreign_key: {to_table: "operations_tasks"}, null: true
+      t.string :type
+      t.integer :task_status, default: 0, null: false
+      t.string :current_state, default: "start", null: false
+      t.text :data
+      t.datetime :wakes_at
+      t.datetime :expires_at
+      t.datetime :completed_at
+      t.datetime :failed_at
+      t.datetime :delete_at
+      t.timestamps
+
+      t.index [:task_status, :wakes_at], name: "operations_task_wakes_at"
+      t.index [:task_status, :delete_at], name: "operations_task_delete_at"
+    end
+  end
+end

data/db/migrate/20250702113801_create_task_participants.rb

@@ -0,0 +1,10 @@
+class CreateTaskParticipants < ActiveRecord::Migration[8.0]
+  def change
+    create_table :operations_task_participants do |t|
+      t.belongs_to :task, foreign_key: {to_table: "operations_tasks"}
+      t.belongs_to :participant, polymorphic: true, index: true
+      t.string :attribute_name, default: "", null: false
+      t.timestamps
+    end
+  end
+end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/operations.rb

@@ -1,5 +1,5 @@
 require "ostruct"
-require "global_id_serialiser"
+require "has_attributes"
 
 module Operations
   class Error < StandardError
@@ -9,12 +9,10 @@ module Operations
     end
     attr_reader :task
   end
-  require "operations/has_data_attributes"
   require "operations/version"
   require "operations/engine"
   require "operations/failure"
   require "operations/timeout"
   require "operations/no_decision"
   require "operations/invalid_state"
-  require "operations/exporters/svg"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Rahoul Baruah
 bindir: bin
 cert_chain: []
-date: 2025-05-29 00:00:00.000000000 Z
+date: 2025-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,7 +24,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 7.1.3
 - !ruby/object:Gem::Dependency
-  name: standard_procedure_global_id_serialiser
+  name: standard_procedure_has_attributes
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -47,39 +47,27 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- app/jobs/operations/agent/find_timeouts_job.rb
-- app/jobs/operations/agent/runner_job.rb
-- app/jobs/operations/agent/timeout_job.rb
-- app/jobs/operations/agent/wake_agents_job.rb
 - app/jobs/operations/application_job.rb
+- app/jobs/operations/delete_old_task_job.rb
+- app/jobs/operations/wake_task_job.rb
 - app/models/concerns/operations/participant.rb
-- app/models/operations/agent.rb
-- app/models/operations/agent/interaction_handler.rb
-- app/models/operations/agent/plan.rb
-- app/models/operations/agent/runner.rb
-- app/models/operations/agent/wait_handler.rb
 - app/models/operations/task.rb
-- app/models/operations/task/data_carrier.rb
-- app/models/operations/task/deletion.rb
-- app/models/operations/task/exports.rb
-- app/models/operations/task/input_validation.rb
+- app/models/operations/task/index.rb
 - app/models/operations/task/plan.rb
 - app/models/operations/task/plan/action_handler.rb
 - app/models/operations/task/plan/decision_handler.rb
+- app/models/operations/task/plan/interaction_handler.rb
 - app/models/operations/task/plan/result_handler.rb
-- app/models/operations/task/testing.rb
+- app/models/operations/task/plan/wait_handler.rb
+- app/models/operations/task/runner.rb
 - app/models/operations/task_participant.rb
 - config/routes.rb
-- db/migrate/20250127160616_create_operations_tasks.rb
-- db/migrate/20250309160616_create_operations_task_participants.rb
-- db/migrate/20250404085321_add_becomes_zombie_at_field.operations.rb
-- db/migrate/20250407143513_agent_fields.rb
-- db/migrate/20250408124423_add_task_participant_indexes.rb
+- db/migrate/20250701190516_rename_existing_operations_tables.rb
+- db/migrate/20250701190716_create_new_operations_tasks.rb
+- db/migrate/20250702113801_create_task_participants.rb
 - lib/operations.rb
 - lib/operations/engine.rb
-- lib/operations/exporters/svg.rb
 - lib/operations/failure.rb
-- lib/operations/has_data_attributes.rb
 - lib/operations/invalid_state.rb
 - lib/operations/matchers.rb
 - lib/operations/no_decision.rb

data/app/jobs/operations/agent/find_timeouts_job.rb

@@ -1,5 +0,0 @@
-class Operations::Agent::FindTimeoutsJob < ApplicationJob
-  queue_as :default
-
-  def perform = Operations::Agent.active.timed_out.find_each { |agent| Operations::AgentTimeoutJob.perform_later(agent) }
-end

data/app/jobs/operations/agent/runner_job.rb

@@ -1,5 +0,0 @@
-class Operations::Agent::RunnerJob < ApplicationJob
-  queue_as :default
-
-  def perform(agent) = agent.perform!
-end

data/app/jobs/operations/agent/timeout_job.rb

@@ -1,5 +0,0 @@
-class Operations::Agent::TimeoutJob < ApplicationJob
-  queue_as :default
-
-  def perform(agent) = agent.timeout!
-end

data/app/jobs/operations/agent/wake_agents_job.rb

@@ -1,5 +0,0 @@
-class Operations::Agent::WakeAgentsJob < ApplicationJob
-  queue_as :default
-
-  def perform = Operations::Agent.waiting.ready_to_wake.find_each { |agent| Operations::Agent::RunnerJob.perform_later(agent) }
-end

data/app/models/operations/agent/interaction_handler.rb

@@ -1,30 +0,0 @@
-class Operations::Agent::InteractionHandler
-  def initialize name, klass, &implementation
-    @legal_states = []
-    build_method_on klass, name, self, implementation
-  end
-  attr_reader :legal_states
-
-  def when *legal_states
-    @legal_states = legal_states.map(&:to_sym).freeze
-  end
-
-  private def call(task, data, *args)
-    data.instance_exec(*args, &@implementation)
-  end
-
-  private def build_method_on klass, name, handler, implementation
-    klass.define_method name.to_sym do |*args|
-      raise Operations::InvalidState.new("#{klass}##{name} cannot be called in #{state}") if !handler.legal_states.empty? && !handler.legal_states.include?(state.to_sym)
-      Rails.logger.debug { "#{data[:task]}: interaction #{name} with #{data}" }
-      carrier_for(data).tap do |data|
-        data.instance_exec(*args, &implementation)
-        record_state_transition! data: data
-        perform
-      end
-    rescue => ex
-      record_exception(ex)
-      raise ex
-    end
-  end
-end

data/app/models/operations/agent/plan.rb

@@ -1,38 +0,0 @@
-module Operations::Agent::Plan
-  extend ActiveSupport::Concern
-
-  class_methods do
-    def delay(value) = @background_delay = value
-
-    def timeout(value) = @execution_timeout = value
-
-    def on_timeout(&handler) = @on_timeout = handler
-
-    def wait_until(name, &config) = state_handlers[name.to_sym] = Operations::Agent::WaitHandler.new(name, &config)
-
-    def interaction(name, &implementation) = interaction_handlers[name.to_sym] = Operations::Agent::InteractionHandler.new(name, self, &implementation)
-
-    def background_delay = @background_delay ||= 5.minutes
-
-    def execution_timeout = @execution_timeout ||= 24.hours
-
-    def timeout_handler = @on_timeout
-
-    def interaction_handlers = @interaction_handlers ||= {}
-
-    def interaction_handler_for(name) = interaction_handlers[name.to_sym]
-  end
-
-  def timeout!
-    call_timeout_handler if timeout_expired?
-  end
-
-  private def background_delay = self.class.background_delay
-  private def execution_timeout = self.class.execution_timeout
-  private def timeout_handler = self.class.timeout_handler
-  private def timeout_expired? = times_out_at.present? && times_out_at < Time.now.utc
-  private def call_timeout_handler
-    record_state_transition!
-    timeout_handler.nil? ? raise(Operations::Timeout.new("Timeout expired", self)) : timeout_handler.call
-  end
-end

data/app/models/operations/agent.rb

@@ -1,31 +0,0 @@
-module Operations
-  class Agent < Task
-    include Plan
-    scope :ready_to_wake, -> { ready_to_wake_at(Time.now) }
-    scope :ready_to_wake_at, ->(time) { where(wakes_at: ..time) }
-    scope :timed_out, -> { timed_out_at(Time.now) }
-    scope :timed_out_at, ->(time) { where(times_out_at: ..time) }
-
-    def go_to(state, data = {}, message: nil)
-      record_state_transition! state: state, data: data.to_h, status_message: (message || state).to_s.truncate(240)
-      handler_for(state).immediate? ? perform : wait
-    end
-
-    def perform! = waiting? ? perform : nil
-
-    alias_method :waiting_until?, :is?
-
-    protected def record_state_transition! **params
-      params[:wakes_at] = Time.now.utc + background_delay
-      params[:times_out_at] ||= Time.now.utc + execution_timeout
-      super
-    end
-
-    private def wait
-      waiting!
-    rescue => ex
-      record_exception(ex)
-      raise ex
-    end
-  end
-end

data/app/models/operations/task/data_carrier.rb

@@ -1,16 +0,0 @@
-class Operations::Task::DataCarrier < OpenStruct
-  def fail_with(message) = task.fail_with(message)
-
-  def call(sub_task_class, **data, &result_handler) = task.call(sub_task_class, **data, &result_handler)
-
-  def go_to(state, data = nil) = task.go_to state, data || self
-
-  def complete(results) = task.complete(results)
-
-  def inputs(*names)
-    missing_inputs = (names.map(&:to_sym) - to_h.keys)
-    raise ArgumentError.new("Missing inputs: #{missing_inputs.join(", ")}") if missing_inputs.any?
-  end
-
-  def optional(*names) = nil
-end

data/app/models/operations/task/deletion.rb

@@ -1,17 +0,0 @@
-module Operations::Task::Deletion
-  extend ActiveSupport::Concern
-
-  included do
-    scope :for_deletion, -> { where(delete_at: ..Time.now.utc) }
-    attribute :delete_at, :datetime, default: -> { deletes_after.from_now.utc }
-    validates :delete_at, presence: true
-  end
-
-  class_methods do
-    def delete_after(value) = @@deletes_after = value
-
-    def deletes_after = @@deletes_after ||= 90.days
-
-    def delete_expired = for_deletion.destroy_all
-  end
-end