rack-jet_router 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7c6751942e65d4b71cede69c49f3af1358a01df8
+  data.tar.gz: 399a8826aa1cd09d46ff602e769095ef1835c1f6
+SHA512:
+  metadata.gz: 676af23010d1a41ea37db5320356ecfc398792f9b606a1e029f94d1c8cc12b3cab2ec464df9954ac7d5397a779a1e77d5edcf1c2ad3685a906fcb12eb152abff
+  data.tar.gz: ed4ee93454abecf030a50a318d55c2fa6e12eb18631fd962ab42f3944e88bef70bfd6f76ffff21f113b11428cf2881739f878b827d2845f8cd07f2ae95064586

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+$Copyright: copyright(c) 2015 kuwata-lab.com all rights reserved $
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# Rack::JetRouter
+
+Rack::JetRouter is crazy-fast router library for Rack application,
+derived from [Keight.rb](https://github.com/kwatch/keight/tree/ruby).
+
+
+## Benchmark
+
+Benchmark script is [here](https://github.com/kwatch/rack-jet_router/blob/dev/bench/bench.rb).
+
+```
+## Ranking                        real[ns]
+(Rack plain)  /api/hello             1.555 (100.0%) ********************
+(JetRouter)   /api/hello             1.597 ( 97.4%) *******************
+(JetRouter)   /api/hello/123         6.424 ( 24.2%) *****
+(R::Req+Res)  /api/hello             9.837 ( 15.8%) ***
+(Sinatra)     /api/hello           106.965 (  1.5%)
+(Sinatra)     /api/hello/123       116.672 (  1.3%)
+```
+
+* If URL path has no path parameter (such as `/api/hello`),
+  Rack::JetRouter is just a litte slower than plain Rack application.
+* If URL path contains path parameter (such as `/api/hello/:id`),
+  Rack::JetRouter becomes slower, but it is enough small (about 6.4ns/req).
+* Overhead of Rack::JetRouter is smaller than that of Rack::Reqeust +
+  Rack::Response.
+* Sinatra is too slow.
+
+
+## Examples
+
+### #1: Depends only on Request Path
+
+```ruby
+# -*- coding: utf-8 -*-
+
+require 'rack'
+require 'rack/jet_router'
+
+## Assume that welcome_app, books_api, ... are Rack application.
+urlpath_mapping = [
+    ['/'                       , welcome_app],
+    ['/api', [
+        ['/books', [
+            [''                , books_api],
+            ['/:id(.:format)'  , book_api],
+            ['/:book_id/comments/:comment_id', comment_api],
+        ]],
+    ]],
+    ['/admin', [
+        ['/books'              , admin_books_app],
+    ]],
+]
+
+router = Rack::JetRouter.new(urlpath_mapping)
+p router.find('/api/books/123.html')
+    #=> [book_api, {"id"=>"123", "format"=>"html"}]
+
+status, headers, body = router.call(env)
+```
+
+
+### #2: Depends on both Request Path and Method
+
+```ruby
+# -*- coding: utf-8 -*-
+
+require 'rack'
+require 'rack/jet_router'
+
+## Assume that welcome_app, book_list_api, ... are Rack application.
+urlpath_mapping = [
+    ['/'                       , {GET: welcome_app}],
+    ['/api', [
+        ['/books', [
+            [''                , {GET: book_list_api, POST: book_create_api}],
+            ['/:id(.:format)'  , {GET: book_show_api, PUT: book_update_api}],
+            ['/:book_id/comments/:comment_id', {POST: comment_create_api}],
+        ]],
+    ]],
+    ['/admin', [
+        ['/books'              , {ANY: admin_books_app}],
+    ]],
+]
+
+router = Rack::JetRouter.new(urlpath_mapping)
+p router.find('/api/books/123')
+    #=> [{"GET"=>book_show_api, "PUT"=>book_update_api}, {"id"=>"123", "format"=>nil}]
+
+status, headers, body = router.call(env)
+```
+
+Notice that `{GET: ..., PUT: ...}` is converted into `{"GET"=>..., "PUT"=>...}`
+automatically when passing to `Rack::JetRouter.new()`.
+
+
+### #3: RESTful Framework
+
+```ruby
+# -*- coding: utf-8 -*-
+
+require 'rack'
+require 'rack/jet_router'
+
+class API
+  def initialize(request, response)
+    @request  = request
+    @response = response
+  end
+  attr_reader :request, :response
+end
+
+class BooksAPI < API
+  def index(); ....; end
+  def create(); ....; end
+  def show(id); ....; end
+  def update(id: nil); ....; end
+  def delete(id: nil); ....; end
+end
+
+urlpath_mapping = [
+    ['/api', [
+        ['/books', [
+            [''      , {GET:    [BooksAPI, :index],
+                        POST:   [BooksAPI, :create]}],
+            ['/:id'  , {GET:    [BooksAPI, :show],
+                        PUT:    [BooksAPI, :update],
+                        DELETE: [BooksAPI, :delete]}],
+        ]],
+    ]],
+]
+router = Rack::JetRouter.new(urlpath_mapping)
+p router.find('/api/books/123')
+    #=> [{"GET"=>[BooksAPI, :show], "PUT"=>..., "DELETE"=>...}, {"id"=>"123"}]
+
+dict, args = router.find('/api/books/123')
+klass, action = dict["GET"]
+handler = klass.new(Rack::Request.new(env), Rack::Response.new)
+handler.__send__(action, args)
+```
+
+
+## Topics
+
+
+### URL Path Parameters
+
+URL path parameters (such as `{"id"=>"123"}`) is available via
+`env['rack.urlpath_params']`.
+
+```ruby
+BookApp = proc {|env|
+  p env['rack.urlpath_params']   #=> {"id"=>"123"}
+  [200, {}, []]
+}
+```
+
+If you want to tweak URL path parameters, define subclass of Rack::JetRouter
+and override `#build_urlpath_parameter_vars(env, vars)`.
+
+```ruby
+class MyRouter < JetRouter
+
+  def build_urlpath_parameter_vars(names, values)
+    return names.zip(values).each_with_object({}) {|(k, v), d|
+      ## converts urlpath pavam value into integer
+      v = v.to_i if k == 'id' || k.end_with?('_id')
+      d[k] = v
+    }
+  end
+
+end
+```
+
+
+### Variable URL Path Cache
+
+It is possible to classify URL path patterns into two types: fixed and variable.
+
+* **Fixed URL path pattern** doesn't contain any urlpath paramters.<br>
+  Example: `/`, `/login`, `/api/books`
+* **Variable URL path pattern** contains urlpath parameters.<br>
+  Example: `/api/books/:id`, `/index(.:format)`
+
+`Rack::JetRouter` caches only fixed URL path patterns in default.
+It is possible for `Rack::JetRouter` to cache variable URL path patterns
+as well as fixed ones. It will make routing much faster.
+
+```ruby
+## Enable variable urlpath cache.
+router = Rack::JetRouter.new(urlpath_mapping, urlpath_cache_size: 200)
+p router.find('/api/books/123')   # caches even varaible urlpath
+```
+
+
+### Custom Error Response
+
+```ruby
+class MyRouter < Rack::JetRouter
+
+  def error_not_found(env)
+    html = ("<h2>404 Not Found</h2>\n" \
+            "<p>Path: #{env['PATH_INFO']}</p>\n")
+    [404, {"Content-Type"=>"text/html"}, [html]]
+  end
+
+  def error_not_allowed(env)
+    html = ("<h2>405 Method Not Allowed</h2>\n" \
+            "<p>Method: #{env['REQUEST_METHOD']}</p>\n")
+    [405, {"Content-Type"=>"text/html"}, [html]]
+  end
+
+end
+```
+
+Above methods are invoked from `Rack::JetRouter#call()`.
+
+
+## Copyright and License
+
+$Copyright: copyright(c) 2015 kuwata-lab.com all rights reserved $
+
+$License: MIT License $
+
+
+## History
+
+### 2015-12-06: Release 0.1.0
+
+* First release

data/Rakefile

@@ -0,0 +1,57 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test
+
+
+desc "show how to release"
+task :help do
+  puts <<END
+How to release:
+
+    $ git checkout dev
+    $ git diff
+    $ which ruby
+    $ rake test                 # for confirmation
+    $ git checkout -b rel-1.0   # or git checkout rel-1.0
+    $ rake edit rel=1.0.0
+    $ git diff
+    $ git commit -a -m "release preparation for 1.0.0"
+    $ rake build                # for confirmation
+    $ rake install              # for confirmation
+    $ #rake release
+    $ gem push pkg/rake-jet_router-1.0.0.gem
+    $ git tag v1.0.0
+    $ git push -u origin rel-1.0
+    $ git push --tags
+END
+
+end
+
+
+desc "edit files (for release preparation)"
+task :edit do
+  rel = ENV['rel']  or
+    raise "ERROR: 'rel' environment variable expected."
+  filenames = Dir[*%w[lib/**/*.rb test/**/*_test.rb test/test_helper.rb *.gemspec]]
+  filenames.each do |fname|
+    File.open(fname, 'r+', encoding: 'utf-8') do |f|
+      content = f.read()
+      x = content.gsub!(/\$Release:.*?\$/, "$Release: #{rel} $")
+      if x.nil?
+        puts "[_] #{fname}"
+      else
+        puts "[C] #{fname}"
+        f.rewind()
+        f.truncate(0)
+        f.write(content)
+      end
+    end
+  end
+end

data/lib/rack/jet_router.rb

@@ -0,0 +1,298 @@
+# -*- coding: utf-8 -*-
+
+###
+### $Release: 1.0.0 $
+### $Copyright: copyright(c) 2015 kuwata-lab.com all rights reserved $
+### $License: MIT License $
+###
+
+require 'rack'
+
+
+module Rack
+
+
+  ##
+  ## Jet-speed router class, derived from Keight.rb.
+  ##
+  ## ex:
+  ##   urlpath_mapping = [
+  ##       ['/'                       , welcome_app],
+  ##       ['/api', [
+  ##           ['/books', [
+  ##               [''                , books_api],
+  ##               ['/:id(.:format)'  , book_api],
+  ##               ['/:book_id/comments/:comment_id', comment_api],
+  ##           ]],
+  ##       ]],
+  ##       ['/admin', [
+  ##           ['/books'              , admin_books_app],
+  ##       ]],
+  ##   ]
+  ##   router = Rack::JetRouter.new(urlpath_mapping)
+  ##   router.find('/api/books/123.html')
+  ##       #=> [book_api, {"id"=>"123", "format"=>"html"}]
+  ##   status, headers, body = router.call(env)
+  ##
+  ##   ### or:
+  ##   urlpath_mapping = [
+  ##       ['/'                       , {GET: welcome_app}],
+  ##       ['/api', [
+  ##           ['/books', [
+  ##               [''                , {GET: book_list_api, POST: book_create_api}],
+  ##               ['/:id(.:format)'  , {GET: book_show_api, PUT: book_update_api}],
+  ##               ['/:book_id/comments/:comment_id', {POST: comment_create_api}],
+  ##           ]],
+  ##       ]],
+  ##       ['/admin', [
+  ##           ['/books'              , {ANY: admin_books_app}],
+  ##       ]],
+  ##   ]
+  ##   router = Rack::JetRouter.new(urlpath_mapping)
+  ##   router.find('/api/books/123')
+  ##       #=> [{"GET"=>book_show_api, "PUT"=>book_update_api}, {"id"=>"123", "format"=>nil}]
+  ##   status, headers, body = router.call(env)
+  ##
+  class JetRouter
+
+    def initialize(mapping, urlpath_cache_size: 0)
+      #; [!u2ff4] compiles urlpath mapping.
+      (@urlpath_rexp,          # ex: {'/api/books'=>BooksApp}
+       @fixed_urlpath_dict,    # ex: [[%r'\A/api/books/([^./]+)\z', ['id'], BookApp]]
+       @variable_urlpath_list, # ex: %r'\A(?:/api(?:/books(?:/[^./]+(\z))))\z'
+      ) = compile_mapping(mapping)
+      ## cache for variable urlpath (= containg urlpath parameters)
+      @urlpath_cache_size = urlpath_cache_size
+      @variable_urlpath_cache = urlpath_cache_size > 0 ? {} : nil
+    end
+
+    ## Finds rack app according to PATH_INFO and REQUEST_METHOD and invokes it.
+    def call(env)
+      #; [!fpw8x] finds mapped app according to env['PATH_INFO'].
+      req_path = env['PATH_INFO']
+      app, urlpath_params = find(req_path)
+      #; [!wxt2g] guesses correct urlpath and redirects to it automaticaly when request path not found.
+      #; [!3vsua] doesn't redict automatically when request path is '/'.
+      unless app || req_path == '/'
+        location = req_path =~ /\/\z/ ? req_path[0..-2] : req_path + '/'
+        app, urlpath_params = find(location)
+        return redirect_to(location) if app
+      end
+      #; [!30x0k] returns 404 when request urlpath not found.
+      return error_not_found(env) unless app
+      #; [!gclbs] if mapped object is a Hash...
+      if app.is_a?(Hash)
+        #; [!p1fzn] invokes app mapped to request method.
+        #; [!5m64a] returns 405 when request method is not allowed.
+        #; [!ys1e2] uses GET method when HEAD is not mapped.
+        #; [!2hx6j] try ANY method when request method is not mapped.
+        dict = app
+        req_meth = env['REQUEST_METHOD']
+        app = dict[req_meth] || (req_meth == 'HEAD' ? dict['GET'] : nil) || dict['ANY']
+        return error_not_allowed(env) unless app
+      end
+      #; [!2c32f] stores urlpath parameters as env['rack.urlpath_params'].
+      store_urlpath_params(env, urlpath_params)
+      #; [!hse47] invokes app mapped to request urlpath.
+      return app.call(env)   # make body empty when HEAD?
+    end
+
+    ## Finds app or Hash mapped to request path.
+    ##
+    ## ex:
+    ##    find('/api/books/123')   #=> [BookApp, {"id"=>"123"}]
+    def find(req_path)
+      #; [!24khb] finds in fixed urlpaths at first.
+      #; [!iwyzd] urlpath param value is nil when found in fixed urlpaths.
+      obj = @fixed_urlpath_dict[req_path]
+      return obj, nil if obj
+      #; [!upacd] finds in variable urlpath cache if it is enabled.
+      #; [!1zx7t] variable urlpath cache is based on LRU.
+      cache = @variable_urlpath_cache
+      if cache && (pair = cache.delete(req_path))
+        cache[req_path] = pair
+        return pair
+      end
+      #; [!vpdzn] returns nil when urlpath not found.
+      m = @urlpath_rexp.match(req_path)
+      return nil unless m
+      index = m.captures.find_index('')
+      return nil unless index
+      #; [!ijqws] returns mapped object and urlpath parameter values when urlpath found.
+      full_urlpath_rexp, param_names, obj = @variable_urlpath_list[index]
+      m = full_urlpath_rexp.match(req_path)
+      param_values = m.captures
+      vars = build_urlpath_parameter_vars(param_names, param_values)
+      #; [!84inr] caches result when variable urlpath cache enabled.
+      if cache
+        cache.shift() if cache.length >= @urlpath_cache_size
+        cache[req_path] = [obj, vars]
+      end
+      return obj, vars
+    end
+
+    protected
+
+    ## Returns [404, {...}, [...]]. Override in subclass if necessary.
+    def error_not_found(env)
+      #; [!mlruv] returns 404 response.
+      return [404, {"Content-Type"=>"text/plain"}, ["404 Not Found"]]
+    end
+
+    ## Returns [405, {...}, [...]]. Override in subclass if necessary.
+    def error_not_allowed(env)
+      #; [!mjigf] returns 405 response.
+      return [405, {"Content-Type"=>"text/plain"}, ["405 Method Not Allowed"]]
+    end
+
+    ## Returns [301, {"Location"=>location, ...}, [...]]. Override in subclass if necessary.
+    def redirect_to(location)
+      content = "Redirect to #{location}"
+      return [301, {"Content-Type"=>"text/plain", "Location"=>location}, [content]]
+    end
+
+    ## Sets env['rack.urlpath_params'] = vars. Override in subclass if necessary.
+    def store_urlpath_params(env, vars)
+      env['rack.urlpath_params'] = vars if vars
+    end
+
+    ## Returns Hash object representing urlpath parameters. Override if necessary.
+    ##
+    ## ex:
+    ##     class MyRouter < JetRouter
+    ##       def build_urlpath_parameter_vars(names, values)
+    ##         return names.zip(values).each_with_object({}) {|(k, v), d|
+    ##           ## converts urlpath pavam value into integer
+    ##           v = v.to_i if k == 'id' || k.end_with?('_id')
+    ##           d[k] = v
+    ##         }
+    ##       end
+    ##     end
+    def build_urlpath_parameter_vars(names, values)
+      return Hash[names.zip(values)]
+    end
+
+    private
+
+    ## Compiles urlpath mapping. Called from '#initialize()'.
+    def compile_mapping(mapping)
+      rexp_buf          = ['\A']
+      prefix_pat        = ''
+      fixed_urlpaths    = {}  # ex: {'/api/books'=>BooksApp}
+      variable_urlpaths = []  # ex: [[%r'\A/api/books/([^./]+)\z', ['id'], BookApp]]
+      _compile_mapping(mapping, rexp_buf, prefix_pat, fixed_urlpaths, variable_urlpaths)
+      ## ex: %r'\A(?:/api(?:/books(?:/[^./]+(\z)|/[^./]+/edit(\z))))\z'
+      rexp_buf << '\z'
+      urlpath_rexp = Regexp.new(rexp_buf.join())
+      #; [!xzo7k] returns regexp, hash, and array.
+      return urlpath_rexp, fixed_urlpaths, variable_urlpaths
+    end
+
+    def _compile_mapping(mapping, rexp_buf, prefix_pat, fixed_dict, variable_list)
+      param_pat1 = '[^./]+'
+      param_pat2 = '([^./]+)'
+      rexp_buf << '(?:'
+      len = rexp_buf.length
+      mapping.each do |urlpath_pat, obj|
+        rexp_buf << '|' if rexp_buf.length != len
+        full_urlpath_pat = "#{prefix_pat}#{urlpath_pat}"
+        #; [!ospaf] accepts nested mapping.
+        if obj.is_a?(Array)
+          rexp_str, _ = compile_urlpath_pattern(urlpath_pat, param_pat1)
+          rexp_buf << rexp_str
+          len2 = rexp_buf.length
+          _compile_mapping(obj, rexp_buf, full_urlpath_pat, fixed_dict, variable_list)
+          #; [!pv2au] deletes unnecessary urlpath regexp.
+          if rexp_buf.length == len2
+            x = rexp_buf.pop()
+            x == rexp_str  or raise "assertion failed"
+          end
+        #; [!2ktpf] handles end-point.
+        else
+          #; [!guhdc] if mapping dict is specified...
+          if obj.is_a?(Hash)
+            obj = normalize_mapping_keys(obj)
+          end
+          #; [!l63vu] handles urlpath pattern as fixed when no urlpath params.
+          full_urlpath_rexp_str, param_names = compile_urlpath_pattern(full_urlpath_pat, param_pat2)
+          fixed_pattern = param_names.nil?
+          if fixed_pattern
+            fixed_dict[full_urlpath_pat] = obj
+          #; [!vfytw] handles urlpath pattern as variable when urlpath param exists.
+          else
+            rexp_str, _ = compile_urlpath_pattern(urlpath_pat, param_pat1)
+            rexp_buf << rexp_str << '(\z)'
+            full_urlpath_rexp = Regexp.new("\\A#{full_urlpath_rexp_str}\\z")
+            variable_list << [full_urlpath_rexp, param_names, obj]
+          end
+        end
+      end
+      #; [!gfxgr] deletes unnecessary grouping.
+      if rexp_buf.length == len
+        x = rexp_buf.pop()    # delete '(?:'
+        x == '(?:'  or raise "assertion failed"
+      else
+        rexp_buf << ')'
+      end
+    end
+
+    ## Compiles '/books/:id' into ['/books/([^./]+)', ["id"]].
+    def compile_urlpath_pattern(urlpath_pat, param_pat='([^./]+)')
+      s = "".dup()
+      param_names = []
+      pos = 0
+      urlpath_pat.scan(/:(\w+)|\((.*?)\)/) do |name, optional|
+        #; [!joozm] escapes metachars with backslash in text part.
+        m = Regexp.last_match
+        text = urlpath_pat[pos...m.begin(0)]
+        pos = m.end(0)
+        s << Regexp.escape(text)
+        #; [!rpezs] converts '/books/:id' into '/books/([^./]+)'.
+        if name
+          param_names << name
+          s << param_pat
+        #; [!4dcsa] converts '/index(.:format)' into '/index(?:\.([^./]+))?'.
+        elsif optional
+          s << '(?:'
+          optional.scan(/(.*?)(?::(\w+))/) do |text2, name2|
+            s << Regexp.escape(text2) << param_pat
+            param_names << name2
+          end
+          s << Regexp.escape($' || optional)
+          s << ')?'
+        #
+        else
+          raise "unreachable: urlpath=#{urlpath.inspect}"
+        end
+      end
+      #; [!1d5ya] rethrns compiled string and nil when no urlpath parameters nor parens.
+      #; [!of1zq] returns compiled string and urlpath param names when urlpath param or parens exist.
+      if pos == 0
+        return Regexp.escape(urlpath_pat), nil
+      else
+        s << Regexp.escape(urlpath_pat[pos..-1])
+        return s, param_names
+      end
+    end
+
+    def normalize_mapping_keys(dict)
+      #; [!r7cmk] converts keys into string.
+      #; [!z9kww] allows 'ANY' as request method.
+      #; [!k7sme] raises error when unknown request method specified.
+      request_methods = REQUEST_METHODS
+      return dict.each_with_object({}) do |(meth, app), newdict|
+        meth_str = meth.to_s
+        request_methods[meth_str] || meth_str == 'ANY'  or
+          raise ArgumentError.new("#{meth.inspect}: unknown request method.")
+        newdict[meth_str] = app
+      end
+    end
+
+    #; [!haggu] contains available request methods.
+    REQUEST_METHODS = %w[GET POST PUT DELETE PATCH HEAD OPTIONS TRACE LINK UNLINK] \
+                        .each_with_object({}) {|s, d| d[s] = s.intern }
+
+  end
+
+
+end