lotus-controller 0.2.0 → 0.3.0

data/lib/lotus/action/throwable.rb

@@ -19,8 +19,12 @@ module Lotus
         base.extend ClassMethods
       end
 
+      # Throw API class methods
+      #
+      # @since 0.1.0
+      # @api private
       module ClassMethods
-        protected
+        private
 
         # Handle the given exception with an HTTP status code.
         #
@@ -74,8 +78,8 @@ module Lotus
       # @see Lotus::Controller#handled_exceptions
       # @see Lotus::Action::Throwable#handle_exception
       # @see Lotus::Http::Status:ALL
-      def halt(code)
-        status(*Http::Status.for_code(code))
+      def halt(code = nil)
+        status(*Http::Status.for_code(code)) if code
         throw :halt
       end
 
@@ -124,7 +128,23 @@ module Lotus
       # @api private
       def _handle_exception(exception)
         raise unless configuration.handle_exceptions
-        halt configuration.exception_code(exception.class)
+
+        instance_exec(
+          exception,
+          &_exception_handler(exception)
+        )
+      end
+
+      # @since 0.3.0
+      # @api private
+      def _exception_handler(exception)
+        handler = configuration.exception_handler(exception)
+
+        if respond_to?(handler.to_s, true)
+          method(handler)
+        else
+          ->(ex) { halt handler }
+        end
       end
     end
   end

data/lib/lotus/action/validatable.rb

@@ -0,0 +1,128 @@
+module Lotus
+  module Action
+    module Validatable
+      # Defines the class name for anoymous params
+      #
+      # @api private
+      # @since 0.3.0
+      PARAMS_CLASS_NAME = 'Params'.freeze
+
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+          expose :params, :errors
+        end
+      end
+
+      # Validatable API class methods
+      #
+      # @since 0.1.0
+      # @api private
+      module ClassMethods
+        # Whitelist valid parameters to be passed to Lotus::Action#call.
+        #
+        # This feature isn't mandatory, but higly recommended for security
+        # reasons.
+        #
+        # Because params come into your application from untrusted sources, it's
+        # a good practice to filter only the wanted keys that serve for your
+        # specific use case.
+        #
+        # Once whitelisted, the params are available as an Hash with symbols
+        # as keys.
+        #
+        #
+        #
+        # It accepts an anonymous block where all the params can be listed.
+        # It internally creates an inner class which inherits from
+        # Lotus::Action::Params.
+        #
+        #
+        # Alternatively, it accepts an concrete class that should inherit from
+        # Lotus::Action::Params.
+        #
+        # @param klass [Class,nil] a Lotus::Action::Params subclass
+        # @param blk [Proc] a block which defines the whitelisted params
+        #
+        # @return void
+        #
+        # @since 0.3.0
+        #
+        # @see Lotus::Action::Params
+        #
+        # @example Anonymous Block
+        #   require 'lotus/controller'
+        #
+        #   class Signup
+        #     include Lotus::Action
+        #
+        #     params do
+        #       param :first_name
+        #       param :last_name
+        #       param :email
+        #     end
+        #
+        #     def call(params)
+        #       puts params.class            # => Signup::Params
+        #       puts params.class.superclass # => Lotus::Action::Params
+        #
+        #       puts params[:first_name]     # => "Luca"
+        #       puts params[:admin]          # => nil
+        #     end
+        #   end
+        #
+        # @example Concrete class
+        #   require 'lotus/controller'
+        #
+        #   class SignupParams < Lotus::Action::Params
+        #     param :first_name
+        #     param :last_name
+        #     param :email
+        #   end
+        #
+        #   class Signup
+        #     include Lotus::Action
+        #     params SignupParams
+        #
+        #     def call(params)
+        #       puts params.class            # => SignupParams
+        #       puts params.class.superclass # => Lotus::Action::Params
+        #
+        #       params[:first_name]          # => "Luca"
+        #       params[:admin]               # => nil
+        #     end
+        #   end
+        def params(klass = nil, &blk)
+          if block_given?
+            @params_class = const_set(PARAMS_CLASS_NAME,
+                                      Class.new(Params, &blk))
+          else
+            @params_class = klass
+          end
+        end
+
+        # Returns the class which defines the params
+        #
+        # Returns the class which has been provided to define the
+        # params. By default this will be Lotus::Action::Params.
+        #
+        # @return [Class] A params class (when whitelisted) or
+        #   Lotus::Action::Params
+        #
+        # @api private
+        # @since 0.3.0
+        def params_class
+          @params_class ||= params { }
+        end
+
+      end
+    end
+
+    # Expose validation errors
+    #
+    # @since 0.3.0
+    def errors
+      params.errors
+    end
+  end
+end

