standard_procedure_operations 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 278552bfcbf35e101f4022a0d95004cc593473803b0b6578349afe945c1b6d18
-  data.tar.gz: 6be975b9b3d9b88e67eb63cef2cb582c9fbb12ff7b881a1ceb288f33ac74c21d
+  metadata.gz: f99019aca1964cfe7e6607d45c1c253ed73f8081702b596bb6fdbb918c7d74f7
+  data.tar.gz: 8c6599fe4f7227226ecc23773902eb8f2c3e0a5d37d2f6f3a918a8dfff8ee35b
 SHA512:
-  metadata.gz: d271751ea12a1efd3083b32445ae3dfceeadcdea464702515ff83bfbf1c91157192bf4797149557ca0a1009d9963a97fcd62910359b78375d15eb2225f5c9612
-  data.tar.gz: 670ac183d0f130c4086ac4d0057e265fc69bdc5f7898628837fd8ed831588551d5cf1c37b9c81e8a4cfa104a957ba4caee870fc943f655201ab38baf1a9909b8
+  metadata.gz: 2d40c6a60efea70434ae993ad37d5872f71173cf1c4d6e61cf436f735538dc9e72c9d268a40a7c7be81ebb66a7bc46ff70b868ff6af66bf30db1c574eca8787b
+  data.tar.gz: 5931d257ab4d45b04d20f96244ce20a65d292808bf10eae66930fcfe0bf35e52d1c539bde83c8fabf8ddff0cdb44be548f763b0949671aaaa5309bda039f285d

data/README.md

@@ -49,6 +49,7 @@ class PrepareDocumentForDownload < Operations::Task
 
   decision :authorised? do
     inputs :user
+    condition { user.can?(:read, data.document) }
 
     if_true :within_download_limits?
     if_false { fail_with "unauthorised" }
@@ -56,6 +57,7 @@ class PrepareDocumentForDownload < Operations::Task
 
   decision :within_download_limits? do
     inputs :user
+    condition { user.within_download_limits? }
 
     if_true :use_filename_scrambler?
     if_false { fail_with "download_limit_reached" }
@@ -82,21 +84,19 @@ class PrepareDocumentForDownload < Operations::Task
 
     results.filename = filename || document.filename.to_s
   end
-
-  private def authorised?(data) = data.user.can?(:read, data.document)
-  private def within_download_limits?(data) = data.user.within_download_limits?
 end
+
+task = PrepareDocumentForDownload.call user: @user, document: @document, use_filename_scrambler: @account.feature_flags[:use_filename_scramber]
+puts task.results[:filename]
 ```
 
-The five states are represented as three [decision](#decisions) handlers, one [action](#actions) handler and a [result](#results) handler.  
+The task declares that it requires `user`, `document` and `use_filename_scrambler` parameters and that it starts in the `authorised?` state.  
 
-The task also declares that it requires a `user`, `document` and `use_filename_scrambler` parameter to be provided, and also declares its initial state - `authorised?`.  
+The five states are represented as three [decision](#decisions) handlers, one [action](#actions) handler and a [result](#results) handler.  
 
 ### Decisions
 A decision handler evaluates a condition, then changes state depending upon if the result is true or false. 
 
-It's up to you whether you define the condition as a block, as part of the decision handler, or as a method on the task object.  
-
 ```ruby
 decision :is_it_the_weekend? do 
   condition { Date.today.wday.in? [0, 6] }
@@ -105,40 +105,29 @@ decision :is_it_the_weekend? do
   if_false :go_to_work
 end
 ```
-Or
-```ruby
-decision :is_it_the_weekend? do 
-  if_true :have_a_party 
-  if_false :go_to_work
-end
-
-def is_it_the_weekend?(data)
-  Date.today.wday.in? [0, 6]
-end
-```
-
-A decision can also mark a failure, which will terminate the task.  
+A decision can also mark a failure, which will terminate the task and raise an `Operations::Failure`.  
 ```ruby
 decision :authorised? do 
   condition { user.administrator? }
+
   if_true :do_some_work 
   if_false { fail_with "Unauthorised" }
 end
 ```
+(In theory the block used in the `fail_with` case can do anything within the [DataCarrier context](#data-and-results) - so you could set internal state or call methods on the containing task - but I've not tried this yet).
 
 You can specify the data that is required for a decision handler to run by specifying `inputs` and `optionals`:
 ```ruby
 decision :authorised? do 
