standard_procedure_operations 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cfaaef3f5470debfff84e64763fd703752ae0c70a7c62c2926468aa9b897c83
-  data.tar.gz: 2af99adbc94c3c6f734e9272b909d42d199ddc7d7f18a866f4d14bd2ad78b9ff
+  metadata.gz: 1d0da11583bd5edf6619553813c302fbe675ce5563921e9960149d79888130c5
+  data.tar.gz: aefecc4a15ed64289822318feb10c68128c121a359e049ede7f8a2805ca6405c
 SHA512:
-  metadata.gz: 40ba366b5f54cfd1d376ac34731f1d8e462afffef0512b9011603734a3c45319e40994b7790f556e6bfd27923b0cf67aadd521bebf98f004b71d7aad5956c53f
-  data.tar.gz: 833099833d7ef03773530f4301ee5b66434c26c94af54508e0c006aa082e6d4c812b84fd621dd9e5d9cb9a300be17292bf4be7c46679f5429c50937d5362a94b
+  metadata.gz: 998bca6b52931b7048585a22ab6cc53a53a9a872290bd6243a84bed7442c57209a2ea71f0502b744aeaa8b65461e9e7d1aca22321a3811fdac7f7a7d156e15e1
+  data.tar.gz: 474207de30dbe046bd59587f1dfe0fa5f14f7a13d2f72075838e6594d8533c1c9b8ab79e245eafecaf490782329f220fe5dc0f9546e194138c0dafedf0544ef3

data/README.md

@@ -44,6 +44,7 @@ Here's how this would be represented using Operations.
 
 ```ruby
 class PrepareDocumentForDownload < Operations::Task
+  inputs :user, :document, :use_filename_scrambler
   starts_with :authorised?
 
   decision :authorised? do
@@ -78,6 +79,8 @@ end
 
 The five states are represented as three [decision](#decisions) handlers, one [action](#actions) handler and a [result](#results) handler.  
 
+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?`.  
+
 ### Decisions
 A decision handler evaluates a condition, then changes state depending upon if the result is true or false. 
 
@@ -194,14 +197,12 @@ Handlers can alternatively be implemented as methods on the task itself.  This m
 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`.
 
 ### 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.exception_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`.
 
 ### Task life-cycle and the database
-
-There is an ActiveRecord migration that creates the `operations_tasks` table.  Use `bin/rails app:operations:install:migrations` to copy it to your application.  
+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.  
 
 When you `call` a task, it is written to the database.  Then whenever a state transition occurs, the task record is updated.  
 
@@ -226,21 +227,17 @@ Coming soon.
 Coming soon.  
 
 ## Installation
-Add this line to your application's Gemfile:
+Add the gem to your Rails application's Gemfile:
 
 ```ruby
 gem "standard_procedure_operations"
 ```
-
-Run `bundle install`, copy and run the migrations to add the tasks table to your database:
-
+Run `bundle install`, then copy and run the migrations to add the tasks table to your database:
 ```sh
-bin/rails app:operations:install:migrations 
+bin/rails operations:install:migrations 
 bin/rails db:migrate
 ```
-
-Then create your own operations by inheriting from `Operations::Task`.
-
+Create your own operations by inheriting from `Operations::Task` and revel in the stateful flowcharts!
 ```ruby
 class DailyLife < Operations::Task
   starts_with :am_i_awake?

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

@@ -7,6 +7,10 @@ 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
@@ -20,13 +24,17 @@ module Operations::Task::StateManagement
     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", results: OpenStruct.new(exception_message: ex.message, exception_class: ex.class.name, exception_backtrace: ex.backtrace)
+    update! status: "failed", results: OpenStruct.new(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

@@ -6,7 +6,12 @@ module Operations
     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 = {}) = create!(state: initial_state).tap { |task| task.send(:process_current_state, DataCarrier.new(data.merge(task: task))) }
+    def self.call(data = {})
+      raise MissingInputsError, "Missing inputs: #{missing_inputs_from(data).join(", ")}" unless required_inputs_are_present_in?(data)
+      create!(state: initial_state).tap do |task|
+        task.send(:process_current_state, DataCarrier.new(data.merge(task: task)))
+      end
+    end
 
     def go_to(state, data = {}, message = nil)
       update!(state: state, status_message: message || state.to_s)

data/db/migrate/20250127160616_create_operations_tasks.rb

@@ -1,12 +1,12 @@
-class CreateOperationsTasks < ActiveRecord::Migration[8.0]
+class CreateOperationsTasks < ActiveRecord::Migration[7.1]
   def change
     create_table :operations_tasks do |t|
       t.string :type
       t.integer :status, default: 0, null: false
       t.string :state, null: false
       t.string :status_message, default: "", null: false
-      t.text :data, default: "{}"
-      t.text :results, default: "{}"
+      t.text :data
+      t.text :results
       t.boolean :background, default: false, null: false
       t.datetime :delete_at, null: false, index: true
       t.timestamps

data/lib/operations/missing_inputs_error.rb

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

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/operations.rb

@@ -1,7 +1,10 @@
 require "ostruct"
 
 module Operations
+  class Error < StandardError
+  end
   require "operations/version"
   require "operations/engine"
   require "operations/global_id_serialiser"
+  require "operations/missing_inputs_error"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Rahoul Baruah
@@ -42,6 +42,7 @@ files:
 - lib/operations.rb
 - lib/operations/engine.rb
 - lib/operations/global_id_serialiser.rb
+- lib/operations/missing_inputs_error.rb
 - lib/operations/version.rb
 - lib/standard_procedure_operations.rb
 - lib/tasks/operations_tasks.rake
@@ -52,7 +53,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://theartandscienceofruby.com/
   source_code_uri: https://github.com/standard-procedure/operations
-  changelog_uri: https://github.com/standard-procedure/operations/releases
+  changelog_uri: https://github.com/standard-procedure/operations/tags
 rdoc_options: []
 require_paths:
 - lib