action_operation 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac4f5bc88c4689c01c68d6761631feb15ff1b17e54274be64223b3e9d6190f50
+  data.tar.gz: ccced431a6f77242476bc749a94c5d3a742f8b91cb24ced140543c14f9cff55f
+SHA512:
+  metadata.gz: 1d93d27a24c101660023688e238d7d84743c5586b901dc73942524422f7317587ac9b38925967dbbefd0ad1193a4dc9b39fd295d4b32a1ac280dfceabcca6507
+  data.tar.gz: 5f9f49b17ca20437080e52466d07195f19fe752adb52237a196b3e6011d39d3ca950b4bd749640be5f62c0eb47db32d419d54dfd5b132efb70d872f8ad0f6b9d

data/README.md

@@ -0,0 +1,261 @@
+# action_operation
+
+  - [![Build](http://img.shields.io/travis-ci/krainboltgreene/action_operation.rb.svg?style=flat-square)](https://travis-ci.org/krainboltgreene/action_operation.rb)
+  - [![Downloads](http://img.shields.io/gem/dtv/action_operation.svg?style=flat-square)](https://rubygems.org/gems/action_operation)
+  - [![Version](http://img.shields.io/gem/v/action_operation.svg?style=flat-square)](https://rubygems.org/gems/action_operation)
+
+
+A simple set of right-to-left operations, similar to many other gems out there.
+
+
+## Using
+
+Alright, so you have some business logic you'd like to control in your application. You've found that putting in the controllers sucks, because an application is more than it's HTTP requests. You've found that putting in the model sucks, because there's not enough context and does too many things. You've found that "service classes" have no form or shape and get way too out of hand.
+
+ActionOperation is here to help! This, like many others before and after, gives a concise way to describe a series of business requirements. It has as much context as you give it and only does the thing you need it to do. It can be used anywhere and everywhere.
+
+First let's make our operation:
+
+``` ruby
+class AddToCartOperation
+  include ActionOperation
+
+  task :check_for_missing_product
+  task :carbon_copy_cart_item
+  task :lock
+  task :persist
+  task :publish
+  error :notify, catch: ProductMissingFromCartItemError
+  error :reraise
+
+  state :check_for_missing_product do
+    field :cart_item, type: Types.Instance(CartItem)
+  end
+  step :check_for_missing_product do |state|
+    raise ProductMissingFromCartItemError if state.cart_item.product.nil?
+  end
+
+  state :carbon_copy_cart_item do
+    field :cart_item, type: Types.Instance(CartItem)
+  end
+  step :carbon_copy_cart_item do |state|
+    state.cart_item.carbon_copy
+  end
+
+  state :lock do
+    field :cart_item, type: Types.Instance(CartItem)
+  end
+  step :lock do |state|
+    GlobalLock.(state.cart_item.owner, state.cart_item, expires_in: 15.minutes)
+  end
+
+  state :persist do
+    field :cart_item, type: Types.Instance(CartItem)
+  end
+  step :persist do |state|
+    CartItem.transaction do
+      state.cart_item.save!
+    end
+
+    fresh(current_account: state.cart_item.owner, cart_item: state.cart_item)
+  end
+
+  state :publish do
+    field :cart_item, type: Types.Instance(CartItem)
+    field :current_account, type: Types.Instance(Account)
+  end
+  step :publish do |state|
+    CartItemPickedMessage.(subject: state.cart_item, to: state.current_account).via_pubsub.deliver_later!
+  end
+
+  step :notify do |exception|
+    Bugsnag.notify(exception)
+  end
+end
+```
+
+There's a lot to take in here, so lets go through each point:
+
+``` ruby
+class AddToCartOperation
+  # ...
+
+  task :check_for_missing_product
+  task :carbon_copy_cart_item
+  task :lock
+  task :persist
+  task :publish
+  error :notify, catch: ProductMissingFromCartItemError
+  error :reraise
+
+  # ...
+end
+```
+
+These are the steps our process will take. Each `task` call is *in the order it is listed*, which means that `check_for_missing_product` will happen before `carbon_copy_cart_item`. Each `error` is also *in the order it is listed*, but they only trigger when one of the `task` raises an exception. In this case, we only want to `notify` when there's something seriously wrong!
+
+Finally, before we leave, notice the `reraise` error step. This is built in to the operation layer so that you can easily pass the buck to whomever owns the action currently.
+
+Okay, so on to our first step:
+
+``` ruby
+class AddToCartOperation
+  # ...
+
+  state :check_for_missing_product do
+    field :cart_item, type: Types.Instance(CartItem)
+  end
+  step :check_for_missing_product do |state|
+    raise ProductMissingFromCartItemError if state.cart_item.product.nil?
+  end
+
+  # ...
+end
+```
+
+There's two things we want to talk about there and the first is `state`. It defines the shape of the *immutable* state that the step will receive. We use [smart_params](https://github.com/krainboltgreene/smart_params.rb) which means each field is typed with [dry-types](https://github.com/dry-rb/dry-types). Read up on both of those libraries for more fine grained control over your data.
+
+Second is the `step` definition itself which provides a `state` object that is based on the schema defined above. You have four choices on what you can do in a `step`. You can:
+
+  - Return any value, which will simply proceed to the next step.
+  - Raise an exception, which will move you into the left track (that uses `error` steps)
+  - Return a fresh state, which will be described below
+  - Return a drift instruction, which will be described below
+
+### Fresh State
+
+Sometimes you want to change the data that is passed around after a step is completed. To achieve this functionality we provide the `fresh()` function:
+
+``` ruby
+class AddToCartOperation
+  # ...
+
+  step :persist do |state|
+    CartItem.transaction do
+      state.cart_item.save!
+    end
+
+    fresh(current_account: state.cart_item.owner, cart_item: state.cart_item)
+  end
+
+  # ...
+end
+```
+
+This is the only way to "change" the shape of the state.
+
+
+### Receivers
+
+Sometimes you need to share functionality across multiple operations. You can do this via modules and inheritance like normal or you can use our specialized interface:
+
+``` ruby
+class DocumentUploadOperation
+  include ActionOperation
+
+  task :upload_to_s3, receiver: S3UploadOperation
+end
+```
+
+This will give the `DocumentUploadOperation` a task that is on another operation! Sometimes that other task has a different name, so we also provide aliasing:
+
+``` ruby
+class DocumentUploadOperation
+  include ActionOperation
+
+  task :upload_to_s3, receiver: S3UploadOperation, :upload
+end
+```
+
+So when `DocumentUploadOperation` finally gets to the `upload_to_s3` task it's actually calling the `S3UploadOperation` task called `upload`. More on why this is useful in the next section.
+
+
+### Drifting
+
+Alright, so lets say you have a business requirement to upload important documents to the cloud. You have multiple providers (S3, Azure, and DigitalOcean Spaces) and you want to make sure it gets pushed to at least one. Here's how you would write this:
+
+``` ruby
+class S3UploadOperation
+  include ActionOperation
+
+  task :upload
+
+  state :upload do
+    field :document, type: Types.Instance(Document)
+  end
+  step :upload do |state|
+    fresh(document: state.document, location: S3.push(state.document))
+  rescue StandardError => exception
+    raise FailedUploadError
+  end
+end
+
+```
+
+``` ruby
+class DocumentUploadOperation
+  include ActionOperation
+
+  task :upload_to_s3, receiver: S3UploadOperation, as: :upload
+  task :upload_to_azure, receiver: AzureUploadOperation, as: :upload, required: false
+  task :upload_to_spaces, receiver: SpacesUploadOperation, as: :upload, required: false
+  task :publish
+  error :retry, catch: FailedUploadError
+  error :reraise
+
+  step :retry do |exception, _, step|
+    case step
+    when :upload_to_s3 then drift(to: :upload_to_azure)
+    when :upload_to_azure then drift(to: :upload_to_spaces)
+    end
+  end
+
+  state :publish do
+    field :document, type: Types.Instance(Document)
+    field :location, type: Types::Strict::String
+  end
+  step :publish do |state|
+    DocumentSuccessfullyUploadedMessage.(owner: state.document.owner, location: state.location).via_pubsub.deliver_later!
+  end
+end
+```
+
+So here's how this works:
+
+  1. First we call `upload_to_s3`, which actually talks to `S3UploadOperation/upload`, but for some reason this fails and gets caught by `failed_upload`, which bubbles up a specific exception that we catch with `DocumentUploadOperation/retry`
+  2. `retry` looks at the last known step and then drifts to `upload_to_azure`, which functions just like above.
+  3. Then somehow we fail to upload to Azure, so we repeat and retry with DigitalOcean Spaces.
+  4. We fail to even upload that, which means the next error step gets called (`reraise`) giving control back to the owner of the operation
+
+
+However, if it finishes successfully we get to push a notification to the document owner in `finish`.
+
+
+### Understanding the design
+
+Each task is a map function wrapped in a HOC for handling the return data. The annotation of each task is `state -> mixed | state` and the HOC is `state -> (state -> mixed | state) -> state`. `error` is like a task, but instead: `exception -> mixed` wrapped in a HOC that matches `exception -> (exception -> mixed) -> exception`.
+
+
+## Installing
+
+Add this line to your application's Gemfile:
+
+    gem "action_operation", "1.0.0"
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself with:
+
+    $ gem install action_operation
+
+
+## Contributing
+
+  1. Read the [Code of Conduct](/CONDUCT.md)
+  2. Fork it
+  3. Create your feature branch (`git checkout -b my-new-feature`)
+  4. Commit your changes (`git commit -am 'Add some feature'`)
+  5. Push to the branch (`git push origin my-new-feature`)
+  6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+desc "Run all the tests in spec"
+RSpec::Core::RakeTask.new(:spec) do |let|
+  let.pattern = "lib/**{,/*/**}/*_spec.rb"
+end
+
+desc "Default: run tests"
+task default: :spec

data/lib/action_operation.rb

@@ -0,0 +1,123 @@
+require "active_support/concern"
+require "active_support/core_ext/array"
+require "smart_params"
+
+module ActionOperation
+  extend ActiveSupport::Concern
+
+  require_relative "action_operation/version"
+  require_relative "action_operation/types"
+  require_relative "action_operation/error"
+
+  State = Struct.new(:raw)
+  Drift = Struct.new(:to)
+
+  attr_reader :raw
+  attr_reader :state
+  attr_reader :step
+
+  def initialize(raw:)
+    @raw = raw
+  end
+
+  def call(forced: nil)
+    right.from(forced || 0).reduce(state || raw) do |state, function|
+      next state unless function.required || (forced && right.at(forced) == function)
+
+      # NOTE: We store this so we can go drift back if an error tells us to
+      @state = state
+
+      # NOTE: We store this so an error step can ask for the last ran step
+      @step = function.name
+
+      raise Error::MissingTask, function unless function.receiver.steps.key?(function.as)
+      raise Error::MissingSchemaForTask, function unless function.receiver.schemas.key?(function.as)
+
+      value = instance_exec(function.receiver.schemas.fetch(function.as).new(state), &function.receiver.steps.fetch(function.as))
+
+      case value
+      when State then value.raw
+      when Drift then break call(forced: right.find_index { |step| step.name == value.to })
+      else state
+      end
+    end
+  rescue *left.select(&:catch).map(&:catch).uniq => handled_exception
+    left.select do |failure|
+      failure.catch === handled_exception
+    end.reduce(handled_exception) do |exception, function|
+      raise Error::MissingError, function unless function.receiver.steps.key?(function.as)
+
+      value = instance_exec(exception, @state, @step, &function.receiver.steps.fetch(function.as))
+
+      if value.kind_of?(Drift)
+        break call(forced: right.find_index { |step| step.name == value.to })
+      else
+        exception
+      end
+    end
+  end
+
+  def fresh(raw)
+    State.new(raw)
+  end
+
+  def drift(to:)
+    Drift.new(to)
+  end
+
+  private def left
+    self.class.left
+  end
+
+  private def right
+    self.class.right
+  end
+
+  included do
+    step :reraise do |exception|
+      raise exception
+    end
+  end
+
+  class_methods do
+    def state(name, &structure)
+      schemas[name] = Class.new do
+        include(SmartParams)
+
+        schema type: SmartParams::Strict::Hash, &structure
+      end
+    end
+
+    def task(name, receiver: self, as: name, required: true)
+      right.<<(OpenStruct.new({name: name, as: as, receiver: receiver || self, required: required}))
+    end
+
+    def error(name, receiver: self, catch: StandardError, as: name)
+      left.<<(OpenStruct.new({name: name, as: as, receiver: receiver || self, catch: catch || StandardError}))
+    end
+
+    def step(name, &process)
+      steps[name] = process
+    end
+
+    def call(raw = {})
+      new(raw: raw).call
+    end
+
+    def right
+      @right ||= Array.new
+    end
+
+    def left
+      @left ||= Array.new
+    end
+
+    def schemas
+      @schemas ||= Hash.new
+    end
+
+    def steps
+      @steps ||= Hash.new
+    end
+  end
+end

data/lib/action_operation/error.rb

@@ -0,0 +1,7 @@
+module ActionOperation
+  class Error < StandardError
+    require_relative "error/missing_error"
+    require_relative "error/missing_schema_for_task"
+    require_relative "error/missing_task"
+  end
+end

data/lib/action_operation/error/missing_error.rb

@@ -0,0 +1,9 @@
+module ActionOperation
+  class Error
+    class MissingError < Error
+      def initialize(function)
+        @function = function
+      end
+    end
+  end
+end

data/lib/action_operation/error/missing_schema_for_task.rb

@@ -0,0 +1,9 @@
+module ActionOperation
+  class Error
+    class MissingSchemaForTask < Error
+      def initialize(function)
+        @function = function
+      end
+    end
+  end
+end

data/lib/action_operation/error/missing_task.rb

@@ -0,0 +1,9 @@
+module ActionOperation
+  class Error
+    class MissingTask < Error
+      def initialize(function)
+        @function = function
+      end
+    end
+  end
+end

data/lib/action_operation/types.rb

@@ -0,0 +1,5 @@
+module ActionOperation
+  module Types
+    include Dry::Types.module
+  end
+end

data/lib/action_operation/version.rb

@@ -0,0 +1,3 @@
+module ActionOperation
+  VERSION = "1.0.0"
+end

data/lib/action_operation/version_spec.rb

@@ -0,0 +1,7 @@
+require "spec_helper"
+
+RSpec.describe ActionOperation::VERSION do
+  it "should be a string" do
+    expect(ActionOperation::VERSION).to be_kind_of(String)
+  end
+end

data/lib/action_operation_spec.rb

@@ -0,0 +1,50 @@
+require "spec_helper"
+
+RSpec.describe ActionOperation do
+  let(:operation) { DocumentUploadOperation }
+
+  describe "#call" do
+    subject { operation.call(arguments) }
+
+    context "with the right arguments" do
+      let(:arguments) {{document: Document.new}}
+
+      it "works" do
+        expect(subject).to match(hash_including(document: a_kind_of(Document), location: "some.s3"))
+      end
+
+      context "drifting from s3" do
+        before do
+          allow(S3).to receive(:push).and_raise(StandardError, 'something')
+        end
+
+        it "works" do
+          expect(subject).to match(hash_including(document: a_kind_of(Document), location: "some.azure"))
+        end
+      end
+
+      context "drifting from s3 and azure" do
+        before do
+          allow(S3).to receive(:push).and_raise(StandardError, 'something')
+          allow(Azure).to receive(:push).and_raise(StandardError, 'something')
+        end
+
+        it "works" do
+          expect(subject).to match(hash_including(document: a_kind_of(Document), location: "some.spaces"))
+        end
+      end
+
+      context "drifting from s3 and azure and spacs" do
+        before do
+          allow(S3).to receive(:push).and_raise(StandardError, 'something')
+          allow(Azure).to receive(:push).and_raise(StandardError, 'something')
+          allow(Spaces).to receive(:push).and_raise(StandardError, 'something')
+        end
+
+        it "works" do
+          expect{subject}.to raise_exception(FailedUploadError)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification
+name: action_operation
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kurtis Rainbolt-Greene
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-05-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: pry-doc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: smart_params
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A set of BPMN style operation logic
+email:
+- kurtis@rainbolt-greene.online
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/action_operation.rb
+- lib/action_operation/error.rb
+- lib/action_operation/error/missing_error.rb
+- lib/action_operation/error/missing_schema_for_task.rb
+- lib/action_operation/error/missing_task.rb
+- lib/action_operation/types.rb
+- lib/action_operation/version.rb
+- lib/action_operation/version_spec.rb
+- lib/action_operation_spec.rb
+homepage: http://krainboltgreene.github.io/action_operation
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: A set of BPMN style operation logic
+test_files: []