standard_procedure_operations 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04267db639d0804b8fdc04e3a6cbe07531ff5870948f0ba95d91c4383188c331
-  data.tar.gz: 02fef265e8c2bae6ba1c5178fccb9fad3b0eca6f1bd87b4bbb0d321a47e55f40
+  metadata.gz: a14742a79230259d8cb55462cac7682b6adfe8993cacc0ec4f35ed3832910858
+  data.tar.gz: 939c54f7cb755794ecd71ee920bfc1ff65f8e925187f6ccd9c1e98515d5a1b3d
 SHA512:
-  metadata.gz: 48a5aaf6c3c5f3b92bd274c62a1578b43c72212452b51ff934cdc3ff9ea8ad1eb8bd597d65db64185620a3cf1cde939bbfd19b78a8f297746d6d3b563b64a430
-  data.tar.gz: 97dbb727aa71212ba5bc485f83f1f5f68a07f3c40a08e37fe115b45246921c249917a5eee4fc841b6d23291cfa8f99d4e1bc80ae78472e62471e1b671f42f7b5
+  metadata.gz: 6c3ec1e16dada2b58d48aa72a11e64aaa7701b7a481836cc9b35ac268f752257b9dabf619eb43ecc6e4541fbc6ed50ae1b51d6ee4b4ed60fe4ad2ec302b1f8b8
+  data.tar.gz: 67d54e8449c264dc2fb1dd4883b64a810cabd47a2b976e931f1060d1573d0579c4964336159f6f8acf1d6d599ae3edf4de64b818f08c4c46c963035534264500

data/README.md

