lotus-controller 0.0.0 → 0.1.0

data/lib/lotus/action/exposable.rb

@@ -0,0 +1,81 @@
+module Lotus
+  module Action
+    # Exposures API
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Action::Exposable::ClassMethods#expose
+    module Exposable
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        # Expose the given attributes on the outside of the object with
+        # a getter and a special method called #exposures.
+        #
+        # @param names [Array<Symbol>] the name(s) of the attribute(s) to be
+        #   exposed
+        #
+        # @return [void]
+        #
+        # @since 0.1.0
+        #
+        # @example
+        #   require 'lotus/controller'
+        #
+        #   class Show
+        #     include Lotus::Action
+        #
+        #     expose :article, :tags
+        #
+        #     def call(params)
+        #       @article = Article.find params[:id]
+        #       @tags    = Tag.for(article)
+        #     end
+        #   end
+        #
+        #   action = Show.new
+        #   action.call({id: 23})
+        #
+        #   action.article # => #<Article ...>
+        #   action.tags    # => [#<Tag ...>, #<Tag ...>]
+        #
+        #   action.exposures # => { :article => #<Article ...>, :tags => [ ... ] }
+        def expose(*names)
+          class_eval do
+            attr_reader    *names
+            exposures.push *names
+          end
+        end
+
+        # Set of exposures attribute names
+        #
+        # @return [Array] the exposures attribute names
+        #
+        # @since 0.1.0
+        # @api private
+        def exposures
+          @exposures ||= []
+        end
+      end
+
+      # Set of exposures
+      #
+      # @return [Hash] the exposures
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Action::Exposable::ClassMethods.expose
+      def exposures
+        {}.tap do |result|
+          self.class.exposures.each do |exposure|
+            result[exposure] = send(exposure)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lotus/action/mime.rb

@@ -0,0 +1,190 @@
+module Lotus
+  module Action
+    # Mime type API
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Action::Mime::ClassMethods#accept
+    module Mime
+      # The key that returns accepted mime types from the Rack env
+      #
+      # @since 0.1.0
+      HTTP_ACCEPT          = 'HTTP_ACCEPT'.freeze
+
+      # The header key to set the mime type of the response
+      #
+      # @since 0.1.0
+      CONTENT_TYPE         = 'Content-Type'.freeze
+
+      # The default mime type for an incoming HTTP request
+      #
+      # @since 0.1.0
+      DEFAULT_ACCEPT       = '*/*'.freeze
+
+      # The default mime type that is returned in the response
+      #
+      # @since 0.1.0
+      DEFAULT_CONTENT_TYPE = 'application/octet-stream'.freeze
+
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        protected
+
+        # Restrict the access to the specified mime type symbols.
+        #
+        # @param mime_types[Array<Symbol>] one or more symbols representing mime type(s)
+        #
+        # @since 0.1.0
+        #
+        # @example
+        #   require 'lotus/controller'
+        #
+        #   class Show
+        #     include Lotus::Action
+        #     accept :html, :json
+        #
+        #     def call(params)
+        #       # ...
+        #     end
+        #   end
+        #
+        #   # When called with "*/*"              => 200
+        #   # When called with "text/html"        => 200
+        #   # When called with "application/json" => 200
+        #   # When called with "application/xml"  => 406
+        def accept(*mime_types)
+          mime_types = mime_types.map do |mt|
+            ::Rack::Mime.mime_type ".#{ mt }"
+          end
+
+          before do
+            unless mime_types.find {|mt| accept?(mt) }
+              throw 406
+            end
+          end
+        end
+      end
+
+      protected
+      # Finalize the response by setting the current content type
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see Lotus::Action#finish
+      def finish
+        super
+        headers.merge! CONTENT_TYPE => content_type
+      end
+
+      # Sets the given content type
+      #
+      # Lotus::Action sets the proper content type automatically, this method
+      #   is designed to override that value.
+      #
+      # @param content_type [String] the content type
+      # @return [void]
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Action::Mime#content_type
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       self.content_type = 'application/json'
+      #     end
+      #   end
+      def content_type=(content_type)
+        @content_type = content_type
+      end
+
+      # The content type that will be automatically set in the response.
+      #
+      # It prefers, in order:
+      #   * Explicit set value (see #content_type=)
+      #   * Weighted value from Accept
+      #   * Default content type
+      #
+      # To override the value, use <tt>#content_type=</tt>
+      #
+      # @return [String] the content type from the request.
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Action::Mime#content_type=
+      # @see Lotus::Action::Mime#DEFAULT_CONTENT_TYPE
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       content_type # => 'text/html'
+      #     end
+      #   end
+      def content_type
+        @content_type || accepts || DEFAULT_CONTENT_TYPE
+      end
+
+      # Match the given mime type with the Accept header
+      #
+      # @return [Boolean] true if the given mime type matches Accept
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       # @_env['HTTP_ACCEPT'] # => 'text/html,application/xhtml+xml,application/xml;q=0.9'
+      #
+      #       accept?('text/html')        # => true
+      #       accept?('application/xml')  # => true
+      #       accept?('application/json') # => false
+      #
+      #
+      #
+      #       # @_env['HTTP_ACCEPT'] # => '*/*'
+      #
+      #       accept?('text/html')        # => true
+      #       accept?('application/xml')  # => true
+      #       accept?('application/json') # => true
+      #     end
+      #   end
+      def accept?(mime_type)
+        !!::Rack::Utils.q_values(accept).find do |mime, _|
+          ::Rack::Mime.match?(mime_type, mime)
+        end
+      end
+
+      private
+      def accept
+        @accept ||= @_env[HTTP_ACCEPT] || DEFAULT_ACCEPT
+      end
+
+      def accepts
+        unless accept == DEFAULT_ACCEPT
+          ::Rack::Utils.best_q_match(accept, ::Rack::Mime::MIME_TYPES.values)
+        end
+      end
+    end
+  end
+end

