lotus-router 0.0.0 → 0.1.0

data/lib/lotus/router/version.rb

@@ -1,5 +1,5 @@
 module Lotus
-  module Router
-    VERSION = "0.0.0"
+  class Router
+    VERSION = '0.1.0'
   end
 end

data/lib/lotus/routing/endpoint.rb

@@ -0,0 +1,114 @@
+require 'delegate'
+require 'lotus/utils/class'
+
+module Lotus
+  module Routing
+    # Endpoint not found
+    # This is raised when the router fails to load an endpoint at the runtime.
+    #
+    # @since 0.1.0
+    class EndpointNotFound < ::Exception
+    end
+
+    # Routing endpoint
+    # This is the object that responds to an HTTP request made against a certain
+    # path.
+    #
+    # The router will use this class for:
+    #
+    #   * Procs and any Rack compatible object (respond to #call)
+    #
+    # @since 0.1.0
+    #
+    # @api private
+    #
+    # @example
+    #   require 'lotus/router'
+    #
+    #   Lotus::Router.new do
+    #     get '/proc',     to: ->(env) { [200, {}, ['This will use Lotus::Routing::Endpoint']] }
+    #     get '/rack-app', to: RackApp.new
+    #   end
+    class Endpoint < SimpleDelegator
+    end
+
+    # Routing endpoint
+    # This is the object that responds to an HTTP request made against a certain
+    # path.
+    #
+    # The router will use this class for:
+    #
+    #   * Classes
+    #   * Lotus::Action endpoints referenced as a class
+    #   * Lotus::Action endpoints referenced a string
+    #   * RESTful resource(s)
+    #
+    # @since 0.1.0
+    #
+    # @api private
+    #
+    # @example
+    #   require 'lotus/router'
+    #
+    #   Lotus::Router.new do
+    #     get '/class',               to: RackMiddleware
+    #     get '/lotus-action-class',  to: DashboardController::Index
+    #     get '/lotus-action-string', to: 'dashboard#index'
+    #
+    #     resource  'identity'
+    #     resources 'articles'
+    #   end
+    class ClassEndpoint < Endpoint
+      # Rack interface
+      #
+      # @since 0.1.0
+      def call(env)
+        __getobj__.new.call(env)
+      end
+    end
+
+    # Routing endpoint
+    # This is the object that responds to an HTTP request made against a certain
+    # path.
+    #
+    # The router will use this class for the same use cases of `ClassEndpoint`,
+    # but when the target class can't be found, instead of raise a `LoadError`
+    # we reference in a lazy endpoint.
+    #
+    # For each incoming HTTP request, it will look for the referenced class,
+    # then it will instantiate and invoke #call on the object.
+    #
+    # This behavior is required to solve a chicken-egg situation when we try
+    # to load the router first and then the application with all its endpoints.
+    #
+    # @since 0.1.0
+    #
+    # @api private
+    #
+    # @see Lotus::Routing::ClassEndpoint
+    class LazyEndpoint < Endpoint
+      # Initialize the lazy endpoint
+      #
+      # @since 0.1.0
+      def initialize(name, namespace)
+        @name, @namespace = name, namespace
+      end
+
+      # Rack interface
+      #
+      # @raise [EndpointNotFound] when the endpoint can't be found.
+      #
+      # @since 0.1.0
+      def call(env)
+        obj.call(env)
+      end
+
+      private
+      def obj
+        Utils::Class.load!(@name, @namespace).new
+      rescue NameError => e
+        raise EndpointNotFound.new(e.message)
+      end
+    end
+  end
+end

data/lib/lotus/routing/endpoint_resolver.rb

