lotus-controller 0.2.0 → 0.3.0

data/lib/lotus/action/params.rb

@@ -1,4 +1,6 @@
 require 'lotus/utils/hash'
+require 'lotus/validations'
+require 'set'
 
 module Lotus
   module Action
@@ -24,6 +26,67 @@ module Lotus
       # @since 0.1.0
       ROUTER_PARAMS = 'router.params'.freeze
 
+      # Whitelist and validate a parameter
+      #
+      # @param name [#to_sym] The name of the param to whitelist
+      #
+      # @raise [ArgumentError] if one the validations is unknown, or if
+      #   the size validator is used with an object that can't be coerced to
+      #   integer.
+      #
+      # @return void
+      #
+      # @since 0.3.0
+      #
+      # @see http://rdoc.info/gems/lotus-validations/Lotus/Validations
+      #
+      # @example Whitelisting
+      #   require 'lotus/controller'
+      #
+      #   class SignupParams < Lotus::Action::Params
+      #     param :email
+      #   end
+      #
+      #   params = SignupParams.new({id: 23, email: 'mjb@example.com'})
+      #
+      #   params[:email] # => 'mjb@example.com'
+      #   params[:id]    # => nil
+      #
+      # @example Validation
+      #   require 'lotus/controller'
+      #
+      #   class SignupParams < Lotus::Action::Params
+      #     param :email, presence: true
+      #   end
+      #
+      #   params = SignupParams.new({})
+      #
+      #   params[:email] # => nil
+      #   params.valid?  # => false
+      #
+      # @example Unknown validation
+      #   require 'lotus/controller'
+      #
+      #   class SignupParams < Lotus::Action::Params
+      #     param :email, unknown: true # => raise ArgumentError
+      #   end
+      #
+      # @example Wrong size validation
+      #   require 'lotus/controller'
+      #
+      #   class SignupParams < Lotus::Action::Params
+      #     param :email, size: 'twentythree'
+      #   end
+      #
+      #   params = SignupParams.new({})
+      #   params.valid? # => raise ArgumentError
+      def self.param(name, options = {})
+        attribute name, options
+        nil
+      end
+
+      include Lotus::Validations
+
       # @attr_reader env [Hash] the Rack env
       #
       # @since 0.2.0
@@ -38,11 +101,16 @@ module Lotus
       #
       # @since 0.1.0
       def initialize(env)
-        @env    = env
-        @params = Utils::Hash.new(_extract).symbolize!
+        @env = env
+        super(_compute_params)
         freeze
       end
 
+      def self.defined_attributes
+        result = super
+        return result if result.to_ary.any?
+      end
+
       # Returns the object associated with the given key
       #
       # @param key [Symbol] the key
@@ -51,10 +119,26 @@ module Lotus
       #
       # @since 0.2.0
       def [](key)
-        @params[key]
+        @attributes.get(key)
       end
 
+      # Returns the Ruby's hash
+      #
+      # @return [Hash]
+      #
+      # @since 0.3.0
+      def to_h
+        @attributes.to_h
+      end
+      alias_method :to_hash, :to_h
+
       private
+      def _compute_params
+        Utils::Hash.new(
+          _extract
+        ).symbolize!
+      end
+
       def _extract
         {}.tap do |result|
           if env.has_key?(RACK_INPUT)

data/lib/lotus/action/rack.rb

@@ -1,15 +1,11 @@
+require 'securerandom'
+
 module Lotus
   module Action
     # Rack integration API
     #
     # @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
@@ -22,6 +18,14 @@ module Lotus
       # @api private
       DEFAULT_RESPONSE_BODY = []
 
+      # The default HTTP Request ID length
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see Lotus::Action::Rack#request_id
+      DEFAULT_REQUEST_ID_LENGTH = 16
+
       # Override Ruby's hook for modules.
       # It includes basic Lotus::Action modules to the given class.
       #
@@ -56,10 +60,9 @@ module Lotus
         # @example Class Middleware
         #   require 'lotus/controller'
         #
