lotus-controller 0.0.0 → 0.1.0

data/Rakefile

@@ -1 +1,17 @@
-require "bundler/gem_tasks"
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.libs.push 'test'
+end
+
+namespace :test do
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['test'].invoke
+  end
+end
+
+task default: :test

data/lib/lotus-controller.rb

@@ -0,0 +1 @@
+require 'lotus/controller'

data/lib/lotus/action.rb

@@ -0,0 +1,55 @@
+require 'lotus/action/rack'
+require 'lotus/action/mime'
+require 'lotus/action/redirect'
+require 'lotus/action/exposable'
+require 'lotus/action/throwable'
+require 'lotus/action/callbacks'
+require 'lotus/action/callable'
+
+module Lotus
+  # An HTTP endpoint
+  #
+  # @since 0.1.0
+  #
+  # @example
+  #   require 'lotus/controller'
+  #
+  #   class Show
+  #     include Lotus::Action
+  #
+  #     def call(params)
+  #       # ...
+  #     end
+  #   end
+  module Action
+    def self.included(base)
+      base.class_eval do
+        include Rack
+        include Mime
+        include Redirect
+        include Exposable
+        include Throwable
+        include Callbacks
+        prepend Callable
+      end
+    end
+
+    protected
+
+    # Finalize the response
+    #
+    # This method is abstract and COULD be implemented by included modules in
+    # order to prepare their data before the reponse will be returned to the
+    # webserver.
+    #
+    # @since 0.1.0
+    # @api private
+    # @abstract
+    #
+    # @see Lotus::Action::Mime
+    # @see Lotus::Action::Cookies
+    # @see Lotus::Action::Callable
+    def finish
+    end
+  end
+end

data/lib/lotus/action/callable.rb

@@ -0,0 +1,93 @@
+require 'lotus/action/params'
+
+module Lotus
+  module Action
+    module Callable
+      # Execute application logic.
+      # It implements the Rack protocol.
+      #
+      # The request params are passed as an argument to the `#call` method.
+      #
+      # If routed with Lotus::Router, it extracts the relevant bits from the
+      # Rack `env` (eg the requested `:id`).
+      #
+      # Otherwise everything it's passed as it is: the full Rack `env`
+      # in production, and the given `Hash` for unit tests. See the examples
+      # below.
+      #
+      # Application developers are forced to implement this method in their
+      # actions.
+      #
+      # @param env [Hash] the full Rack env or the params. This value may vary,
+      #   see the examples below.
+      #
+      # @return [Array] a serialized Rack response (eg. `[200, {}, ["Hi!"]]`)
+      #
+      # @since 0.1.0
+      #
+      # @example with Lotus::Router
+      #   require 'lotus/controller'
+      #
+      #    class Show
+      #      include Lotus::Action
+      #
+      #      def call(params)
+      #        # ...
+      #        puts params # => { id: 23 } extracted from Rack env
+      #      end
+      #    end
+      #
+      # @example Standalone
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       puts params
+      #         # => { :"rack.version"=>[1, 2],
+      #         #      :"rack.input"=>#<StringIO:0x007fa563463948>, ... }
+      #     end
+      #   end
+      #
+      # @example Unit Testing
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       puts params # => { id: 23, key: 'value' } passed as it is from testing
+      #     end
+      #   end
+      #
+      #   action   = Show.new
+      #   response = action.call({ id: 23, key: 'value' })
+      def call(env)
+        _rescue do
+          @_env    = env
+          @headers = ::Rack::Utils::HeaderHash.new
+          super        Params.new(@_env)
+        end
+
+        finish
+      end
+
+      protected
+
+      # Prepare the Rack response before the control is returned to the
+      # webserver.
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see Lotus::Action#finish
+      def finish
+        super
+        response
+      end
+    end
+  end
+end

data/lib/lotus/action/callbacks.rb

@@ -0,0 +1,138 @@
+require 'lotus/utils/class_attribute'
+require 'lotus/utils/callbacks'
+
+module Lotus
+  module Action
+    # Before and after callbacks
+    #
+    # @since 0.1.0
+    # @see Lotus::Action::ClassMethods#before
+    # @see Lotus::Action::ClassMethods#after
+    module Callbacks
+      def self.included(base)
+        base.class_eval do
+          extend  ClassMethods
+          prepend InstanceMethods
+        end
+      end
+
+      module ClassMethods
+        def self.extended(base)
+          base.class_eval do
+            include Utils::ClassAttribute
+
+            class_attribute :before_callbacks
+            self.before_callbacks = Utils::Callbacks::Chain.new
+
+            class_attribute :after_callbacks
+            self.after_callbacks = Utils::Callbacks::Chain.new
+          end
+        end
+
+        # Define a callback for an Action.
+        # The callback will be executed **before** the action is called, in the
+        # order they are added.
+        #
+        # @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
+        #   each of them is representing a name of a method available in the
+        #   context of the Action.
+        #
+        # @param blk [Proc] an anonymous function to be executed
+        #
+        # @return [void]
+        #
+        # @since 0.1.0
+        #
+        # @example Method names (symbols)
+        #   require 'lotus/controller'
+        #
+        #   class Show
+        #     include Lotus::Action
+        #
+        #     before :authenticate, :set_article
+        #
+        #     def call(params)
+        #     end
+        #
+        #     private
+        #     def authenticate
+        #       # ...
+        #     end
+        #
+        #     # `params` in the method signature is optional
+        #     def set_article(params)
+        #       @article = Article.find params[:id]
+        #     end
+        #   end
+        #
+        #   # The order of execution will be:
+        #   #
+        #   # 1. #authenticate
+        #   # 2. #set_article
+        #   # 3. #call
+        #
+        # @example Anonymous functions (Procs)
+        #   require 'lotus/controller'
+        #
+        #   class Show
+        #     include Lotus::Action
+        #
+        #     before { ... } # 1 do some authentication stuff
+        #     before {|params| @article = Article.find params[:id] } # 2
+        #
+        #     def call(params)
+        #     end
+        #   end
+        #
+        #   # The order of execution will be:
+        #   #
+        #   # 1. authentication
+        #   # 2. set the article
+        #   # 3. #call
+        def before(*callbacks, &blk)
+          before_callbacks.add *callbacks, &blk
+        end
+
+        # Define a callback for an Action.
+        # The callback will be executed **after** the action is called, in the
+        # order they are added.
+        #
+        # @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
+        #   each of them is representing a name of a method available in the
+        #   context of the Action.
+        #
+        # @param blk [Proc] an anonymous function to be executed
+        #
+        # @return [void]
+        #
+        # @since 0.1.0
+        #
+        # @see Lotus::Action::Callbacks::ClassMethods#before
+        def after(*callbacks, &blk)
+          after_callbacks.add *callbacks, &blk
+        end
+      end
+
+      module InstanceMethods
+        # Implements the Rack/Lotus::Action protocol
+        #
+        # @since 0.1.0
+        # @api private
+        def call(params)
+          _run_before_callbacks(params)
+          super
+          _run_after_callbacks(params)
+        end
+
+        private
+        def _run_before_callbacks(params)
+          self.class.before_callbacks.run(self, params)
+        end
+
+        def _run_after_callbacks(params)
+          self.class.after_callbacks.run(self, params)
+        end
+      end
+    end
+  end
+end

