lotus-controller 0.1.0 → 0.2.0

data/lib/lotus/action/params.rb

@@ -12,7 +12,7 @@ module Lotus
     #   * Default: it returns the given hash as it is. It's useful for testing purposes.
     #
     # @since 0.1.0
-    class Params < Utils::Hash
+    class Params
       # The key that returns raw input from the Rack env
       #
       # @since 0.1.0
@@ -24,6 +24,12 @@ module Lotus
       # @since 0.1.0
       ROUTER_PARAMS = 'router.params'.freeze
 
+      # @attr_reader env [Hash] the Rack env
+      #
+      # @since 0.2.0
+      # @api private
+      attr_reader :env
+
       # Initialize the params and freeze them.
       #
       # @param env [Hash] a Rack env or an hash of params.
@@ -32,13 +38,24 @@ module Lotus
       #
       # @since 0.1.0
       def initialize(env)
-        super _extract(env)
-        symbolize!
+        @env    = env
+        @params = Utils::Hash.new(_extract).symbolize!
         freeze
       end
 
+      # Returns the object associated with the given key
+      #
+      # @param key [Symbol] the key
+      #
+      # @return [Object,nil] return the associated object, if found
+      #
+      # @since 0.2.0
+      def [](key)
+        @params[key]
+      end
+
       private
-      def _extract(env)
+      def _extract
         {}.tap do |result|
           if env.has_key?(RACK_INPUT)
             result.merge! ::Rack::Request.new(env).params

data/lib/lotus/action/rack.rb

@@ -4,10 +4,91 @@ module Lotus
     #
     # @since 0.1.0
     module Rack
+      # The default session key for Rack
+      #
+      # @since 0.1.0
+      # @api private
       SESSION_KEY           = 'rack.session'.freeze
+
+      # The default HTTP response code
+      #
+      # @since 0.1.0
+      # @api private
       DEFAULT_RESPONSE_CODE = 200
+
+      # The default Rack response body
+      #
+      # @since 0.1.0
+      # @api private
       DEFAULT_RESPONSE_BODY = []
 
+      # Override Ruby's hook for modules.
+      # It includes basic Lotus::Action modules to the given class.
+      #
+      # @param base [Class] the target action
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Use a Rack middleware as a before callback.
+        #
+        # The middleware will be used as it is, no matter if it's a class or an
+        # instance. If it needs to be initialized, please do it before to pass
+        # it as the argument of this method.
+        #
+        # At the runtime, the middleware be invoked with the raw Rack env.
+        #
+        # Multiple middlewares can be employed, just by using multiple times
+        # this method.
+        #
+        # @param middleware [#call] A Rack middleware
+        #
+        # @since 0.2.0
+        #
+        # @see Lotus::Action::Callbacks::ClassMethods#before
+        #
+        # @example Class Middleware
+        #   require 'lotus/controller'
+        #
+        #   class SessionsController
+        #     include Lotus::Controller
+        #
+        #     action 'Create' do
+        #       use OmniAuth
+        #
+        #       def call(params)
+        #         # ...
+        #       end
+        #     end
+        #   end
+        #
+        # @example Instance Middleware
+        #   require 'lotus/controller'
+        #
+        #   class SessionsController
+        #     include Lotus::Controller
+        #
+        #     action 'Create' do
+        #       use XMiddleware.new('x', 123)
+        #
+        #       def call(params)
+        #         # ...
+        #       end
+        #     end
+        #   end
+        def use(middleware)
+          before do |params|
+            middleware.call(params.env)
+          end
+        end
+      end
+
       protected
       # Sets the HTTP status code for the response
       #

data/lib/lotus/action/redirect.rb

@@ -4,6 +4,11 @@ module Lotus
     #
     # @since 0.1.0
     module Redirect
+      # The HTTP header for redirects
+      #
+      # @since 0.2.0
+      # @api private
+      LOCATION = 'Location'.freeze
 
       protected
 
@@ -26,7 +31,7 @@ module Lotus
       #     end
       #   end
       def redirect_to(url, status: 302)
