hanami-controller 0.0.0 → 0.6.0

data/lib/hanami/action/params.rb

@@ -0,0 +1,285 @@
+require 'hanami/validations'
+require 'hanami/utils/attributes'
+require 'set'
+
+module Hanami
+  module Action
+    # A set of params requested by the client
+    #
+    # It's able to extract the relevant params from a Rack env of from an Hash.
+    #
+    # There are three scenarios:
+    #   * When used with Hanami::Router: it contains only the params from the request
+    #   * When used standalone: it contains all the Rack env
+    #   * Default: it returns the given hash as it is. It's useful for testing purposes.
+    #
+    # @since 0.1.0
+    class Params
+      # The key that returns raw input from the Rack env
+      #
+      # @since 0.1.0
+      RACK_INPUT    = 'rack.input'.freeze
+
+      # The key that returns router params from the Rack env
+      # This is a builtin integration for Hanami::Router
+      #
+      # @since 0.1.0
+      ROUTER_PARAMS = 'router.params'.freeze
+
+      # CSRF params key
+      #
+      # This key is shared with <tt>hanamirb</tt> and <tt>hanami-helpers</tt>
+      #
+      # @since 0.4.4
+      # @api private
+      CSRF_TOKEN = '_csrf_token'.freeze
+
+      # Set of params that are never filtered
+      #
+      # @since 0.4.4
+      # @api private
+      DEFAULT_PARAMS = Hash[CSRF_TOKEN => true].freeze
+
+      # Separator for #get
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see Hanami::Action::Params#get
+      GET_SEPARATOR = '.'.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/hanami-validations/Hanami/Validations
+      #
+      # @example Whitelisting
+      #   require 'hanami/controller'
+      #
+      #   class SignupParams < Hanami::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 'hanami/controller'
+      #
+      #   class SignupParams < Hanami::Action::Params
+      #     param :email, presence: true
+      #   end
+      #
+      #   params = SignupParams.new({})
+      #
+      #   params[:email] # => nil
+      #   params.valid?  # => false
+      #
+      # @example Unknown validation
+      #   require 'hanami/controller'
+      #
+      #   class SignupParams < Hanami::Action::Params
+      #     param :email, unknown: true # => raise ArgumentError
+      #   end
+      #
+      # @example Wrong size validation
+      #   require 'hanami/controller'
+      #
+      #   class SignupParams < Hanami::Action::Params
+      #     param :email, size: 'twentythree'
+      #   end
+      #
+      #   params = SignupParams.new({})
+      #   params.valid? # => raise ArgumentError
+      def self.param(name, options = {}, &block)
+        attribute name, options, &block
+        nil
+      end
+
+      include Hanami::Validations
+
+      def self.whitelisting?
+        defined_attributes.any?
+      end
+
+      # Overrides the method in Hanami::Validation to build a class that
+      # inherits from Params rather than only Hanami::Validations.
+      #
+      # @since 0.3.2
+      # @api private
+      def self.build_validation_class(&block)
+        kls = Class.new(Params) do
+          def hanami_nested_attributes?
+            true
+          end
+        end
+        kls.class_eval(&block)
+        kls
+      end
+
+      # @attr_reader env [Hash] the Rack env
+      #
+      # @since 0.2.0
+      # @api private
+      attr_reader :env
+
+      # @attr_reader raw [Hanami::Utils::Attributes] all request's attributes
+      #
+      # @since 0.3.2
+      attr_reader :raw
+
+      # Initialize the params and freeze them.
+      #
+      # @param env [Hash] a Rack env or an hash of params.
+      #
+      # @return [Params]
+      #
+      # @since 0.1.0
+      def initialize(env)
+        @env = env
+        super(_compute_params)
+        # 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)
+        @attributes.get(key)
+      end
+
+      # Get an attribute value associated with the given key.
+      # Nested attributes are reached with a dot notation.
+      #
+      # @param key [String] the key
+      #
+      # @return [Object,NilClass] return the associated value, if found
+      #
+      # @since 0.4.0
+      #
+      # @example
+      #   require 'hanami/controller'
+      #
+      #   module Deliveries
+      #     class Create
+      #       include Hanami::Action
+      #
+      #       params do
+      #         param :customer_name
+      #         param :address do
+      #           param :city
+      #         end
+      #       end
+      #
+      #       def call(params)
+      #         params.get('customer_name')   # => "Luca"
+      #         params.get('uknown')          # => nil
+      #
+      #         params.get('address.city')    # => "Rome"
+      #         params.get('address.unknown') # => nil
+      #
+      #         params.get(nil)               # => nil
+      #       end
+      #     end
+      #   end
+      def get(key)
+        key, *keys = key.to_s.split(GET_SEPARATOR)
+        result     = self[key]
+
+        Array(keys).each do |k|
+          break if result.nil?
+          result = result[k]
+        end
+
+        result
+      end
+
+      # Serialize params to Hash
+      #
+      # @return [::Hash]
+      #
+      # @since 0.3.0
+      def to_h
+        @attributes.to_h
+      end
+      alias_method :to_hash, :to_h
+
+      # Assign CSRF Token.
+      # This method is here for compatibility with <tt>Hanami::Validations</tt>.
+      #
+      # NOTE: When we will not support indifferent access anymore, we can probably
+      # remove this method.
+      #
+      # @since 0.4.4
+      # @api private
+      def _csrf_token=(value)
+        @attributes.set(CSRF_TOKEN, value)
+      end
+
+      private
+      # @since 0.3.1
+      # @api private
+      def _compute_params
+        if self.class.whitelisting?
+          _whitelisted_params
+        else
+          @attributes = _raw
+        end
+      end
+
+      # @since 0.3.2
+      # @api private
+      def _raw
+        @raw ||= Utils::Attributes.new(_params)
+      end
+
+      # @since 0.3.1
+      # @api private
+      def _params
+        {}.tap do |result|
+          if env.has_key?(RACK_INPUT)
+            result.merge! ::Rack::Request.new(env).params
+            result.merge! env.fetch(ROUTER_PARAMS, {})
+          else
+            result.merge! env.fetch(ROUTER_PARAMS, env)
+          end
+        end
+      end
+
+      # @since 0.3.1
+      # @api private
+      def _whitelisted_params
+        {}.tap do |result|
+          _raw.to_h.each do |k, v|
+            next unless assign_attribute?(k)
+
+            result[k] = v
+          end
+        end
+      end
+
+      # Override <tt>Hanami::Validations</tt> method
+      #
+      # @since 0.4.4
+      # @api private
+      def assign_attribute?(key)
+        DEFAULT_PARAMS[key.to_s] || super
+      end
+    end
+  end
+end

