bizness 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 52657da3321f8216c3aed22df7aa598b0ddce78d
-  data.tar.gz: 351634c989bf984d60e09d97f625b12176f2c5e9
+  metadata.gz: fdcd210e4eec5f7e5f9d8b1945b83f4b400eb5c2
+  data.tar.gz: 501a8155d69ae354e60d6452af7b4861268f6071
 SHA512:
-  metadata.gz: 944b4590e34e31ce2d4c127ed3e05e95712327b4077e2aa004e0c38566c3399b4ab8d154178e541ffab617c7b0cce242f31111ae7d720c92cca7442bbc2bc980
-  data.tar.gz: 3e8b318b87f9243688fa97bde6d296fd5187184c5ce18d79974fe0f750924c6575123782bd37a95dfa24299d43e5bda45db0c67e8bda3dc569280511e82e90a7
+  metadata.gz: 0ce4d947499f155a46e627ac620b3fafa6d4c2da916c7da6867110b9793c8299a2798cb107b221f39cf97ee4c5f6089c07f88cf2cdd3b80e3005fb9d15f2fcd4
+  data.tar.gz: c020189fa5e2d77db8939a151021bcb568a5e7010d2d3b97506b3207a6df211e78462a6c01feb008be397526a52d102456bc38dccde5b1e97c7b5aaf542395fe

data/README.md

