standard_procedure_operations 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01add4a31dd9bc5fadf9c8c133ab46ad0ce7d562061bcf176324d3b5bb7bcdcc
-  data.tar.gz: b807c6c826e7f572581bfc93eb1676d1c472377771ae872ff882d0ff6360ab7e
+  metadata.gz: 27f6593a2e233607d6247450ca043995e23d33dcb4af69129c314d4e89d2dab1
+  data.tar.gz: 6ba1683666c67b27de61f3d99ed61a4f2badb962622f06e7174cb71a09ccee93
 SHA512:
-  metadata.gz: 15c50c2237db2c236f256071035e74795f345f632550b8c1dab4878e02914c698819252b75977630e52c47b607dc312b0b42abd44646e36ef285c82d024e23aa
-  data.tar.gz: 430746923c58ff6e3081f4aaf4dd5fb9e69a3fd38927af926282136fc2ea4594756e5e99d813303754a23fcbaf560f1aecc884a91999b6d97c76232365eba13b
+  metadata.gz: b40b93fd31799d31f53294a234733c492520731332aeeea6bc6e1fa747fa19c550a5d407a4573f0fd0161404ba4e63a046454ce28b423ddb0b384700139812cf
+  data.tar.gz: 0d4e28d7e9a5d4d77343d8bcb56b0deff90f76c79d1da0bb980e8134354302e68bdf745d71f97e0d86f43ade3c419ed8486db444e47a92ba03597e33605b4f78

data/README.md

@@ -157,7 +157,7 @@ result :ready_to_party do |results|
   results.invited_friends = invited_friends
 end
 ```
-After this result handler has executed, the task will then be marked as `completed?`, the task's state will be `ready_to_party` and `results.invited_friends` will contain an array of the people you sent invitations to.  
+After this result handler has executed, the task will then be marked as `completed?`, the task's state will be `ready_to_party` and `results[:invited_friends]` will contain an array of the people you sent invitations to.  
 
 If you don't have any meaningful results, you can omit the block on your result handler.  
 ```ruby
@@ -190,16 +190,22 @@ Each operation carries its own, mutable, data for the duration of the operation.
 
 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. 
 
-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"`.  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.  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.  
+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"`.  
+
+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.  
+
+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.  
 
 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`.  
 
-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 accessed as an OpenStruct that is encoded into JSON.  But any ActiveRecord models are translated using a [GlobalID](https://github.com/rails/globalid) using [ActiveJob::Arguments](https://guides.rubyonrails.org/active_job_basics.html#supported-types-for-arguments).  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 the `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`.
+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).  
+
+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`.
 
 ### 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.  
+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 mark the task as `failed?` and the `reeults` 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.  
@@ -254,9 +260,15 @@ To test the results from a result handler:
 MyOperation.handling(:a_result, some: "data") do |test|
   assert_equal test.outcome, "everything is as expected"
   # or
+  assert_equal test[:outcome], "everything is as expected"
+  # or
   expect(test.outcome).to eq "everything is as expected"
+  # or
+  expect(test[:outcome]).to eq "everything is as expected"
 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).
+
 To test if a handler has failed:
 ```ruby
 MyOperation.handling(:a_failure, some: "data") do |test|
@@ -297,3 +309,12 @@ Step 4: If you're using RSpec for testing, add `require "operations/matchers" to
 
 ## License
 The gem is available as open source under the terms of the [LGPL License](/LICENSE).  This may or may not make it suitable for your needs.
+
+## Roadmap
+
+- [ ] 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)
+- [ ] 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

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

@@ -34,7 +34,7 @@ module Operations::Task::StateManagement
   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: OpenStruct.new(failure_message: ex.message, exception_class: ex.class.name, exception_backtrace: ex.backtrace)
+    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?

data/app/models/operations/task.rb

@@ -4,7 +4,6 @@ module Operations
     include Deletion
     include Testing
     enum :status, in_progress: 0, completed: 1, failed: -1
-    composed_of :results, class_name: "OpenStruct", constructor: ->(results) { results.to_h }, converter: ->(hash) { OpenStruct.new(hash) }
     serialize :results, coder: Operations::GlobalIDSerialiser, type: Hash, default: {}
 
     def self.call(data = {})
@@ -21,6 +20,6 @@ module Operations
 
     def fail_with(message) = update! status: "failed", status_message: message.to_s.truncate(240), results: {failure_message: message.to_s}
 
-    def complete(results) = update!(status: "completed", status_message: "completed", results: results)
+    def complete(results) = update!(status: "completed", status_message: "completed", results: results.to_h)
   end
 end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Rahoul Baruah