data/lib/hanami/action/rack.rb

@@ -0,0 +1,270 @@
+require 'securerandom'
+require 'hanami/action/request'
+require 'hanami/action/rack/callable'
+require 'hanami/action/rack/file'
+
+module Hanami
+  module Action
+    # Rack integration API
+    #
+    # @since 0.1.0
+    module Rack
+      # 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 = []
+
+      # The default HTTP Request ID length
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see Hanami::Action::Rack#request_id
+      DEFAULT_REQUEST_ID_LENGTH = 16
+
+      # The request method
+      #
+      # @since 0.3.2
+      # @api private
+      REQUEST_METHOD = 'REQUEST_METHOD'.freeze
+
+      # HEAD request
+      #
+      # @since 0.3.2
+      # @api private
+      HEAD = 'HEAD'.freeze
+
+      # Override Ruby's hook for modules.
+      # It includes basic Hanami::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
+        # Build rack builder
+        #
+        # @return [Rack::Builder]
+        def rack_builder
+          @rack_builder ||= begin
+            extend Hanami::Action::Rack::Callable
+            rack_builder = ::Rack::Builder.new
+            rack_builder.run ->(env) { self.new.call(env) }
+            rack_builder
+          end
+        end
+        # Use a Rack middleware
+        #
+        # The middleware will be used as it is.
+        #
+        # 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
+        # @param args [Array] Array arguments for middleware
+        #
+        # @since 0.2.0
+        #
+        # @see Hanami::Action::Callbacks::ClassMethods#before
+        #
+        # @example Middleware
+        #   require 'hanami/controller'
+        #
+        #   module Sessions
+        #     class Create
+        #       include Hanami::Action
+        #       use OmniAuth
+        #
+        #       def call(params)
+        #         # ...
+        #       end
+        #     end
+        #   end
+        def use(middleware, *args, &block)
+          rack_builder.use middleware, *args, &block
+        end
+      end
+
+      protected
+      # Gets the headers from the response
+      #
+      # @return [Hash] the HTTP headers from the response
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'hanami/controller'
+      #
+      #   class Show
+      #     include Hanami::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       self.headers            # => { ... }
+      #       self.headers.merge!({'X-Custom' => 'OK'})
+      #     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 Hanami::Action::Rack::DEFAULT_RESPONSE_CODE
+      # @see Hanami::Action::Rack::DEFAULT_RESPONSE_BODY
+      # @see Hanami::Action::Rack#status=
+      # @see Hanami::Action::Rack#headers
+      # @see Hanami::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
+
+      # Returns a Hanami specialized rack request
+      #
+      # @return [Hanami::Action::Request] The request
+      #
+      # @since 0.3.1
+      #
+      # @example
+      #   require 'hanami/controller'
+      #
+      #   class Create
+      #     include Hanami::Action
+      #
+      #     def call(params)
+      #       ip     = request.ip
+      #       secure = request.ssl?
+      #     end
+      #   end
+      def request
+        @request ||= ::Hanami::Action::Request.new(@_env)
+      end
+
+      private
+
+      # Sets the HTTP status code for the response
+      #
+      # @param status [Fixnum] an HTTP status code
+      # @return [void]
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'hanami/controller'
+      #
+      #   class Create
+      #     include Hanami::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       self.status = 201
+      #     end
+      #   end
+      def status=(status)
+        @_status = status
+      end
+
+      # Sets the body of the response
+      #
+      # @param body [String] the body of the response
+      # @return [void]
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'hanami/controller'
+      #
+      #   class Show
+      #     include Hanami::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       self.body = 'Hi!'
+      #     end
+      #   end
+      def body=(body)
+        body   = Array(body) unless body.respond_to?(:each)
+        @_body = body
+      end
+
+      # Send a file as response.
+      #
+      # It automatically handle the following cases:
+      #
+      #   * <tt>Content-Type</tt> and <tt>Content-Length</tt>
+      #   * File Not found (returns a 404)
+      #   * Conditional GET (via <tt>If-Modified-Since</tt> header)
+      #   * Range requests (via <tt>Range</tt> header)
+      #
+      # @param path [String, Pathname] the body of the response
+      # @return [void]
+      #
+      # @since 0.4.3
+      #
+      # @example
+      #   require 'hanami/controller'
+      #
+      #   class Show
+      #     include Hanami::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       send_file Pathname.new('path/to/file')
+      #     end
+      #   end
+      def send_file(path)
+        result = File.new(path).call(@_env)
+        headers.merge!(result[1])
+        halt result[0], result[2]
+      end
+
+      # Check if the current request is a HEAD
+      #
+      # @return [TrueClass,FalseClass] the result of the check
+      #
+      # @since 0.3.2
+      def head?
+        request_method == HEAD
+      end
+
+      # NOTE: <tt>Hanami::Action::CSRFProtection</tt> (<tt>hanamirb</tt> gem) depends on this.
+      #
+      # @api private
+      # @since 0.4.4
+      def request_method
+        @_env[REQUEST_METHOD]
+      end
+    end
+  end
+end