data/lib/lotus/controller.rb

@@ -1,7 +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'
 
@@ -15,14 +14,16 @@ module Lotus
   # @example
   #   require 'lotus/controller'
   #
-  #   class ArticlesController
-  #     include Lotus::Controller
+  #   module Articles
+  #     class Index
+  #       include Lotus::Action
   #
-  #     action 'Index' do
   #       # ...
   #     end
   #
-  #     action 'Show' do
+  #     class Show
+  #       include Lotus::Action
+  #
   #       # ...
   #     end
   #   end
@@ -241,28 +242,13 @@ module Lotus
       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
+    # Framework loading entry point
     #
-    # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
+    # @return [void]
     #
-    # @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
+    # @since 0.3.0
+    def self.load!
+      configuration.load!
     end
   end
 end

data/lib/lotus/controller/configuration.rb

@@ -68,9 +68,9 @@ module Lotus
       #     Controller = Lotus::Controller.duplicate(self)
       #
       #     module Controllers::Dashboard
-      #       include MyApp::Controller
+      #       class Index
+      #         include MyApp::Action
       #
-      #       action 'Index' do
       #         def call(params)
       #           # ...
       #         end
@@ -89,7 +89,7 @@ module Lotus
       #     # => will duplicate from MyApp::Controller
       def self.for(base)
         namespace = Utils::String.new(base).namespace
-        framework = Utils::Class.load!("(#{namespace}|Lotus)::Controller")
+        framework = Utils::Class.load_from_pattern!("(#{namespace}|Lotus)::Controller")
         framework.configuration.duplicate
       end
 
@@ -103,15 +103,17 @@ module Lotus
         reset!
       end
 
-      # @attr_writer handle_exceptions [TrueClass,FalseClass] Decide if handle
-      #   exceptions with an HTTP status or not
+      # @attr_writer handle_exceptions [TrueClass,FalseClass] Handle exceptions
+      #   with an HTTP status or leave them uncaught
       #
       # @since 0.2.0
       #
+      # @return void
+      #
       # @see Lotus::Controller::Configuration#handle_exceptions
       attr_writer :handle_exceptions
 
-      # Decide if handle exceptions with an HTTP status or let them uncaught
+      # Handle exceptions with an HTTP status or let them uncaught
       #
       # If this value is set to `true`, the configured exceptions will return
       # the specified HTTP status, the rest of them with `500`.
@@ -180,20 +182,16 @@ module Lotus
         @handled_exceptions.merge!(exception)
       end
 
-      # Return the HTTP status for the given exception
-      #
-      # Raised exceptions will return the configured HTTP status, only if
-      #   `handled_exceptions` is set on `true`.
+      # Return a callable handler for the given exception
       #
-      # @param exception [Hash] the exception class must be the key and the HTTP
-      #   status the value of the hash
+      # @param exception [Exception] an exception
       #
-      # @since 0.2.0
+      # @since 0.3.0
       # @api private
       #
       # @see Lotus::Controller::Configuration#handle_exception
-      def exception_code(exception)
-        @handled_exceptions.fetch(exception) { DEFAULT_ERROR_CODE }
+      def exception_handler(exception)
+        @handled_exceptions.fetch(exception.class) { DEFAULT_ERROR_CODE }
       end
 
       # Specify which is the default action module to be included when we use
