action_operation 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f97e8fc036a03a7ff4b0fdab9e4316d2312ad17ae5cf1a1844dc1ceb7cf84ad1
-  data.tar.gz: e2e2b98a9c87a50b42acbe2b2d1cfa507a4972d2871f6e26ad5a938d5a28c464
+  metadata.gz: df39296baae3026a586088215fec2ab3b0bd6630141beb4c67167d38f61ae663
+  data.tar.gz: c767f034411fc574752a5a8d43d94a7fab54ad9ff4c6f57bcb2da96722709bf9
 SHA512:
-  metadata.gz: b0d55912ff981d7298d3c9ca0c24babeea983427af130714e808d8767913cfde985b9a5fd5cb611d2f87c9c0986f133daa6357dd5645d460d740ea4f29e44e42
-  data.tar.gz: 90dca03f785f51506abb76bdcda2a2448e1236de32957ab5e9592e2252c3f63f125eb83c7e4e17477619d534a06fcbeb07788e266182b1e2abadf32bd89a1eb1
+  metadata.gz: 9ceab9d1a6fd7d8202fd82e07cebcc03a01716ceb4c49a53bc20a4453155475893b2b968e104d840107bd0f81d72d75ec80c1cb4e627dd416e0bc31cae78cbbc
+  data.tar.gz: fdfb512b613d99eeeef8903051547dc60285676cb7d2eb95967f5abe2d601716e01048cafb10cf88e0aaf024773fa52688359c49456238b544593c3aa80ad4cd

data/README.md

@@ -234,11 +234,69 @@ So here's how this works:
 However, if it finishes successfully we get to push a notification to the document owner in `publish()`.
 
 
+### Callbacks
+
+Sometimes we want to make sure an operation or it's individual parts are wrapped in safety measures, like a transaction or a timeout. You can achieve these with special built in instance methods. I'll show you each one and why you would use it.
+
+To start, the highest wrapper is `around_steps`, which wraps around both tasks and catches. A good use for this is
+
+``` ruby
+class AddProductToCart < ApplicationOperation
+  def around_steps(raw:)
+    Rails.logger.tagged("operation-id=#{SecureRandom.uuid}") do
+      Rails.logger.debug("Started adding cart to product operation with (#{raw.to_json})")
+
+      yield
+    end
+  end
+end
+```
+
+Here we're making sure every log we write will be tagged with a unique identifier for the entire operation, an extremely valuable option for debugging. The `around_steps` hook will be told about the raw data it receives in the call (`AddProductToCart.({cart: current_cart, product: product})`).
+
+While `around_steps` is on the entire operation, you might want individual wrapping. Let me present: `around_step`!
+
+``` ruby
+class AddProductToCart < ApplicationOperation
+  def around_step(step:)
+    Rails.logger.tagged("step-id=#{SecureRandom.uuid}") do
+      yield
+    end
+  end
+end
+```
+
+This `around_step` will give you a per-step unique id tag for all logs in a step, another fantastic tool in debugging. This hook will be told of the `Task|Catch` object which responds to `#name` and `#receiver`. Additionally a `Task` responds to `#required` and a `Catch` responds to `#exception`.
+
+Finally, there are 4 other type specific hooks: `around_tasks`, `around_task`, `around_catches`, and `around_catch`. Here are example uses:
+
+
+``` ruby
+class AddProductToCart < ApplicationOperation
+  def around_tasks
+    Timeout.new(30.seconds) do
+      yield
+    end
+  end
+
+  def around_task(step:, state:)
+    Rails.logger.debug("Working on #{step.receiver}##{step.name} using (#{state.to_json})")
+
+    Timeout.new(10.seconds) do
+      ApplicationRecord.transaction do
+        yield
+      end
+    end
+  end
+end
+```
+
+
 ## Installing
 
 Add this line to your application's Gemfile:
 
-    gem "action_operation", "2.0.0"
+    gem "action_operation", "2.1.0"
 
 And then execute:
 

data/lib/action_operation/error/missing_error.rb

@@ -1,7 +1,7 @@
 module ActionOperation
   class Error
     class MissingError < Error
-      def initialize(step)
+      def initialize(step:)
         @step = step
       end
 

data/lib/action_operation/error/missing_schema.rb

@@ -1,7 +1,7 @@
 module ActionOperation
   class Error
     class MissingSchema < Error
-      def initialize(step)
+      def initialize(step:)
         @step = step
       end
 

data/lib/action_operation/error/missing_task.rb

@@ -1,7 +1,7 @@
 module ActionOperation
   class Error
     class MissingTask < Error
-      def initialize(step)
+      def initialize(step:)
         @step = step
       end
 

data/lib/action_operation/error/step_schema_mismatch.rb

@@ -0,0 +1,15 @@
+module ActionOperation
+  class Error
+    class StepSchemaMismatch < Error
+      def initialize(step:, schema:, raw:)
+        @step = step
+        @schema = schema
+        @raw = raw
+      end
+
+      def message
+        "#{@step.receiver}##{@step.name} #{cause.message} and received #{@raw}"
+      end
+    end
+  end
+end

data/lib/action_operation/error.rb

@@ -3,5 +3,6 @@ module ActionOperation
     require_relative "error/missing_error"
     require_relative "error/missing_schema"
     require_relative "error/missing_task"
+    require_relative "error/step_schema_mismatch"
   end
 end

data/lib/action_operation/version.rb

@@ -1,3 +1,3 @@
 module ActionOperation
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/lib/action_operation.rb

@@ -11,8 +11,8 @@ module ActionOperation
 
   State = Struct.new(:raw)
   Drift = Struct.new(:to)
