standard_procedure_operations 0.4.3 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04267db639d0804b8fdc04e3a6cbe07531ff5870948f0ba95d91c4383188c331
-  data.tar.gz: 02fef265e8c2bae6ba1c5178fccb9fad3b0eca6f1bd87b4bbb0d321a47e55f40
+  metadata.gz: d9a47b950a0831c0bf0a1be69de7b7f75c80237ec73a75673397a0b8112aa846
+  data.tar.gz: 62e9741fcd4053d0f4139aa956f5d51025d644188b2da460d6b7550873257030
 SHA512:
-  metadata.gz: 48a5aaf6c3c5f3b92bd274c62a1578b43c72212452b51ff934cdc3ff9ea8ad1eb8bd597d65db64185620a3cf1cde939bbfd19b78a8f297746d6d3b563b64a430
-  data.tar.gz: 97dbb727aa71212ba5bc485f83f1f5f68a07f3c40a08e37fe115b45246921c249917a5eee4fc841b6d23291cfa8f99d4e1bc80ae78472e62471e1b671f42f7b5
+  metadata.gz: 611b50e5912231a593187ea4dc59c5e270674f65413b1c3bbd34d3e1f40849f817954282750d729bdadf23a1bacb35b202c9fb71b2edaccfa59dddd209746234
+  data.tar.gz: 5b4fbf04648dfe9347330385f1dfdfc32eeadfe4adbb89a015a562c79b0a7b7f6e6b0e91b8d65f3d934e7f3af19bbaf8856ea39555cdd1b649f2ae9f2937ab81

data/README.md

@@ -48,7 +48,6 @@ class PrepareDocumentForDownload < Operations::Task
   starts_with :authorised?
 
   decision :authorised? do
-    inputs :user
     condition { user.can?(:read, data.document) }
 
     if_true :within_download_limits?
@@ -56,7 +55,6 @@ class PrepareDocumentForDownload < Operations::Task
   end
 
   decision :within_download_limits? do
-    inputs :user
     condition { user.within_download_limits? }
 
     if_true :use_filename_scrambler?
@@ -64,7 +62,6 @@ class PrepareDocumentForDownload < Operations::Task
   end
 
   decision :use_filename_scrambler? do
-    inputs :use_filename_scrambler
     condition { use_filename_scrambler }
 
     if_true :scramble_filename
@@ -72,16 +69,11 @@ class PrepareDocumentForDownload < Operations::Task
   end
 
   action :scramble_filename do
-    inputs :document
-
     self.filename = "#{Faker::Lorem.word}#{File.extname(document.filename.to_s)}"
-end
+  end
   go_to :return_filename
 
   result :return_filename do |results|
-    inputs :document
-    optional :filename
-
     results.filename = filename || document.filename.to_s
   end
 end
@@ -158,7 +150,9 @@ go_to :send_invitations
 You can also specify the required and optional data for your action handler using parameters or within the block. `optional` is decorative and helps with documentation. When using the block form, ensure you call `inputs` at the start of the block so that the task fails before doing any meaningful work.
 
 ```ruby 
-action :have_a_party, inputs: [:number_of_guests], optional: [:music] do
+action :have_a_party do 
+  inputs :number_of_guests 
+  optional :music
   self.food = task.buy_some_food_for(number_of_guests)
   self.beer = task.buy_some_beer_for(number_of_guests)
   self.music ||= task.plan_a_party_playlist
@@ -166,8 +160,6 @@ end
 go_to :send_invitations
 ```
 
-Defining state transitions statically with `go_to` ensures that all transitions are known when the operation class is loaded, making the flow easier to understand and analyze. The `go_to` method will automatically associate the transition with the most recently defined action handler.
-
 ### Waiting
 Wait handlers are very similar to decision handlers but only work within [background tasks](#background-operations-and-pauses).  
 
@@ -280,17 +272,36 @@ task = CombineNames.call first_name: "Alice", last_name: "Aardvark"
 task.results[:name] # => Alice Aardvark
 ```
 
-Because handlers are run in the context of the data carrier, you do not have direct access to methods or properties on your task object.  However, the data carrier holds a reference to your task; use `task.do_something` or `task.some_attribute` to access it.  The exception is the `fail_with`, `call` and `start` methods which the data carrier understands (and are intercepted when you are [testing](#testing)). Note that `go_to` has been removed from the data carrier to enforce static state transitions with the `go_to` method.  
+Because handlers are run in the context of the data carrier, you do not have direct access to methods or properties on your task object.  However, the data carrier holds a reference to your task; use `task.do_something` or `task.some_attribute` to access it.  The exception is the `fail_with`, `call` and `start` methods which the data carrier understands (and are intercepted when you are [testing](#testing)). 
 
 Both your task's `data` and its final `results` are stored in the database, so they can be examined later.  The `results` because that's what you're interested in, the `data` as it can be useful for debugging or auditing purposes.  
 
 They are both stored as hashes that are encoded into JSON.  
 
-Instead of using the standard [JSON coder](https://api.rubyonrails.org/v4.2/classes/ActiveModel/Serializers/JSON.html), we use a [GlobalIDSerialiser](/lib/operations/global_id_serialiser.rb).  This uses [ActiveJob::Arguments](https://guides.rubyonrails.org/active_job_basics.html#supported-types-for-arguments) to transform any models into [GlobalIDs](https://github.com/rails/globalid) before storage and convert them back to models upon retrieval.  
+Instead of using the standard [JSON coder](https://api.rubyonrails.org/v4.2/classes/ActiveModel/Serializers/JSON.html), we use a [GlobalIdSerialiser](https://github.com/standard-procedure/global_id_serialiser).  This serialises most data into standard JSON types, as you would expect, but it also takes any [GlobalID::Identification](https://github.com/rails/globalid) objects (which includes all ActiveRecord models) and converts them to a GlobalID string.  Then when the data is deserialised from the database, the GlobalID is converted back into the appropriate model.  
 
-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]`.  
+If the original database record was deleted between the time the hash was serialised and when it was retrieved, the `GlobalID::Locator` will fail.  In this case, the deserialised data will contain a `nil` for the value in question.  
 
-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)
+Also note that the GlobalIdSerialiser automatically converts all hash keys into symbols (unlike the standard JSON coder which uses strings).  
+
+#### 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.  
@@ -369,15 +380,11 @@ class UserRegistration < Operations::Task
   starts_with :create_user 
   
   action :create_user do 