@@ -237,11 +235,11 @@ module Lotus
       #     action_module MyAction
       #   end
       #
-      #   class DashboardController
-      #     include Lotus::Controller
-      #
+      #   module Dashboard
       #     # It includes MyAction, instead of Lotus::Action
-      #     action 'Index' do
+      #     class Index
+      #       include MyAction
+      #
       #       def call(params)
       #         # ...
       #       end
@@ -258,7 +256,9 @@ module Lotus
       #       include MyApp::Controller
       #
       #       # It includes MyApp::Action, instead of Lotus::Action
-      #       action 'Index' do
+      #       class Index
+      #         include MyApp::Action
+      #
       #         def call(params)
       #           # ...
       #         end
@@ -273,64 +273,54 @@ module Lotus
         end
       end
 
-      # Specify the default modules to be included when `Lotus::Action` (or the
-      # `action_module`) is included. This also works with
-      # `Lotus::Controller.action`.
+      # Configure the logic to be executed when Lotus::Action is included
+      # This is useful to DRY code by having a single place where to configure
+      # shared behaviors like authentication, sessions, cookies etc.
       #
-      # If not set, this option will be ignored.
+      # This method can be called multiple times.
       #
-      # This is part of a DSL, for this reason when this method is called with
-      # an argument, it will set the corresponding instance variable. When
-      # called without, it will return the already set value, or the default.
+      # @param blk [Proc] the code block
       #
-      # @overload modules(blk)
-      #   Adds the given block
-      #   @param value [Proc] specify the modules to be included
+      # @return [void]
       #
-      # @overload modules
-      #   Gets the value
-      #   @return [Array] the list of the specified procs
+      # @raise [ArgumentError] if called without passing a block
       #
-      # @since 0.2.0
+      # @since 0.3.0
       #
-      # @see Lotus::Controller::Dsl#action
-      # @see Lotus::Controller#duplicate
-      #
-      # @example Getting the value
-      #   require 'lotus/controller'
+      # @see Lotus::Controller.configure
+      # @see Lotus::Controller.duplicate
       #
-      #   Lotus::Controller.configuration.modules # => []
-      #
-      # @example Setting the value
+      # @example Configure shared logic.
       #   require 'lotus/controller'
-      #   require 'lotus/action/cookies'
-      #   require 'lotus/action/session'
       #
       #   Lotus::Controller.configure do
-      #     modules do
-      #       include Lotus::Action::Cookies
-      #       include Lotus::Action::Session
+      #     prepare do
+      #       include Lotus::Action::Sessions
+      #       include MyAuthentication
+      #       use SomeMiddleWare
+      #
+      #       before { authenticate! }
       #     end
       #   end
       #
-      #   class DashboardController
-      #     include Lotus::Controller
+      #   module Dashboard
+      #     class Index
+      #       # When Lotus::Action is included, it will:
+      #       #   * Include `Lotus::Action::Session` and `MyAuthentication`
+      #       #   * Configure to use `SomeMiddleWare`
+      #       #   * Configure a `before` callback that triggers `#authenticate!`
+      #       include Lotus::Action
       #
-      #     # It includes:
-      #     #   * Lotus::Action
-      #     #   * Lotus::Action::Cookies
-      #     #   * Lotus::Action::Session
-      #     action 'Index' do
       #       def call(params)
       #         # ...
       #       end
       #     end
       #   end
-      def modules(&blk)
+      def prepare(&blk)
         if block_given?
           @modules.push(blk)
         else
-          @modules
+          raise ArgumentError.new('Please provide a block')
         end
       end
 
@@ -350,16 +340,18 @@ module Lotus
       #     format custom: 'application/custom'
       #   end
       #
-      #   class ArticlesController
-      #     include Lotus::Controller
+      #   module Articles
+      #     class Index
+      #       include Lotus::Action
       #
