substation 0.0.1

data/lib/substation/dispatcher.rb

@@ -0,0 +1,262 @@
+module Substation
+
+  # Encapsulates all registered actions and their observers
+  #
+  # The only protocol actions must support is +#call(request)+.
+  # Actions are intended to be classes that handle one specific
+  # application use case.
+  class Dispatcher
+
+    # Encapsulates access to one registered action
+    class Action
+
+      # Raised when no action class name is configured
+      MissingHandlerError = Class.new(StandardError)
+
+      # Coerce the given +name+ and +config+ to an {Action} instance
+      #
+      # @param [Hash<Symbol, Object>] config
+      #   the configuration hash
+      #
+      # @return [Action]
+      #   the coerced instance
+      #
+      # @raise [MissingHandlerError]
+      #   if no action handler is configured
+      #
+      # @raise [ArgumentError]
+      #   if action or observer handlers are not coercible
+      #
+      # @api private
+      def self.coerce(config)
+        handler  = config.fetch(:action) { raise(MissingHandlerError) }
+        observer = Observer.coerce(config[:observer])
+
+        new(Utils.coerce_callable(handler), observer)
+      end
+
+      include Concord.new(:handler, :observer)
+      include Adamantium
+
+      # Call the action
+      #
+      # @param [Substation::Request] request
+      #   the request passed to the registered action
+      #
+      # @return [Substation::Response]
+      #   the response returned when calling the action
+      #
+      # @api private
+      def call(request)
+        response = handler.call(request)
+        observer.call(response)
+        response
+      end
+
+    end # class Action
+
+    # Raised when trying to dispatch to an unregistered action
+    UnknownActionError = Class.new(StandardError)
+
+    # Coerce the given +config+ to a {Dispatcher} instance
+    #
+    # @example without observers
+    #
+    #   dispatcher = Substation::Dispatcher.coerce({
+    #     'some_use_case' => { 'action' => 'SomeUseCase' }
+    #   })
+    #
+    # @example with a single observer
+    #
+    #   dispatcher = Substation::Dispatcher.coerce({
+    #     'some_use_case' => {
+    #       'action' => 'SomeUseCase',
+    #       'observer' => 'SomeObserver'
+    #     }
+    #   })
+    #
+    # @example with multiple observers
+    #
+    #   dispatcher = Substation::Dispatcher.coerce({
+    #     'some_use_case' => {
+    #       'action' => 'SomeUseCase',
+    #       'observer' => [
+    #         'SomeObserver',
+    #         'AnotherObserver'
+    #       ]
+    #     }
+    #   })
+    #
+    # @example with Symbol keys and const handlers
+    #
+    #   module App
+    #     class SomeUseCase
+    #       def self.call(request)
+    #         data = perform_work
+    #         request.success(data)
+    #       end
+    #     end
+    #
+    #     class SomeObserver
+    #       def self.call(response)
+    #         # do something
+    #       end
+    #     end
+    #   end
+    #
+    #   dispatcher = Substation::Dispatcher.coerce({
+    #     :some_use_case => {
+    #       :action   => App::SomeUseCase,
+    #       :observer => App::SomeObserver
+    #     }
+    #   })
+    #
+    # @example with Symbol keys and proc handlers
+    #
+    #   dispatcher = Substation::Dispatcher.coerce({
+    #     :some_use_case => {
+    #       :action   => Proc.new { |request| request.success(:foo) },
+    #       :observer => Proc.new { |response| do_something }
+    #     }
+    #   })
+    #
+    # @param [Hash<#to_sym, Object>] config
+    #   the action configuration
+    #
+    # @return [Dispatcher]
+    #   the coerced instance
+    #
+    # @raise [Action::MissingHandlerError]
+    #   if no action handler is configured
+    #
+    # @raise [ArgumentError]
+    #   if action or observer handlers are not coercible
+    #
+    # @api public
+    def self.coerce(config)
+      new(normalize_config(config))
+    end
+
+    # Normalize the given +config+
+    #
+    # @param [Hash<#to_sym, Object>] config
+    #   the action configuration
+    #
+    # @return [Hash<Symbol, Action>]
+    #   the normalized config hash
+    #
+    # @raise [Action::MissingHandlerError]
+    #   if no action handler is configured
+    #
+    # @raise [ArgumentError]
+    #   if action or observer handlers are not coercible
+    #
+    # @api private
+    def self.normalize_config(config)
+      Utils.symbolize_keys(config).each_with_object({}) { |(name, hash), actions|
+        actions[name] = Action.coerce(hash)
+      }
+    end
+
+    private_class_method :normalize_config
+
+    include Concord.new(:actions)
+    include Adamantium
+
+    # Invoke the action identified by +name+
+    #
+    # @example
+    #
+    #   module App
+    #     class Environment
+    #       def initialize(dispatcher, logger)
+    #         @dispatcher, @logger = dispatcher, logger
+    #       end
+    #     end
+    #
+    #     class SomeUseCase
+    #       def self.call(request)
+    #         data = perform_work
+    #         request.success(data)
+    #       end
+    #     end
+    #   end
+    #
+    #   dispatcher = Substation::Dispatcher.coerce({
+    #     :some_use_case => { :action => App::SomeUseCase }
+    #   })
+    #
+    #   env = App::Environment.new(dispatcher, Logger.new($stdout))
+    #
+    #   response = dispatcher.call(:some_use_case, :some_input, env)
+    #   response.success? # => true
+    #
+    # @param [Symbol] name
+    #   a registered action name
+    #
+    # @param [Object] input
+    #   the input model instance to pass to the action
+    #
+    # @param [Object] env
+    #   the application environment
+    #
+    # @return [Response]
+    #   the response returned when calling the action
+    #
+    # @raise [UnknownActionError]
+    #   if no action is registered for +name+
+    #
+    # @api public
+    def call(name, input, env)
+      fetch(name).call(Request.new(env, input))
+    end
+
+    # The names of all registered actions
+    #
+    # @example
+    #
+    #   module App
+    #     class SomeUseCase
+    #       def self.call(request)
+    #         data = perform_work
+    #         request.success(data)
+    #       end
+    #     end
+    #   end
+    #
+    #   dispatcher = Substation::Dispatcher.coerce({
+    #     :some_use_case => { :action => App::SomeUseCase }
+    #   })
+    #
+    #   dispatcher.action_names # => #<Set: {:some_use_case}>
+    #
+    # @return [Set<Symbol>]
+    #   the set of registered action names
+    #
+    # @api public
+    def action_names
+      Set.new(actions.keys)
+    end
+
+    memoize :action_names
+
+    private
+
+    # The action registered with +name+
+    #
+    # @param [Symbol] name
+    #   a name for which an action is registered
+    #
+    # @return [Action]
+    #   the action configuration registered for +name+
+    #
+    # @raise [KeyError]
+    #   if no action is registered with +name+
+    #
+    # @api private
+    def fetch(name)
+      actions.fetch(name) { raise(UnknownActionError) }
+    end
+
+  end # class Dispatcher
+end # module Substation