-        headers.merge!('Location' => url)
+        headers.merge!(LOCATION => url)
         self.status = status
       end
     end

data/lib/lotus/action/session.rb

@@ -9,6 +9,7 @@ module Lotus
       # The key that returns raw session from the Rack env
       #
       # @since 0.1.0
+      # @api private
       SESSION_KEY = 'rack.session'.freeze
 
       protected

data/lib/lotus/action/throwable.rb

@@ -8,38 +8,18 @@ module Lotus
     # @since 0.1.0
     #
     # @see Lotus::Action::Throwable::ClassMethods#handle_exception
-    # @see Lotus::Action::Throwable#throw
+    # @see Lotus::Action::Throwable#halt
     # @see Lotus::Action::Throwable#status
     module Throwable
+      # @since 0.2.0
+      # @api private
+      RACK_ERRORS = 'rack.errors'.freeze
+
       def self.included(base)
-        base.class_eval do
-          extend ClassMethods
-        end
+        base.extend ClassMethods
       end
 
       module ClassMethods
-        def self.extended(base)
-          base.class_eval do
-            include Utils::ClassAttribute
-
-            # Action handled exceptions.
-            #
-            # When an handled exception is raised during #call execution, it will be
-            # translated into the associated HTTP status.
-            #
-            # By default there aren't handled exceptions, all the errors are threaded
-            # as a Server Side Error (500).
-            #
-            # @api private
-            # @since 0.1.0
-            #
-            # @see Lotus::Controller.handled_exceptions
-            # @see Lotus::Action::Throwable.handle_exception
-            class_attribute :handled_exceptions
-            self.handled_exceptions = Controller.handled_exceptions.dup
-          end
-        end
-
         protected
 
         # Handle the given exception with an HTTP status code.
@@ -50,8 +30,8 @@ module Lotus
         # This is a fine grained control, for a global configuration see
         # Lotus::Action.handled_exceptions
         #
-        # @param exception [Class] the exception class
-        # @param status [Fixmun] a valid HTTP status
+        # @param exception [Hash] the exception class must be the key and the
+        #   HTTP status the value of the hash
         #
         # @since 0.1.0
         #
@@ -62,7 +42,7 @@ module Lotus
         #
         #   class Show
         #     include Lotus::Action
-        #     handle_exception RecordNotFound, 404
+        #     handle_exception RecordNotFound => 404
         #
         #     def call(params)
         #       # ...
@@ -71,14 +51,14 @@ module Lotus
         #   end
         #
         #   Show.new.call({id: 1}) # => [404, {}, ['Not Found']]
-        def handle_exception(exception, status)
-          self.handled_exceptions[exception] = status
+        def handle_exception(exception)
+          configuration.handle_exception(exception)
         end
       end
 
       protected
 
-      # Throw the given HTTP status code.
+      # Halt the action execution with the given HTTP status code.
       #
       # When used, the execution of a callback or of an action is interrupted
       # and the control returns to the framework, that decides how to handle
@@ -89,14 +69,14 @@ module Lotus
       #
       # @param code [Fixnum] a valid HTTP status code
       #
-      # @since 0.1.0
+      # @since 0.2.0
       #
       # @see Lotus::Controller#handled_exceptions
       # @see Lotus::Action::Throwable#handle_exception
       # @see Lotus::Http::Status:ALL
-      def throw(code)
+      def halt(code)
         status(*Http::Status.for_code(code))
-        super :halt
+        throw :halt
       end
 
       # Sets the given code and message for the response
@@ -112,18 +92,39 @@ module Lotus
       end
 
       private
+      # @since 0.1.0
+      # @api private
       def _rescue
         catch :halt do
           begin
             yield
           rescue => exception
+            _reference_in_rack_errors(exception)
             _handle_exception(exception)
           end
         end
       end
 