-        #   class SessionsController
-        #     include Lotus::Controller
-        #
-        #     action 'Create' do
+        #   module Sessions
+        #     class Create
+        #       include Lotus::Action
         #       use OmniAuth
         #
         #       def call(params)
@@ -71,10 +74,9 @@ module Lotus
         # @example Instance Middleware
         #   require 'lotus/controller'
         #
-        #   class SessionsController
-        #     include Lotus::Controller
-        #
-        #     action 'Create' do
+        #   module Sessions
+        #     class Create
+        #       include Lotus::Controller
         #       use XMiddleware.new('x', 123)
         #
         #       def call(params)
@@ -90,31 +92,61 @@ module Lotus
       end
 
       protected
-      # Sets the HTTP status code for the response
+
+      # Gets the headers from the response
       #
-      # @param status [Fixnum] an HTTP status code
-      # @return [void]
+      # @return [Hash] the HTTP headers from the response
       #
       # @since 0.1.0
       #
       # @example
       #   require 'lotus/controller'
       #
-      #   class Create
+      #   class Show
       #     include Lotus::Action
       #
       #     def call(params)
       #       # ...
-      #       self.status = 201
+      #       self.headers            # => { ... }
+      #       self.headers.merge!({'X-Custom' => 'OK'})
       #     end
       #   end
-      def status=(status)
-        @_status = status
+      def headers
+        @headers
       end
 
-      # Sets the body of the response
+      # Returns a serialized Rack response (Array), according to the current
+      #   status code, headers, and body.
       #
-      # @param body [String] the body of the response
+      # @return [Array] the serialized response
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see Lotus::Action::Rack::DEFAULT_RESPONSE_CODE
+      # @see Lotus::Action::Rack::DEFAULT_RESPONSE_BODY
+      # @see Lotus::Action::Rack#status=
+      # @see Lotus::Action::Rack#headers
+      # @see Lotus::Action::Rack#body=
+      def response
+        [ @_status || DEFAULT_RESPONSE_CODE, headers, @_body || DEFAULT_RESPONSE_BODY.dup ]
+      end
+
+      # Calculates an unique ID for the current request
+      #
+      # @return [String] The unique ID
+      #
+      # @since 0.3.0
+      def request_id
+        # FIXME make this number configurable and document the probabilities of clashes
+        @request_id ||= SecureRandom.hex(DEFAULT_REQUEST_ID_LENGTH)
+      end
+
+      private
+
+      # Sets the HTTP status code for the response
+      #
+      # @param status [Fixnum] an HTTP status code
       # @return [void]
       #
       # @since 0.1.0
@@ -122,22 +154,22 @@ module Lotus
       # @example
       #   require 'lotus/controller'
       #
-      #   class Show
+      #   class Create
       #     include Lotus::Action
       #
       #     def call(params)
       #       # ...
-      #       self.body = 'Hi!'
+      #       self.status = 201
       #     end
       #   end
-      def body=(body)
-        body   = Array(body) unless body.respond_to?(:each)
-        @_body = body
+      def status=(status)
+        @_status = status
       end
 
-      # Gets the headers from the response
+      # Sets the body of the response
       #
-      # @return [Hash] the HTTP headers from the response
+      # @param body [String] the body of the response
+      # @return [void]
       #
       # @since 0.1.0
       #
@@ -149,29 +181,12 @@ module Lotus
       #
       #     def call(params)
       #       # ...
-      #       self.headers            # => { ... }
-      #       self.headers.merge!({'X-Custom' => 'OK'})
+      #       self.body = 'Hi!'
       #     end
       #   end
-      def headers
-        @headers
-      end
-
-      # Returns a serialized Rack response (Array), according to the current
-      #   status code, headers, and body.
-      #
-      # @return [Array] the serialized response
-      #
-      # @since 0.1.0
-      # @api private
-      #
-      # @see Lotus::Action::Rack::DEFAULT_RESPONSE_CODE
-      # @see Lotus::Action::Rack::DEFAULT_RESPONSE_BODY
-      # @see Lotus::Action::Rack#status=
-      # @see Lotus::Action::Rack#headers
-      # @see Lotus::Action::Rack#body=
-      def response
-        [ @_status || DEFAULT_RESPONSE_CODE, headers, @_body || DEFAULT_RESPONSE_BODY.dup ]
+      def body=(body)
+        body   = Array(body) unless body.respond_to?(:each)
+        @_body = body
       end
     end
   end

