pendragon 0.6.2 → 1.0.0

data/Rakefile

@@ -2,24 +2,9 @@ require 'rake'
 require 'rake/testtask'
 require 'pendragon'
 
-Rake::TestTask.new(:test_without_compiler) do |test|
+Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
-  test.test_files = Dir['test/**/*_test.rb']
-  test.verbose = true
+  test.test_files = Dir['test/**/test_*.rb']
 end
 
-Rake::TestTask.new(:test_with_compiler) do |test|
-  test.libs << 'test'
-  test.ruby_opts = ["-r compile_helper.rb"]
-  test.test_files = Dir['test/**/*_test.rb']
-  test.verbose = true
-end
-
-Rake::TestTask.new(:configuration) do |test|
-  test.libs << 'test'
-  test.test_files = Dir['test/**/*_configuration.rb']
-  test.verbose = true
-end
-
-task :test => [:test_without_compiler, :test_with_compiler, :configuration]
-task :default => :test
+task default: :test

data/benchmark.rb

@@ -0,0 +1,31 @@
+require 'benchmark'
+require 'pendragon'
+require 'rack'
+
+routers = %i[liner realism radix].map do |type|
+  Pendragon[type].new do
+    1000.times { |n| get "/#{n}", to: ->(env) { [200, {}, [n.to_s]] } }
+    namespace :foo do
+      get '/:user_id' do
+        [200, {}, ['yahoo']]
+      end
+    end
+  end
+end
+
+env = Rack::MockRequest.env_for("/999")
+
+routers.each do |router|
+  p "router_class: #{router.class}"
+  p router.call(env)
+end
+
+Benchmark.bm do |x|
+  routers.each do |router|
+    x.report do
+      10000.times do |n|
+        router.call(env)
+      end
+    end
+  end
+end

data/lib/pendragon.rb

@@ -1,55 +1,71 @@
 require 'pendragon/router'
+require 'thread'
 
 module Pendragon
+  # Type to use if no type is given.
+  # @api private
+  DEFAULT_TYPE = :realism
 
-  # Allow the verbs of these.
-  HTTP_VERBS = %w[GET POST PUT PATCH DELETE HEAD OPTIONS LINK UNLINK].freeze
+  # Creates a new router.
+  # 
+  # @example creating new routes.
+  #   require 'pendragon'
+  #
+  #    Pendragon.new do
+  #      get('/') { [200, {}, ['hello world']] }
+  #      namespace :users do
+  #        get('/',    to: ->(env) { [200, {}, ['User page index']] })
+  #        get('/:id', to: UserApplication.new)
+  #      end
+  #    end
+  #
+  # @yield block for definig routes, it will be evaluated in instance context.
+  # @yieldreturn [Pendragon::Router]
+  def self.new(type: DEFAULT_TYPE, &block)
+    type ||= DEFAULT_TYPE
+    self[type].new(&block)
+  end
 
-  class << self
-    # A new instance of Pendragon::Router
-    # @see Pendragon::Router#initialize
-    def new(&block)
-      Router.new(&block)
-    end
-  
-    # @deprecated
-    # Yields Pendragon configuration block
-    # @example
-    #   Pendragon.configure do |config|
-    #     config.enable_compiler = true
-    #   end
-    # @see Pendragon::Configuration
-    def configure(&block)
-      configuration_warning(:configure)
-      block.call(configuration) if block_given?
-      configuration
-    end
-  
-    # @deprecated
-    # Returns Pendragon configuration
-    def configuration
-      configuration_warning(:configuration)
-      @configuration ||= Configuration.new
-    end
+  @mutex ||= Mutex.new
+  @types ||= {}
 