+      # @since 0.2.0
+      # @api private
+      def _reference_in_rack_errors(exception)
+        if errors = @_env[RACK_ERRORS]
+          errors.write(_dump_exception(exception))
+          errors.flush
+        end
+      end
+
+      # @since 0.2.0
+      # @api private
+      def _dump_exception(exception)
+        [[exception.class, exception.message].compact.join(": "), *exception.backtrace].join("\n\t")
+      end
+
+      # @since 0.1.0
+      # @api private
       def _handle_exception(exception)
-        throw self.class.handled_exceptions.fetch(exception.class, 500)
+        raise unless configuration.handle_exceptions
+        halt configuration.exception_code(exception.class)
       end
     end
   end

data/lib/lotus/controller.rb

@@ -1,5 +1,6 @@
 require 'lotus/utils/class_attribute'
 require 'lotus/action'
+require 'lotus/controller/configuration'
 require 'lotus/controller/dsl'
 require 'lotus/controller/version'
 require 'rack-patch'
@@ -26,43 +27,241 @@ module Lotus
   #     end
   #   end
   module Controller
+    # Unknown format error
+    #
+    # This error is raised when a action sets a format that it isn't recognized
+    # both by `Lotus::Controller::Configuration` and the list of Rack mime types
+    #
+    # @since 0.2.0
+    #
+    # @see Lotus::Action::Mime#format=
+    class UnknownFormatError < ::StandardError
+      def initialize(format)
+        super("Cannot find a corresponding Mime type for '#{ format }'. Please configure it with Lotus::Controller::Configuration#format.")
+      end
+    end
+
     include Utils::ClassAttribute
 
-    # Global handled exceptions.
-    # When an handled exception is raised during #call execution, it will be
-    # translated into the associated HTTP status.
+    # Framework configuration
     #
-    # By default there aren't handled exceptions, all the errors are threaded
-    # as a Server Side Error (500).
+    # @since 0.2.0
+    # @api private
+    class_attribute :configuration
+    self.configuration = Configuration.new
+
+    # Configure the framework.
+    # It yields the given block in the context of the configuration
     #
-    # **Important:** Be sure to set this configuration, **before** the actions
-    # and controllers of your application are loaded.
+    # @param blk [Proc] the configuration block
     #
-    # @since 0.1.0
+    # @since 0.2.0
     #
-    # @see Lotus::Action::Throwable
+    # @see Lotus::Controller::Configuration
     #
     # @example
     #   require 'lotus/controller'
     #
-    #   Lotus::Controller.handled_exceptions = { RecordNotFound => 404 }
+    #   Lotus::Controller.configure do
+    #     handle_exceptions false
+    #   end
+    def self.configure(&blk)
+      configuration.instance_eval(&blk)
+    end
+
+    # Duplicate Lotus::Controller in order to create a new separated instance
+    # of the framework.
+    #
+    # The new instance of the framework will be completely decoupled from the
+    # original. It will inherit the configuration, but all the changes that
+    # happen after the duplication, won't be reflected on the other copies.
+    #
+    # @return [Module] a copy of Lotus::Controller
+    #
+    # @since 0.2.0
+    # @api private
+    #
+    # @example Basic usage
+    #   require 'lotus/controller'
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.dupe
+    #   end
+    #
+    #   MyApp::Controller == Lotus::Controller # => false
+    #
+    #   MyApp::Controller.configuration ==
+    #     Lotus::Controller.configuration # => false
+    #
+    # @example Inheriting configuration
+    #   require 'lotus/controller'
+    #
+    #   Lotus::Controller.configure do
+    #     handle_exceptions false
+    #   end
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.dupe
+    #   end
+    #
+    #   module MyApi
+    #     Controller = Lotus::Controller.dupe
+    #     Controller.configure do
+    #       handle_exceptions true
+    #     end
+    #   end
+    #
+    #   Lotus::Controller.configuration.handle_exceptions # => false
+    #   MyApp::Controller.configuration.handle_exceptions # => false
+    #   MyApi::Controller.configuration.handle_exceptions # => true
+    def self.dupe
+      dup.tap do |duplicated|
+        duplicated.configuration = configuration.duplicate
+      end
+    end
+
+    # Duplicate the framework and generate modules for the target application
+    #
+    # @param mod [Module] the Ruby namespace of the application
+    # @param controllers [String] the optional namespace where the application's
+    #   controllers will live
+    # @param blk [Proc] an optional block to configure the framework
+    #
+    # @return [Module] a copy of Lotus::Controller
+    #
+    # @since 0.2.0
+    #
+    # @see Lotus::Controller#dupe
+    # @see Lotus::Controller::Configuration
+    # @see Lotus::Controller::Configuration#action_module
+    #
+    # @example Basic usage
+    #   require 'lotus/controller'
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.duplicate(self)
+    #   end
+    #
+    #   # It will:
+    #   #
+    #   # 1. Generate MyApp::Controller
+    #   # 2. Generate MyApp::Action
+    #   # 3. Generate MyApp::Controllers
+    #   # 4. Configure MyApp::Action as the default module for actions
+    #
+    #  module MyApp::Controllers::Dashboard
+    #    include MyApp::Controller
     #