data/lib/substation/observer.rb

@@ -0,0 +1,66 @@
+module Substation
+
+  # Abstract observer base class
+  #
+  # @abstract
+  class Observer
+
+    include AbstractType
+    include Adamantium::Flat
+
+    # Notify the observer
+    #
+    # @param [Response] response
+    #   the response returned when calling the observed action
+    #
+    # @return [self]
+    #
+    # @api private
+    abstract_method :call
+
+    # Coerce +input+ to an instance of {Observer}
+    #
+    # @param [NilClass, String, Array<String>] input
+    #   0..n observer class names
+    #
+    # @return [Observer::NULL, Object, Observer::Chain]
+    #   a null observer, an observer object, or a chain of observers
+    #
+    # @api private
+    def self.coerce(input)
+      case input
+      when NilClass
+        NULL
+      when Array
+        Chain.new(input.map { |item| coerce(item) })
+      else
+        Utils.coerce_callable(input)
+      end
+    end
+
+    # Null observer
+    NULL = Class.new(self) { def call(_response); self; end; }.new.freeze
+
+    # Chain of observers
+    class Chain < self
+
+      include Concord.new(:observers)
+
+      # Notify the observer
+      #
+      # @param [Response] response
+      #   the response returned when calling the observed action
+      #
+      # @return [self]
+      #
+      # @api private
+      def call(response)
+        observers.each do |observer|
+          observer.call(response)
+        end
+        self
+      end
+
+    end # Chain
+  end # Observer
+end # Substation

data/lib/substation/request.rb