-  inputs  :user 
-  optionals :override
-
+  inputs :user 
+  optional :override
   condition { override || user.administrator? }
 
   if_true :do_some_work 
   if_false { fail_with "Unauthorised" }
 end
 ```
-In this case, the task will fail if there is no `user` specified.  However, `override` is optional (and in fact the `optional` method is just there to help you document your operations).
+In this case, the task will fail (with an `ArgumentError`) if there is no `user` specified.  However, `override` is optional (in fact the `optional` method does nothing and is just there for documentation purposes).
 
 ### Actions
 An action handler does some work, then moves to another state.  
@@ -148,51 +137,40 @@ action :have_a_party do
   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
+
   go_to :send_invitations
 end
 ```
-You can specify the required and optional data for your action handler within the block.  `optional` is decorative and to help with your documentation.  Ensure you call `inputs` at the start of the block.  
+You can specify the required and optional data for your action handler within the block.  `optional` is decorative and to help with your documentation.  Ensure you call `inputs` at the start of the block so that the task fails before you do any meaningful work.  
 
 ```ruby 
 action :have_a_party do
-  inputs :task 
+  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
-  go_to :send_invitations
-end
-```
 
-Again, instead of using a block in the action handler, you could provide a method to do the work.  However, you cannot specify `inputs` or `optional` data when using a method.  
-
-```ruby
-action :have_a_party
-
-def have_a_party(data)
-  data.food = buy_some_food_for(data.number_of_guests)
-  data.beer = buy_some_beer_for(data.number_of_guests)
-  data.music = plan_a_party_playlist
   go_to :send_invitations
 end
 ```
