rack-jet_router 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c763fbc224d9c9c21718bf685203b35694c20f3b
-  data.tar.gz: 56bc71a1d83180f2970f1d95985fc8b2fa9b91bc
+SHA256:
+  metadata.gz: ffb2322f3ac227a3d07fa95c120d25c3dcb8763f9ea925be7a3a03df11c00ba9
+  data.tar.gz: 60b292dd4a1307a2fd1cbfcb474746131599fe0ba0ae93768b40f2cf0c9e5fa5
 SHA512:
-  metadata.gz: b72f539eb7750a754daea1189aa0035e8010a93d7debf74ef7f6a4b927223daf19f4bfbf0165192aab08c0e395289fabc423ee4690e6ab0ff0417603185334f1
-  data.tar.gz: 565dcf52b9c34e81803474de3c212f2b2b92d543a85057f3ab7959764f724b1ea2a5dc07c11caa4aca06a79aa318410000dabb98001ef4e0cbad4aaaa711fe11
+  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,39 +1,55 @@
 # Rack::JetRouter
 
-($Release: 1.1.1 $)
+($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
 
-Benchmark script is [here](https://github.com/kwatch/rack-jet_router/blob/dev/bench/bench.rb).
+Benchmark script is [here](https://github.com/kwatch/rack-jet_router/blob/release/bench/bench.rb).
 
-### JetRouter vs. Rack vs. Sinatra vs. Keight.rb:
+| Name               | Version |
+| ------------------ | ------- |
+| Ruby               | 3.2.2   |
+| Rack               | 2.2.8   |
+| Rack::JetRouter    | 1.3.0   |
+| Rack::Multiplexer  | 0.0.8   |
+| Sinatra            | 3.1.0   |
+| Keight.rb          | 1.0.0   |
+| Hanami::Router     | 2.0.2   |
+
+(Macbook Pro, Apple M1 Pro, macOS Ventura 13.6.2)
+
+
+### JetRouter vs. Rack vs. Sinatra vs. Keight.rb vs. Hanami:
 
 ```
 ## Ranking                         usec/req  Graph (longer=faster)
-(Rack plain)  /api/aaa01             1.0619  ***************
-(Rack plain)  /api/aaa01/123         0.8729  ******************
-(R::Req+Res)  /api/aaa01             9.5361  **
-(R::Req+Res)  /api/aaa01/123         9.5321  **
-(JetRouter)   /api/aaa01             1.3231  ************
-(JetRouter)   /api/aaa01/123         5.9796  ***
-(Keight.rb)   /api/aaa01             6.4314  **
-(Keight.rb)   /api/aaa01/123        10.2339  **
-(Sinatra)     /api/aaa01           104.7575
-(Sinatra)     /api/aaa01/123       115.8220
+(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 slower than JetRouter, but quite enough fast.
 * Sinatra is too slow.
 
 
@@ -41,17 +57,35 @@ Benchmark script is [here](https://github.com/kwatch/rack-jet_router/blob/dev/be
 
 ```
 ## Ranking                         usec/req  Graph (longer=faster)
-(JetRouter)   /api/aaa01             1.3231  ************
-(JetRouter)   /api/aaa01/123         5.9796  ***
-(JetRouter)   /api/zzz26             1.4089  ***********
-(JetRouter)   /api/zzz26/789         6.5142  **
-(Multiplexer) /api/aaa01             5.9073  ***
-(Multiplexer) /api/aaa01/123        18.2102  *
-(Multiplexer) /api/zzz26            24.4013  *
-(Multiplexer) /api/zzz26/789        36.1558
+(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 3~5 times faster than Rack::Multiplexer.
+* 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
@@ -169,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
@@ -181,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')
@@ -199,6 +302,81 @@ end
 ```
 
 
+### 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.
+
+* When `/foo` is provided and `/foo/` is requested, then Rack::JetRouter redirects to `/foo` automatically.
+* When `/foo/` is provided and `/foo` is requested, then Rack::JetRouter redirects to `/foo/` automatically.
+
+Notice that auto-redirection is occurred only on `GET` or `HEAD` methods, because
+browser cannot handle redirection on `POST`, `PUT`, and `DELETE` methods correctly.
+Don't depend on auto-redirection feature so much.
+
+
 ### Variable URL Path Cache
 
 It is useful to classify URL path patterns into two types: fixed and variable.
@@ -249,29 +427,6 @@ Above methods are invoked from `Rack::JetRouter#call()`.
 
 ## Copyright and License
 
-$Copyright: copyright(c) 2015 kuwata-lab.com all rights reserved $
+$Copyright: copyright(c) 2015 kwatch@gmail.com $
 
 $License: MIT License $
-
-
-## History
-
-
-### 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