standard_procedure_operations 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 247457067fee3dc2c60698254bcb9f9d51474762d9414547f525f84e0d76be1b
-  data.tar.gz: b17839f7c5e0e25891c53551d419611c7cabfc2a235ea850a16c6742a47ca49a
+  metadata.gz: 227d7875d414fd181b6f620f403dbdd3d4fb098e86853563c328d871f521cc33
+  data.tar.gz: 1512b85b79a129784ecfdea2d2c82c3ea842aca78ce69c4c6b1a1e65662b9ea4
 SHA512:
-  metadata.gz: ca73b99af337d62e70cc542e2c63cb401f1f269d349008bc01fea0856a4147a3b5eed1458504e3fbb9f0bf9b1dc5b6aa4ec420c594f7741d22bec1fbd39d963c
-  data.tar.gz: 315a25627f2c5ce4798f2efa6e26375a44ffcbef30981f1df4f87946373bd3d6513cf51c7b9ce6202fa8b8325278471473d9591b3d9380cdfa626d44c9727fa8
+  metadata.gz: e4f1e35fb4ffffbf58cae1e98ead209656542115c9a05cc6b6d7122a8659a63ae82599700fa804650c8539fe38f980ad77521b2ad4744734326813f6fa44aaaf
+  data.tar.gz: 53c72faa3640bc85f6283ae4bb8ff5aaac2d462994cff1b4654d84c88642039fb62082dcdf212d7c643edd4d2d84d37f85ea34c0f1259333bb44a0cca1e28b89

data/README.md

@@ -48,27 +48,38 @@ class PrepareDocumentForDownload < Operations::Task
   starts_with :authorised?
 
   decision :authorised? do
+    inputs :user
+
     if_true :within_download_limits?
     if_false { fail_with "unauthorised" }
   end
 
   decision :within_download_limits? do
+    inputs :user
+
     if_true :use_filename_scrambler?
     if_false { fail_with "download_limit_reached" }
   end
 
   decision :use_filename_scrambler? do
+    inputs :use_filename_scrambler
     condition { use_filename_scrambler }
+
     if_true :scramble_filename
     if_false :return_filename
   end
 
   action :scramble_filename do
+    inputs :document
+
     self.filename = "#{Faker::Lorem.word}#{File.extname(document.filename.to_s)}"
     go_to :return_filename
   end
 
   result :return_filename do |results|
+    inputs :document
+    optional :filename
+
     results.filename = filename || document.filename.to_s
   end
 
@@ -89,6 +100,7 @@ It's up to you whether you define the condition as a block, as part of the decis
 ```ruby
 decision :is_it_the_weekend? do 
   condition { Date.today.wday.in? [0, 6] }
+
   if_true :have_a_party 
   if_false :go_to_work
 end
@@ -104,6 +116,7 @@ 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.  
 ```ruby
 decision :authorised? do 
@@ -113,6 +126,20 @@ decision :authorised? do
 end
 ```
 
+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
+
+  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).
+
 ### Actions
 An action handler does some work, then moves to another state.  
 
@@ -124,7 +151,21 @@ action :have_a_party do
   go_to :send_invitations
 end
 ```
-Again, instead of using a block in the action handler, you could provide a method to do the work.
+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.  
+
+```ruby 
+action :have_a_party do
+  inputs :task 
+  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
@@ -143,6 +184,8 @@ Do not forget to call `go_to` from your action handler, otherwise the operation
 ### 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.  
+
 ```ruby
 action :send_invitations do 
   self.invited_friends = (0..number_of_guests).collect do |i|