-  Task = Struct.new(:name, :required)
-  Catch = Struct.new(:name, :exception)
+  Task = Struct.new(:name, :receiver, :required)
+  Catch = Struct.new(:name, :receiver, :exception)
 
   def initialize(raw:)
     raise ArgumentError, "needs to be a Hash" unless raw.kind_of?(Hash)
@@ -20,31 +20,72 @@ module ActionOperation
     @raw = raw
   end
 
+  private def callbackings(arounds, &process)
+    arounds.reverse.reduce(process) do |compound, callback|
+      callback.call(&compound).call
+    end.call
+  end
+
   def call(start: nil, raw: @raw)
+    around_steps do
+      begin
+        around_tasks do
+          tasks(start, raw)
+        end
+      rescue *left.select(&:exception).map(&:exception).uniq => handled_exception
+        around_catches do
+          catches(handled_exception, raw)
+        end
+      end
+    end
+  end
+
+  private def tasks(start, raw)
     right.from(start || 0).reduce(raw) do |state, step|
       next state unless step.required || (start && right.at(start) == step)
 
-      raise Error::MissingTask, step unless respond_to?(step.name)
-      raise Error::MissingSchema, step unless self.class.schemas.key?(step.name)
+      raise Error::MissingTask, step: step unless respond_to?(step.name)
+      raise Error::MissingSchema, step: step unless self.class.schemas.key?(step.name)
 
-      # NOTE: We only care about this so we can refernece it in the rescue
+      # NOTE: We only care about this so we can reference it in the rescue
       @latest_step = step
 
-      value = public_send(step.name, state: self.class.schemas.fetch(step.name).new(state))
+      # puts "#{step.class}::#{step.receiver}##{step.name}"
+
+      begin
+        value = around_task do
+          public_send(step.name, state: self.class.schemas.fetch(step.name).new(state))
+        end
+        # puts "#{step.class}::#{step.receiver}##{step.name} #{value}"
+      rescue SmartParams::Error::InvalidPropertyType => invalid_property_type_exception
+        raise Error::StepSchemaMismatch, step: step, schema: self.class.schemas.fetch(step.name), raw: raw, cause: invalid_property_type_exception
+      end
+
 
       case value
-      when State then value.raw
-      when Drift then break call(start: right.find_index { |step| step.name == value.to }, raw: raw)
-      else state
+        when State then value.raw
+        when Drift then break call(start: right.find_index { |step| step.name == value.to }, raw: state)
+        else state
       end
     end
-  rescue *left.select(&:exception).map(&:exception).uniq => handled_exception
-    left.select do |failure|
-      failure.exception === handled_exception
-    end.reduce(handled_exception) do |exception, step|
-      raise Error::MissingError, step unless respond_to?(step.name)
+  end
 
-      value = public_send(step.name, exception: exception, state: self.class.schemas.fetch(@latest_step.name).new(raw), step: @latest_step)
+  private def catches(exception, raw)
+    left.select do |failure|
+      failure.exception === exception
+    end.reduce(exception) do |exception, step|
+      raise Error::MissingError, step: step unless respond_to?(step.name)
+
+      # puts "#{step.class}::#{step.receiver}##{step.name}"
+
+      begin
+        value = around_catch do
+          public_send(step.name, exception: exception, state: raw, step: @latest_step)
+        end
+        # puts "#{step.class}::#{step.receiver}##{step.name} #{value}"
+      rescue SmartParams::Error::InvalidPropertyType => invalid_property_type_exception
+        raise Error::StepSchemaMismatch, step: @latest_step, schema: self.class.schemas.fetch(@latest_step.name), raw: raw, cause: invalid_property_type_exception
+      end
 
       if value.kind_of?(Drift)
         break call(start: right.find_index { |step| step.name == value.to }, raw: raw)
@@ -66,6 +107,30 @@ module ActionOperation
     Drift.new(to)
   end
 
+  def around_steps(&callback)
+    callback.call
+  end
+
+  def around_step(&callback)
+    callback.call
+  end
+
+  def around_tasks(&callback)
+    callback.call
+  end
+
+  def around_task(&callback)
+    callback.call
+  end
+
+  def around_catches(&callback)
+    callback.call
+  end
+
+  def around_catch(&callback)
+    callback.call
+  end
+
   private def left
     self.class.left
   end
@@ -92,11 +157,11 @@ module ActionOperation
     end
 
     def task(name, required: true)
-      right << Task.new(name, required)
+      right << Task.new(name, self, required)
     end
 
     def catch(name, exception: StandardError)
-      left << Catch.new(name, exception)
+      left << Catch.new(name, self, exception)
     end
 
     def right

data/lib/action_operation_spec.rb

@@ -1,14 +1,24 @@
 require "spec_helper"
 
 RSpec.describe ActionOperation do
-  let(:operation) { DocumentUploadOperation }
+  let(:operation) { DocumentUploadOperation.new(raw: arguments) }
+
+  before do
+    allow(operation).to receive(:logger)
+  end
 
   describe "#call" do
-    subject { operation.call(arguments) }
+    subject { operation.call }
 
     context "with the right arguments" do
       let(:arguments) {{document: Document.new}}
 
+      it "calls the around steps callback" do
+        expect(operation).to receive(:logger).twice
+
+        subject
+      end
+
       it "works" do
         expect(subject).to match(hash_including(document: a_kind_of(Document), location: "some.s3"))
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: action_operation
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Kurtis Rainbolt-Greene
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-05 00:00:00.000000000 Z
+date: 2018-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -140,6 +140,7 @@ files:
 - lib/action_operation/error/missing_error.rb
 - lib/action_operation/error/missing_schema.rb
 - lib/action_operation/error/missing_task.rb
+- lib/action_operation/error/step_schema_mismatch.rb
 - lib/action_operation/types.rb
 - lib/action_operation/version.rb
 - lib/action_operation/version_spec.rb