adama 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4e62f6593e1502cfac772a33f167c0bbac14635c
+  data.tar.gz: 2eda051000fc7e546346b3db4eda8a7830542dee
+SHA512:
+  metadata.gz: 8e2c2916e4431d88986df3fc430d0e09ff6a0868011cb30310c2af39b468dc542c74dc74083fdd6c8011f446355d5a9a29f6de1591578dda9618c53dbb78b711
+  data.tar.gz: 504500aec933751018fb61dac3d943ed3e5654cca601de17063ddbe4d1ac69f20582d7e49d7740d08a4afd0edecd4e315e10acfcc7814c4a81e78c9c7da64a1e

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.14.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in adama.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,8 @@
+MIT License
+Copyright (c) 2017 Bugcrowd, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# Commander Adama
+
+Commander Adama is a bare bones command pattern library inspired by Collective Idea's [Interactor](https://github.com/collectiveidea/interactor) gem.
+
+Commands are small classes that represent individual units of work. Each command is executed by a client "calling" it. An invoker is a class responsible for the execution of one or more commands.
+
+## Getting Started
+
+Add Commander Adama to your Gemfile and `bundle install`.
+
+```ruby
+gem 'adama'
+```
+
+## Usage
+
+### Command
+
+To create a command, include the `Adama::Command` module in your command's class definition:
+
+```ruby
+class DestroyCylons
+  include Adama::Command
+end
+```
+
+Including the `Adama::Command` module extends the class with the `.call` class method. So you would execute the command like this:
+
+```ruby
+DestroyCylons.call(captain: :apollo)
+```
+
+The above `.call` method creates an instance of the `DestroyCylons` class, then calls the `#call` instance method. If the `#call` method fails, the `#rollback` method is then called.
+
+At this point our command `DestroyCylons` doesn't do much. As explained above, the `Adama::Command` module has two instance methods: `call` and `rollback`. By default these methods are empty and should be overridden like this:
+
+```ruby
+class DestroyCylons
+  include Adama::Command
+
+  def call
+    got_destroy_cylons(kwargs[:captain])
+  end
+
+  def rollback
+    retreat_and_jump_away()
+  end
+end
+```
+
+The kwargs are available within the `#call` and `#rollback` instance methods due to an `attr_reader` in the `Adama::Command` module.
+
+### Invoker
+
+To create an invoker, include the `Adama::Invoker` module in your invoker's class definition:
+
+```ruby
+class RebuildHumanRace
+  include Adama::Invoker
+end
+```
+
+Because the `Adama::Invoker` module extends `Adama::Command` you can execute an invoker in the exact same way you execute a command, with the `.call` class method:
+
+```ruby
+RebuildHumanRace.call(captain: :apollo, president: :laura)
+```
+
+The `Adama::Invoker` module _also_ extends your invoker class with the `.invoke` class method, which allows you to specify a list of commands to run in sequence, e.g.:
+
+```ruby
+class RebuildHumanRace
+  include Adama::Invoker
+
+  invoke(
+    GetArrowOfApollo,
+    DestroyCylons,
+    FindEarth,
+  )
+end
+```
+
+Now, when you run `RebuildHumanRace.call(captain: :apollo, president: :laura)` it will execute `GetArrowOfApollo`, then `DestroyCylons`, then finally `FindEarth` commands in order.
+
+If there is an error in any of those commands, the invoker will call `FindEarth.rollback`, then `DestroyCylons.rollback`, then `GetArrowOfApollo.rollback` leaving everything just as it was in the beginning.
+
+### Errors
+
+`Adama::Command#call` or `Adama::Invoker#call` will *always* raise an error of type `Adama::Errors::BaseError`.
+
+More specifically:
+
+If a command fails, it will raise `Adama::Errors::CommandError`.
+
+If a command fails while being called in an invoker, the commands will be rolled back and the invoker will raise `Adama::Errors::InvokerError`.
+
+If a command fails while rolling back within the invoker, the invoker will raise `Adama::Errors::InvokerRollbackError`.
+
+The base error type `Adama::Errors::Adama` is designed to be initialized with three optional keyword args:
+
+`error` - the original exception that was rescued in the command or invoker.
+`command` - the failed command instance.
+`invoker` - the failed invoker instance, set if the command or rollback failed in an invoker.
+
+```ruby
+module Adama
+  module Errors
+    class BaseError < StandardError
+      attr_reader :error, :command, :invoker
+
+      def initialize(error: nil, command: nil, invoker: nil)
+        @error = error
+        @command = command
+        @invoker = invoker
+      end
+    end
+  end
+end
+```
+
+### TODOS
+
+I'm contemplating adding support for per-command validation, potentially through the [dry-validation](https://github.com/dry-rb/dry-validation) gem,
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bugcrowd/adama. So Say We All.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/adama.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'adama/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "adama"
+  spec.version       = Adama::VERSION
+  spec.licenses      = ['MIT']
+  spec.authors       = ["dradford"]
+  spec.email         = ["damienradford@gmail.com"]
+
+  spec.summary       = %q{Commander of the fleet.}
+  spec.description   = %q{Command and Invoker pattern.}
+  spec.homepage      = "https://github.com/bugcrowd/adama"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "adama"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/adama/command.rb