data/lib/lotus/action/cookie_jar.rb

@@ -0,0 +1,97 @@
+require 'lotus/utils/hash'
+
+module Lotus
+  module Action
+    # A set of HTTP Cookies
+    #
+    # It acts as an Hash
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Action::Cookies#cookies
+    class CookieJar < Utils::Hash
+      # The key that returns raw cookies from the Rack env
+      #
+      # @since 0.1.0
+      HTTP_HEADER       = 'HTTP_COOKIE'.freeze
+
+      # The key used by Rack to set the cookies as an Hash in the env
+      #
+      # @since 0.1.0
+      COOKIE_HASH_KEY   = 'rack.request.cookie_hash'.freeze
+
+      # The key used by Rack to set the cookies as a String in the env
+      #
+      # @since 0.1.0
+      COOKIE_STRING_KEY = 'rack.request.cookie_string'.freeze
+
+      # Initialize the CookieJar
+      #
+      # @param env [Hash] a raw Rack env
+      # @param headers [Hash] the response headers
+      #
+      # @return [CookieJar]
+      #
+      # @since 0.1.0
+      def initialize(env, headers)
+        @_headers = headers
+
+        super(extract(env))
+        symbolize!
+      end
+
+      # Finalize itself, by setting the proper headers to add and remove
+      # cookies, before the response is returned to the webserver.
+      #
+      # @return [void]
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Action::Cookies#finish
+      def finish
+        each {|k,v| v.nil? ? delete_cookie(k) : set_cookie(k, v) }
+      end
+
+      private
+      # Extract the cookies from the raw Rack env.
+      #
+      # This implementation is borrowed from Rack::Request#cookies.
+      #
+      # @since 0.1.0
+      # @api private
+      def extract(env)
+        hash   = env[COOKIE_HASH_KEY] ||= {}
+        string = env[HTTP_HEADER]
+
+        return hash if string == env[COOKIE_STRING_KEY]
+        hash.clear
+
+        # According to RFC 2109:
+        #   If multiple cookies satisfy the criteria above, they are ordered in
+        #   the Cookie header such that those with more specific Path attributes
+        #   precede those with less specific.  Ordering with respect to other
+        #   attributes (e.g., Domain) is unspecified.
+        cookies = ::Rack::Utils.parse_query(string, ';,') { |s| ::Rack::Utils.unescape(s) rescue s }
+        cookies.each { |k,v| hash[k] = Array === v ? v.first : v }
+        env[COOKIE_STRING_KEY] = string
+        hash
+      end
+
+      # Set a cookie in the headers
+      #
+      # @since 0.1.0
+      # @api private
+      def set_cookie(key, value)
+        ::Rack::Utils.set_cookie_header!(@_headers, key, value)
+      end
+
+      # Remove a cookie from the headers
+      #
+      # @since 0.1.0
+      # @api private
+      def delete_cookie(key)
+        ::Rack::Utils.delete_cookie_header!(@_headers, key, {})
+      end
+    end
+  end
+end

data/lib/lotus/action/cookies.rb

@@ -0,0 +1,60 @@
+require 'lotus/action/cookie_jar'
+
+module Lotus
+  module Action
+    # Cookies API
+    #
+    # This module isn't included by default.
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Action::Cookies#cookies
+    module Cookies
+
+      protected
+
+      # Finalize the response by flushing cookies into the response
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see Lotus::Action#finish
+      def finish
+        super
+        cookies.finish
+      end
+
+      # Gets the cookies from the request and expose them as an Hash
+      #
+      # @return [Lotus::Action::CookieJar] the cookies
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example
+      #   require 'lotus/controller'
+      #   require 'lotus/action/cookies'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #     include Lotus::Action::Cookies
+      #
+      #     def call(params)
+      #       # ...
+      #
+      #       # get a value
+      #       cookies[:user_id] # => '23'
+      #
+      #       # set a value
+      #       cookies[:foo] = 'bar'
+      #
+      #       # remove a value
+      #       cookies[:bax] = nil
+      #     end
+      #   end
+      def cookies
+        @cookies ||= CookieJar.new(@_env.dup, headers)
+      end
+    end
+  end
+end