-    #   class Show
-    #     include Lotus::Action
+    #    action 'Index' do # this will inject MyApp::Action
+    #      def call(params)
+    #        # ...
+    #      end
+    #    end
+    #  end
     #
-    #     def call(params)
+    # @example Compare code
+    #   require 'lotus/controller'
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.duplicate(self) do
     #       # ...
-    #       raise RecordNotFound.new
     #     end
     #   end
     #
-    #   Show.new.call({id: 1}) # => [404, {}, ['Not Found']]
-    class_attribute :handled_exceptions
-    self.handled_exceptions = {}
+    #   # it's equivalent to:
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.dupe
+    #     Action     = Lotus::Action.dup
+    #
+    #     module Controllers
+    #     end
+    #
+    #     Controller.configure do
+    #       action_module MyApp::Action
+    #     end
+    #
+    #     Controller.configure do
+    #       # ...
+    #     end
+    #   end
+    #
+    # @example Custom controllers module
+    #   require 'lotus/controller'
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.duplicate(self, 'Ctrls')
+    #   end
+    #
+    #   defined?(MyApp::Controllers) # => nil
+    #   defined?(MyApp::Ctrls)       # => "constant"
+    #
+    #   # Developers can namespace controllers under Ctrls
+    #   module MyApp::Ctrls::Dashboard
+    #     # ...
+    #   end
+    #
+    # @example Nil controllers module
+    #   require 'lotus/controller'
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.duplicate(self, nil)
+    #   end
+    #
+    #   defined?(MyApp::Controllers) # => nil
+    #
+    #   # Developers can namespace controllers under MyApp
+    #   module MyApp::DashboardController
+    #     # ...
+    #   end
+    #
+    # @example Block usage
+    #   require 'lotus/controller'
+    #
+    #   module MyApp
+    #     Controller = Lotus::Controller.duplicate(self) do
+    #       handle_exceptions false
+    #     end
+    #   end
+    #
+    #   Lotus::Controller.configuration.handle_exceptions # => true
+    #   MyApp::Controller.configuration.handle_exceptions # => false
+    def self.duplicate(mod, controllers = 'Controllers', &blk)
+      dupe.tap do |duplicated|
+        mod.module_eval %{ module #{ controllers }; end } if controllers
+        mod.module_eval %{ Action = Lotus::Action.dup }
+
+        duplicated.module_eval %{
+          configure do
+            action_module #{ mod }::Action
+          end
+        }
 
+        duplicated.configure(&blk) if block_given?
+      end
+    end
+
+    # Override Ruby's hook for modules.
+    # It includes basic Lotus::Controller modules to the given Class (or Module).
+    # It sets a copy of the framework configuration
+    #
+    # @param base [Class,Module] the target controller
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
+    #
+    # @see Lotus::Controller::Dsl
     def self.included(base)
+      conf = self.configuration.duplicate
+
       base.class_eval do
         include Dsl
+        include Utils::ClassAttribute
+
+        class_attribute :configuration
+        self.configuration = conf
       end
     end
   end