lev 0.0.1

data/lib/lev/handle_with.rb

@@ -0,0 +1,48 @@
+
+module Lev
+
+  # A utility method for calling handlers from controllers.  To use,
+  # include this in your relevant controllers (or in your ApplicationController),
+  # e.g.:
+  #
+  #   class ApplicationController
+  #     include Lev::HandleWith
+  #     ...
+  #   end
+  #
+  # Then, call it from your various controller actions, e.g.:
+  #
+  #   handle_with(MyFormHandler,
+  #               params: params,
+  #               success: lambda { redirect_to 'show', notice: 'Success!'},
+  #               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
+  #
+  # 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.
+  #
+  # Specifying 'params' is optional.  If you don't specify it, HandleWith will
+  # use the entire params hash from the request.
+  #
+  module HandleWith
+    def handle_with(handler, options)
+      options[:success] ||= lambda {}
+      options[:failure] ||= lambda {}
+      options[:params] ||= params
+
+      @results, @errors = handler.handle(current_user, options[:params])
+
+      if options[:complete].nil?
+        @errors.empty? ?
+          options[:success].call :
+          options[:failure].call    
+      else
+        options[:complete].call
+      end
+    end
+  end
+
+end

data/lib/lev/handler/error.rb

@@ -0,0 +1,30 @@
+module Lev::Handler
+
+  class Error
+    # need a type or source that can be :activerecord
+    # when activerecord, data should contain specific fields that
+    # can be used by generate_message in BetterErrors
+    attr_accessor :code
+    attr_accessor :data
+    attr_accessor :kind
+    attr_accessor :message
+    attr_accessor :offending_params
+
+    def initialize(args={})
+      raise IllegalArgument if args[:code].blank?
+
+      self.code = args[:code]
+      self.data = args[:data]
+      self.kind = args[:kind]
+      self.message = args[:message]
+      
+      self.offending_params = args[:offending_params]
+      self.offending_params = [self.offending_params] if !(self.offending_params.is_a? Array)
+    end
+
+    def translate
+      ErrorTranslator.translate(self)
+    end
+  end
+
+end

data/lib/lev/handler/error_transferer.rb

@@ -0,0 +1,28 @@
+module Lev::Handler
+
+  class ErrorTransferer
+
+    def self.transfer(source, handler_target, param_group)
+      case source
+      when ActiveRecord::Base, Lev::Paramifier
+        source.errors.each_with_type_and_message do |attribute, type, message|
+          handler_target.errors.add(
+            code: type, 
+            data: {
+              model: source,
+              attribute: attribute
+            }, 
+            kind: :activerecord,
+            message: message,
+            offending_params: [param_group].flatten << attribute
+          )
+        end
+      else
+        raise Exception
+      end
+
+    end
+
+  end
+
+end

data/lib/lev/handler/error_translator.rb

@@ -0,0 +1,20 @@
+module Lev::Handler
+
+  class ErrorTranslator
+
+    def self.translate(error)
+      case error.kind
+      when :activerecord
+        model = error.data[:model]
+        attribute = error.data[:attribute]
+        # TODO error.message might always be populated now -- really need the other call after ||?
+        message = error.message || Lev::BetterActiveModelErrors.generate_message(model, attribute, error.code)
+        Lev::BetterActiveModelErrors.full_message(model, attribute, message)
+      else
+        error.code.to_s
+      end      
+    end
+
+  end
+
+end

data/lib/lev/handler/errors.rb

@@ -0,0 +1,19 @@
+module Lev::Handler
+
+  class Errors < Array
+    def add(args)
+      push(Error.new(args))
+    end
+
+    def [](key)
+      self[key]
+    end
+
+    # Checks to see if the provided param identifier is one of the offending
+    # params, e.g. has_offending_param?([:my_form, :my_text_field_name])
+    def has_offending_param?(param)
+      self.any?{|error| error.offending_params == param}
+    end
+  end
+
+end

data/lib/lev/handler.rb