-Note that when using a method you need to refer to the `data` parameter directly, when using a block, you need to refer to the `task` - see the section on "[Data](#data-and-results)" for more information.
+Do not forget to call `go_to` from your action handler, otherwise the operation will just stop whilst still being marked as in progress.  (TODO: don't let this happen).
 
-Do not forget to call `go_to` from your action handler, otherwise the operation will just stop whilst still being marked as in progress.  
+### Waiting
+Wait handlers only work within [background tasks](#background-operations-and-pauses).  They define a condition that is evaluated; if it is false, the task is paused and the condition re-evaluated later.  If it is true, the task moves to the next state.  
 
 ### Results
-A result handler marks the end of an operation, optionally returning some results.  You need to copy your desired results from your [data](#data-and-results) to your results object.  This is so only the information that matters to you is stored in the database (as many operations may have a large set of working data).  
-
-There is no method equivalent to a block handler.  
+A result handler marks the end of an operation, optionally returning some results.  You need to copy your desired results from your [data](#data-and-results) to your results object.  This is so only the information that matters to you is stored as the results.  
 
 ```ruby
 action :send_invitations do 
   self.invited_friends = (0..number_of_guests).collect do |i|
     friend = friends.pop
-    FriendsMailer.with(recipient: friend).party_invitation.deliver_later
+    FriendsMailer.with(recipient: friend).party_invitation.deliver_later unless friend.nil?
     friend 
-  end
+  end.compact
+
   go_to :ready_to_party
 end
 
@@ -211,12 +189,14 @@ In this case, the task will be marked as `completed?`, the task's state will be
 You can also specify the required and optional data for your result handler within the block.  `optional` is decorative and to help with your documentation.  Ensure you call `inputs` at the start of the block.  
 ```ruby
 action :send_invitations do 
-  inputs :number_of_guests
+  inputs :number_of_guests, :friends
+
   self.invited_friends = (0..number_of_guests).collect do |i|
     friend = friends.pop
-    FriendsMailer.with(recipient: friend).party_invitation.deliver_later
+    FriendsMailer.with(recipient: friend).party_invitation.deliver_later unless friend.nil?
     friend 
-  end
+  end.compact
+
   go_to :ready_to_party
 end
 
@@ -225,6 +205,7 @@ result :ready_to_party do |results|
 
   results.invited_friends = invited_friends
 end
+```
 
 ### Calling an operation
 You would use the earlier [PrepareDocumentForDownload](spec/examples/prepare_document_for_download_spec.rb) operation in a controller like this:
@@ -232,41 +213,65 @@ You would use the earlier [PrepareDocumentForDownload](spec/examples/prepare_doc
 ```ruby
 class DownloadsController < ApplicationController 
   def show 
-    @document = Document.includes(:account).find(params[:id])
-    @task = PrepareDocumentForDownload.call(user: Current.user, document: @document, use_filename_scrambler: @document.account.use_filename_scrambler?)
-    if @task.completed?
-      @filename = @task.results.filename
-      send_data @document.contents, filename: @filename, disposition: "attachment"
-    else
-      render action: "error", message: @task.results.failure_message, status: 401
-    end
+    @document = Document.find(params[:id])
+    @task = PrepareDocumentForDownload.call(user: Current.user, document: @document, use_filename_scrambler: Current.account.use_filename_scrambler?)
+
+    send_data @document.contents, filename: @task.results[:filename], disposition: "attachment"
+
+  rescue => failure
+    render action: "error", locals: {error: failure.message}, status: 422
   end
 end
 ```
 
-OK - so that's a pretty longwinded way of performing a simple task.  But, in Collabor8Online, the actual operation for handling downloads has over twenty states, with half of them being decisions (as there are a number of feature flags and per-account configuration options).  When you get to complex decision trees like that, being able to lay them out as state transitions becomes invaluable.  
+OK - so that's a pretty longwinded way of performing a simple task.  
+
+But many operations end up as complex flows of conditionals and actions, often spread across multiple classes and objects.  This means that someone trying to understand the rules for an operation can spend a lot of time tracing through code, understanding that flow.  
+
+In Collabor8Online, the actual operation for handling downloads has over twenty states, with half of them being decisions (there are a number of feature flags and per-account configuration options which need to be considered).  Now they are defined as four ruby classes (using [composition](#sub-tasks) to split the workload) and the logic is extremely easy to follow.  
 
 ### Data and results
-Each operation carries its own, mutable, data for the duration of the operation.  This is provided when you `call` the operation to start it and is passed through to each decision, action and result.  This data is transient and not stored in the database. If you modify the data then that modification is passed on to the next handler.  
+Each operation carries its own, mutable, [data](/app/models/operations/task/data_carrier.rb) for the duration of the operation.  
+
+This is provided when you `call` the operation to start it and is passed through to each decision, action and result.  If you modify the data then that modification is passed on to the next handler.  
+
+Within handlers you can read the data directly (the implementation uses `instance_eval`/`instance_exec`).  Here the `build_name` action knows the `first_name` and `last_name` provided and adds in a new property of `name`.  
+
+```ruby 
+class CombineNames < Operations::Task 
+  inputs :first_name, :last_name 
+  starts_with :build_name 
+
+  action :build_name do 
+    self.name = "#{first_name} #{last_name}"
+    go_to :done 
+  end
+
+  result :done do |results|
+    results.name = name 
+  end
+end
 
-For example, in the [DownloadsController](#calling-an-operation) shown above, the `user`, `document` and `use_filename_scrambler` are set within the data object when the operation is started.  But if the `scramble_filename` action is called, it generates a new filename and adds that to the data object as well.  Finally the `return_filename` result handler then returns either the scrambled or the original filename to the caller. 
+task = CombineNames.call first_name: "Alice", last_name: "Aardvark"
+task.results[:name] # => Alice Aardvark
+```
 
-Within handlers implemented as blocks, you can read the data directly - for example, `condition { use_filename_scrambler }` from the `use_filename_scrambler?` decision shown earlier.  If you want to modify a value, or add a new one, you must use `self` - `self.my_data = "something important"`.  
+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 exceptions are the `go_to`, `fail_with`, `call` and `start` methods which the data carrier understands (and are intercepted when you are [testing](#testing)).  
 
-This is because the data is carried using a [DataCarrier](/app/models/operations/task/data_carrier.rb) object and `instance_eval` is used within your block handlers.  
+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.  
 
-This also means that block handlers must use `task.method` to access methods or data on the task object itself (as you are not actually within the context of the task object itself).  The exceptions are the `go_to` and `fail_with` methods which the data carrier forwards to the task.  
+They are both stored as hashes that are encoded into JSON.  
 
-Handlers can alternatively be implemented as methods on the task itself.  This means that they are executed within the context of the task and can methods and variables belonging to the task.  Each handler method receives a `data` parameter which is the data carrier for that task.  Individual items can be accessed as a hash - `data[:my_item]` - or as an attribute - `data.my_item`.  
+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.  
 
-The final `results` data from any `result` handlers is stored, along with the task, in the database, so it can be examined later.  It is a Hash that is encoded into JSON with any ActiveRecord models translated using a [GlobalID](https://github.com/rails/globalid) (this uses [ActiveJob::Arguments](https://guides.rubyonrails.org/active_job_basics.html#supported-types-for-arguments) so works the same way as passing models to ActiveJob).  
+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]`.  
 
-Be aware that if you do store an ActiveRecord model into your `results` and that model is later deleted from the database, your task's `results` will be unavailable (as `GlobalID::Locator` will fail when it tries to load the record).  The data is not lost though - if the deserialisation fails, the routine will return the JSON string as `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)
 
 ### 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.  
 
-You can also stop a task at any point by calling `fail_with message`.  This will mark the task as `failed?` and the `reeults` has will contain `results[:failure_message]`.
+You can also stop a task at any point by calling `fail_with message`.  This will raise an `Operations::Failure` exception, marking the task as `failed?` and the `results` has will contain `results[:failure_message]`.
 
 ### Task life-cycle and the database
 There is an ActiveRecord migration that creates the `operations_tasks` table.  Use `bin/rails operations:install:migrations` to copy it to your application, then run `bin/rails db:migrate` to add the table to your application's database.  
@@ -279,22 +284,163 @@ This gives you a number of possibilities:
 - tasks can run in the background (using ActiveJob) and other parts of your code can interact with them whilst they are in progress - see "[background operations](#background-operations-and-pauses)" below
 - the tasks table acts as an audit trail or activity log for your application
 
-However, it also means that your database table could fill up with junk that you're no longer interested in.  Therefore you can specify the maximum age of a task and, periodically, clean old tasks away.  Every task has a `delete_at` field that, by default, is set to `90.days.from_now`.  This can be changed by calling `Operations::Task.delete_after 7.days` (or whatever value you prefer).  Then, run a cron job (once per day) that calls `Operations::Task.delete_expired`, removing any tasks whose `deleted_at` date has passed.  
+However, it also means that your database table could fill up with junk that you're no longer interested in.  Therefore you can specify the maximum age of a task and, periodically, clean old tasks away.  Every task has a `delete_at` field that, by default, is set to `90.days.from_now`.  This can be changed by calling `Operations::Task.delete_after 7.days` (or whatever value you prefer) in an initializer.  Then, run a cron job, or other scheduled task, once per day that calls `Operations::Task.delete_expired`.  This will delete any tasks whose `delete_at` time has passed.  
 
 ### Status messages
 Documentation coming soon.  
 
-### Child tasks
-Coming soon.  
+### Sub tasks
+Any operation can be composed out of other operations and can therefore call other subtasks.  
+
+```ruby
+class PrepareDownload < Operations::Task 
+  inputs :user, :document 
+  starts_with :get_authorisation
+  
+  action :get_authorisation do 
+    inputs :user, :document 
+
+    results = call GetAuthorisation, user: user, document: document 
+    self.authorised = results[:authorised]
+
+    go_to :whatever_happens_next
+  end
+end
+```
+If the sub-task succeeds, `call` returns the results from the sub-task.  If it fails, then any exceptions are re-raised.  
+
+You can also access the results in a block: 
+```ruby
+class PrepareDownload < Operations::Task 
+  inputs :user, :document 
+  starts_with :get_authorisation
+  
+  action :get_authorisation do 
+    inputs :user, :document 
+
+    call GetAuthorisation, user: user, document: document do |results|
+      self.authorised = results[:authorised]
+    end
+
+    go_to :whatever_happens_next
+  end
+end
+```
+
+If you want the sub-task to be a [background task](#background-operations-and-pauses), use `start` instead of `call`.  This will return the newly created sub-task immediately.  As the sub-task will not have completed, you cannot access its results unless you [wait](#waiting-for-sub-tasks-to-complete) (which is only possible if the parent task is a background task as well).  
 
 ### Background operations and pauses
-Coming soon.  
+If you have ActiveJob configured, you can run your operations in the background.  
+
+Instead of using `call`, use `start` to initiate the operation.  This takes the same data parameters and returns a task object that you can refer back to.  But it will be `waiting?` instead of `in_progress?` or `completed?`.  An `Operations::TaskRunnerJob` will be queued and it will mark the task as `in_progress?`, then call a _single_ state handler.  Instead of handling the next state immediately another `Operations::TaskRunnerJob` is queued.  And so on, until the task either fails or is completed.  
+
+By itself, this is not particularly useful - it just makes your operation take even longer to complete.  
+
+But if your operation may need to wait for something else to happen, background tasks are perfect.  
+
+#### Waiting for user input
+For example, maybe you're handling a user registration process and you need to wait until the verification link has been clicked.  The verification link goes to another controller and updates the user record in question.  Once clicked, you can then notify the administrator.  
+
+```ruby
+class UserRegistration < Operations::Task 
+  inputs :email
+  starts_with :create_user 
+  
+  action :create_user do 
+    inputs :email 
+
+    self.user = User.create! email: email
+    go_to :send_verification_email 
+  end 
+
+  action :send_verification_email do 
+    inputs :user 
+
+    UserMailer.with(user: user).verification_email.deliver_later 
+    go_to :verified? 
+  end 
+
+  wait_until :verified? do 
+    condition { user.verified? }
+    go_to :notify_administrator 
+  end 
+
+  action :notify_administrator do 
+    inputs :user 
+
+    AdminMailer.with(user: user).verification_completed.deliver_later
+  end
+end
+
+@task = UserRegistration.start email: "someone@example.com"
+```
+Because background tasks use ActiveJobs, every time the `verified?` condition is evaluated, the task object (and hence its data) will be reloaded from the database.  So the `user.verified?` property will be refreshed on each evaluation.  
+
+#### Waiting for sub-tasks to complete
+Alternatively, you may have a number of sub-tasks that you want to run in parallel then continue once they have all completed.  This allows you to spread their execution across multiple processes or even servers (depending upon how your job queue processes are configured).
+
+```ruby
+class ParallelTasks < Operations::Task 
+  inputs :number_of_sub_tasks
+  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 }
+    go_to :do_something_else 
+  end 
+
+  action :do_something_else do 
+    # do something else while the sub-tasks do their thing
+    go_to :sub_tasks_completed? 
+  end 
+
+  wait_until :sub_tasks_completed? do 
+    condition { sub_tasks.all? { |t| t.completed? } }
+    go_to :done
+  end 
+
+  result :done 
+end
+
+@task = ParallelTasks.start number_of_sub_tasks: 5
+```
+The principle is the same as above; we store the newly created sub-tasks in our own `data` property.  As they are ActiveRecord models, they get reloaded each time `sub_tasks_completed?` is evaluated - and we check to see that they have all completed before moving on.  
+
+#### Delays and Timeouts
+When you run an operation in the background, it schedules an [ActiveJob](app/jobs/operations/task_runner_job.rb) which performs the individual state handler, scheduling a follow-up job for subsequent states.  By default, these jobs are scheduled to run after 1 second - so a five state operation will take a minimum of five seconds to complete (depending upon the backlog in your job queues).  This is to prevent a single operation from starving the job process of resources and allow other ActiveJobs the time to execute.  
+
+However, if you know that your `wait_until` condition may take a while you can change the default delay to something longer.  In your operations definition, declare the required delay: 
+
+```ruby
+class ParallelTasks < Operations::Tasks 
+  delay 1.minute
+  ...
+end
+```
+
+Likewise, it's possible for a background task to get stuck.  In the sub-tasks example above, if one of the sub-tasks fails, waiting for them _all_ to complete will never happen.  Every operation has a default timeout of 5 minutes - if the operation has not completed or failed 5 minutes after it was initially started, it will fail with an `Operations::Timeout` exception.  
+
+If you need to change this (such as the user verification example above), you can declare the timeout when defining the operation.  Long timeouts fit well with longer delays, so you're not filling the job queues with jobs that are meaninglessly evaluating your conditions.
+
+```ruby
+class UserRegistration < Operations::Task 
+  timeout 24.hours 
+  delay 15.minutes
+  ...
+end
+```
 
 ## Testing
 Because operations are intended to model long, complex, flowcharts of decisions and actions, it can be a pain coming up with the combinations of inputs to test every path through the sequence.  
 
-Instead, you can test each state handler in isolation.  As the handlers are state-less, we can simulate calling one by creating a task object and then calling the appropriate handler with the data that it expects.  This is done by calling `handling`, which yields a `test` object with outcomes from the handler that we can inspect
+Instead, you can test each state handler _in isolation_.  
+
+As the handlers are stateless, we can call one without hitting the database; instead creating a dummy task object and then triggering the handler with the correct parameters.  
+
+This is done by calling `handling`, which yields a `test` object that we can inspect.
 
+### Testing state transitions
 To test if we have moved on to another state (for actions or decisions):
 ```ruby
 MyOperation.handling(:an_action_or_decision, some: "data") do |test|
@@ -303,19 +449,23 @@ MyOperation.handling(:an_action_or_decision, some: "data") do |test|
   expect(test).to have_moved_to "new_state"
 end
 ```
+
+### Testing data modifications
 To test if some data has been set or modified (for actions):
 ```ruby
 MyOperation.handling(:an_action, existing_data: "some_value") do |test|
-  # has a new data value been added?
-  assert_equal test.new_data, "new_value"
-  # or
-  expect(test.new_data).to eq "new_value"
   # has an existing data value been modified?
   assert_equal test.existing_data, "some_other_value"
   # or
   expect(test.existing_data).to eq "some_other_value"
+  # has a new data value been added?
+  assert_equal test.new_data, "new_value"
+  # or
+  expect(test.new_data).to eq "new_value"
 end
 ```
+
+### Testing results
 To test the results from a result handler:
 ```ruby
 MyOperation.handling(:a_result, some: "data") do |test|
@@ -330,14 +480,33 @@ end
 ```
 (Note - although results are stored in the database as a Hash, within your test, the results object is still carried as an OpenStruct, so you can access it using either notation).
 
+### Testing sub-tasks 
+```ruby 
+MyOperation.handling(:a_sub_task, some: "data") do |test|
+  # Test which sub-tasks were called
+  assert_includes test.sub_tasks.keys, MySubTask
+  # or 
+  expect(test.sub_tasks).to include MySubTask
+end
+```
+TODO: I'm still figuring out how to test the data passed to sub-tasks.  And calling a sub-task will actually execute that sub-task, so you need to stub `MySubTask.call` if it's an expensive operation.  
+
+```ruby 
+# Sorry, don't know the Minitest syntax for this
+@sub_task = double "Operations::Task", results: { some: "answers" }
+allow(MySubTask).to receive(:call).and_return(@sub_task)
+
+MyOperation.handling(:a_sub_task, some: "data") do |test|
+  expect(test.sub_tasks).to include MySubTask
+end
+```
+### Testing failures 
 To test if a handler has failed:
 ```ruby
-MyOperation.handling(:a_failure, some: "data") do |test|
-  assert_equal test.failure_message, "oh dear"
-  # or
-  expect(test).to have_failed_with "oh dear"
-end
+
+expect { MyOperation.handling(:a_failure, some: "data") }.to raise_error(SomeException)
 ```
+
 If you are using RSpec, you must `require "operations/matchers"` to make the matchers available to your specs.  
 
 ## Installation
@@ -356,14 +525,14 @@ class DailyLife < Operations::Task
   starts_with :am_i_awake?
 
   decision :am_i_awake? do 
+    condition { (7..23).include?(Time.now.hour) }
+
     if_true :live_like_theres_no_tomorrow 
     if_false :rest_and_recuperate
   end 
 
   result :live_like_theres_no_tomorrow 
   result :rest_and_recuperate
-
-  def am_i_awake? = (7..23).include?(Time.now.hour)
 end
 ```
 Step 4: If you're using RSpec for testing, add `require "operations/matchers" to your "spec/rails_helper.rb" file.
@@ -374,9 +543,16 @@ The gem is available as open source under the terms of the [LGPL License](/LICEN
 ## Roadmap
 
 - [x] Specify inputs (required and optional) per-state, not just at the start
-- [ ] Always raise errors instead of just recording a failure (will be useful when dealing with sub-tasks)
-- [ ] Simplify calling sub-tasks (and testing the same)
+- [x] Always raise errors instead of just recording a failure (will be useful when dealing with sub-tasks)
+- [ ] Deal with actions that have forgotten to call `go_to` (probably related to future `pause` functionality)
+- [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)
-- [ ] Make Operations::Task work in the background using ActiveJob
-- [ ] Add pause/resume capabilities (for example, when a task needs to wait for user input)
-- [ ] Add wait for sub-tasks capabilities
+- [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
+- [ ] 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/jobs/operations/application_job.rb

@@ -0,0 +1,9 @@
+module Operations
+  class ApplicationJob < ActiveJob::Base
+    # Automatically retry jobs that encountered a deadlock
+    # retry_on ActiveRecord::Deadlocked
+
+    # Most jobs are safe to ignore if the underlying records are no longer available
+    # discard_on ActiveJob::DeserializationError
+  end
+end

data/app/jobs/operations/task_runner_job.rb

@@ -0,0 +1,11 @@
+module Operations
+  class TaskRunnerJob < ApplicationJob
+    queue_as :default
+
+    def perform task
+      task.perform if task.waiting?
+    rescue => ex
+      Rails.logger.error "TaskRunnerJob failed: #{ex.message} for #{task.inspect}"
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Operations::Task::Background
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def delay(value)
+      @background_delay = value
+    end
+
+    def timeout(value)
+      @execution_timeout = value
+    end
+
+    def background_delay = @background_delay ||= 1.second
+
+    def execution_timeout = @execution_timeout ||= 5.minutes
+
+    def with_timeout(data) = data.merge(_execution_timeout: execution_timeout.from_now.utc)
+  end
+
+  private def background_delay = self.class.background_delay
+  private def execution_timeout = self.class.execution_timeout
+  private def timeout!
+    raise Operations::Timeout.new("Timeout expired", self) if timeout_expired?
+  end
+  private def timeout_expired? = data[:_execution_timeout].present? && data[:_execution_timeout] < Time.now.utc
+end

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

@@ -1,8 +1,12 @@
 class Operations::Task::DataCarrier < OpenStruct
-  def go_to(state, message = nil) = task.go_to(state, self, message)
+  def go_to(state, message: nil) = task.go_to(state, self, message: message)
 
   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 start(sub_task_class, **data, &result_handler) = task.start(sub_task_class, **data, &result_handler)
+
   def complete(results) = task.complete(results)
 
   def inputs(*names)

data/app/models/operations/task/state_management/action_handler.rb

@@ -6,7 +6,5 @@ class Operations::Task::StateManagement::ActionHandler
     @action = action
   end
 
-  def call(task, data)
-    @action.nil? ? task.send(@name, data) : data.instance_exec(&@action)
-  end
+  def call(task, data) = data.instance_exec(&@action)
 end

data/app/models/operations/task/state_management/decision_handler.rb

@@ -17,8 +17,7 @@ class Operations::Task::StateManagement::DecisionHandler
 
   def call(task, data)
     validate_inputs! data.to_h
-    result = @condition.nil? ? task.send(@name, data) : data.instance_exec(&@condition)
-    next_state = result ? @true_state : @false_state
-    next_state.respond_to?(:call) ? data.instance_eval(&next_state) : data.go_to(next_state, data)
+    next_state = data.instance_eval(&@condition) ? @true_state : @false_state
+    next_state.respond_to?(:call) ? data.instance_eval(&next_state) : data.go_to(next_state)
   end
 end

data/app/models/operations/task/state_management/wait_handler.rb

@@ -0,0 +1,18 @@
+class Operations::Task::StateManagement::WaitHandler
+  def initialize name, &config
+    @name = name.to_sym
+    @next_state = nil
+    @condition = nil
+    instance_eval(&config)
+  end
+
+  def condition(&condition) = @condition = condition
+
+  def go_to(state) = @next_state = state
+
+  def call(task, data)
+    raise Operations::CannotWaitInForeground.new("#{task.class} cannot wait in the foreground", task) unless task.background?
+    next_state = data.instance_eval(&@condition) ? @next_state : task.state
+    data.go_to(next_state)
+  end
+end

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

@@ -15,6 +15,8 @@ module Operations::Task::StateManagement
 
     def action(name, inputs: [], optional: [], &handler) = state_handlers[name.to_sym] = ActionHandler.new(name, inputs, optional, &handler)
 
+    def wait_until(name, &config) = state_handlers[name.to_sym] = WaitHandler.new(name, &config)
+
     def result(name, inputs: [], optional: [], &results) = state_handlers[name.to_sym] = CompletionHandler.new(name, inputs, optional, &results)
 
     def state_handlers = @state_handlers ||= {}
@@ -23,11 +25,6 @@ module Operations::Task::StateManagement
   end
 
   private def handler_for(state) = self.class.handler_for(state.to_sym)
-  private def process_current_state(data)
-    handler_for(state).call(self, data)
-  rescue => ex
-    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 state_is_valid
     errors.add :state, :invalid if state.blank? || handler_for(state.to_sym).nil?
   end

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

@@ -20,8 +20,23 @@ module Operations::Task::Testing
       self.failure_message = message
     end
 
+    def call(sub_task_class, **data, &result_handler)
+      record_sub_task sub_task_class
+      super
+    end
+
+    def start(sub_task_class, **data, &result_handler)
+      record_sub_task sub_task_class
+      super
+    end
+
     def complete(results)
       self.completion_results = results
     end
+
+    private def record_sub_task sub_task_class
+      self.sub_tasks ||= []
+      self.sub_tasks << sub_task_class
+    end
   end
 end

data/app/models/operations/task.rb

@@ -3,25 +3,66 @@ module Operations
     include StateManagement
     include Deletion
     include Testing
+    include Background
     extend InputValidation
 
-    enum :status, in_progress: 0, completed: 1, failed: -1
+    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: {}
 
-    def self.call(data = {})
-      validate_inputs! data
-      create!(state: initial_state, status_message: "").tap do |task|
-        task.send(:process_current_state, DataCarrier.new(data.merge(task: task)))
+    def call sub_task_class, **data, &result_handler
+      sub_task = sub_task_class.call(**data)
+      result_handler&.call(sub_task.results)
+      sub_task.results
+    end
+
+    def start sub_task_class, **data, &result_handler
+      sub_task_class.start(**data)
+    end
+
+    def perform
+      timeout!
+      in_progress!
+      handler_for(state).call(self, carrier_for(data))
+    rescue => ex
+      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}
+      raise ex
+    end
+
+    def perform_later
+      waiting!
+      TaskRunnerJob.set(wait_until: background_delay.from_now).perform_later self
+    end
+
+    def self.call(**)
+      build(background: false, **).tap do |task|
+        task.perform
       end
     end
 
-    def go_to(state, data = {}, message = nil)
-      update!(state: state, status_message: (message || state).to_s.truncate(240))
-      process_current_state(data)
+    def self.start(**data)
+      build(background: true, **with_timeout(data)).tap do |task|
+        task.perform_later
+      end
+    end
+
+    def go_to(state, data = {}, message: nil)
+      update!(state: state, data: data.to_h, status_message: (message || state).to_s.truncate(240))
+      background? ? perform_later : perform
     end
 
-    def fail_with(message) = update! status: "failed", status_message: message.to_s.truncate(240), results: {failure_message: message.to_s}
+    def fail_with(message)
+      update! status: "failed", status_message: message.to_s.truncate(240), results: {failure_message: message.to_s}
+      raise Operations::Failure.new(message, self)
+    end
 
     def complete(results) = update!(status: "completed", status_message: "completed", results: results.to_h)
+
+    private def carrier_for(data) = data.is_a?(DataCarrier) ? data : DataCarrier.new(data.merge(task: self))
+
+    def self.build(background:, **data)
+      validate_inputs! data
+      create!(state: initial_state, status: background ? "waiting" : "in_progress", data: data, status_message: "", background: background)
+    end
   end
 end

data/lib/operations/cannot_wait_in_foreground.rb

@@ -0,0 +1,2 @@
+class Operations::CannotWaitInForeground < Operations::Error
+end

data/lib/operations/failure.rb

@@ -0,0 +1,2 @@
+class Operations::Failure < Operations::Error
+end

data/lib/operations/global_id_serialiser.rb

@@ -15,7 +15,15 @@ module Operations
     def self.load(json)
       ActiveJob::Arguments.deserialize(ActiveSupport::JSON.decode(json)).first
     rescue => ex
-      {exception_message: ex.message, exception_class: ex.class.name, raw_data: json.to_s}
+      _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

data/lib/operations/timeout.rb

@@ -0,0 +1,2 @@
+class Operations::Timeout < Operations::Error
+end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.2.5"
+  VERSION = "0.3.0"
 end

data/lib/operations.rb

@@ -2,9 +2,16 @@ require "ostruct"
 
 module Operations
   class Error < StandardError
+    def initialize message, task = nil
+      super(message)
+      @task = task
+    end
+    attr_reader :task
   end
   require "operations/version"
   require "operations/engine"
   require "operations/global_id_serialiser"
-  require "operations/missing_inputs_error"
+  require "operations/failure"
+  require "operations/cannot_wait_in_foreground"
+  require "operations/timeout"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Rahoul Baruah
 bindir: bin
 cert_chain: []
-date: 2025-02-03 00:00:00.000000000 Z
+date: 2025-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -33,7 +33,10 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- app/jobs/operations/application_job.rb
+- app/jobs/operations/task_runner_job.rb
 - app/models/operations/task.rb
+- app/models/operations/task/background.rb
 - app/models/operations/task/data_carrier.rb
 - app/models/operations/task/deletion.rb
 - app/models/operations/task/input_validation.rb
@@ -41,14 +44,17 @@ files:
 - app/models/operations/task/state_management/action_handler.rb
 - app/models/operations/task/state_management/completion_handler.rb
 - app/models/operations/task/state_management/decision_handler.rb
+- app/models/operations/task/state_management/wait_handler.rb
 - app/models/operations/task/testing.rb
 - config/routes.rb
 - db/migrate/20250127160616_create_operations_tasks.rb
 - lib/operations.rb
+- lib/operations/cannot_wait_in_foreground.rb
 - lib/operations/engine.rb
+- lib/operations/failure.rb
 - lib/operations/global_id_serialiser.rb
 - lib/operations/matchers.rb
-- lib/operations/missing_inputs_error.rb
+- lib/operations/timeout.rb
 - lib/operations/version.rb
 - lib/standard_procedure_operations.rb
 - lib/tasks/operations_tasks.rake

data/lib/operations/missing_inputs_error.rb

@@ -1,2 +0,0 @@
-class Operations::MissingInputsError < Operations::Error
-end