data/lib/lotus/action/redirect.rb

@@ -10,7 +10,7 @@ module Lotus
       # @api private
       LOCATION = 'Location'.freeze
 
-      protected
+      private
 
       # Redirect to the given URL
       #
@@ -19,7 +19,7 @@ module Lotus
       #
       # @since 0.1.0
       #
-      # @example
+      # @example With default status code (302)
       #   require 'lotus/controller'
       #
       #   class Create
@@ -30,8 +30,26 @@ module Lotus
       #       redirect_to 'http://example.com/articles/23'
       #     end
       #   end
+      #
+      #   action = Create.new
+      #   action.call({}) # => [302, {'Location' => '/articles/23'}, '']
+      #
+      # @example With custom status code
+      #   require 'lotus/controller'
+      #
+      #   class Create
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       redirect_to 'http://example.com/articles/23', status: 301
+      #     end
+      #   end
+      #
+      #   action = Create.new
+      #   action.call({}) # => [301, {'Location' => '/articles/23'}, '']
       def redirect_to(url, status: 302)
-        headers.merge!(LOCATION => url)
+        headers[LOCATION] = url
         self.status = status
       end
     end

data/lib/lotus/action/session.rb

@@ -1,3 +1,5 @@
+require 'lotus/action/flash'
+
 module Lotus
   module Action
     # Session API
@@ -12,6 +14,12 @@ module Lotus
       # @api private
       SESSION_KEY = 'rack.session'.freeze
 
+      # The key that is used by flash to transport errors
+      #
+      # @since 0.3.0
+      # @api private
+      ERRORS_KEY  = :__errors
+
       protected
 
       # Gets the session from the request and expose it as an Hash.
@@ -44,6 +52,95 @@ module Lotus
       def session
         @_env[SESSION_KEY] ||= {}
       end
+
+      private
+
+      # Container useful to transport data with the HTTP session
+      #
+      # @return [Lotus::Action::Flash] a Flash instance
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see Lotus::Action::Flash
+      def flash
+        @flash ||= Flash.new(session, request_id)
+      end
+
+      # In case of validations errors, preserve those informations after a
+      # redirect.
+      #
+      # @return [void]
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see Lotus::Action::Redirect#redirect_to
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   module Comments
+      #     class Index
+      #       include Lotus::Action
+      #       include Lotus::Action::Session
+      #
+      #       expose :comments
+      #
+      #       def call(params)
+      #         @comments = CommentRepository.all
+      #       end
+      #     end
+      #
+      #     class Create
+      #       include Lotus::Action
+      #       include Lotus::Action::Session
+      #
+      #       params do
+      #         param :text, type: String, presence: true
+      #       end
+      #
+      #       def call(params)
+      #         comment = Comment.new(params)
+      #         CommentRepository.create(comment) if params.valid?
+      #
+      #         redirect_to '/comments'
+      #       end
+      #     end
+      #   end
+      #
+      #   # The validation errors caused by Comments::Create are available
+      #   # **after the redirect** in the context of Comments::Index.
+      def redirect_to(*args)
+        super
+        flash[ERRORS_KEY] = errors.to_a unless params.valid?
+      end
+
+      # Read errors from flash or delegate to the superclass
+      #
+      # @return [Lotus::Validations::Errors] A collection of validation errors
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see Lotus::Action::Validatable
+      # @see Lotus::Action::Session#flash
+      def errors
+        flash[ERRORS_KEY] || super
+      end
+
+      # Finalize the response
+      #
+      # @return [void]
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see Lotus::Action#finish
+      def finish
+        super
+        flash.clear
+      end
     end
   end
 end