-    # @deprecated
-    # Resets Pendragon configuration
-    def reset_configuration!
-      @configuration = nil
+  # Returns router by given name.
+  #
+  # @example
+  #   Pendragon[:realism] #=> Pendragon::Realism
+  #
+  # @param [Symbol] name a router type identifier
+  # @raise [ArgumentError] if the name is not supported
+  # @return [Class, #new]
+  def self.[](name)
+    @types.fetch(normalized = normalize_type(name)) do
+      @mutex.synchronize do
+        error = try_require "pendragon/#{normalized}"
+        @types.fetch(normalized) do
+          fail ArgumentError,
+            "unsupported type %p #{ " (#{error.message})" if error }" % name
+        end
+      end
     end
+  end
 
-    # @!visibility private
-    def configuration_warning(method)
-      warn <<-WARN
-Pendragon.#{method} is deprecated because it isn't thread-safe.
-Please use new syntax.
-Pendragon.new do |config|
-  config.auto_rack_format = false
-  config.enable_compiler  = true
-end
-      WARN
-    end
+  # @return [LoadError, nil]
+  # @!visibility private
+  def self.try_require(path)
+    require(path)
+    nil
+  rescue LoadError => error
+    raise(error) unless error.path == path
+    error
+  end
+
+  # @!visibility private
+  def self.register(name, type)
+    @types[normalize_type(name)] = type
+  end
 
-    private :configuration_warning
+  # @!visibility private
+  def self.normalize_type(type)
+    type.to_s.gsub('-', '_').downcase
   end
 end

data/lib/pendragon/constants.rb

@@ -0,0 +1,27 @@
+module Pendragon
+  # A module for unifying magic numbers
+  # @!visibility private
+  module Constants
+    module Http
+      GET     = 'GET'.freeze
+      POST    = 'POST'.freeze
+      PUT     = 'PUT'.freeze
+      DELETE  = 'DELETE'.freeze
+      HEAD    = 'HEAD'.freeze
+      OPTIONS = 'OPTIONS'.freeze
+
+      NOT_FOUND             = 404.freeze
+      METHOD_NOT_ALLOWED    = 405.freeze
+      INTERNAL_SERVER_ERROR = 500.freeze
+    end
+
+    module Header
+      CASCADE = 'X-Cascade'.freeze
+    end
+
+    module Env
+      PATH_INFO      = 'PATH_INFO'.freeze
+      REQUEST_METHOD = 'REQUEST_METHOD'.freeze
+    end
+  end
+end

data/lib/pendragon/errors.rb

@@ -0,0 +1,72 @@
+require 'rack/utils'
+
+module Pendragon
+  # Module for creating any error classes.
+  module Errors
+    # Class for handling HTTP error.
+    class Base < StandardError
+      attr_accessor :status, :headers, :message
+
+      # Creates a new error class.
+      #
+      # @example
+      #   require 'pendragon/errors'
+      #
+      #   BadRequest = Pendragon::Errors::Base.create(status: 400)
+      #
+      # @option [Integer] status
+      # @option [Hash{String => String}] headers
+      # @option [String] message
+      # @return [Class]
+      def self.create(**options, &block)
+        Class.new(self) do
+          options.each { |k, v| define_singleton_method(k) { v } }
+          class_eval(&block) if block_given?
+        end
+      end
+
+      # Returns default message.
+      #
+      # @see [Rack::Utils::HTTP_STATUS_CODES]
+      # @return [String] default message for current status.
+      def self.default_message
+        @default_message ||= Rack::Utils::HTTP_STATUS_CODES.fetch(status, 'server error').downcase
+      end
+
+      # Returns default headers.
+      #
+      # @return [Hash{String => String}] HTTP headers
+      def self.default_headers
+        @default_headers ||= { 'Content-Type' => 'text/plain' }
+      end
+
+      # Constructs an instance of Errors::Base
+      #
+      # @option [Hash{String => String}] headers
+      # @option [Integer] status
+      # @option [String] message
+      # @options payload
+      # @return [Pendragon::Errors::Base]
+      def initialize(headers: {}, status: self.class.status, message: self.class.default_message, **payload)
+        self.headers = self.class.default_headers.merge(headers)
+        self.status, self.message = status, message
+        parse_payload(**payload) if payload.kind_of?(Hash) && respond_to?(:parse_payload)
+        super(message)
+      end
+
+      # Converts self into response conformed Rack style.
+      #
+      # @return [Array<Integer, Hash{String => String}, #each>] response
+      def to_response
+        [status, headers, [message]]
+      end
+    end
+
+    NotFound         = Base.create(status: 404)
+    MethodNotAllowed = Base.create(status: 405) do
+      define_method(:parse_payload) do |allows: [], **payload|
+        self.headers['Allows'] = allows.join(?,) unless allows.empty?
+      end
+    end
+  end
+end

data/lib/pendragon/linear.rb

@@ -0,0 +1,9 @@
+require 'pendragon/router'
+
+module Pendragon
+  class Linear < Router
+    register :linear
+
+    on(:call) { |env| rotation(env) { |route| route.exec(env) } }
+  end
+end

data/lib/pendragon/realism.rb

@@ -0,0 +1,49 @@
+require 'pendragon/router'
+
+module Pendragon
+  class Realism < Router
+    register :realism
+
+    on :call do |env|
+      identity(env) || rotation(env) { |route| route.exec(env) }
+    end
+
+    on :compile do |method, routes|
+      patterns = routes.map.with_index do |route, index|
+        route.index  = index
+        route.regexp = /(?<_#{index}>#{route.pattern.to_regexp})/
+      end
+      omap[method] = Regexp.union(patterns)
+    end
+
+    private
+
+    # @!visibility private
+    def omap
+      @omap ||= Hash.new { |hash, key| hash[key] = // }
+    end
+
+    # @!visibility private
+    def match?(input, method)
+      current_regexp = omap[method]
+      return unless current_regexp.match(input)
+      last_match = Regexp.last_match
+      map[method].detect { |route| last_match["_#{route.index}"] }
+    end
+
+    # @!visibility private
+    def identity(env, route = nil)
+      with_transaction(env) do |input, method|
+        route = match?(input, method)
+        route.exec(env) if route
+      end
+    end
+
+    # @!visibility private
+    def with_transaction(env)
+      input, method = extract(env)
+      response = yield(input, method)
+      response && !(cascade = cascade?(response)) ? response : nil
+    end
+  end
+end

data/lib/pendragon/router.rb

@@ -1,188 +1,341 @@
-require 'pendragon/route'
-require 'pendragon/matcher'
-require 'pendragon/error'
-require 'pendragon/configuration'
-require 'pendragon/engine/compiler'
-require 'rack'
+require 'pendragon/constants'
+require 'pendragon/errors'
+require 'mustermann'
+require 'forwardable'
+require 'ostruct'
 
 module Pendragon
-  # A class for the router
-  #
-  # @example Construct with a block which has no argument
-  #   router = Pendragon do
-  #     get("/"){ "hello world" }
-  #   end
-  #
-  # @example Construct with a block which has an argument
-  #   router = Pendragon.new do |config|
-  #     config.enable_compiler = true
-  #   end
   class Router
-    # The accessors are useful to access from Pendragon::Route
-    attr_accessor :current, :routes
+    # @!visibility private
+    attr_accessor :prefix
 
-    # @see Pendragon::Configuration#lock?
-    @@mutex = Mutex.new
+    # Registers new router type onto global maps.
+    #
+    # @example registring new router type.
+    #   require 'pendragon'
+    #
+    #   class Pendragon::SuperFast < Pendragon::Router
+    #     register :super_fast
+    #   end
+    #
+    #   Pendragon[:super_fast] #=> Pendragon::SuperFast
+    #
+    # @param [Symbol] name a router type identifier
+    # @see Pendragon.register
+    def self.register(name)
+      Pendragon.register(name, self)
+    end
 
-    # Constructs a new instance of Pendragon::Router
-    # Possible to pass the block
+    # Adds event listener in router class.
+    #
+    # @example
+    #   require 'pendragon'
     #
-    # @example with a block
-    #   app = Pendragon::Router.new do |config|
-    #     config.enable_compiler  = true
-    #     config.auto_rack_format = false
+    #   class Pendragon::SuperFast < Pendragon::Router
+    #     register :super_fast
+    #
+    #     on :call do |env|
+    #       rotation(env) { |route| route.exec(env) }
+    #     end
+    #
+    #     on :compile do |method, routes|
+    #       routes.each do |route|
+    #         route.pattern = route.pattern.to_regexp
+    #       end
+    #     end
     #   end
     #
-    # @example with base style
-    #   app = Pendragon::Router.new
-    #   app.get("/"){ "hello!" }
-    #   app.post("/"){ "hello post!" }
+    # @param [Symbol] event a event name which is :call or :compile
+    #
+    # @yieldparam [optional, Hash] env a request environment variables on :call event.
+    # @yieldreturn [optional, Array<Integer, Hash, #each>, Rack::Response] response
+    #
+    # @yieldparam [String] method
+    # @yieldparam [Array<Pendragon::Route>] routes
+    def self.on(event, &listener)
+      define_method('on_%s_listener' % event, &listener)
+    end
+
+    # Construcsts an instance of router class.
+    #
+    # @example construction for router class
+    #   require 'pendragon'
+    #
+    #   Pendragon.new do
+    #     get '/', to: -> { [200, {}, ['hello']] }
+    #   end
+    #
+    # @yield block a block is evaluated in instance context.
+    # @return [Pendragon::Router]
     def initialize(&block)
-      reset!
-      if block_given?
-        if block.arity.zero?
-          instance_eval(&block)
-        else
-          @configuration = Configuration.new
-          block.call(configuration)
-        end
-      end
+      @compiled = false
+      instance_eval(&block) if block_given?
     end
 
-    # Finds the routes if request method is valid
-    # @return the Rack style response
+    # Prefixes a namespace to route path inside given block.
+    #
+    # @example
+    #   require 'pendragon'
+    #
+    #   Pendragon.new do
+    #     namespace :foo do
+    #       # This definition is dispatched to '/foo/bar'.
+    #       get '/bar', to: -> { [200, {}, ['hello']] }
+    #     end
+    #   end
+    # 
+    # @yield block a block is evaluated in instance context.
+    def namespace(name, &block)
+      fail ArgumentError unless block_given?
+      (self.prefix ||= []) << name.to_s
+      instance_eval(&block)
+    ensure
+      prefix.pop
+    end
+
+    # Calls by given env, returns a response conformed Rack style.
+    #
+    # @example
+    #   require 'pendragon'
+    #
+    #   router = Pendragon.new do
+    #     get '/', to: -> { [200, {}, ['hello']]  }
+    #   end
+    #
+    #   env = Rack::MockRequest.env_for('/')
+    #   router.call(env) #=> [200, {}, ['hello']]
+    #
+    # @return [Array<Integer, Hash, #each>, Rack::Response] response conformed Rack style
     def call(env)
-      request = Rack::Request.new(env)
-      recognize(request).each do |route, params|
-        catch(:pass){ return invoke(route, params) }
+      catch(:halt) { with_optimization { invoke(env) } }
+    end
+
+    # Class for delegation based structure.
+    # @!visibility private
+    class Route < OpenStruct
+      # @!visibility private
+      attr_accessor :pattern
+
+      # @!visibility private
+      attr_reader :request_method, :path
+
+      extend Forwardable
+      def_delegators :@pattern, :match, :params
+
+      # @!visibility private
+      def initialize(method:, pattern:, application:, **attributes)
+        super(attributes)
+
+        @app            = application
+        @path           = pattern
+        @pattern        = Mustermann.new(pattern)
+        @executable     = to_executable
+        @request_method = method.to_s.upcase
+      end
+
+      # @!visibility private
+      def exec(env)
+        return @app.call(env) unless executable?
+        path_info = env[Constants::Env::PATH_INFO]
+        params = pattern.params(path_info)
+        captures = pattern.match(path_info).captures
+        Context.new(env, params: params, captures: captures).trigger(@executable)
+      end
+
+      private
+
+      # @!visibility private
+      def executable?
+        @app.kind_of?(Proc)
+      end
+
+      # @!visibility private
+      def to_executable
+        return @app unless executable?
+        Context.to_method(request_method, path, @app)
+      end
+
+      # Class for providing helpers like :env, :params and :captures.
+      # This class will be available if given application is an kind of Proc.
+      # @!visibility private
+      class Context
+        # @!visibility private
+        attr_reader :env, :params, :captures
+
+        # @!visibility private
+        def self.generate_method(name, callable)
+          define_method(name, &callable)
+          method = instance_method(name)
+          remove_method(name)
+          method
+        end
+
+        # @!visibility private
+        def self.to_method(*args, callable)
+          unbound = generate_method(args.join(' '), callable)
+          if unbound.arity.zero?
+            proc { |app, captures| unbound.bind(app).call }
+          else
+            proc { |app, captures| unbound.bind(app).call(*captures) }
+          end
+        end
+
+        # @!visibility private
+        def initialize(env, params: {}, captures: [])
+          @env = env
+          @params = params
+          @captures = captures
+        end
+
+        # @!visibility private
+        def trigger(executable)
+          executable[self, captures]
+        end
       end
-    rescue BadRequest, NotFound, MethodNotAllowed
-      $!.call
     end
 
-    # Calls a route, and build return value of the router
-    # @param [Pendragon::Route] route The route matched with the condition of request
-    # @param [Hash] params The params will be passed with the route
-    # @return [Array<Fixnum, Hash, Array>] The return value of the route block
-    def invoke(route, params)
-      response = route.arity != 0 ? route.call(params) : route.call
-      return response unless configuration.auto_rack_format?
-      status = route.options[:status] || 200
-      header = {'Content-Type' => 'text/html;charset=utf-8'}.merge(route.options[:header] || {})
-      [status, header, Array(response)]
+    # Appends a route of GET method
+    # @see [Pendragon::Router#route]
+    def get(path, to: nil, **options, &block)
+      route Constants::Http::GET, path, to: to, **options, &block
     end
 
-    # Provides some methods intuitive than #add
-    # Basic usage is the same as #add
-    # @see Pendragon::Router#add
-    def get(path, options = {}, &block);    add :get,    path, options, &block end
-    def post(path, options = {}, &block);   add :post,   path, options, &block end
-    def delete(path, options = {}, &block); add :delete, path, options, &block end
-    def put(path, options = {}, &block);    add :put,    path, options, &block end
-    def head(path, options = {}, &block);   add :head,   path, options, &block end
+    # Appends a route of POST method
+    # @see [Pendragon::Router#route]
+    def post(path, to: nil, **options, &block)
+      route Constants::Http::POST, path, to: to, **options, &block
+    end
 
-    # Adds a new route to router
-    # @return [Pendragon::Route]
-    def add(verb, path, options = {}, &block)
-      routes << (route = Route.new(path, verb, options, &block))
-      route.router = self
-      route
+    # Appends a route of PUT method
+    # @see [Pendragon::Router#route]
+    def put(path, to: nil, **options, &block)
+      route Constants::Http::PUT, path, to: to, **options, &block
     end
 
-    # Resets the router's instance variables
-    def reset!
-      @routes = []
-      @current = 0
-      @prepared = nil
+    # Appends a route of DELETE method
+    # @see [Pendragon::Router#route]
+    def delete(path, to: nil, **options, &block)
+      route Constants::Http::DELETE, path, to: to, **options, &block
     end
 
-    # Prepares the router for route's priority
-    # This method is executed only once in the initial load
-    def prepare!
-      @routes.sort_by!(&:order)
-      @engine = (configuration.enable_compiler? ? Compiler : Recognizer).new(routes)
-      @prepared = true
+    # Appends a route of HEAD method
+    # @see [Pendragon::Router#route]
+    def head(path, to: nil, **options, &block)
+      route Constants::Http::HEAD, path, to: to, **options, &block
     end
 
-    # @return [Boolean] the router is already prepared?
-    def prepared?
-      !!@prepared
+    # Appends a route of OPTIONS method
+    # @see [Pendragon::Router#route]
+    def options(path, to: nil, **options, &block)
+      route Constants::Http::OPTIONS, path, to: to, **options, &block
     end
 
-    # Increments for the integrity of priorities
-    def increment_order!
-      @current += 1
+    # Appends a new route to router.
+    #
+    # @param [String] method A request method, it should be upcased.
+    # @param [String] path The application is dispatched to given path.
+    # @option [Class, #call] :to
+    def route(method, path, to: nil, **options, &block)
+      app = block_given? ? block : to
+      fail ArgumentError, 'Rack application could not be found' unless app
+      path = ?/ + prefix.join(?/) + path if prefix && !prefix.empty?
+      append Route.new(method: method, pattern: path, application: app, **options)
     end
 
-    # Recognizes the route by request
-    # @param request [Rack::Request]
-    # @return [Array]
-    def recognize(request)
-      prepare! unless prepared?
-      synchronize { @engine.call(request) }
+    # Maps all routes for each request methods.
+    # @return [Hash{String => Array}] map
+    def map
+      @map ||= Hash.new { |hash, key| hash[key] = [] }
     end
 
-    # Recognizes a given path
-    # @param path_info [String]
-    # @return [Array]
-    def recognize_path(path_info)
-      route, params = recognize(Rack::MockRequest.env_for(path_info)).first
-      [route.name, params.inject({}){|hash, (key, value)| hash[key] = value; hash }]
+    # Maps all routes.
+    # @return [Array<Pendragon::Route>] flat_map
+    def flat_map
+      @flat_map ||= []
     end
 
-    # Returns an expanded path matched with the conditions as arguments
-    # @return [String, Regexp]
-    # @example
-    #   router = Pendragon.new
-    #   index = router.get("/:id", :name => :index){}
-    #   router.path(:index, :id => 1) #=> "/1"
-    #   router.path(:index, :id => 2, :foo => "bar") #=> "/1?foo=bar"
-    def path(name, *args)
-      extract_with(name, *args) do |route, params, matcher|
-        matcher.mustermann? ? matcher.expand(params) : route.path
+    private
+
+    # @!visibility private
+    def append(route)
+      flat_map << route
+      map[route.request_method] << route
+    end
+
+    # @!visibility private
+    def invoke(env)
+      response = on_call_listener(env)
+      if !response && (allows = find_allows(env))
+        error!(Errors::MethodNotAllowed, allows: allows)
       end
+      response || error!(Errors::NotFound)
     end
 
-    # Returns Pendragon configuration
-    # @return [Pendragon::Configuration]
-    def configuration
-      @configuration || Pendragon.configuration
+    # @!visibility private
+    def error!(error_class, **payload)
+      throw :halt, error_class.new(**payload).to_response
     end
 
     # @!visibility private
-    # @example
-    #   extract_with(:index) do |route, params|
-    #     route.matcher.mustermann? ? route.matcher.expand(params) : route.path
-    #   end
-    def extract_with(name, *args)
-      params = args.delete_at(args.last.is_a?(Hash) ? -1 : 0) || {}
-      saved_args = args.dup
-      @routes.each do |route|
-        next unless route.name == name
-        matcher = route.matcher
-        if !args.empty? and matcher.mustermann?
-          matcher_names = matcher.names
-          params_for_expand = Hash[matcher_names.map{|matcher_name|
-            [matcher_name.to_sym, (params[matcher_name] || args.shift)]}]
-          params_for_expand.merge!(Hash[params.select{|k, v| !matcher_names.include?(name) }])
-          args = saved_args.dup
-        else
-          params_for_expand = params.dup
-        end
-        return yield(route, params_for_expand, matcher)
-      end
-      raise InvalidRouteException
+    def find_allows(env)
+      pattern = env[Constants::Env::PATH_INFO]
+      hits = flat_map.select { |route| route.match(pattern) }.map(&:request_method)
+      hits.empty? ? nil : hits
+    end
+
+    # @!visibility private
+    def extract(env, required: [:input, :method])
+      extracted = []
+      extracted << env[Constants::Env::PATH_INFO] if required.include?(:input)
+      extracted << env[Constants::Env::REQUEST_METHOD] if required.include?(:method)
+      extracted
     end
 
     # @!visibility private
-    def synchronize(&block)
-      if configuration.lock?
-        @@mutex.synchronize(&block)
-      else
-        yield
+    def rotation(env, exact_route = nil)
+      input, method = extract(env)
+      response = nil
+      map[method].each do |route|
+        next unless route.match(input)
+        response = yield(route)
+        break(response) unless cascade?(response)
+        response = nil
       end
+      response
+    end
+
+    # @!visibility private
+    def cascade?(response)
+      response && response[1][Constants::Header::CASCADE] == 'pass'
+    end
+
+    # @!visibility private
+    def compile
+      map.each(&method(:on_compile_listener))
+      @compiled = true
     end
 
-    private :extract_with, :synchronize
+    # @!visibility private
+    def with_optimization
+      compile unless compiled?
+      yield
+    end
+
+    # Optional event listener
+    # @param [String] method A request method like GET, POST
+    # @param [Array<Pendragon::Route>] routes All routes associated to the method
+    # @!visibility private
+    def on_compile_listener(method, routes)
+    end
+
+    # @!visibility private
+    def on_call_listener(env)
+      fail NotImplementedError
+    end
+
+    # @!visibility private
+    def compiled?
+      @compiled
+    end
   end
 end