@@ -157,7 +200,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
@@ -165,6 +208,24 @@ result :go_to_work
 ```
 In this case, the task will be marked as `completed?`, the task's state will be `go_to_work` and `results` will be empty.  
 
+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
+  self.invited_friends = (0..number_of_guests).collect do |i|
+    friend = friends.pop
+    FriendsMailer.with(recipient: friend).party_invitation.deliver_later
+    friend 
+  end
+  go_to :ready_to_party
+end
+
+result :ready_to_party do |results|
+  inputs :invited_friends 
+
+  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:
 
@@ -190,16 +251,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 +321,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|
@@ -300,6 +373,7 @@ 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)
 - [ ] Split out the state-management definition stuff from the task class (so you can use it without subclassing Operations::Task)

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

@@ -4,4 +4,11 @@ class Operations::Task::DataCarrier < OpenStruct
   def fail_with(message) = task.fail_with(message)
 
   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/input_validation.rb

@@ -0,0 +1,17 @@
+module Operations::Task::InputValidation
+  def inputs(*names) = @required_inputs = names.map(&:to_sym)
+
+  def optional(*names) = @optional_inputs = names.map(&:to_sym)
+
+  def optional_inputs = @optional_inputs ||= []
+
+  def required_inputs = @required_inputs ||= []
+
+  def required_inputs_are_present_in?(hash) = missing_inputs_from(hash).empty?
+
+  def missing_inputs_from(hash) = (required_inputs - hash.keys.map(&:to_sym))
+
+  def validate_inputs! hash
+    raise ArgumentError, "Missing inputs: #{missing_inputs_from(hash).join(", ")}" unless required_inputs_are_present_in?(hash)
+  end
+end

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

@@ -0,0 +1,12 @@
+class Operations::Task::StateManagement::ActionHandler
+  def initialize name, inputs = [], optional = [], &action
+    @name = name.to_sym
+    @required_inputs = inputs
+    @optional_inputs = optional
+    @action = action
+  end
+
+  def call(task, data)
+    @action.nil? ? task.send(@name, data) : data.instance_exec(&@action)
+  end
+end

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

@@ -0,0 +1,14 @@
+class Operations::Task::StateManagement::CompletionHandler
+  def initialize name, inputs = [], optional = [], &handler
+    @name = name.to_sym
+    @required_inputs = inputs
+    @optional_inputs = optional
+    @handler = handler
+  end
+
+  def call(task, data)
+    results = OpenStruct.new
+    data.instance_exec(results, &@handler) unless @handler.nil?
+    data.complete(results)
+  end
+end

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

@@ -0,0 +1,24 @@
+class Operations::Task::StateManagement::DecisionHandler
+  include Operations::Task::InputValidation
+
+  def initialize name, &config
+    @name = name.to_sym
+    @condition = nil
+    @true_state = nil
+    @false_state = nil
+    instance_eval(&config)
+  end
+
+  def condition(&condition) = @condition = condition
+
+  def if_true(state = nil, &handler) = @true_state = state || handler
+
+  def if_false(state = nil, &handler) = @false_state = state || handler
+
+  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)
+  end
+end

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

@@ -7,82 +7,28 @@ module Operations::Task::StateManagement
   end
 
   class_methods do
-    def inputs(*names) = @required_inputs = names.map(&:to_sym)
-
-    def required_inputs = @required_inputs ||= []
-
     def starts_with(value) = @initial_state = value.to_sym
 
     def initial_state = @initial_state
 
     def decision(name, &config) = state_handlers[name.to_sym] = DecisionHandler.new(name, &config)
 
-    def action(name, &handler) = state_handlers[name.to_sym] = ActionHandler.new(name, &handler)
+    def action(name, inputs: [], optional: [], &handler) = state_handlers[name.to_sym] = ActionHandler.new(name, inputs, optional, &handler)
 
-    def result(name, &results) = state_handlers[name.to_sym] = CompletionHandler.new(name, &results)
+    def result(name, inputs: [], optional: [], &results) = state_handlers[name.to_sym] = CompletionHandler.new(name, inputs, optional, &results)
 
     def state_handlers = @state_handlers ||= {}
 
     def handler_for(state) = state_handlers[state.to_sym]
-
-    def required_inputs_are_present_in?(data) = missing_inputs_from(data).empty?
-
-    def missing_inputs_from(data) = (required_inputs - data.keys.map(&:to_sym))
   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: 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?
   end
-
-  class ActionHandler
-    def initialize name, &action
-      @name = name.to_sym
-      @action = action
-    end
-
-    def call(task, data)
-      @action.nil? ? task.send(@name, data) : data.instance_exec(&@action)
-    end
-  end
-
-  class DecisionHandler
-    def initialize name, &config
-      @name = name.to_sym
-      @condition = nil
-      @true_state = nil
-      @false_state = nil
-      instance_eval(&config)
-    end
-
-    def condition(&condition) = @condition = condition
-
-    def if_true(state = nil, &handler) = @true_state = state || handler
-
-    def if_false(state = nil, &handler) = @false_state = state || handler
-
-    def call(task, data)
-      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)
-    end
-  end
-
-  class CompletionHandler
-    def initialize name, &handler
-      @name = name.to_sym
-      @handler = handler
-    end
-
-    def call(task, data)
-      results = OpenStruct.new
-      data.instance_exec(results, &@handler) unless @handler.nil?
-      data.complete(results)
-    end
-  end
 end

data/app/models/operations/task.rb

@@ -3,12 +3,13 @@ module Operations
     include StateManagement
     include Deletion
     include Testing
+    extend InputValidation
+
     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 = {})
-      raise MissingInputsError, "Missing inputs: #{missing_inputs_from(data).join(", ")}" unless required_inputs_are_present_in?(data)
+      validate_inputs! data
       create!(state: initial_state, status_message: "").tap do |task|
         task.send(:process_current_state, DataCarrier.new(data.merge(task: task)))
       end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.2.2"
+  VERSION = "0.2.4"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Rahoul Baruah
 bindir: bin
 cert_chain: []
-date: 2025-01-31 00:00:00.000000000 Z
+date: 2025-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -36,7 +36,11 @@ files:
 - app/models/operations/task.rb
 - app/models/operations/task/data_carrier.rb
 - app/models/operations/task/deletion.rb
+- app/models/operations/task/input_validation.rb
 - app/models/operations/task/state_management.rb
+- 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/testing.rb
 - config/routes.rb
 - db/migrate/20250127160616_create_operations_tasks.rb