@@ -0,0 +1,251 @@
+require 'lotus/utils/string'
+require 'lotus/utils/class'
+require 'lotus/routing/endpoint'
+
+module Lotus
+  module Routing
+    # Resolve duck-typed endpoints
+    #
+    # @since 0.1.0
+    #
+    # @api private
+    class EndpointResolver
+      # Default suffix appended to the controller#action string.
+      # A different suffix can be passed to #initialize with the `:suffix` option.
+      #
+      # @see #initialize
+      # @see #resolve
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new do
+      #     get '/', to: 'articles#show'
+      #   end
+      #
+      #   # That string is transformed into "Articles(::Controller::|Controller::)Show"
+      #   # because the risolver is able to lookup (in the given order) for:
+      #   #
+      #   #  * Articles::Controller::Show
+      #   #  * ArticlesController::Show
+      #   #
+      #   # When it finds a class, it stops the lookup and returns the result.
+      SUFFIX = '(::Controller::|Controller::)'.freeze
+
+      # Default separator for controller and action.
+      # A different separator can be passed to #initialize with the `:separator` option.
+      #
+      # @see #initialize
+      # @see #resolve
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new do
+      #     get '/', to: 'articles#show'
+      #   end
+      ACTION_SEPARATOR = '#'.freeze
+
+      attr_reader :action_separator
+
+      # Initialize an endpoint resolver
+      #
+      # @param options [Hash] the options used to customize lookup behavior
+      #
+      # @option options [Class] :endpoint the endpoint class that is returned
+      #   by `#resolve`. (defaults to `Lotus::Routing::Endpoint`)
+      #
+      # @option options [Class,Module] :namespace the Ruby namespace where to
+      #   lookup for controllers and actions. (defaults to `Object`)
+      #
+      # @option options [String] :suffix the suffix appended to the controller
+      #   name during the lookup. (defaults to `SUFFIX`)
+      #
+      # @option options [String] :action_separator the sepatator between controller and
+      #   action name. (defaults to `ACTION_SEPARATOR`)
+      #
+      #
+      #
+      # @return [Lotus::Routing::EndpointResolver] self
+      #
+      #
+      #
+      # @since 0.1.0
+      #
+      #
+      #
+      # @example Specify custom endpoint class
+      #   require 'lotus/router'
+      #
+      #   resolver = Lotus::Routing::EndpointResolver.new(endpoint: CustomEndpoint)
+      #   router   = Lotus::Router.new(resolver: resolver)
+      #
+      #   router.get('/', to: endpoint).dest # => #<CustomEndpoint:0x007f97f3359570 ...>
+      #
+      #
+      #
+      # @example Specify custom Ruby namespace
+      #   require 'lotus/router'
+      #
+      #   resolver = Lotus::Routing::EndpointResolver.new(namespace: MyApp)
+      #   router   = Lotus::Router.new(resolver: resolver)
+      #
+      #   router.get('/', to: 'articles#show')
+      #   # => Will look for:
+      #   #  * MyApp::Articles::Controller::Show
+      #   #  * MyApp::ArticlesController::Show
+      #
+      #
+      #
+      # @example Specify custom controller suffix
+      #   require 'lotus/router'
+      #
+      #   resolver = Lotus::Routing::EndpointResolver.new(suffix: '(Controller::|Ctrl::)')
+      #   router   = Lotus::Router.new(resolver: resolver)
+      #
+      #   router.get('/', to: 'articles#show')
+      #   # => Will look for:
+      #   #  * ArticlesController::Show
+      #   #  * ArticlesCtrl::Show
+      #
+      #
+      #
+      # @example Specify custom controller-action separator
+      #   require 'lotus/router'
+      #
+      #   resolver = Lotus::Routing::EndpointResolver.new(separator: '@')
+      #   router   = Lotus::Router.new(resolver: resolver)
+      #
+      #   router.get('/', to: 'articles@show')
+      #   # => Will look for:
+      #   #  * Articles::Controller::Show
+      #   #  * ArticlesController::Show
+      def initialize(options = {})
+        @endpoint_class   = options[:endpoint]         || Endpoint
+        @namespace        = options[:namespace]        || Object
+        @suffix           = options[:suffix]           || SUFFIX
+        @action_separator = options[:action_separator] || ACTION_SEPARATOR
+      end
+
+      # Resolve the given set of HTTP verb, path, endpoint and options.
+      # If it fails to resolve, it will mount the default endpoint to the given
+      # path, which returns an 404 (Not Found).
+      #
+      # @param options [Hash] the options required to resolve the endpoint
+      #
+      # @option options [String,Proc,Class,Object#call] :to the endpoint
+      # @option options [String] :prefix an optional path prefix
+      #
+      # @return [Endpoint] this may vary according to the :endpoint option
+      #   passed to #initialize
+      #
+      # @since 0.1.0
+      #
+      # @see #initialize
+      # @see #find
+      #
+      # @example Resolve to a Proc
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new
+      #   router.get '/', to: ->(env) { [200, {}, ['Hi!']] }
+      #
+      # @example Resolve to a class
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new
+      #   router.get '/', to: RackMiddleware
+      #
+      # @example Resolve to a Rack compatible object (respond to #call)
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new
+      #   router.get '/', to: AnotherMiddleware.new
+      #
+      # @example Resolve to a Lotus::Action from a string (see Lotus::Controller framework)
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new
+      #   router.get '/', to: 'articles#show'
+      #
+      # @example Resolve to a Lotus::Action (see Lotus::Controller framework)
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new
+      #   router.get '/', to: ArticlesController::Show
+      #
+      # @example Resolve with a path prefix
+      #   require 'lotus/router'
+      #
+      #   router = Lotus::Router.new
+      #   router.get '/dashboard', to: BackendApp.new, prefix: 'backend'
+      #     # => Will be available under '/backend/dashboard'
+      def resolve(options, &endpoint)
+        result = endpoint || find(options)
+        resolve_callable(result) || resolve_matchable(result) || default
+      end
+
+      # Finds a path from the given options.
+      #
+      # @param options [Hash] the path description
+      # @option options [String,Proc,Class,Object#call] :to the endpoint
+      # @option options [String] :prefix an optional path prefix
+      #
+      # @since 0.1.0
+      #
+      # @return [Object]
+      def find(options)
+        if prefix = options[:prefix]
+          prefix.join(options[:to])
+        else
+          options[:to]
+        end
+      end
+
+      protected
+      def default
+        @endpoint_class.new(
+          ->(env) { [404, {'X-Cascade' => 'pass'}, 'Not Found'] }
+        )
+      end
+
+      def constantize(string)
+        begin
+          ClassEndpoint.new(Utils::Class.load!(string, @namespace))
+        rescue NameError
+          LazyEndpoint.new(string, @namespace)
+        end
+      end
+
+      def classify(string)
+        Utils::String.new(string).classify
+      end
+
+      private
+      def resolve_callable(callable)
+        if callable.respond_to?(:call)
+          @endpoint_class.new(callable)
+        end
+      end
+
+      def resolve_matchable(matchable)
+        if matchable.respond_to?(:match)
+          constantize(
+            resolve_action(matchable) || classify(matchable)
+          )
+        end
+      end
+
+      def resolve_action(string)
+        if string.match(action_separator)
+          controller, action = string.split(action_separator).map {|token| classify(token) }
+          controller + @suffix + action
+        end
+      end
+    end
+  end
+end