@@ -1,8 +1,6 @@
 # Bizness
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/bizness`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Get your bizness right and organize your business logic into operations.
 
 ## Installation
 
@@ -22,13 +20,119 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+## Why use this?
+
+First of all, you need to buy into the idea that ActiveRecord is an egregious violator of the Single Responsibility Principle.
+Breaking out its responsibilities into separate objects, such as Query, Policy, Form and Service objects, has been a trend for some time now. These objects allow you to better organize and isolate your business logic, leading to faster design and better testing. You spend less time wondering how a feature's classes should be organized and more time addressing the needs of your domain.
+
+ShippingEasy adopted this strategy, but we opted to use the term Operation rather than the nebulous term "Service Object" (or Interactor for that matter).
+
+As we wrote more and more operations, some insights emerged:
+
+  1. We always ran an operation in a transaction
+  2. An operation nearly always corresponded to an important system event ("Complete Registration")
+  3. Logging these events into a dashboard like Kibana could provide us with valuable metrics and insight into how our system was performing at a business logic level
+
+Bizness, therefore, allows you to create PORO operation objects and easily augment their business logic execution via a series of filters. Out of the box there are filters to wrap every operation in a transaction as well as automatically broadcasting every operation as a series of events.
+ A filter is just a SimpleDelegator, so it's easy to create your own. Moving these responsbilities out of your operation classes keeps them lean and focused, and in the case of the event filters, automatically instruments every important business operation in your codebase (depending on how widely you adopt them).
+
+### Writing your own operation
+
+1. Ensure your class responds to the instance method `call`.
+
+2. If you are using the `EventFilter` and want to customize the message that is published when your operation is run, write a `to_h` instance method that returns a hash.
+
+3. You should raise all errors as runtime exceptions if your operation fails so the filters can rollback and react accordingly.
+
+### Running an operation
+
+The pipeline can be executed from `Bizness.run`. You can either pass in an object, or execute a block.
+
+```ruby
+Bizness.run(operation)
+```
+
+```ruby
+Bizness.run do
+  puts “foo”
+end
+```
+
+By default, all filters that are globally configured on Bizness are run, but you may optionally pass in overrides as well:
+
+```ruby
+Bizness.run(filters: Bizness::Filters::EventFilter) do
+  puts “foo”
+end
+```
+
+### The Operation module
+
+Though you don't need to use the `Bizness::Operation` module to define an operation, one is provided as a convenience. This module has several methods that make calling operations and running them through the pipeline more intuitive.
+
+For example:
 
-## Development
+```ruby
+op = CompleteRegistrationOperation.new(customer: customer)
+
+op.call! # submits itself through the filter pipeline
+
+op.error # Exceptions are caught and the message is set on error
+
+op.successful? # True if error is nil
+
+op.to_h
+```
+
+### Pubsub
+
+#### Publishing
+
+Automatically publishing operations as events via the `EventFilter` is one of the primary reasons we developed Bizness. The `EventFilter` will always publish two events. For example, if your operation class is named `CompleteRegistrationOperation`, these events will be published:
+
+  * "operations:complete_registration:executed" - This event includes the start time, end time and duration of the operation
+  * "operations:complete_registration:succeeded" or "operations:complete_registration:failed" depending on if an exception was raised or not
+
+#### Subscribing
+
+Once an operation is publishing events, we wanted to make it easy for other operations to subscribe to those events. To wire up a class to easily subscribe to these events, simply extend the `Bizness::Subscriber` module. That gives your class access to the `subscribe` method.
+
+You can use the `subscribe` method in one of two ways: with or without a block. You can use the block as a builder for your operation, translating the values coming in from the message into the arguments necessary to initialize your operation. You should always return an initialized operation from this block.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+For example, if your operation requires a model to initialize:
 
-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).
+```ruby
+class SendWelcomeEmailOperation
+  extend Bizness::Subscriber
+
+  subscribe(“operations:registration_complete:succeeded”) do |event_data|
+    customer = Customer.find(event_data[:customer_id])
+    new(customer: customer)
+  end
+
+  def initialize(customer:)
+    @customer = customer
+  end
+
+  # …. omitted for brevity
+end
+```
+
+If no block is passed, the attributes from the event payload will be used directly to initialize and execute your operations:
+
+```ruby
+class SendWelcomeEmailOperation
+  extend Bizness::Subscriber
+
+  subscribe(“operations:registration_complete:succeeded”)
+
+  def initialize(customer_id:)
+    @customer = Customer.find(customer_id)
+  end
+
+  # …. omitted for brevity
+end
+```
 
 ## Contributing
 

data/lib/bizness/filters/active_record_transaction_filter.rb

@@ -3,7 +3,6 @@ module Bizness::Filters
     def call
       ActiveRecord::Base.transaction(requires_new: true) do
         filtered_operation.call
-        raise ActiveRecord::Rollback unless successful?
       end
     end
   end

data/lib/bizness/filters/base_filter.rb

@@ -5,10 +5,6 @@ module Bizness::Filters
       super(operation)
     end
 
-    def self.wrap(collection)
-      collection.map { |object| new(object) }
-    end
-
     private
 
     attr_reader :__original_operation__

data/lib/bizness/filters/event_filter.rb

@@ -1,7 +1,7 @@
 module Bizness::Filters
   class EventFilter < Bizness::Filters::BaseFilter
     def call
-      Hey.publish!("#{event_name}:executed", context.to_h) do
+      Hey.publish!("#{event_name}:executed", payload) do
         evented_call
       end
     end
@@ -9,16 +9,25 @@ module Bizness::Filters
     private
 
     def evented_call
-      filtered_operation.call
-      Hey.publish!("#{event_name}:#{successful? ? "succeeded" : "failed"}", context.to_h)
+      result = filtered_operation.call
+      Hey.publish!("#{event_name}:#{successful? ? "succeeded" : "failed"}", payload(result))
     rescue => e
-      context.error = e.message
-      Hey.publish!("#{event_name}:failed", context.to_h)
+      Hey.publish!("#{event_name}:failed", payload.merge(error: e.message))
       raise e
     end
 
     def event_name
       __original_operation__.class.name.underscore.gsub("/", ":")
     end
+
+    def payload(result = nil)
+      if self.respond_to?(:to_h)
+        to_h
+      elsif result.is_a?(Hash)
+        result
+      else
+        Hash.new
+      end
+    end
   end
 end

data/lib/bizness/operation.rb

@@ -1,46 +1,32 @@
-class Bizness::Operation
-  extend Forwardable
+module Bizness::Operation
+  attr_reader :error
 
-  def_delegators :context, :error, :successful?
-
-  attr_reader :context
-
-  def initialize(context = {})
-    @context = Bizness::Context.new(context.to_h)
+  def call!
+    run
+    successful?
   end
 
-  def self.filters
-    Bizness.filters
+  def call
+    raise NotImplementedError
   end
 
-  def self.call!(context = {})
-    new(context).call!
+  def successful?
+    error.nil?
   end
 
-  def call!
-    execute_filtered_operation!
-    context
+  def to_h
+    {}
   end
 
-  def call
-    raise NotImplementedError
-  end
+  protected
 
-  def fail!(error:)
-    context.error = error
-  end
+  attr_writer :error
 
   private
 
-  def execute_filtered_operation!
-    filtered_operation.call
-    raise Bizness::Failure, context.error unless successful?
+  def run
+    Bizness.run(self)
   rescue => e
-    context.error = e.message
-  end
-
-  def filtered_operation
-    return self if self.class.filters.empty?
-    self.class.filters.reduce(self) { |filtered_op, filter| filter.new(filtered_op) }
+    self.error = e.message
   end
 end

data/lib/bizness/subscriber.rb

@@ -1,8 +1,9 @@
 module Bizness::Subscriber
-  def subscribe(*event_names)
+  def subscribe(*event_names, &block)
     event_names.each do |event_name|
       Hey.subscribe!(event_name) do |event|
-        call!(event[:metadata])
+        instance = block_given? ? block.call(event[:metadata]) : new(event[:metadata])
+        instance.call!
       end
     end
   end

data/lib/bizness/version.rb

@@ -1,3 +1,3 @@
 module Bizness
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/bizness.rb

@@ -5,7 +5,6 @@ require "hey"
 
 module Bizness
   def self.configure
-    Hey.configuration.namespace = "operations"
     yield(configuration)
   end
 
@@ -16,12 +15,15 @@ module Bizness
   def self.filters
     configuration.filters
   end
+
+  def self.run(operation = nil, filters: self.filters, &block)
+    operation = block if block_given?
+    filters.reduce(operation) { |filtered_op, filter| filter.new(filtered_op) }.call
+  end
 end
 
 require "bizness/configuration"
-require "bizness/context"
 require "bizness/operation"
-require "bizness/failure"
 require "bizness/subscriber"
 require "bizness/filters/base_filter"
 require "bizness/filters/active_record_transaction_filter"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bizness
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - ShippingEasy
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-08-09 00:00:00.000000000 Z
+date: 2015-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -113,8 +113,6 @@ files:
 - bizness.gemspec
 - lib/bizness.rb
 - lib/bizness/configuration.rb
-- lib/bizness/context.rb
-- lib/bizness/failure.rb
 - lib/bizness/filters/active_record_transaction_filter.rb
 - lib/bizness/filters/base_filter.rb
 - lib/bizness/filters/event_filter.rb

data/lib/bizness/context.rb

@@ -1,18 +0,0 @@
-require "ostruct"
-
-class Bizness::Context < OpenStruct
-  attr_accessor :error
-
-  def successful?
-    error.nil?
-  end
-
-  # If a value responds to #id, automatically set an equivalent "_id" key/value pair. For example, if an instance
-  # of an ActiveRecord class Widget is set on a context object of :widget, set another attribute called :widget_id with
-  # the value of the object's ID. This helps ensure the context's values can be sent as a message across application
-  # boundries.
-  def to_h
-    super.each { |k, v| send("#{k}_id=", v.id) if v.respond_to?(:id) && send("#{k}_id").nil? }
-    super
-  end
-end

data/lib/bizness/failure.rb

@@ -1,6 +0,0 @@
-class Bizness::Failure < StandardError
-  def initialize(context = nil)
-    @context = context
-    super
-  end
-end