r3/README.md

407 lines
11 KiB
Markdown
Raw Normal View History

2014-05-14 12:18:59 -04:00
R3
2014-05-11 18:52:36 -04:00
================
2014-05-20 04:22:46 -04:00
[![Build Status](https://travis-ci.org/c9s/r3.svg?branch=master)](https://travis-ci.org/c9s/r3)
2014-05-20 11:11:28 -04:00
[![Coverage Status](https://coveralls.io/repos/c9s/r3/badge.png)](https://coveralls.io/r/c9s/r3)
2014-05-16 21:38:21 -04:00
R3 is an URL router library with high performance, thus, it's implemented in C.
2014-05-16 08:11:59 -04:00
It compiles your route paths into a prefix trie.
2014-05-23 22:03:40 -04:00
By using the prefix tree constructed in the start-up time, you can dispatch
the path to the controller with high efficiency.
2014-05-11 18:52:36 -04:00
2014-05-16 08:11:59 -04:00
Requirement
-----------------------
2014-05-23 22:03:40 -04:00
### Build Requirement
2014-05-16 21:38:21 -04:00
* autoconf
* automake
2014-05-16 08:11:59 -04:00
* check
2014-05-23 22:03:40 -04:00
* pkg-config
### Runtime Requirement
2014-05-16 08:11:59 -04:00
* pcre
2014-06-03 06:14:52 -04:00
* (optional) graphviz version 2.38.0 (20140413.2041)
* (optional) libjson-c-dev
2014-05-16 08:11:59 -04:00
2014-05-11 20:24:22 -04:00
Pattern Syntax
-----------------------
/blog/post/{id} use [^/]+ regular expression by default.
/blog/post/{id:\d+} use `\d+` regular expression instead of default.
2014-05-11 18:52:36 -04:00
API
2014-05-16 03:29:25 -04:00
------------------------
```c
2014-06-03 11:51:26 -04:00
#include <r3/r3.h>
2014-05-17 22:29:36 -04:00
2014-05-16 03:29:25 -04:00
// create a router tree with 10 children capacity (this capacity can grow dynamically)
2014-07-29 09:47:58 -04:00
node *n = r3_tree_create(10);
2014-05-16 03:29:25 -04:00
int route_data = 3;
// insert the route path into the router tree
r3_tree_insert_path(n, "/bar", &route_data); // ignore the length of path
2014-05-18 22:34:48 -04:00
2014-05-20 12:47:09 -04:00
r3_tree_insert_pathl(n, "/zoo", strlen("/zoo"), &route_data );
r3_tree_insert_pathl(n, "/foo/bar", strlen("/foo/bar"), &route_data );
2014-05-18 22:34:48 -04:00
2014-05-20 12:47:09 -04:00
r3_tree_insert_pathl(n ,"/post/{id}", strlen("/post/{id}") , &route_data );
2014-05-18 22:34:48 -04:00
2014-05-20 12:47:09 -04:00
r3_tree_insert_pathl(n, "/user/{id:\\d+}", strlen("/user/{id:\\d+}"), &route_data );
2014-05-16 03:29:25 -04:00
2014-06-03 06:17:18 -04:00
2014-06-03 10:37:09 -04:00
// if you want to catch error, you may call the extended path function for insertion
2014-06-03 06:17:18 -04:00
int data = 10;
char *errstr = NULL;
node *ret = r3_tree_insert_pathl_ex(n, "/foo/{name:\\d{5}", strlen("/foo/{name:\\d{5}"), NULL, &data, &errstr);
if (ret == NULL) {
// failed insertion
printf("error: %s\n", errstr);
free(errstr); // errstr is created from `asprintf`, so you have to free it manually.
}
2014-05-16 03:29:25 -04:00
// let's compile the tree!
2014-05-31 14:08:16 -04:00
char *errstr = NULL;
2014-05-31 15:04:59 -04:00
int err = r3_tree_compile(n, &errstr);
2014-06-03 06:19:07 -04:00
if (err != 0) {
// fail
printf("error: %s\n", errstr);
free(errstr); // errstr is created from `asprintf`, so you have to free it manually.
}
2014-05-16 03:29:25 -04:00
// dump the compiled tree
2014-05-16 06:57:36 -04:00
r3_tree_dump(n, 0);
2014-05-16 03:29:25 -04:00
// match a route
2014-05-27 00:32:07 -04:00
node *matched_node = r3_tree_matchl(n, "/foo/bar", strlen("/foo/bar"), NULL);
2014-05-18 22:34:48 -04:00
if (matched_node) {
2014-07-29 09:47:58 -04:00
int ret = *( (int*) matched_node->data );
2014-05-18 22:34:48 -04:00
}
2014-05-18 22:53:47 -04:00
// release the tree
r3_tree_free(n);
2014-05-18 22:34:48 -04:00
```
2014-06-03 08:44:35 -04:00
**Capture Dynamic Variables**
If you want to capture the variables from regular expression, you will need to
create a `match_entry` object and pass the object to `r3_tree_matchl` function,
2014-05-18 22:34:48 -04:00
the catched variables will be pushed into the match entry structure:
```c
match_entry * entry = match_entry_create("/foo/bar");
// free the match entry
match_entry_free(entry);
2014-05-18 22:34:48 -04:00
```
And you can even specify the request method restriction:
```c
entry->request_method = METHOD_GET;
entry->request_method = METHOD_POST;
entry->request_method = METHOD_GET | METHOD_POST;
```
When using `match_entry`, you may match the route with `r3_tree_match_entry` function:
```c
node *matched_node = r3_tree_match_entry(n, entry);
2014-05-16 03:29:25 -04:00
```
2014-06-03 08:44:35 -04:00
**Release Memroy**
To release the memory, you may call `r3_tree_free(node *tree)` to release the whole tree structure,
`node*`, `edge*`, `route*` objects that were inserted into the tree will be freed.
### Routing with conditions
```c
// create a router tree with 10 children capacity (this capacity can grow dynamically)
n = r3_tree_create(10);
int route_data = 3;
2014-05-18 02:14:04 -04:00
// insert the route path into the router tree
2014-05-31 07:56:46 -04:00
r3_tree_insert_routel(n, METHOD_GET | METHOD_POST, "/blog/post", sizeof("/blog/post") - 1, &route_data );
2014-05-31 14:08:16 -04:00
char *errstr = NULL;
2014-06-03 06:19:07 -04:00
int err = r3_tree_compile(n, &errstr);
if (err != 0) {
// fail
printf("error: %s\n", errstr);
free(errstr); // errstr is created from `asprintf`, so you have to free it manually.
}
2014-05-31 07:56:46 -04:00
// in your http server handler
// create the match entry for capturing dynamic variables.
match_entry * entry = match_entry_create("/blog/post");
2014-05-31 07:56:46 -04:00
entry->request_method = METHOD_GET;
2014-05-18 22:34:48 -04:00
route *matched_route = r3_tree_match_route(n, entry);
matched_route->data; // get the data from matched route
// free the objects at the end
match_entry_free(entry);
r3_tree_free(n);
```
2014-05-23 11:15:32 -04:00
Slug
-----------------------
2014-05-23 11:17:58 -04:00
A slug is a placeholder, which captures the string from the URL as a variable.
Slugs will be compiled into regular expression patterns.
2014-05-16 03:29:25 -04:00
2014-05-23 22:03:40 -04:00
Slugs without patterns (like `/user/{userId}`) will be compiled into the `[^/]+` pattern.
2014-05-23 11:15:32 -04:00
To specify the pattern of a slug, you may write a colon to separate the slug name and the pattern:
"/user/{userId:\\d+}"
The above route will use `\d+` as its pattern.
Optimization
2014-05-23 10:46:35 -04:00
-----------------------
2014-05-23 11:20:32 -04:00
Simple regular expressions are optimized through a regexp pattern to opcode
2014-05-23 22:03:40 -04:00
translator, which translates simple patterns into small & fast scanners.
2014-05-23 11:15:32 -04:00
By using this method, r3 reduces the matching overhead of pcre library.
Optimized patterns are: `[a-z]+`, `[0-9]+`, `\d+`, `\w+`, `[^/]+` or `[^-]+`
2014-05-23 22:03:40 -04:00
Slugs without specified regular expression will be compiled into the `[^/]+` pattern. therefore, it's optimized too.
2014-05-23 10:46:35 -04:00
2014-05-23 11:20:32 -04:00
Complex regular expressions will still use libpcre to match URL (partially).
2014-05-23 10:46:35 -04:00
2014-05-11 18:52:36 -04:00
2014-05-23 10:46:35 -04:00
Performance
2014-05-16 07:17:59 -04:00
-----------------------
The routing benchmark from stevegraham/rails' PR <https://github.com/stevegraham/rails/pull/1>:
omg 10462.0 (±6.7%) i/s - 52417 in 5.030416s
And here is the result of the router journey:
omg 9932.9 (±4.8%) i/s - 49873 in 5.033452s
r3 uses the same route path data for benchmarking, and here is the benchmark:
2014-05-16 21:41:00 -04:00
3 runs, 5000000 iterations each run, finished in 1.308894 seconds
11460057.83 i/sec
2014-05-16 07:17:59 -04:00
2014-06-04 02:54:42 -04:00
### The Route Paths Of Benchmark
2014-05-16 07:18:47 -04:00
The route path generator is from <https://github.com/stevegraham/rails/pull/1>:
```ruby
#!/usr/bin/env ruby
arr = ["foo", "bar", "baz", "qux", "quux", "corge", "grault", "garply"]
paths = arr.permutation(3).map { |a| "/#{a.join '/'}" }
paths.each do |path|
puts "r3_tree_insert_path(n, \"#{path}\", NULL);"
end
```
2014-05-23 11:15:32 -04:00
Function prefix mapping
-----------------------
|Function Prefix |Description |
|------------------|------------------------------------------------------------------------------------|
|`r3_tree_*` |Tree related operations, which require a node to operate a whole tree |
|`r3_node_*` |Single node related operations, which do not go through its own children or parent. |
|`r3_edge_*` |Edge related operations |
|`r3_route_*` |Route related operations, which are needed only when the tree is defined by routes |
|`match_entry_*` |Match entry related operations, a `match_entry` is just like the request parameters |
2014-05-16 07:18:47 -04:00
2014-06-03 06:52:40 -04:00
Rendering Routes With Graphviz
2014-06-03 06:14:52 -04:00
---------------------------------------
The `r3_tree_render_file` API let you render the whole route trie into a image.
To use graphviz, you need to enable graphviz while you run `configure`:
./configure --enable-graphviz
Here is the sample code of generating graph output:
```c
node * n = r3_tree_create(1);
r3_tree_insert_path(n, "/foo/bar/baz", NULL);
r3_tree_insert_path(n, "/foo/bar/qux", NULL);
r3_tree_insert_path(n, "/foo/bar/quux", NULL);
r3_tree_insert_path(n, "/foo/bar/corge", NULL);
r3_tree_insert_path(n, "/foo/bar/grault", NULL);
r3_tree_insert_path(n, "/garply/grault/foo", NULL);
r3_tree_insert_path(n, "/garply/grault/bar", NULL);
r3_tree_insert_path(n, "/user/{id}", NULL);
r3_tree_insert_path(n, "/post/{title:\\w+}", NULL);
char *errstr = NULL;
2014-06-03 06:19:07 -04:00
int err;
err = r3_tree_compile(n, &errstr);
if (err != 0) {
// fail
printf("error: %s\n", errstr);
free(errstr); // errstr is created from `asprintf`, so you have to free it manually.
}
2014-06-03 06:14:52 -04:00
r3_tree_render_file(n, "png", "check_gvc.png");
r3_tree_free(n);
```
2014-05-17 20:19:32 -04:00
2014-06-27 13:25:29 -04:00
![Imgur](http://imgur.com/HrUoEbI.png)
2014-06-01 08:30:22 -04:00
2014-05-17 20:19:32 -04:00
Or you can even export it with dot format:
```dot
digraph g {
graph [bb="0,0,205.1,471"];
node [label="\N"];
"{root}" [height=0.5,
pos="35.097,453",
width=0.97491];
"#1" [height=0.5,
pos="35.097,366",
width=0.75];
....
```
2014-06-03 06:42:47 -04:00
### Graphviz Related Functions
```c
int r3_tree_render_file(const node * tree, const char * format, const char * filename);
int r3_tree_render(const node * tree, const char *layout, const char * format, FILE *fp);
int r3_tree_render_dot(const node * tree, const char *layout, FILE *fp);
int r3_tree_render_file(const node * tree, const char * format, const char * filename);
```
2014-06-03 06:52:40 -04:00
JSON Output
2014-06-03 06:14:52 -04:00
----------------------------------------
You can render the whole tree structure into json format output.
Please run `configure` with the `--enable-json` option.
Here is the sample code to generate JSON string:
```c
json_object * obj = r3_node_to_json_object(n);
const char *json = r3_node_to_json_pretty_string(n);
printf("Pretty JSON: %s\n",json);
const char *json = r3_node_to_json_string(n);
printf("JSON: %s\n",json);
```
2014-05-11 18:52:36 -04:00
Use case in PHP
-----------------------
2014-05-23 10:46:35 -04:00
**not implemented yet**
2014-05-11 18:52:36 -04:00
```php
// Here is the paths data structure
$paths = [
2014-05-13 04:13:20 -04:00
'/blog/post/{id}' => [ 'controller' => 'PostController' , 'action' => 'item' , 'method' => 'GET' ] ,
'/blog/post' => [ 'controller' => 'PostController' , 'action' => 'list' , 'method' => 'GET' ] ,
'/blog/post' => [ 'controller' => 'PostController' , 'action' => 'create' , 'method' => 'POST' ] ,
'/blog' => [ 'controller' => 'BlogController' , 'action' => 'list' , 'method' => 'GET' ] ,
2014-05-11 18:52:36 -04:00
];
2014-05-16 07:13:24 -04:00
$rs = r3_compile($paths, 'persisten-table-id');
$ret = r3_dispatch($rs, '/blog/post/3' );
2014-05-11 18:52:36 -04:00
list($complete, $route, $variables) = $ret;
2014-05-16 07:13:24 -04:00
// matched conditions aren't done yet
list($error, $message) = r3_validate($route); // validate route conditions
2014-05-11 18:52:36 -04:00
if ( $error ) {
echo $message; // "Method not allowed", "...";
}
```
2014-05-16 08:35:16 -04:00
Install
2014-05-16 08:11:59 -04:00
----------------------
2014-05-18 23:45:39 -04:00
sudo apt-get install check libpcre3 libpcre3-dev libjemalloc-dev libjemalloc1 build-essential libtool automake autoconf pkg-config
sudo apt-get install graphviz-dev graphviz # if you want graphviz
2014-05-16 21:38:21 -04:00
./autogen.sh
2014-05-17 03:33:12 -04:00
./configure && make
2014-05-16 08:35:16 -04:00
sudo make install
2014-05-16 08:11:59 -04:00
And we support debian-based distro now!
sudo apt-get install build-essential autoconf automake libpcre3-dev pkg-config debhelper libtool check
mv dist-debian debian
dpkg-buildpackage -b -us -uc
sudo gdebi ../libr3*.deb
2014-05-24 04:28:53 -04:00
#### Run Unit Tests
./configure --enable-check
make check
2014-05-21 23:59:45 -04:00
#### Enable Graphviz
2014-05-16 21:38:21 -04:00
2014-05-17 21:31:08 -04:00
./configure --enable-graphviz
2014-05-16 21:38:21 -04:00
2014-05-21 23:59:45 -04:00
#### With jemalloc
./configure --with-malloc=jemalloc
2014-05-16 21:38:21 -04:00
2014-06-18 11:48:17 -04:00
ubuntu PPA
----------------------
The PPA for libr3 can be found in <https://launchpad.net/~r3-team/+archive/libr3-daily>.
2014-05-17 22:28:19 -04:00
2014-06-04 02:57:34 -04:00
Binding For Other Languages
---------------------------
2014-06-07 07:03:23 -04:00
* Perl Router::R3 by @CindyLinz <https://metacpan.org/pod/Router::R3>
* Python pyr3 by @lucemia <https://github.com/lucemia/pyr3>
* Python pyr3 by @thedrow <https://github.com/thedrow/pyr3>
* Haskell r3 by @MnO2 <https://github.com/MnO2/r3>
* Vala r3-vala by @Ronmi <https://github.com/Ronmi/r3-vala>
* Node.js node-r3 by @othree <https://github.com/othree/node-r3>
* Node.js node-libr3 by @caasi <https://github.com/caasi/node-r3>
2014-07-29 17:28:33 -04:00
* Ruby rr3 by @tonytonyjan <https://github.com/tonytonyjan/rr3>
2014-06-04 02:57:34 -04:00
2014-05-17 22:28:19 -04:00
License
--------------------
This software is released under MIT License.