@@ -0,0 +1,53 @@
+module Adama
+  # Extend class with module methods
+  #
+  # class CollectUnderpantsCommand
+  #   include Adama::Command
+  #
+  #   def call
+  #     got_get_underpants()
+  #   end
+  #
+  #   def rollback
+  #     return_underpants_to_rightful_owner()
+  #   end
+  # end
+  module Command
+    # Internal: Install Command's behavior in the given class.
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        attr_reader :kwargs
+      end
+    end
+
+    module ClassMethods
+      # public invoke a command
+      def call(kwargs = {})
+        new(kwargs).tap(&:run)
+      end
+    end
+
+    def initialize(kwargs = {})
+      @kwargs = kwargs
+    end
+
+    # Internal instance method. Called by both the call class method, and by
+    # the call method in the invoker. If it fails it rolls back the command
+    # and raises a CommandError.
+    def run(enable_rollback: true)
+      call
+    rescue => error
+      rollback if enable_rollback
+      raise Errors::CommandError.new error: error, command: self
+    end
+
+    # Public instance method. Override this in classes this module is
+    # included in.
+    def call; end
+
+    # Public instance method. Override this in classes this module is
+    # included in.
+    def rollback; end
+  end
+end

data/lib/adama/errors.rb

@@ -0,0 +1,16 @@
+module Adama
+  module Errors
+    class BaseError < StandardError
+      attr_reader :error, :command, :invoker
+
+      def initialize(error: nil, command: nil, invoker: nil)
+        @error = error
+        @command = command
+        @invoker = invoker
+      end
+    end
+    class CommandError < BaseError; end
+    class InvokerError < BaseError; end
+    class InvokerRollbackError < BaseError; end
+  end
+end

data/lib/adama/invoker.rb

@@ -0,0 +1,116 @@
+module Adama
+  # Invoker lets you run many commands in sequence, and roll them back
+  # in reverse order.
+  #
+  # class SuccessfulBusinessCreator
+  #   include Adama::Invoker
+  #
+  #   invoke(
+  #     CollectUnderpantsCommand,
+  #     MagicHappensCommand,
+  #     ProfitCommand,
+  #   )
+  # end
+  #
+  # SuccessfulBusinessCreator.call(min_underpants: 100)
+  #
+  module Invoker
+    # Internal: Install Command's behavior in the given class.
+    def self.included(base)
+      base.class_eval do
+        # We inherit the Command module's call methods
+        include Command
+
+        # Our new class methods enable us to set the command list
+        extend ClassMethods
+
+        # We override the Command class instance methods:
+        #
+        #   run
+        #   call
+        #   rollback
+        include InstanceMethods
+      end
+    end
+
+    # Our new class methods enable us to set the command list
+    module ClassMethods
+
+      # Public class method. Call invoke in your class definition to
+      # specify which commands will be executed.
+      #
+      # class SuccessfulBusinessCreator
+      #   include Adama::Invoker
+      #
+      #   invoke(
+      #     CollectUnderpantsCommand,
+      #     MagicHappensCommand,
+      #     ProfitCommand,
+      #   )
+      # end
+      def invoke(*command_list)
+        @commands = command_list.flatten
+      end
+
+      # internal class method. So we can loop through the commands that
+      # have been assigned by the including class.
+      def commands
+        @commands ||= []
+      end
+    end
+
+    module InstanceMethods
+      # Internal instance method. Called by the included Command module's .call
+      # class method. We've overridden command's instance method because we
+      # don't want it to have optional rollback.
+      #
+      # Always raises Errors::InvokerError and has the #invoker and #error
+      # attribute set. In the case where the error is raised within the
+      # invoker "call" instance method, we won't have access to error's
+      # command so need to test for it's existence.
+      def run
+        call
+      rescue => error
+        rollback
+        raise Errors::InvokerError.new(
+          error: error,
+          command: error.respond_to?(:command) ? error.command : nil,
+          invoker: self
+        )
+      end
+
+      # Maintain an array of commands that have been called.
+      def _called
+        @called ||= []
+      end
+
+      # To unwind the invoker, we rollback the _called array in reverse order.
+      #
+      # If anything fails in the command's rollback method we should raise
+      # and drop out of the process as we'll need to manually remove something.
+      def rollback
+        _called.reverse_each do |command|
+          begin
+            command.rollback
+          rescue => error
+            raise Errors::InvokerRollbackError.new(error: error, command: command, invoker: self)
+          end
+        end
+      end
+
+      # Iterate over the commands array, instantiate each command, add it to
+      # the called list and then run it. We don't want the command to call
+      # rollback itself as that will be handled by the rollback method above.
+      # To ensure this doesn't happen we pass in enable_rollback: false.
+      # Please ensure the command is placed on the array _prior_ to calling
+      # run, or else we'll miss rolling back the command that failed.
+      def call
+        self.class.commands.each do |command_klass|
+          command = command_klass.new(kwargs)
+          _called << command
+          command.run(enable_rollback: false)
+        end
+      end
+    end
+  end
+end

data/lib/adama/version.rb

@@ -0,0 +1,3 @@
+module Adama
+  VERSION = "0.1.0"
+end

data/lib/adama.rb

@@ -0,0 +1,4 @@
+require "adama/version"
+require "adama/errors"
+require "adama/command"
+require "adama/invoker"

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: adama
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dradford
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-06-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Command and Invoker pattern.
+email:
+- damienradford@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- adama.gemspec
+- bin/console
+- bin/setup
+- lib/adama.rb
+- lib/adama/command.rb
+- lib/adama/errors.rb
+- lib/adama/invoker.rb
+- lib/adama/version.rb
+homepage: https://github.com/bugcrowd/adama
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+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.5.1
+signing_key: 
+specification_version: 4
+summary: Commander of the fleet.
+test_files: []