@@ -0,0 +1,69 @@
+module Substation
+
+  # Encapsulates the application environment and an input model instance
+  class Request
+
+    include Concord.new(:env, :input)
+    include Adamantium
+
+    # Create a new successful response
+    #
+    # @example
+    #
+    #   class SomeUseCase
+    #     def self.call(request)
+    #       data = perform_use_case
+    #       request.success(data)
+    #     end
+    #   end
+    #
+    # @param [Object] output
+    #   the data associated with the response
+    #
+    # @return [Response::Success]
+    #
+    # @api public
+    def success(output)
+      respond_with(Response::Success, output)
+    end
+
+    # Create a new failure response
+    #
+    # @example
+    #
+    #   class SomeUseCase
+    #     def self.call(request)
+    #       error = perform_use_case
+    #       request.error(error)
+    #     end
+    #   end
+    #
+    # @param [Object] output
+    #   the data associated with the response
+    #
+    # @return [Response::Failure]
+    #
+    # @api public
+    def error(output)
+      respond_with(Response::Failure, output)
+    end
+
+    private
+
+    # Instantiate an instance of +klass+ and pass +output+
+    #
+    # @param [Response::Success, Response::Failure] klass
+    #   the response class
+    #
+    # @param [Object] output
+    #   the data associated with the response
+    #
+    # @return [Response::Success, Response::Failure]
+    #
+    # @api private
+    def respond_with(klass, output)
+      klass.new(self, output)
+    end
+
+  end # class Request
+end # module Substation

data/lib/substation/response.rb

@@ -0,0 +1,178 @@
+module Substation
+
+  # Base class for action responses
+  #
+  # @abstract
+  class Response
+
+    include AbstractType
+    include Equalizer.new(:request, :output)
+    include Adamantium
+
+    # The environment used to return this response
+    #
+    # @return [Environment]
+    #
+    # @api private
+    attr_reader :env
+
+    # The request model instance passed into an action
+    #
+    # @example
+    #
+    #   class SomeUseCase
+    #     def self.call(request)
+    #       data = perform_work
+    #       request.success(data)
+    #     end
+    #   end
+    #
+    #   env = Substation::Environment.coerce({
+    #     'some_use_case' => { 'action' => 'SomeUseCase' }
+    #   })
+    #
+    #   response = env.dispatch(:some_use_case, :input)
+    #   response.input # => :input
+    #
+    # @see Request#input
+    #
+    # @return [Object]
+    #
+    # @api public
+    attr_reader :input
+
+    # The data wrapped inside an action {Response}
+    #
+    # @example
+    #
+    #   class SomeUseCase
+    #     def self.call(request)
+    #       request.success(:output)
+    #     end
+    #   end
+    #
+    #   env = Substation::Environment.coerce({
+    #     'some_use_case' => { 'action' => 'SomeUseCase' }
+    #   })
+    #
+    #   response = env.dispatch(:some_use_case, :input)
+    #   response.output # => :output
+    #
+    # @return [Object]
+    #
+    # @api public
+    attr_reader :output
+
+    # Initialize a new instance
+    #
+    # @param [Request] request
+    #   the request passed to the action that returned this response
+    #
+    # @param [Object] output
+    #   the data returned from the action that returned this response
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def initialize(request, output)
+      @request = request
+      @env     = @request.env
+      @input   = @request.input
+      @output  = output
+    end
+
+    # Indicates wether this is a successful response or not
+    #
+    # @abstract
+    #
+    # @see Success#success?
+    # @see Failure#success?
+    #
+    # @example
+    #
+    #   class SomeUseCase
+    #     def self.call(request)
+    #       request.success(:data)
+    #     end
+    #   end
+    #
+    #   env = Substation::Environment.coerce({
+    #     'some_use_case' => { 'action' => 'SomeUseCase' }
+    #   })
+    #
+    #   response = env.dispatch(:some_use_case, :input)
+    #   response.class    # Substation::Response::Success
+    #   response.success? # => true
+    #
+    # @return [Boolean]
+    #   true if successful, false otherwise
+    #
+    # @api public
+    abstract_method :success?
+
+    protected
+
+    # The request that lead to this response
+    #
+    # @return [Request]
+    #
+    # @api private
+    attr_reader :request
+
+    # An errorneous {Response}
+    class Failure < self
+
+      # Tests wether this response was successful
+      #
+      # @example
+      #
+      #   class SomeUseCase
+      #     def self.call(request)
+      #       request.error(:output)
+      #     end
+      #   end
+      #
+      #   env = Substation::Environment.coerce({
+      #     'some_use_case' => { 'action' => 'SomeUseCase' }
+      #   })
+      #
+      #   response = env.dispatch(:some_use_case, :input)
+      #   response.success? # => false
+      #
+      # @return [false]
+      #
+      # @api public
+      def success?
+        false
+      end
+    end
+
+    # A successful {Response}
+    class Success < self
+
+      # Tests wether this response was successful
+      #
+      # @example
+      #
+      #   class SomeUseCase
+      #     def self.call(request)
+      #       request.success(:data)
+      #     end
+      #   end
+      #
+      #   env = Substation::Environment.coerce({
+      #     'some_use_case' => { 'action' => 'SomeUseCase' }
+      #   })
+      #
+      #   response = env.dispatch(:some_use_case, :input)
+      #   response.success? # => true
+      #
+      # @return [true]
+      #
+      # @api public
+      def success?
+        true
+      end
+    end
+  end
+end

