rack-jet_router 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: dbed04ca4adfdce5a3e82234dd6182e18519dc62
-  data.tar.gz: bdec9db77792ffba5bca3e05ae4bf62f35cbf555
+SHA256:
+  metadata.gz: ffb2322f3ac227a3d07fa95c120d25c3dcb8763f9ea925be7a3a03df11c00ba9
+  data.tar.gz: 60b292dd4a1307a2fd1cbfcb474746131599fe0ba0ae93768b40f2cf0c9e5fa5
 SHA512:
-  metadata.gz: 0d90ffbb230351b7f0054d7d382b377dca41832cbfe2a47d6793c0ac88dbc075104535bf4529a6e1c50251365faadefb8d1fa02342d7104420cd8eb6316ea495
-  data.tar.gz: af141052683402fd8dedc4538b548bab59c816714e423236fe83cd70d2865f77337f5c6b9e0d93380e49fe4547995e36f256943be6426a20b1d04a82cfe69697
+  metadata.gz: d33fb4622786b549f6681f6a89fd578f631235548b7d67644431483815a71e62d0a438c22b82e2534074c52e704cd68607f02060153ea8477898e13725c3e836
+  data.tar.gz: 36be6953b2ed04a82f56c97e0c3eaf51022b21546116a0ead5b1a125ff82c746c1297a9c4e153012ca0a922e1a55161a1ea7a534036857d97cd91529aa4118d9

data/CHANGES.md

@@ -0,0 +1,52 @@
+CHANGES
+=======
+
+
+Release 1.3.0 (2023-12-09)
+--------------------------
+
+* [enhance] Performance has improved (about 10%). This improvement was achieved by optimizing regular expressions.
+* [enhance] URL path mapping can be nested Hash as well as nested Array. See the document for detail.
+* [enhance] Passing the `int_param: /(?:\A|_)id\z/` keyword argument to `JetRouter.new()` changes the router to treat urlpath parameter `id` or `xxx_id` as integer type.
+* [enhance] Passing the `env_key:` keyword argument to `JetRouter.new()` changes the key of environemnt to store URL path parameter values.
+* [change] Keyword parameter `urlpath_cache_size:` of `JetRouter.new()` is renamed to `cache_size:`. Old parameter name is also available for backward compatibility, but it is recommended to use new parameter name.
+* [change] Rename `JetRouter#build_urlpath_parameter_vars()` to `JetRouter#build_param_values()`.
+* [change] Update benchmark script to require 'benchmarker' gem.
+
+
+Release 1.2.0 (2016-10-16)
+--------------------------
+
+* Change auto-redirection to be occurred only on GET or HEAD methods.
+* Code is rewrited, especially around `Rack::JetRouter#compile_mapping()`.
+* Update benchmark script to support `Hanabi::Router`.
+
+
+Release 1.1.1 (2015-12-29)
+--------------------------
+
+* Fix benchmark script.
+* Fix document.
+
+
+Release 1.1.0 (2015-12-28)
+--------------------------
+
+* **NOTICE** `Rack::JetRouter#find()` is renamed to `#lookup()`.
+  `#find()` is also available for compatibility, but not recommended.
+* Performance improved when number of URL path parameter is 1.
+* Regular expression generated is improved.
+* Benchmark script is improved to take some command-line options.
+* Document fixed.
+
+
+Release 1.0.1 (2015-12-06)
+--------------------------
+
+* Fix document
+
+
+Release 1.0.0 (2015-12-06)
+--------------------------
+
+* First release

data/MIT-LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-$Copyright: copyright(c) 2015 kuwata-lab.com all rights reserved $
+$Copyright: copyright(c) 2015 kwatch@gmail.com $
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,11 +1,11 @@
 # Rack::JetRouter
 