-      #     action 'Index' do
       #       def call(params)
       #         # ...
       #       end
       #     end
       #
-      #     action 'Show' do
+      #     class Show
+      #       include Lotus::Action
+      #
       #       def call(params)
       #         # ...
       #         self.format = :custom
@@ -367,7 +359,7 @@ module Lotus
       #     end
       #   end
       #
-      #   action = ArticlesController::Index.new
+      #   action = Articles::Index.new
       #
       #   action.call({ 'HTTP_ACCEPT' => 'text/html' })
       #     # => Content-Type "text/html"
@@ -379,7 +371,7 @@ module Lotus
       #
       #
       #
-      #   action = ArticlesController::Show.new
+      #   action = Articles::Show.new
       #
       #   action.call({ 'HTTP_ACCEPT' => 'text/html' })
       #     # => Content-Type "application/custom"
@@ -395,7 +387,7 @@ module Lotus
       # requirement for the mime type.
       #
       # The given format must be coercible to a symbol, and be a valid mime type
-      # alias. If it isn't, at the runtime the framework will raise a 
+      # alias. If it isn't, at the runtime the framework will raise a
       # `Lotus::Controller::UnknownFormatError`.
       #
       # By default this value is nil.
@@ -436,6 +428,34 @@ module Lotus
         end
       end
 
+      # Set a charset as default fallback for all the requests without a strict
+      # requirement for the charset.
+      #
+      # By default this value is nil.
+      #
+      # @since 0.3.0
+      #
+      # @see Lotus::Action::Mime
+      #
+      # @example Getting the value
+      #   require 'lotus/controller'
+      #
+      #   Lotus::Controller.configuration.default_charset # => nil
+      #
+      # @example Setting the value
+      #   require 'lotus/controller'
+      #
+      #   Lotus::Controller.configure do
+      #     default_charset 'koi8-r'
+      #   end
+      def default_charset(charset = nil)
+        if charset
+          @default_charset = charset
+        else
+          @default_charset
+        end
+      end
+
       # Returns a format for the given mime type
       #
       # @param mime_type [#to_s,#to_str] A mime type
@@ -455,6 +475,9 @@ module Lotus
       # @param format [#to_sym] a format
       #
       # @return [String,nil] the corresponding mime type, if present
+      #
+      # @since 0.2.0
+      # @api private
       def mime_type_for(format)
         @formats.key(format)
       end
@@ -473,9 +496,20 @@ module Lotus
           c.modules            = modules.dup
           c.formats            = formats.dup
           c.default_format     = default_format
+          c.default_charset    = default_charset
         end
       end
 
+      # Return included modules
+      #
+      # @return [Array<Proc>] array of included blocks
+      #
+      # @since 0.2.0
+      # @api private
+      #
+      # @see Lotus::Controller::Configuration#prepare
+      attr_reader :modules
+
       # Reset all the values to the defaults
       #
       # @since 0.2.0
@@ -486,25 +520,42 @@ module Lotus
         @modules            = []
         @formats            = DEFAULT_FORMATS.dup
         @default_format     = nil
+        @default_charset    = nil
         @action_module      = ::Lotus::Action
       end
 
-      # Load the configuration for the given action
+      # Copy the configuration for the given action
       #
-      # @since 0.2.0
+      # @param base [Class] the target action
+      #
+      # @return void
+      #
+      # @since 0.3.0
       # @api private
-      def load!(base)
+      #
+      # @see Lotus::Controller::Configurable.included
+      def copy!(base)
         modules.each do |mod|
           base.class_eval(&mod)
         end
       end
 
+      # Load the framework
+      #
+      # @since 0.3.0
+      # @api private
+      def load!
+        freeze
+      end
+
       protected
+
       attr_accessor :handled_exceptions
       attr_accessor :formats
       attr_writer :action_module
       attr_writer :modules
       attr_writer :default_format
+      attr_writer :default_charset
     end
   end
 end