Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/iresty/lua-resty-libr3
High-performance path dispatching library base on libr3 for OpenResty
https://github.com/iresty/lua-resty-libr3
Last synced: 3 months ago
JSON representation
High-performance path dispatching library base on libr3 for OpenResty
- Host: GitHub
- URL: https://github.com/iresty/lua-resty-libr3
- Owner: iresty
- License: apache-2.0
- Created: 2019-02-22T12:23:57.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-06-21T04:14:11.000Z (over 3 years ago)
- Last Synced: 2024-04-17T17:08:49.708Z (7 months ago)
- Language: Perl
- Homepage:
- Size: 521 KB
- Stars: 57
- Watchers: 5
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-resty - lua-resty-libr3 - performance path dispatching library base on [libr3](https://github.com/c9s/r3) for OpenResty (Libraries)
README
Name
====
This is Lua-Openresty implementation library base on FFI for [libr3](https://github.com/c9s/r3).
*NOTICE:*
The Apache APISIX has changed the router to [lua-resty-radixtree](https://github.com/api7/lua-resty-radixtree), which is better than this library. It is highly recommended that you use the new routing implementation.
[](https://travis-ci.org/iresty/lua-resty-libr3)
[](https://github.com/iresty/lua-resty-libr3/blob/master/LICENSE)
Table of Contents
=================
* [Name](#name)
* [Status](#status)
* [Synopsis](#synopsis)
* [Methods](#methods)
* [new](#new)
* [insert_route](#insert_route)
* [add router](#add-router)
* [compile](#compile)
* [dispatch](#dispatch)
* [dispatch2](#dispatch2)
* [Install](#install)
Status
======
**This repository is an experimental.**
Synopsis
========
```lua
location / {
content_by_lua_block {
-- r3 router
local r3 = require("resty.r3").new();
local encode_json = require("cjson.safe").encode
function foo(params) -- foo handler
ngx.say("foo: ", encode_json(params))
end
-- routing
r3:get("/foo/{id}/{name}", foo)
-- don't forget!!!
r3:compile()
-- dispatch
local ok = r3:dispatch("/foo/a/b", ngx.req.get_method())
if not ok then
ngx.exit(404)
end
}
}
```
[Back to TOC](#table-of-contents)
Methods
=======
new
---
`syntax: r3, err = r3router:new()`
Creates a r3 object. In case of failures, returns `nil` and a string describing the error.
`syntax: r3, err = r3router:new(routes)`
The routes is a array table, like `{ {...}, {...}, {...} }`, Each element in the array is a route, which is a hash table.
The attributes of each element may contain these:
* `path`: client request uri.
* `handler`: Lua callback function.
* `host`: optional, client request host, not only supports normal domain name, but also supports wildcard name, both `foo.com` and `*.foo.com` are valid.
* `remote_addr`: optional, client remote address like `192.168.1.100`, and we can use CIDR format, eg `192.168.1.0/24`.
* `methods`: optional, It's an array table, we can put one or more method names together. Here is the valid method name: "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS".
Example:
```lua
-- foo handler
function foo(params)
ngx.say("foo: ", require("cjson").encode(params))
end
local r3route = require "resty.r3"
local r3 = r3route.new({
{
path = [[/foo/{:\w+}/{:\w+}"]],
method = {"GET"},
handler = foo
},
{
path = [[/bar/{:\w+}/{:\w+}]],
host = "*.bar.com",
handler = foo
},
{
path = [[/alice/{:\w+}/{:\w+}]],
remote_addr = "192.168.1.0/24",
handler = foo
},
{
path = [[/bob/{:\w+}/{:\w+}]],
method = {"GET"},
host = "*.bob.com",
remote_addr = "192.168.1.0/24",
handler = foo
},
})
```
[Back to TOC](#table-of-contents)
insert_route
------------
`syntax: r3, err = r3:insert_route(path, callback, opts)`
* `path`: Client request uri.
* `callback`: Lua callback function.
`opts` is optional argument, it is a Lua table.
* `method`: It's an array table, we can put one or more method names together.
* `host`: optional, client request host, not only supports normal domain name, but also supports wildcard name, both `foo.com` and `*.foo.com` are valid.
* `remote_addr`: optional, client remote address like `192.168.1.100`, and we can use CIDR format, eg `192.168.1.0/24`.
```lua
-- route
local function foo(params)
ngx.say("foo")
end
local r3route = require "resty.r3"
local r3 = r3route.new()
r3:insert_route("/a", foo)
r3:insert_route("/b", foo, {method = {"GET"}})
```
add router
----------
BTW, we can add a router by specifying a lowercase method name.
Valid method name list: `get`, `post`, `put`, `delete`, `patch`, `head`, `options`.
```lua
-- route
local function foo(params)
ngx.say("foo")
end
r3:get("/a", foo)
r3:post("/b", foo)
r3:put("/c", foo)
r3:delete("/d", foo)
```
[Back to TOC](#table-of-contents)
compile
-------
`syntax: r3:compile()`
It compiles our route paths into a prefix tree (trie). You must compile after adding all routes, otherwise it may fail to match.
[Back to TOC](#table-of-contents)
dispatch
--------
`syntax: ok = r3:dispatch(path, method)`
* `path`: client request uri.
* `method`: method name of client request.
`syntax: ok = r3:dispatch(path, opts)`
* `path`: client request uri.
* `opts`: a Lua tale
* `method`: optional, method name of client request.
* `host`: optional, client request host, not only supports normal domain name, but also supports wildcard name, both `foo.com` and `*.foo.com` are valid.
* `remote_addr`: optional, client remote address like `192.168.1.100`, and we can use CIDR format, eg `192.168.1.0/24`.
Dispatchs the path to the controller by `method`, `path` and `host`.
```lua
local ok = r3:dispatch(ngx.var.uri, ngx.req.get_method())
```
[Back to TOC](#table-of-contents)
dispatch2
---------
`syntax: ok = r3:dispatch2(param_tab, path, method)`
`syntax: ok = r3:dispatch2(param_tab, path, opts)`
Basically the same as `dispatch`, support for passing in a `table` object to
store parsing parameters, makes it easier to reuse lua table.
[Back to TOC](#table-of-contents)
Install
=======
### Dependent library
```shell
# Ubuntu
sudo apt-get install check libpcre3 libpcre3-dev build-essential libtool \
automake autoconf pkg-config
# CentOS 7
sodu yum install gcc gcc-c++ git make automake autoconf pcre pcre-devel \
libtool pkgconfig
```
### Compile and install
```
sudo make install
```