data/lib/lotus/routing/http_router.rb

@@ -0,0 +1,130 @@
+require 'http_router'
+require 'lotus/utils/io'
+require 'lotus/routing/endpoint_resolver'
+require 'lotus/routing/route'
+
+Lotus::Utils::IO.silence_warnings do
+  HttpRouter::Route::VALID_HTTP_VERBS = %w{GET POST PUT PATCH DELETE HEAD OPTIONS TRACE}
+end
+
+module Lotus
+  module Routing
+    # Invalid route
+    # This is raised when the router fails to recognize a route, because of the
+    # given arguments.
+    #
+    # @since 0.1.0
+    class InvalidRouteException < ::Exception
+    end
+
+    # HTTP router
+    #
+    # This implementation is based on ::HttpRouter (http_router gem).
+    #
+    # Lotus::Router wraps an instance of this class, in order to protect its
+    # public API from any future change of ::HttpRouter.
+    #
+    # @since 0.1.0
+    # @api private
+    class HttpRouter < ::HttpRouter
+      # Initialize the router.
+      #
+      # @see Lotus::Router#initialize
+      #
+      # @since 0.1.0
+      # @api private
+      def initialize(options = {}, &blk)
+        super(options, &nil)
+
+        @default_scheme = options[:scheme]   if options[:scheme]
+        @default_host   = options[:host]     if options[:host]
+        @default_port   = options[:port]     if options[:port]
+        @route_class    = options[:route]    || Routing::Route
+        @resolver       = options[:resolver] || Routing::EndpointResolver.new(options)
+      end
+
+      # Separator between controller and action name.
+      #
+      # @see Lotus::Routing::EndpointResolver::ACTION_SEPARATOR
+      #
+      # @since 0.1.0
+      # @api private
+      def action_separator
+        @resolver.action_separator
+      end
+
+      # Finds a path from the given options.
+      #
+      # @see Lotus::Routing::EndpointResolver#find
+      #
+      # @since 0.1.0
+      # @api private
+      def find(options)
+        @resolver.find(options)
+      end
+
+      # Generate a relative URL for a specified named route.
+      #
+      # @see Lotus::Router#path
+      #
+      # @since 0.1.0
+      # @api private
+      def path(route, *args)
+        _rescue_url_recognition { super }
+      end
+
+      # Generate an absolute URL for a specified named route.
+      #
+      # @see Lotus::Router#path
+      #
+      # @since 0.1.0
+      # @api private
+      def url(route, *args)
+        _rescue_url_recognition { super }
+      end
+
+      # Support for OPTIONS HTTP verb
+      #
+      # @see Lotus::Router#options
+      #
+      # @since 0.1.0
+      # @api private
+      def options(path, options = {}, &blk)
+        add_with_request_method(path, :options, options, &blk)
+      end
+
+      # @api private
+      def reset!
+        uncompile
+        @routes, @named_routes, @root = [], Hash.new{|h,k| h[k] = []}, Node::Root.new(self)
+        @default_host, @default_port, @default_scheme = 'localhost', 80, 'http'
+      end
+
+      # @api private
+      def pass_on_response(response)
+        super response.to_a
+      end
+
+      # @api private
+      def no_response(request, env)
+        if request.acceptable_methods.any? && !request.acceptable_methods.include?(env['REQUEST_METHOD'])
+          [405, {'Allow' => request.acceptable_methods.sort.join(", ")}, []]
+        else
+          @default_app.call(env)
+        end
+      end
+
+      private
+      def add_with_request_method(path, method, opts = {}, &app)
+        super.generate(@resolver, opts, &app)
+      end
+
+      def _rescue_url_recognition
+        yield
+      rescue ::HttpRouter::InvalidRouteException,
+             ::HttpRouter::TooManyParametersException => e
+        raise Routing::InvalidRouteException.new(e.message)
+      end
+    end
+  end
+end