@@ -0,0 +1,194 @@
+
+module Lev
+
+  class Paramifier
+  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.
+  #
+  # All handlers must:
+  #   2) include this module ("include Lev::Handler")
+  #   3) implement the 'exec' 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'.
+  #      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:
+  #      
+  #      when the incoming params includes :search => {:type, :terms, :num_results}
+  #      the Handler class would look like:
+  #
+  #      class MyHandler
+  #        include Lev::Handler
+  #
+  #        paramify :search do
+  #          attribute :search_type, type: String
+  #          validates :search_type, presence: true,
+  #                                  inclusion: { in: %w(Name Username Any),
+  #                                               message: "is not valid" }
+  #
+  #          attribute :search_terms, type: String
+  #          validates :search_terms, presence: true
+  #
+  #          attribute :num_results, type: Integer
+  #          validates :num_results, numericality: { only_integer: true,
+  #                                            greater_than_or_equal_to: 0 }                               
+  #        end
+  #        
+  #        def exec
+  #          # By this time, if there were any errors the handler would have
+  #          # already populated the errors object and returned.
+  #          #
+  #          # Paramify makes a 'search_params' attribute available through
+  #          # which you can access the paramified params, e.g.
+  #          x = search_params.num_results
+  #          ...
+  #        end
+  #      end
+  #
+  # All handler instance methods have the following available to them:
+  #   1) 'params' --  the params from the input
+  #   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
+  #   
+  # See the documentation for Lev::RoutineNesting about other requirements and 
+  # capabilities of handler classes.
+  #
+  # The handle methods take the caller and the params objects, which should be 
+  # self-explanatory.  
+  #
+  # Example:
+  # 
+  #   class MyHandler
+  #     include Lev::Handler
+  #   protected
+  #     def authorized?
+  #       # return true iff exec is allowed to be called, e.g. might
+  #       # check the caller against the params
+  #     def exec
+  #       # do the work, add errors to errors object and results to the results hash as needed
+  #     end
+  #   end
+  #
+  module Handler
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        include Lev::RoutineNesting
+      end
+    end
+
+    def call(caller, params, options={})
+      in_transaction do
+        handle_guts(caller, params)
+      end
+    end
+
+    module ClassMethods
+      def handle(caller, params, options={})
+        new.call(caller, params, options)
+      end
+
+      def paramify(group, options={}, &block)
+        method_name = "#{group.to_s}_params"
+        variable_sym = "@#{method_name}".to_sym
+
+        # Generate the dynamic ActiveAttr class given
+        # the paramify block; I think the caching of the class
+        # in paramify_classes is only necessary to maintain
+        # the name of the class set in the const_set statement
+
+        if paramify_classes[group].nil?
+          paramify_classes[group] = Class.new(Lev::Paramifier) do
+            include ActiveAttr::Model
+            cattr_accessor :group
+          end
+          paramify_classes[group].class_eval(&block)
+          paramify_classes[group].group = group
+
+          # Attach a name to this dynamic class
+          const_set("#{group.to_s.capitalize}Paramifier", 
+                    paramify_classes[group])
+        end
+
+        # Define the "#{group}_params" method to get the paramifier 
+        # instance wrapping the params
+        define_method method_name.to_sym do
+          if !instance_variable_get(variable_sym)
+            instance_variable_set(variable_sym, 
+                                  self.class.paramify_classes[group].new(params[group]))
+          end
+          instance_variable_get(variable_sym)
+        end
+
+        # Keep track of the accessor for the params so we can check
+        # errors in it later
+        paramify_methods.push(method_name.to_sym)
+      end
+
+      def paramify_methods
+        @paramify_methods ||= []
+      end
+
+      def paramify_classes
+        @paramify_classes ||= {}
+      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 :caller
+    attr_accessor :results
+
+    def handle_guts(caller, params)
+      self.params = params
+      self.caller = caller
+      self.errors = Errors.new
+      self.results = {}
+
+      setup
+      raise SecurityTransgression unless authorized?
+      validate_paramified_params
+      exec unless errors?
+
+      [self.results, self.errors]
+    end
+
+    def setup; end
+
+    def authorized?
+      false # default for safety, forces implementation in the handler
+    end
+
+    def validate_paramified_params
+      self.class.paramify_methods.each do |method|
+        params = send(method)
+        transfer_errors_from(params, params.group) if !params.valid?
+      end
+    end
+
+    def errors?
+      errors.any?
+    end
+
+  end
+
+end

data/lib/lev/handler_helper.rb

@@ -0,0 +1,3 @@
+def handler_errors
+  @errors || Lev::Handler::Errors.new
+end

data/lib/lev/routine_nesting.rb