data/lib/substation/support/utils.rb

@@ -0,0 +1,68 @@
+module Substation
+
+  # A collection of utility methods
+  module Utils
+
+    # Get the constant for the given FQN
+    #
+    # @param [#to_s] name
+    #   the FQN denoting a constant
+    #
+    # @return [Class, nil]
+    #
+    # @api private
+    def self.const_get(name)
+      list = name.to_s.split("::")
+      list.shift if list.first.empty?
+      obj = Object
+      list.each do |const|
+        # This is required because const_get tries to look for constants in the
+        # ancestor chain, but we only want constants that are HERE
+        obj =
+          if obj.const_defined?(const)
+            obj.const_get(const)
+          else
+            obj.const_missing(const)
+          end
+      end
+      obj
+    end
+
+    # Converts string keys into symbol keys
+    #
+    # @param [Hash<#to_sym, Object>] hash
+    #   a hash with keys that respond to `#to_sym`
+    #
+    # @return [Hash<Symbol, Object>]
+    #   a hash with symbol keys
+    #
+    # @api private
+    def self.symbolize_keys(hash)
+      hash.each_with_object({}) { |(key, value), normalized_hash|
+        normalized_value = value.is_a?(Hash) ? symbolize_keys(value) : value
+        normalized_hash[key.to_sym] = normalized_value
+      }
+    end
+
+    # Coerce the given +handler+ object
+    #
+    # @param [Symbol, String, Proc] handler
+    #   a name denoting a const that responds to `#call(object)`, or a proc
+    #
+    # @return [Class, Proc]
+    #   the callable action handler
+    #
+    # @api private
+    def self.coerce_callable(handler)
+      case handler
+      when Symbol, String
+        Utils.const_get(handler)
+      when Proc
+        handler
+      else
+        raise(ArgumentError)
+      end
+    end
+
+  end # module Utils
+end # module Substation

data/lib/substation/version.rb

@@ -0,0 +1,4 @@
+module Substation
+  # Gem version
+  VERSION = '0.0.1'.freeze
+end

data/lib/substation.rb

@@ -0,0 +1,40 @@
+require 'set'
+require 'forwardable'
+
+require 'adamantium'
+require 'equalizer'
+require 'abstract_type'
+require 'concord'
+
+# Substation can be thought of as a domain level request router. It assumes
+# that every usecase in your application has a name and is implemented in a
+# dedicated class that will be referred to as an *action* in the context of
+# substation. The only protocol such actions must support is `#call(request)`.
+#
+# The contract for actions specifies that when invoked, actions can
+# receive arbitrary input data which will be available in `request.input`.
+# Additionally, `request.env` contains an arbitrary object that
+# represents your application environment and will typically provide access
+# to useful things like a logger or a storage engine abstraction.
+#
+# The contract further specifies that every action must return an instance
+# of either `Substation::Response::Success` or `Substation::Response::Failure`.
+# Again, arbitrary data can be associated with any kind of response, and will
+# be available in `response.data`. In addition to that, `response.success?` is
+# available and will indicate wether invoking the action was successful or not.
+#
+# `Substation::Dispatcher` stores a mapping of action names to the actual
+# objects implementing the action. Clients can use
+# `Substation::Dispatcher#call(name, input, env)` to dispatch to any
+# registered action. For example, a web application could map an http
+# route to a specific action name and pass relevant http params on to the
+# action.
+
+module Substation
+end
+
+require 'substation/request'
+require 'substation/response'
+require 'substation/observer'
+require 'substation/dispatcher'
+require 'substation/support/utils'