-    inputs :email 
-
     self.user = User.create! email: email
   end
   go_to :send_verification_email
 
   action :send_verification_email do 
-    inputs :user 
-
     UserMailer.with(user: user).verification_email.deliver_later 
   end
   go_to :verified?
@@ -388,8 +395,6 @@ class UserRegistration < Operations::Task
   end 
 
   action :notify_administrator do 
-    inputs :user 
-
     AdminMailer.with(user: user).verification_completed.deliver_later
   end
 end
@@ -407,7 +412,6 @@ class ParallelTasks < Operations::Task
   starts_with :start_sub_tasks 
   
   action :start_sub_tasks do 
-    inputs :number_of_sub_tasks
     self.sub_tasks = (1..number_of_sub_tasks).collect { |i| start LongRunningTask, number: i }
   end
   go_to :do_something_else
@@ -581,7 +585,6 @@ end
 
 The visualization includes:
 - Color-coded nodes by state type (decisions, actions, wait states, results)
-- Required and optional inputs for each state
 - Transition conditions between states with custom labels when provided
 - Special handling for custom transition blocks
 
@@ -626,12 +629,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,8 +8,12 @@ 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: {}
+
+    serialize :data, coder: GlobalIdSerialiser, type: Hash, default: {}
+    serialize :results, coder: 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)
@@ -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.1"
 end

data/lib/operations.rb

@@ -1,4 +1,5 @@
 require "ostruct"
+require "global_id_serialiser"
 
 module Operations
   class Error < StandardError
@@ -10,7 +11,6 @@ module Operations
   end
   require "operations/version"
   require "operations/engine"
-  require "operations/global_id_serialiser"
   require "operations/failure"
   require "operations/cannot_wait_in_foreground"
   require "operations/timeout"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.1
 platform: ruby
 authors:
 - Rahoul Baruah
 bindir: bin
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.1.3
+- !ruby/object:Gem::Dependency
+  name: standard_procedure_global_id_serialiser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Pipelines and State Machines for composable, trackable business logic
 email:
 - rahoulb@echodek.co
@@ -35,6 +49,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,14 +62,15 @@ 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
 - lib/operations/exporters/graphviz.rb
 - lib/operations/failure.rb
-- lib/operations/global_id_serialiser.rb
 - lib/operations/matchers.rb
 - lib/operations/no_decision.rb
 - lib/operations/timeout.rb

data/lib/operations/global_id_serialiser.rb

@@ -1,29 +0,0 @@
-module Operations
-  # Serialise and deserialise data to and from JSON
-  # Unlike the standard JSON coder, this coder uses the ActiveJob::Arguments serializer.
-  # This means that if the data contains an ActiveRecord model, it will be serialised as a GlobalID string
-  #
-  # Usage:
-  # class MyModel < ApplicationRecord
-  #   serialize :data, coder: GlobalIDSerialiser, type: Hash, default: {}
-  # end
-  # @my_model = MyModel.create! data: {hello: "world", user: User.first}
-  # puts @my_model[:data] # => {hello: "world", user: #<User id: 1>}
-  class GlobalIDSerialiser
-    def self.dump(data) = ActiveSupport::JSON.dump(ActiveJob::Arguments.serialize([data]))
-
-    def self.load(json)
-      ActiveJob::Arguments.deserialize(ActiveSupport::JSON.decode(json)).first
-    rescue => ex
-      _load_without_global_ids(json).merge exception_message: ex.message, exception_class: ex.class.name, raw_data: json.to_s
-    end
-
-    def self._load_without_global_ids(json)
-      ActiveSupport::JSON.decode(json).first.tap do |hash|
-        hash.delete("_aj_symbol_keys")
-      end.transform_values do |value|
-        (value.is_a?(Hash) && value.key?("_aj_globalid")) ? value["_aj_globalid"] : value
-      end.transform_keys(&:to_sym)
-    end
-  end
-end