@@ -0,0 +1,127 @@
+module Lev
+
+  # Manages running of routines inside other routines.  In the Lev context, 
+  # Handlers and Algorithms are routines.  A routine and any routines nested
+  # inside of it are executed within a single transaction, or depending on the
+  # requirements of all the routines, no transaction at all.
+  #
+  # Classes that include this module get:
+  #
+  #  1) a "run" method for running nested routines in a standardized way.
+  #     Routines executed through the run method get hooked into the calling
+  #     hierarchy.
+  # 
+  #  2) a "runner" accessor which points to the routine which called it. If
+  #     runner is nil that means that no other routine called it (some other 
+  #     code did)
+  # 
+  #  3) a "topmost_runner" which points to the highest routine in the calling
+  #     hierarchy (that routine whose 'runner' is nil)
+  #
+  # Classes that include this module must:
+  #
+  #  1) supply a "call" instance method (def call(*args, &block)) that passes
+  #     its arguments and block to whatever code inside the class does the work
+  #     of the class
+  #
+  # Classes that include this module may:
+  #
+  #  1) Call the class-level "uses_routine" method to indicate which other 
+  #     routines will be run.  Helps set isolation levels, etc.  When this
+  #     method is used, the provided routine may
+  #  
+  #  2) Set a default transaction isolation level by declaring a class method
+  #     named "default_transaction_isolation" that returns an instance of 
+  #     Lev::TransactionIsolation
+  #   
+  #
+  module RoutineNesting
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      
+      # Called at a routine's class level to foretell which other routines will
+      # be used when this routine executes.  Helpful for figuring out ahead of
+      # time what kind of transaction isolation level should be used.
+      def uses_routine(routine_class, options={})
+        symbol = options[:as] || routine_class.name.underscore.gsub('/','_').to_sym
+
+        raise IllegalArgument, "Routine #{routine_class} has already been registered" \
+          if nested_routines[symbol]
+
+        nested_routines[symbol] = routine_class
+
+        transaction_isolation.replace_if_more_isolated(routine_class.transaction_isolation)
+      end
+
+      def transaction_isolation
+        @transaction_isolation ||= default_transaction_isolation
+      end
+
+      def default_transaction_isolation
+        TransactionIsolation.no_transaction 
+      end
+
+      def nested_routines
+        @nested_routines ||= {}
+      end
+
+    end
+
+    def in_transaction(options={}) 
+      if self == topmost_runner || self.class.transaction_isolation == TransactionIsolation.no_transaction
+        yield
+      else
+        ActiveRecord::Base.isolation_level( self.class.transaction_isolation.symbol ) do
+          ActiveRecord::Base.transaction { yield }
+        end
+      end
+    end
+
+    def run(other_routine, *args, &block)
+      if other_routine.is_a? Symbol
+        nested_routine = self.class.nested_routines[other_routine]
+        if nested_routine.nil?
+          raise IllegalArgument, 
+                "Routine symbol #{other_routine} does not point to a registered routine"
+        end
+        other_routine = nested_routine
+      end
+
+      other_routine = other_routine.new if other_routine.is_a? Class
+
+      included_modules = other_routine.eigenclass.included_modules
+
+      raise IllegalArgument, "Can only run another nested routine" \
+        if !(included_modules.include? Lev::RoutineNesting)
+
+      other_routine.runner = self
+      other_routine.call(*args, &block)
+    end
+
+    attr_reader :runner
+
+  protected
+
+    attr_writer :runner
+
+    def topmost_runner
+      runner.nil? ? self : runner.topmost_runner
+    end
+
+    def runner=(runner)
+      @runner = runner
+
+      if topmost_runner.class.transaction_isolation.weaker_than(self.class.default_transaction_isolation)
+        raise IsolationMismatch, 
+              "The routine being run has a stronger isolation requirement than " + 
+              "the isolation being used by the routine(s) running it; call the " +
+              "'uses' method in the running routine's initializer"
+      end
+    end
+
+  end
+end

data/lib/lev/transaction_isolation.rb

@@ -0,0 +1,59 @@
+module Lev
+  class TransactionIsolation
+
+    def initialize(symbol)
+      raise IllegalArgument, "Invalid isolation symbol" if !@@symbols_to_isolation_levels.has_key?(symbol)
+      @symbol = symbol
+    end
+
+    def self.no_transaction;   new(:no_transaction);   end
+    def self.read_uncommitted; new(:read_uncommitted); end
+    def self.read_committed;   new(:read_committed);   end
+    def self.repeatable_read;  new(:repeatable_read);  end
+    def self.serializable;     new(:serializable);     end
+
+
+    def replace_if_more_isolated(other_transaction_isolation)
+      if other_transaction_isolation.isolation_level > self.isolation_level
+        self.symbol = other_transaction_isolation.symbol
+      end
+      self
+    end
+
+    def weaker_than(other)
+      self.isolation_level < other.isolation_level
+    end
+
+    def self.mysql_default
+      # MySQL default per https://blog.engineyard.com/2010/a-gentle-introduction-to-isolation-levels
+      repeatable_read
+    end
+
+    def ==(other)
+      self.symbol == other.symbol
+    end
+
+    def eql?(other)
+      self == other
+    end
+    
+    attr_reader :symbol
+
+  protected
+
+    def isolation_level
+      @@symbols_to_isolation_levels[symbol]
+    end
+
+    @@symbols_to_isolation_levels = {
+      no_transaction:   0,
+      read_uncommitted: 1,
+      read_committed:   2,
+      repeatable_read:  3,
+      serializable:     4
+    }
+
+    attr_writer :symbol
+
+  end
+end

data/lib/lev/version.rb

@@ -0,0 +1,3 @@
+module Lev
+  VERSION = "0.0.1"
+end

data/lib/lev.rb

@@ -0,0 +1,57 @@
+require "transaction_isolation"
+require "transaction_retry"
+require "active_attr"
+
+require "lev/version"
+require "lev/exceptions"
+require "lev/routine_nesting"
+require "lev/better_active_model_errors"
+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/form_builder"
+require "lev/algorithm"
+require "lev/delegate_to_algorithm"
+require "lev/transaction_isolation"
+
+
+module Lev
+  class << self
+    
+    ###########################################################################
+    #
+    # Configuration machinery.
+    #
+    # To configure Lev, put the following code in your applications 
+    # initialization logic (eg. in the config/initializers in a Rails app)
+    #
+    #   Lev.configure do |config|
+    #     config.form_error_class = 'fancy_error'
+    #     ...
+    #   end
+    #
+    
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    class Configuration
+      # This HTML class is added to form fields that caused errors
+      attr_accessor :form_error_class
+      
+      def initialize      
+        @form_error_class = 'error'
+        super
+      end
+    end
+        
+  end
+end