lev 0.0.3 → 1.0.0

data/.gitignore

@@ -5,4 +5,4 @@ spec/dummy/db/*.sqlite3
 spec/dummy/log/*.log
 spec/dummy/tmp/
 spec/dummy/.sass-cache
-.DS_Store
+*.DS_Store

data/.rspec

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

data/Gemfile.lock

@@ -1,14 +1,23 @@
 PATH
   remote: .
   specs:
-    lev (0.0.3)
+    lev (1.0.0)
+      actionpack (>= 3.0)
       active_attr
+      activemodel (>= 3.0)
+      activerecord (>= 3.0)
       transaction_isolation
       transaction_retry
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionpack (4.0.0)
+      activesupport (= 4.0.0)
+      builder (~> 3.1.0)
+      erubis (~> 2.7.0)
+      rack (~> 1.5.2)
+      rack-test (~> 0.6.2)
     active_attr (0.8.2)
       activemodel (>= 3.0.2, < 4.1)
       activesupport (>= 3.0.2, < 4.1)
@@ -30,10 +39,30 @@ GEM
     arel (4.0.0)
     atomic (1.1.14)
     builder (3.1.4)
+    columnize (0.3.6)
+    debugger (1.6.2)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.2.3)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.2.3)
+    diff-lcs (1.2.4)
+    erubis (2.7.0)
     i18n (0.6.5)
     minitest (4.7.5)
     multi_json (1.8.0)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
     rake (10.1.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.5)
+    rspec-expectations (2.14.3)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.3)
     thread_safe (0.1.3)
       atomic
     transaction_isolation (1.0.3)
@@ -48,5 +77,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.3)
+  debugger
   lev!
   rake
+  rspec

data/README.md

@@ -1,6 +1,50 @@
 # Lev
 
-TODO: Write a gem description
+Rails is fantastic and obviously super successful.  Lev is an attempt to improve Rails by:
+
+1. Providing a better, more structured, and more organized way to implement code features
+2. De-emphasizing the "model is king" mindset when appropriate
+
+Rails' MVC-view of the world is very compelling and provides a sturdy scaffold with which to create applications quickly.  However, sometimes it can lead to business logic code getting a little spread out.  When trying to figure out where to best put business logic, you often hear folks recommending "fat models" and "skinny controllers".  They are saying that the business logic of your app should live in the model classes and not in the controllers.  I agree that the logic shouldn't live in the controllers, but I also argue that it shouldn't always live in the models either, especially when that logic touches multiple models.
+
+When all of the business logic lives in the models, some bad things can happen:
+
+1. your models can become bloated with code that only applies to certain features
+2. your models end up knowing way too much about other models, sometimes multiple hops away
+3. your business logic gets spread all over the place.  The execution of one "feature" can jump between bits of code in multiple models, their various ActiveRecord life cycle callbacks (before_create, etc), and their associated observers.
+
+Lev introduces "routines" which you can think of as pieces of code that have all the responsibility for making one thing (use case) happen, e.g. "add an email to a user", "register a student to a class", etc).  
+
+Routines...
+
+1. Can call other routines
+2. Have a common error reporting framework
+3. Run within a single transaction with a controllable isolation level
+
+Handlers are specialized routines that take user input (e.g. form data) and then take an action based on that input.  
+
+Handlers...
+
+1. Help you verify that the calling user is authorized to run the handler
+2. Provide ways to validate incoming parameters in a very ActiveModel-like way (even when the parameters are not associated with a model)
+3. Integrate will with basic routines
+
+In a Lev-oriented Rails app, controllers are just responsible for connecting routes to Handlers.  In fact, controller methods just end up being calls to ```handle_with(MyHandler)```, ```handle_with``` being a helper method provided by Lev.  
+
+Lev also provides a ```lev_form_for``` form builder to replace ```form_for```.  This builder integrates well with the error reporting infrastructure in routines and handlers, and in general is a nice way to get away from forms that are very single-model-centric.
+
+When using Lev, model classes have the following responsibilities:
+
+
+1. Hook into the ORM (i.e., inherit from ActiveRecord::Base)
+2. Establish relationships to other models (e.g. belongs_to, has_many, including dependent: :destroy)
+3. Validate internal state
+    1. Do not validate state in related models
+    2. Can validate the presence of relationship (can check that a foreign key is present)
+4. Can perform queries when those queries only use internal model state and are aware of internal model state (e.g. arguments to queries should be in the language of the model state)
+5. Can create records when those creations only need values internal to this model and take arguments in the language of the internal model state.
+
+The result of the principles above and below, model classes end up being very small.  This is good because a lot of code depends on the models and having the be small normally means they are also stable.
 
 ## Installation
 
@@ -18,7 +62,14 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+For the moment, details on how to use lev live in big sections of comments at the top of:
+
+* https://github.com/lml/lev/blob/master/lib/lev/routine.rb
+* https://github.com/lml/lev/blob/master/lib/lev/handler.rb
+* https://github.com/lml/lev/blob/master/lib/lev/handle_with.rb
+* https://github.com/lml/lev/blob/master/lib/lev/form_builder.rb
+
+TBD: talk about ```delegate_to_routine```.
 
 ## Contributing
 

data/lev.gemspec

@@ -18,10 +18,16 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "transaction_isolation"
-  spec.add_dependency "transaction_retry"
-  spec.add_dependency "active_attr"
+  spec.add_runtime_dependency(%q<activemodel>, [">= 3.0"])
+  spec.add_runtime_dependency(%q<activerecord>, [">= 3.0"])
+  spec.add_runtime_dependency(%q<actionpack>, [">= 3.0"])
+  spec.add_runtime_dependency "transaction_isolation"
+  spec.add_runtime_dependency "transaction_retry"
+  spec.add_runtime_dependency "active_attr"
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "debugger"
+
 end

data/lib/lev.rb

@@ -1,21 +1,24 @@
+require "action_view"
 require "transaction_isolation"
 require "transaction_retry"
 require "active_attr"
 
 require "lev/version"
+require "lev/utilities"
 require "lev/exceptions"
-require "lev/routine_nesting"
 require "lev/better_active_model_errors"
+require "lev/term_mapper"
+require "lev/routine"
 require "lev/handler"
 require "lev/handle_with"
 require "lev/handler_helper"
-require "lev/handler/error"
-require "lev/handler/errors"
-require "lev/handler/error_transferer"
-require "lev/handler/error_translator"
+require "lev/error"
+require "lev/errors"
+require "lev/error_transferer"
+require "lev/error_translator"
+
 require "lev/form_builder"
-require "lev/algorithm"
-require "lev/delegate_to_algorithm"
+require "lev/delegate_to_routine"
 require "lev/transaction_isolation"
 
 

data/lib/lev/delegate_to_routine.rb

@@ -0,0 +1,25 @@
+# ActiveRecord::Base.delegate_to_routine
+#
+# Let active records delegate certain (likely non-trivial) actions to routines
+# 
+# Arguments:
+#   method: a symbol for the instance method to delegate, e.g. :destroy
+#   options: a hash of options including...
+#      :routine_class => The class of the routine to delegate to; if not 
+#        given, 
+ActiveRecord::Base.define_singleton_method(:delegate_to_routine) do |method, options={}|
+  routine_class = options[:routine_class]
+
+  if routine_class.nil?
+    routine_class_name = "#{method.to_s.capitalize}#{self.name}"
+    routine_class = Kernel.const_get(routine_class_name)
+  end
+
+  self.instance_eval do
+    alias_method "#{method}_original".to_sym, method
+    define_method method do
+      routine_class.call(self)
+    end
+  end
+
+end

data/lib/lev/error.rb

@@ -0,0 +1,28 @@
+module Lev
+
+  class Error
+
+    attr_accessor :code
+    attr_accessor :data
+    attr_accessor :kind
+    attr_accessor :message
+
+    # The inputs related to this error
+    attr_accessor :offending_inputs
+
+    def initialize(args={})
+      raise IllegalArgument, "must supply a :code" if args[:code].blank?
+
+      self.code = args[:code]
+      self.data = args[:data]
+      self.kind = args[:kind]
+      self.message = args[:message]
+      self.offending_inputs = args[:offending_inputs]
+    end
+
+    def translate
+      ErrorTranslator.translate(self)
+    end
+  end
+
+end

data/lib/lev/error_transferer.rb

@@ -0,0 +1,41 @@
+module Lev
+
+  class ErrorTransferer
+
+    def self.transfer(source, target_routine, input_mapper, fail_if_errors=false)
+      case source
+      when ActiveRecord::Base, Lev::Paramifier
+        source.errors.each_with_type_and_message do |attribute, type, message|
+          target_routine.nonfatal_error(
+            code: type, 
+            data: {
+              model: source,
+              attribute: attribute
+            }, 
+            kind: :activerecord,
+            message: message,
+            offending_inputs: input_mapper.map(attribute)
+          )
+        end
+      when Lev::Errors
+        source.each do |error|
+          target_routine.nonfatal_error(
+            code: error.code,
+            data: error.data,
+            kind: error.kind,
+            message: error.message,
+            offending_inputs: input_mapper.map(error.offending_inputs)
+          )
+        end
+      else
+        raise Exception
+      end
+
+      # We add nonfatal errors above and then have this call here so that all
+      # errors can be transferred before we freak out.
+      throw :fatal_errors_encountered if target_routine.errors? && fail_if_errors
+    end
+
+  end
+
+end

data/lib/lev/{handler/error_translator.rb → error_translator.rb}

@@ -1,4 +1,4 @@
-module Lev::Handler
+module Lev
 
   class ErrorTranslator
 

data/lib/lev/errors.rb

@@ -0,0 +1,41 @@
+module Lev
+
+  # A collection of Error objects.  
+  #
+  class Errors < Array
+
+    def add(fail, args={}) 
+      args[:kind] ||= :lev
+      error = Error.new(args)
+      return if ignored_error_procs.any?{|proc| proc.call(error)}
+      self.push(error)
+      throw :fatal_errors_encountered if fail
+    end
+
+    def ignore(arg)
+      proc = arg.is_a?(Symbol) ?
+               Proc.new{|error| error.code == arg} :
+               arg
+      
+      raise IllegalArgument if !proc.respond_to?(:call)
+
+      ignored_error_procs.push(proc)
+    end
+
+    def [](key)
+      self[key]
+    end
+
+    # Checks to see if the provided input is associated with one of the errors.
+    def has_offending_input?(input)
+      self.any? {|error| [error.offending_inputs].flatten.include? input}
+    end
+
+  protected
+
+    def ignored_error_procs
+      @ignored_error_procs ||= []
+    end
+
+  end
+end

data/lib/lev/exceptions.rb

@@ -1,2 +1,4 @@
 class Lev::IsolationMismatch < StandardError; end
-class Lev::SecurityTransgression < StandardError; end
+class Lev::SecurityTransgression < StandardError; end
+class Lev::AlgorithmError < StandardError; end
+class Lev::AbstractMethodCalled < StandardError; end

data/lib/lev/form_builder.rb

@@ -26,7 +26,7 @@ module Lev
     def fields_for(record_name, record_object = nil, fields_options = {}, &block)
       raise "Didn't put fields_for into LevitateFormBuilder yet"
     end
-
+ 
   protected
 
     def get_form_params_entry(name)
@@ -38,7 +38,7 @@ module Lev
     end
 
     def has_error?(name)
-      @options[:errors].present? ? @options[:errors].has_offending_param?([@object_name, name]) : false
+      @options[:errors].present? ? @options[:errors].has_offending_input?([@object_name, name]) : false
     end
 
     def set_value_if_available(method, options)
@@ -58,6 +58,6 @@ end
 def lev_form_for(record_or_name_or_array, *args, &proc)
   options = args.extract_options!
   options[:params] = params
-  options[:errors] = @errors || []
+  options[:errors] = handler_errors # @errors || (@handler_outcome ? @handler_outcome.errors : [])
   form_for(record_or_name_or_array, *(args << options.merge(:builder => Lev::FormBuilder)), &proc)
 end

data/lib/lev/handle_with.rb

@@ -18,14 +18,13 @@ module Lev
   #               failure: lambda { render 'new', alert: 'Error' })
   #
   # handle_with takes care of calling the handler and populates
-  # @errors and @results objects with the return values from the handler
-  #
+  # a @handler_result object with the return value from the handler
   #
   # The 'success' and 'failure' lambdas are called if there aren't or are errors,
   # respectively.  Alternatively, if you supply a 'complete' lambda, that lambda
   # will be called regardless of whether there are any errors.  Inside these lambdas
-  # (and inside the views they connect to), there will be @errors and @results 
-  # variables containing the errors and results from the handler.
+  # (and inside the views they connect to), there will be the @handler_outcome 
+  # variable containing the errors and results from the handler.
   #
   # Specifying 'params' is optional.  If you don't specify it, HandleWith will
   # use the entire params hash from the request.
@@ -42,10 +41,10 @@ module Lev
       options[:request] ||= request
       options[:caller] ||= current_user
 
-      @results, @errors = handler.handle(options)
+      @handler_result = handler.handle(options)
 
       if complete_action.nil?
-        @errors.empty? ?
+        @handler_result.errors.empty? ?
           success_action.call :
           failure_action.call    
       else

data/lib/lev/handler.rb

@@ -2,29 +2,33 @@
 module Lev
 
   class Paramifier
+    def as_hash(keys)
+      keys = [keys].flatten.compact
+      Hash[keys.collect { |key| [key, self.send(key)] }]
+    end
   end
 
-  # Common methods for all handlers.  Handlers are classes that are responsible 
-  # for taking input data from a form or other widget and doing something
-  # with it.
+  # Common methods for all handlers.  Handlers are extensions of Routines 
+  # and are responsible for taking input data from a form or other widget and 
+  # doing something with it.  See Lev::Routine for more information.
   #
   # All handlers must:
   #   2) include this module ("include Lev::Handler")
-  #   3) implement the 'exec' method which takes no arguments and does the 
+  #   3) implement the 'handle' method which takes no arguments and does the 
   #      work the handler is charged with
   #   4) implement the 'authorized?' method which returns true iff the 
   #      caller is authorized to do what the handler is charged with
   #
   # Handlers may:
-  #   1) implement the 'setup' method which runs before 'authorized?' and 'exec'.
+  #   1) implement the 'setup' method which runs before 'authorized?' and 'handle'.
   #      This method can do anything, and will likely include setting up some 
   #      instance objects based on the params.
   #   2) Call the class method "paramify" to declare, cast, and validate parts of
   #      the params hash. The first argument to paramify is the key in params
   #      which points to a hash of params to be paramified.  The block passed to
-  #      paramify looks just like the guts of an ActiveAttr model.  Examples:
+  #      paramify looks just like the guts of an ActiveAttr model.
   #      
-  #      when the incoming params includes :search => {:type, :terms, :num_results}
+  #      When the incoming params includes :search => {:type, :terms, :num_results}
   #      the Handler class would look like:
   #
   #      class MyHandler
@@ -44,7 +48,7 @@ module Lev
   #                                            greater_than_or_equal_to: 0 }                               
   #        end
   #        
-  #        def exec
+  #        def handle
   #          # By this time, if there were any errors the handler would have
   #          # already populated the errors object and returned.
   #          #
@@ -60,26 +64,27 @@ module Lev
   #   2) 'caller' --  the user submitting the input
   #   3) 'errors' --  an object in which to store errors
   #   4) 'results' -- a hash in which to store results for return to calling code
-  #   5) 'options' -- a hash containing the options passed in, useful for other
+  #   5) 'request' -- the HTTP request
+  #   6) 'options' -- a hash containing the options passed in, useful for other
   #                   nonstandard data.
-  #   
-  # Handler 'exec' methods don't return anything; they just set values in 
+  #
+  # These methods are available iff these data were supplied in the call
+  # to the handler (not all handlers need all of this).  However, note that
+  # the Lev::HandleWith module supplies an easy way to call Handlers from 
+  # controllers -- when this way is used, all of the methods above are available.
+  #
+  # Handler 'handle' methods don't return anything; they just set values in 
   # the errors and results objects.  The documentation for each handler
   # should explain what the results will be and any nonstandard data required
   # to be passed in in the options.
   #
-  # See the documentation for Lev::RoutineNesting about other requirements and 
-  # capabilities of handler classes.
-  #
-  # The handle methods take a hash of arguments.  
-  #   caller: the calling user
-  #   params: the params object
-  #   request: the http request object
+  # In addition to the class- and instance-level "call" methods provided by 
+  # Lev::Routine, Handlers have a class-level "handle" method (an alias of
+  # the class-level "call" method).  The convention for handlers is that the
+  # call methods take a hash of options/inputs.  The instance-level handle
+  # method doesn't take any arguments since the arguments have been stored
+  # as instance variables by the time the instance-level handle method is called.
   # 
-  # These arguments are optional or required depending on the implementation of
-  # the specific handler, i.e. if a handler wants to use the 'caller' method, it 
-  # must have been supplied to the handle method.  
-  #
   # Example:
   # 
   #   class MyHandler
@@ -88,7 +93,7 @@ module Lev
   #     def authorized?
   #       # return true iff exec is allowed to be called, e.g. might
   #       # check the caller against the params
-  #     def exec
+  #     def handle
   #       # do the work, add errors to errors object and results to the results hash as needed
   #     end
   #   end
@@ -98,21 +103,14 @@ module Lev
     def self.included(base)
       base.extend(ClassMethods)
       base.class_eval do
-        include Lev::RoutineNesting
+        include Lev::Routine
       end
     end
 
-    def handle(options={})
-      in_transaction do
-        handle_guts(options)
-      end
-    end
-
-    alias_method :call, :handle
-
     module ClassMethods
+  
       def handle(options={})
-        new.handle(options)
+        call(options)
       end
 
       def paramify(group, options={}, &block)
@@ -161,53 +159,57 @@ module Lev
       end
     end
 
-    def transfer_errors_from(source, param_group)
-      ErrorTransferer.transfer(source, self, param_group)
-    end
-
-    attr_accessor :errors
-
   protected
 
     attr_accessor :params
     attr_accessor :request
     attr_accessor :options
     attr_accessor :caller
-    attr_accessor :results
 
-    def handle_guts(options)
+    # Provided for development / debugging purposes -- gives a way to pass
+    # information in a raised security transgression when authorized? is false
+    attr_accessor :auth_error_details
+
+    # This is a method required by Lev::Routine.  It enforces the steps common
+    # to all handlers.  
+    def exec(options)
       self.params = options.delete(:params)
       self.request = options.delete(:request)
       self.caller = options.delete(:caller)
       self.options = options
-      self.errors = Errors.new
-      self.results = {}
 
       setup
-      raise Lev.configuration.security_transgression_error unless authorized?
+      raise Lev.configuration.security_transgression_error, auth_error_details unless authorized?
       validate_paramified_params
-      exec unless errors?
-
-      [self.results, self.errors]
+      handle unless errors?
     end
 
+    # Default setup implementation -- a no-op
     def setup; end
 
+    # Default authorized? implementation.  It returns true so that every 
+    # handler realization has to make a conscious decision about who is authorized
+    # to call the handler. To help the common error of forgetting to override this 
+    # method in a handler instance, we provide an error message when this default
+    # implementation is called.
     def authorized?
-      false # default for safety, forces implementation in the handler
+      self.auth_error_details = 
+        "Access to handlers is prevented by default.  You need to override the " +
+        "'authorized?' in this handler to explicitly grant access."
+      false
     end
 
+    
+
+    # Helper method to validate paramified params and to transfer any errors
+    # into the handler.
     def validate_paramified_params
       self.class.paramify_methods.each do |method|
         params = send(method)
-        transfer_errors_from(params, params.group) if !params.valid?
+        transfer_errors_from(params, TermsMapper.scope(params.group)) if !params.valid?
       end
     end
 
-    def errors?
-      errors.any?
-    end
-
   end
 
 end