-($Release: 1.2.0 $)
+($Release: 1.3.0 $)
 
 Rack::JetRouter is crazy-fast router library for Rack application,
 derived from [Keight.rb](https://github.com/kwatch/keight/tree/ruby).
 
-Rack::JetRouter requires Ruby >= 2.0.
+Rack::JetRouter requires Ruby >= 2.4.
 
 
 ## Benchmark
@@ -14,45 +14,42 @@ Benchmark script is [here](https://github.com/kwatch/rack-jet_router/blob/releas
 
 | Name               | Version |
 | ------------------ | ------- |
-| Ruby               | 2.3.1   |
-| Rack               | 1.6.4   |
-| Rack::JetRouter    | 1.2.0   |
+| Ruby               | 3.2.2   |
+| Rack               | 2.2.8   |
+| Rack::JetRouter    | 1.3.0   |
 | Rack::Multiplexer  | 0.0.8   |
-| Sinatra            | 1.4.6   |
-| Keight.rb          | 0.3.0   |
-| Hanami             | 0.8.0   |
+| Sinatra            | 3.1.0   |
+| Keight.rb          | 1.0.0   |
+| Hanami::Router     | 2.0.2   |
 
-(Macbook Air, Intel Core i7 1.7GHz, OS X EL Capitan)
+(Macbook Pro, Apple M1 Pro, macOS Ventura 13.6.2)
 
 
 ### JetRouter vs. Rack vs. Sinatra vs. Keight.rb vs. Hanami:
 
 ```
-## Ranking                             real
-(Rack plain)  /api/aaa01             0.9316 (100.0%) ********************
-(Rack plain)  /api/aaa01/123         1.0222 ( 91.1%) ******************
-(JetRouter)   /api/aaa01             1.4191 ( 65.6%) *************
-(JetRouter)   /api/aaa01/123         6.0146 ( 15.5%) ***
-(Multiplexer) /api/aaa01             6.1026 ( 15.3%) ***
-(Keight.rb)   /api/aaa01             7.2330 ( 12.9%) ***
-(R::Req+Res)  /api/aaa01            10.7835 (  8.6%) **
-(R::Req+Res)  /api/aaa01/123        10.8412 (  8.6%) **
-(Keight.rb)   /api/aaa01/123        10.8708 (  8.6%) **
-(Hanami::Router) /api/zzz26         11.5185 (  8.1%) **
-(Hanami::Router) /api/aaa01         11.7033 (  8.0%) **
-(Hanami::Router) /api/aaa01/123     17.9229 (  5.2%) *
-(Multiplexer) /api/aaa01/123        18.6987 (  5.0%) *
-(Sinatra)     /api/aaa01           109.7597 (  0.8%) 
-(Sinatra)     /api/aaa01/123       121.3258 (  0.8%) 
+## Ranking                         usec/req  Graph (longer=faster)
+(JetRouter)      /api/aaa01          0.2816 (100.0%) ********************
+(Multiplexer)    /api/aaa01          1.2586 ( 22.4%) ****
+(Hanami::Router) /api/aaa01          1.3296 ( 21.2%) ****
+(JetRouter)      /api/aaa01/123      1.5861 ( 17.8%) ****
+(Rack::Req+Res)  /api/aaa01/123      1.7369 ( 16.2%) ***
+(Rack::Req+Res)  /api/aaa01          1.7438 ( 16.1%) ***
+(Keight)         /api/aaa01          1.8906 ( 14.9%) ***
+(Keight)         /api/aaa01/123      2.8998 (  9.7%) **
+(Multiplexer)    /api/aaa01/123      2.9166 (  9.7%) **
+(Hanami::Router) /api/aaa01/123      4.0996 (  6.9%) *
+(Sinatra)        /api/aaa01         49.6862 (  0.6%)
+(Sinatra)        /api/aaa01/123     54.3448 (  0.5%)
 ```
 
 * If URL path has no path parameter (such as `/api/hello`),
-  Rack::JetRouter is a litte shower than plain Rack application.
+  JetRouter is significantly fast.
 * If URL path contains path parameter (such as `/api/hello/:id`),
-  Rack::JetRouter becomes slower, but it is enough small (about 6usec/req).
-* Overhead of Rack::JetRouter is smaller than that of Rack::Reqeuast +
+  JetRouter becomes slower, but it is enough small (about 1.3 usec/req).
+* Overhead of JetRouter is smaller than that of Rack::Reqeuast +
   Rack::Response.
-* Hanami is a litte slow.
+* Hanami is slower than JetRouter, but quite enough fast.
 * Sinatra is too slow.
 
 
@@ -60,20 +57,37 @@ Benchmark script is [here](https://github.com/kwatch/rack-jet_router/blob/releas
 
 ```
 ## Ranking                         usec/req  Graph (longer=faster)
-(JetRouter)   /api/aaa01             1.4191 ( 65.6%) *************
-(JetRouter)   /api/zzz26             1.4300 ( 65.1%) *************
-(JetRouter)   /api/aaa01/123         6.0146 ( 15.5%) ***
-(Multiplexer) /api/aaa01             6.1026 ( 15.3%) ***
-(JetRouter)   /api/zzz26/789         6.9102 ( 13.5%) ***
-(Multiplexer) /api/aaa01/123        18.6987 (  5.0%) *
-(Multiplexer) /api/zzz26            30.7618 (  3.0%) *
-(Multiplexer) /api/zzz26/789        42.6660 (  2.2%) 
+(JetRouter)      /api/aaa01          0.2816 (100.0%) ********************
+(JetRouter)      /api/zzz26          0.2823 ( 99.7%) ********************
+(Multiplexer)    /api/aaa01          1.2586 ( 22.4%) ****
+(JetRouter)      /api/aaa01/123      1.5861 ( 17.8%) ****
+(Multiplexer)    /api/aaa01/123      2.9166 (  9.7%) **
+(JetRouter)      /api/zzz26/456      3.5767 (  7.9%) **
+(Multiplexer)    /api/zzz26         14.8423 (  1.9%)
+(Multiplexer)    /api/zzz26/456     16.8930 (  1.7%)
 ```
 
 * JetRouter is about 4~6 times faster than Rack::Multiplexer.
 * Rack::Multiplexer is getting worse in promotion to the number of URL paths.
 
 
+### JetRouter vs. Hanami::Router
+
+```
+## Ranking                         usec/req  Graph (longer=faster)
+(JetRouter)      /api/aaa01          0.2816 (100.0%) ********************
+(JetRouter)      /api/zzz26          0.2823 ( 99.7%) ********************
+(Hanami::Router) /api/zzz26          1.3280 ( 21.2%) ****
+(Hanami::Router) /api/aaa01          1.3296 ( 21.2%) ****
+(JetRouter)      /api/aaa01/123      1.5861 ( 17.8%) ****
+(JetRouter)      /api/zzz26/456      3.5767 (  7.9%) **
+(Hanami::Router) /api/zzz26/456      4.0898 (  6.9%) *
+(Hanami::Router) /api/aaa01/123      4.0996 (  6.9%) *
+```
+
+* Hanami is slower than JetRouter, but it has enough speed.
+
+
 ## Examples
 
 ### #1: Depends only on Request Path
@@ -189,6 +203,69 @@ handler.__send__(action, args)
 ## Topics
 
 
+### Nested Array v.s. Nested Hash
+
+URL path mapping can be not only nested Array but also nested Hash.
+
+```ruby
+## nested Array
+mapping = [
+    ["/api", [
+        ["/books", [
+            [""      , book_list_api],
+            ["/:id"  , book_show_api],
+        ]],
+    ]],
+]
+
+## nested Hash
+mapping = {
+    "/api" => {
+        "/books" => {
+            ""      => book_list_api,
+            "/:id"  => book_show_api,
+        },
+    },
+}
+```
+
+But nested Hash mapping can't include request method mappings, because
+it is hard to distinguish between URL path mapping and request method mapping.
+
+```ruby
+## NOT OK
+mapping = {
+    "/api" => {
+        "/books" => {
+            ""      => {GET: book_list_api, POST: book_create_api},
+            "/:id"  => {GET: book_show_api, PUT: book_update_api},
+        },
+    },
+}
+```
+
+In this case, define subclass of Hash class and use it instead of Hash.
+
+```ruby
+class Map < Hash       # define subclass of Hash class
+end
+
+def Map(**kwargs)      # helper method to create subclass object
+  return Map.new.update(kwargs)
+end
+
+## OK
+mapping = {
+    "/api" => {
+        "/books" => {
+            ""      => Map(GET: book_list_api, POST: book_create_api),
+            "/:id"  => Map(GET: book_show_api, PUT: book_update_api),
+        },
+    },
+}
+```
+
+
 ### URL Path Parameters
 
 In Rack application, URL path parameters (such as `{"id"=>"123"}`) are
@@ -201,13 +278,19 @@ BookApp = proc {|env|
 }
 ```
 
+Key name can be changed by ``env_key:`` keyword argument of ``JetRouter.new()``.
+
+```ruby
+router = Rack::JetRouter.new(mapping, env_key: "rack.urlpath_params")
+```
+
 If you want to tweak URL path parameters, define subclass of Rack::JetRouter
-and override `#build_urlpath_parameter_vars(env, vars)`.
+and override `#build_param_values(names, values)`.
 
 ```ruby
 class MyRouter < JetRouter
 
-  def build_urlpath_parameter_vars(names, values)
+  def build_param_values(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')
@@ -219,7 +302,70 @@ end
 ```
 
 
-### Auto-redirection.
+### Integer Type Parameters
+
+Keyword argument ``int_param:`` of ``JetRouter.new()`` specifies
+parameter name pattern (regexp) to treat as integer type.
+For example, ``int_param: /(?:\A|_)id\z/`` treats ``id`` or ``xxx_id``
+parameter values as integer type.
+
+```ruby
+require 'rack'
+require 'rack/jet_router'
+
+rack_app = proc {|env|
+  params = env['rack.urlpath_params']
+  type = params["book_id"].class
+  text = "params=#{params.inspect}, type=#{type}"
+  [200, {}, [text]]
+}
+
+mapping = [
+  ["/api/books/:book_id", rack_app]
+]
+router = Rack::JetRouter.new(mapping, int_param: /(?:\A|_)id\z/
+
+env = Rack::MockRequest.env_for("/api/books/123")
+tuple = router.call(env)
+puts tuple[2]     #=> params={"book_id"=>123}, type=Integer
+```
+
+Integer type parameters match to only integers.
+
+```ruby
+env = Rack::MockRequest.env_for("/api/books/FooBar")
+tuple = router.call(env)
+puts tuple[2]     #=> 404 Not Found
+```
+
+
+<!--
+
+### URL Path Multiple Extension
+
+It is available to specify multiple extension of URL path.
+
+```ruby
+mapping = {
+    "/api/books" => {
+        "/:id(.html|.json)"  => book_api,
+    },
+}
+```
+
+In above example, the following URL path patterns are enabled.
+
+* ``/api/books/:id``
+* ``/api/books/:id.html``
+* ``/api/books/:id.json``
+
+Notice that ``env['rack.urlpath_params']['format']`` is not set
+because ``:format`` is not specified in URL path pattern.
+
+-->
+
+
+### Auto-redirection
 
 Rack::JetRouter implements auto-redirection.
 
@@ -281,42 +427,6 @@ Above methods are invoked from `Rack::JetRouter#call()`.
 
 ## Copyright and License
 
-$Copyright: copyright(c) 2015-2016 kuwata-lab.com all rights reserved $
+$Copyright: copyright(c) 2015 kwatch@gmail.com $
 
 $License: MIT License $
-
-
-## History
-
-
-### 2016-10-16: Release 1.2.0
-
-* Change auto-redirection to be occurred only on GET or HEAD methods.
-* Code is rewrited, especially around `Rack::JetRouter#compile_mapping()`.
-* Update benchmark script to support `Hanabi::Router`.
-
-
-### 2015-12-29: Release 1.1.1
-
-* Fix benchmark script.
-* Fix document.
-
-
-### 2015-12-28: Release 1.1.0
-
-* **NOTICE** `Rack::JetRouter#find()` is renamed to `#lookup()`.<br>
-  `#find()` is also available for compatibility, but not recommended.
-* Performance improved when number of URL path parameter is 1.
-* Regular expression generated is improved.
-* Benchmark script is improved to take some command-line options.
-* Document fixed.
-
-
-### 2015-12-06: Release 1.0.1
-
-* Fix document
-
-
-### 2015-12-06: Release 1.0.0
-
-* First release

data/bench/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "rack"
+gem "sinatra"
+gem "rack-jet_router"
+gem "rack-multiplexer"
+gem "keight"
+#gem "hanami"
+gem "hanami-router"
+
+gem "benchmarker"

data/bench/Rakefile.rb

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+
+desc "run 'bench.rb' script"
+task :bench, :N do |t, args|
+  n = args[:N] || 1000000
+  ruby "bench.rb", "--N=#{n}"
+  #ruby "bench.rb", "--N=#{n}", "--sinatra=0", "--multiplexer=0"
+  #ruby "bench.rb", "--N=#{n}", "--rack=0", "--jetrouter=0", "--keight=0", "--multiplexer=0", "--sinatra=0", "--hanami=0"
+end