data/lib/lotus/action/params.rb

@@ -0,0 +1,53 @@
+require 'lotus/utils/hash'
+
+module Lotus
+  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 Lotus::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 < Utils::Hash
+      # 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 Lotus::Router
+      #
+      # @since 0.1.0
+      ROUTER_PARAMS = 'router.params'.freeze
+
+      # 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)
+        super _extract(env)
+        symbolize!
+        freeze
+      end
+
+      private
+      def _extract(env)
+        {}.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
+    end
+  end
+end

data/lib/lotus/action/rack.rb

@@ -0,0 +1,97 @@
+module Lotus
+  module Action
+    # Rack integration API
+    #
+    # @since 0.1.0
+    module Rack
+      SESSION_KEY           = 'rack.session'.freeze
+      DEFAULT_RESPONSE_CODE = 200
+      DEFAULT_RESPONSE_BODY = []
+
+      protected
+      # Sets the HTTP status code for the response
+      #
+      # @param status [Fixnum] an HTTP status code
+      # @return [void]
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Create
+      #     include Lotus::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 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       self.body = 'Hi!'
+      #     end
+      #   end
+      def body=(body)
+        body   = Array(body) unless body.respond_to?(:each)
+        @_body = body
+      end
+
+      # Gets the headers from the response
+      #
+      # @return [Hash] the HTTP headers from the response
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::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 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
+    end
+  end
+end

data/lib/lotus/action/redirect.rb

@@ -0,0 +1,34 @@
+module Lotus
+  module Action
+    # HTTP redirect API
+    #
+    # @since 0.1.0
+    module Redirect
+
+      protected
+
+      # Redirect to the given URL
+      #
+      # @param url [String] the destination URL
+      # @param status [Fixnum] the http code
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Create
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       redirect_to 'http://example.com/articles/23'
+      #     end
+      #   end
+      def redirect_to(url, status: 302)
+        headers.merge!('Location' => url)
+        self.status = status
+      end
+    end
+  end
+end