@@ -290,7 +290,24 @@ Instead of using the standard [JSON coder](https://api.rubyonrails.org/v4.2/clas
 
 If the original database record was deleted between the time the hash was serialised and when it was retrieved, the `GlobalID::Locator` will fail.  With ActiveJob, this means that the job cannot run and is discarded.  For Operations, we attempt to deserialise a second time, returning the GlobalID string instead of the model.  So be aware that when you access `data` or `results` you may receive a string (similar to `"gid://test-app/User/1"`) instead of the models you were expecting.  And the error handling deserialiser is very simple so you may get format changes in some of the data as well.  If serialisation fails you can access the original JSON string as `data.raw_data` or `results[:raw_data]`.  
 
-TODO: Replace the ActiveJob::Arguments deserialiser with the [transporter](https://github.com/standard-procedure/plumbing/blob/main/lib/plumbing/actor/transporter.rb) from [plumbing](https://github.com/standard-procedure/plumbing)
+#### Indexing data and results
+
+If you need to search through existing tasks by a model that is stored in the `data` or `results` fields - for example, you might want to list all operations that were started by a particular `User` - the models can be indexed alongside the task.  
+
+If your ActiveRecord model (in this example, `User`) includes the `Operations::Participant` module, it will be linked with any task that references that model.  A polymorphic join table, `operations_task_participants` is used for this.  Whenever a task is saved, any `Operations::Participant` records are located in the `data` and `results` collections and a `Operations::TaskParticipant` record created to join the model to the task.  The `context` attribute records whether the association is in the `data` or `results` collection and the `role` attribute is the name of the hash key.  
+
+For example, you create your task as:
+```ruby
+@alice = User.find 123
+@task = DoSomethingImportant.call user: @alice 
+```
+There will not be a `TaskParticipant` record with a `context` of "data", `role` of "user" and `participant` of `@alice`.  
+
+Likewise, you can see all the tasks that Alice was involved with using: 
+```ruby
+@alice.involved_in_operations_as("user") # => collection of tasks where Alice was a "user" in the "data" collection
+@alice.involved_in_operations_as("user", context: "results") # => collection of tasks where Alice was a "user" in the "results" collection
+```
 
 ### Failures and exceptions
 If any handlers raise an exception, the task will be terminated. It will be marked as `failed?` and the `results` hash will contain `results[:failure_message]`, `results[:exception_class]` and `results[:exception_backtrace]` for the exception's message, class name and backtrace respectively.  
@@ -626,12 +643,8 @@ The gem is available as open source under the terms of the [LGPL License](/LICEN
 - [x] Simplify calling sub-tasks (and testing them)
 - [ ] Figure out how to stub calling sub-tasks with known results data 
 - [ ] Figure out how to test the parameters passed to sub-tasks when they are called
-- [ ] Split out the state-management definition stuff from the task class (so you can use it without subclassing Operations::Task)
 - [x] Make Operations::Task work in the background using ActiveJob
 - [x] Add pause/resume capabilities (for example, when a task needs to wait for user input)
 - [x] Add wait for sub-tasks capabilities
 - [x] Add GraphViz visualization export for task flows
-- [ ] Add ActiveModel validations support for task parameters
 - [ ] Option to change background job queue and priority settings
-- [ ] Replace the ActiveJob::Arguments deserialiser with the [transporter](https://github.com/standard-procedure/plumbing/blob/main/lib/plumbing/actor/transporter.rb) from [plumbing](https://github.com/standard-procedure/plumbing)
-- [ ] Maybe? Split this out into two gems - one defining an Operation (pure ruby) and another defining the Task (using ActiveJob as part of a Rails Engine)

data/app/models/concerns/operations/participant.rb

@@ -0,0 +1,17 @@
+module Operations
+  module Participant
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :operations_task_participants, class_name: "Operations::TaskParticipant", as: :participant, dependent: :destroy
+      has_many :operations_tasks, class_name: "Operations::Task", through: :operations_task_participants, source: :task
+
+      scope :involved_in_operation_as, ->(role:, context: "data") do
+        joins(:operations_task_participants).tap do |scope|
+          scope.where(operations_task_participants: {role: role}) if role
+          scope.where(operations_task_participants: {context: context}) if context
+        end
+      end
+    end
+  end
+end

data/app/models/operations/task.rb

@@ -8,9 +8,13 @@ module Operations
     extend InputValidation
 
     enum :status, in_progress: 0, waiting: 10, completed: 100, failed: -1
+
     serialize :data, coder: Operations::GlobalIDSerialiser, type: Hash, default: {}
     serialize :results, coder: Operations::GlobalIDSerialiser, type: Hash, default: {}
 
+    has_many :task_participants, class_name: "Operations::TaskParticipant", dependent: :destroy
+    after_save :record_participants
+
     def call sub_task_class, **data, &result_handler
       sub_task = sub_task_class.call(**data)
       result_handler&.call(sub_task.results)
@@ -61,6 +65,20 @@ module Operations
 
     private def carrier_for(data) = data.is_a?(DataCarrier) ? data : DataCarrier.new(data.merge(task: self))
 
+    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.build(background:, **data)
       validate_inputs! data
       create!(state: initial_state, status: background ? "waiting" : "in_progress", data: data, status_message: "", background: background)

data/app/models/operations/task_participant.rb

@@ -0,0 +1,12 @@
+module Operations
+  class TaskParticipant < ApplicationRecord
+    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) }
+  end
+end

data/db/migrate/20250309_create_operations_task_participants.rb

@@ -0,0 +1,15 @@
+class CreateOperationsTaskParticipants < ActiveRecord::Migration[7.1]
+  def change
+    create_table :operations_task_participants do |t|
+      t.references :task, null: false, foreign_key: {to_table: :operations_tasks}
+      t.references :participant, polymorphic: true, null: false
+      t.string :role, null: false
+      t.string :context, null: false, default: "data"
+      t.timestamps
+    end
+
+    add_index :operations_task_participants, [:task_id, :participant_type, :participant_id, :role, :context],
+      name: "index_operations_task_participants_on_full_identity",
+      unique: true
+  end
+end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Rahoul Baruah
@@ -35,6 +35,7 @@ files:
 - Rakefile
 - app/jobs/operations/application_job.rb
 - app/jobs/operations/task_runner_job.rb
+- app/models/concerns/operations/participant.rb
 - app/models/operations/task.rb
 - app/models/operations/task/background.rb
 - app/models/operations/task/data_carrier.rb
@@ -47,8 +48,10 @@ files:
 - app/models/operations/task/state_management/decision_handler.rb
 - app/models/operations/task/state_management/wait_handler.rb
 - app/models/operations/task/testing.rb
+- app/models/operations/task_participant.rb
 - config/routes.rb
 - db/migrate/20250127160616_create_operations_tasks.rb
+- db/migrate/20250309_create_operations_task_participants.rb
 - lib/operations.rb
 - lib/operations/cannot_wait_in_foreground.rb
 - lib/operations/engine.rb