Skip to content

Commit e620c83

Browse files
author
Sergio Andres Virviescas Santana
committed
Squashed commit of the following:
commit 9d75223df8f161a17a74a92fcff42a34bc4387bf Author: Sergio Andres Virviescas Santana <[email protected]> Date: Sun Mar 8 18:36:23 2020 +0100 Uddate README of examples commit 6bfedb6a9cc4634a6f56be54b0785f8806a2e3cb Author: Sergio Andres Virviescas Santana <[email protected]> Date: Sun Mar 8 18:34:10 2020 +0100 Update README commit a77a142578e14a6e7b129f0f1e6bd29e56ec1ee8 Author: Sergio Andres Virviescas Santana <[email protected]> Date: Sun Mar 8 17:57:12 2020 +0100 Add docs and fixes commit 45fb922f61ae0cb3b7f1095f43462c6ba20a53ff Author: Sergio Andres Virviescas Santana <[email protected]> Date: Sat Mar 7 20:53:40 2020 +0100 New radix tree with more flexibility without lose performance
1 parent 80dc8ef commit e620c83

File tree

13 files changed

+1100
-850
lines changed

13 files changed

+1100
-850
lines changed

.travis.yml

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
language: go
22

3+
sudo: false
34
go:
45
- 1.9.x
56
- 1.10.x
67
- 1.11.x
78
- 1.12.x
89
- 1.13.x
10+
- 1.14.x
911
- tip
1012

1113
os:
@@ -18,7 +20,10 @@ matrix:
1820
fast_finish: true
1921

2022
before_install:
23+
- go get -u -v golang.org/x/tools/cmd/cover
24+
- go get -u -v github.com/modocache/gover
2125
- go get -u -v github.com/mattn/goveralls
26+
- go get -v ./...
2227

2328
script:
2429
# build test for supported platforms
@@ -28,7 +33,13 @@ script:
2833
- GOOS=windows go build
2934
- GOARCH=386 go build
3035

31-
# run tests with the race detector
32-
- go test -v -race
36+
# run tests
37+
- |
38+
pkgs=($(go list ./... | grep -v examples | tr '\n' ' '))
39+
for i in "${!pkgs[@]}"; do
40+
go test -v -cover -race -coverprofile=$i.coverprofile ${pkgs[i]}
41+
done
3342
34-
- $GOPATH/bin/goveralls -v -service=travis-ci -package github.com/fasthttp/router
43+
# send coverage
44+
- $HOME/gopath/bin/gover
45+
- $HOME/gopath/bin/goveralls -coverprofile=gover.coverprofile -service=travis-ci

README.md

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,20 @@
11
# Router
2+
23
[![Build Status](https://travis-ci.org/fasthttp/router.svg?branch=master)](https://travis-ci.org/fasthttp/router)
34
[![Coverage Status](https://coveralls.io/repos/fasthttp/router/badge.svg?branch=master&service=github)](https://coveralls.io/github/fasthttp/router?branch=master)
45
[![Go Report Card](https://goreportcard.com/badge/github.com/fasthttp/router)](https://goreportcard.com/report/github.com/fasthttp/router)
56
[![GoDoc](http://godoc.org/github.com/fasthttp/router?status.svg)](http://godoc.org/github.com/fasthttp/router)
67
[![GitHub release](https://img.shields.io/github/release/fasthttp/router.svg)](https://github.com/fasthttp/router/releases)
78

8-
Router is forked from [httprouter](https://github.com/julienschmidt/httprouter) which is a lightweight high performance HTTP request router
9-
(also called *multiplexer* or just *mux* for short) for [fasthttp](https://github.com/valyala/fasthttp).
9+
Router is a lightweight high performance HTTP request router (also called _multiplexer_ or just _mux_ for short) for [fasthttp](https://github.com/valyala/fasthttp).
1010

1111
This router is optimized for high performance and a small memory footprint. It scales well even with very long paths and a large number of routes. A compressing dynamic trie (radix tree) structure is used for efficient matching.
1212

1313
#### License Related
1414

15+
- This repo is based on [httprouter](https://github.com/julienschmidt/httprouter).
1516
- The author of `httprouter` [@julienschmidt](https://github.com/julienschmidt) did almost all the hard work of this router.
16-
- The author of `fasthttprouter` [@buaazp](https://github.com/buaazp) did all the hard work by porting `httprouter` to fasthttp.
17-
- We ([@buaazp](https://github.com/buaazp) and fasthttp ecosystem team) respect the laws of open source. So LICENSE of `httprouter` is alway stay here: [HttpRouterLicense](HttpRouterLicense).
18-
- What [@buaazp](https://github.com/buaazp) have done is just fit for `fasthttp`. I have no hope to build a huge but toxic go web framwork like [iris](https://github.com/kataras/iris).
19-
- [@buaazp](https://github.com/buaazp) forked `fasthttp` repo is just because there is no router for `fasthttp` at that time. And `fasthttprouter` is the FIRST router for `fasthttp`.
20-
- `fasthttprouter` has been used in huge production environments and processes hundreds of millions requests per day. It is fast and stable, so [@buaazp](https://github.com/buaazp) decide to release a stable version.
21-
- This repo is based on `fasthttprouter` and maintained by official fasthttp ecosystem team. We trying to optimize it even more and check if it works well when we update something huge in fasthttp.
22-
17+
- We (fasthttp ecosystem team) respect the laws of open source. So LICENSE of `httprouter` is alway stay here: [HttpRouterLicense](HttpRouterLicense).
2318

2419
## Features
2520

@@ -31,16 +26,16 @@ This router is optimized for high performance and a small memory footprint. It s
3126

3227
- Concurrency Test (allocations): In 30 ms processing time, the tets result for 100, 1000, 5000 clients is:
3328

34-
\* *Smaller is better*
29+
\* _Smaller is better_
3530

3631
![](https://raw.githubusercontent.com/smallnest/go-web-framework-benchmark/master/concurrency_alloc.png)
3732

3833
See below for technical details of the implementation.
3934

4035
**Only explicit matches:** With other routers, like [http.ServeMux](http://golang.org/pkg/net/http/#ServeMux),
4136
a requested URL path could match multiple patterns. Therefore they have some
42-
awkward pattern priority rules, like *longest match* or *first registered,
43-
first matched*. By design of this router, a request can only match exactly one
37+
awkward pattern priority rules, like _longest match_ or _first registered,
38+
first matched_. By design of this router, a request can only match exactly one
4439
or no route. As a result, there are also no unintended matches, which makes it
4540
great for SEO and improves the user experience.
4641

@@ -73,7 +68,7 @@ PanicHandler log what happened and deliver a nice error page.
7368
RESTful APIs. Moreover it has builtin native support for [OPTIONS requests](http://zacstewart.com/2012/04/14/http-options-method.html)
7469
and `405 Method Not Allowed` replies.
7570

76-
Of course you can also set **custom [NotFound](http://godoc.org/github.com/fasthttp/router#Router.NotFound) and [MethodNotAllowed](http://godoc.org/github.com/fasthttp/router#Router.MethodNotAllowed) handlers** and [**serve static files**](http://godoc.org/github.com/fasthttp/router#Router.ServeFiles).
71+
Of course you can also set **custom [NotFound](http://godoc.org/github.com/fasthttp/router#Router.NotFound) and [MethodNotAllowed](http://godoc.org/github.com/fasthttp/router#Router.MethodNotAllowed) handlers** and [**serve static files**](http://godoc.org/github.com/fasthttp/router#Router.ServeFiles).
7772

7873
## Usage
7974

@@ -111,7 +106,7 @@ func main() {
111106

112107
### Named parameters
113108

114-
As you can see, `:name` is a *named parameter*. The values are accessible via `RequestCtx.UserValues`. You can get the value of a parameter by using the `ctx.UserValue("name")`.
109+
As you can see, `:name` is a _named parameter_. The values are accessible via `RequestCtx.UserValues`. You can get the value of a parameter by using the `ctx.UserValue("name")`.
115110

116111
Named parameters only match a single path segment:
117112

@@ -127,11 +122,12 @@ Pattern: /user/:user
127122
**Note:** Since this router has only explicit matches, you can not register static routes and parameters for the same path segment. For example you can not register the patterns `/user/new` and `/user/:user` for the same request method at the same time. The routing of different request methods is independent from each other.
128123

129124
#### Optional parameters
125+
130126
If you need define an optional parameters, add `?` at the end of param name. `:name?`
131127

132128
### Catch-All parameters
133129

134-
The second type are *catch-all* parameters and have the form `*name`.
130+
The second type are _catch-all_ parameters and have the form `*name`.
135131
Like the name suggests, they match everything.
136132
Therefore they must always be at the **end** of the pattern:
137133

@@ -145,7 +141,7 @@ Pattern: /src/*filepath
145141

146142
## How does it work?
147143

148-
The router relies on a tree structure which makes heavy use of *common prefixes*, it is basically a *compact* [*prefix tree*](https://en.wikipedia.org/wiki/Trie) (or just [*Radix tree*](https://en.wikipedia.org/wiki/Radix_tree)). Nodes with a common prefix also share a common parent. Here is a short example what the routing tree for the `GET` request method could look like:
144+
The router relies on a tree structure which makes heavy use of _common prefixes_, it is basically a _compact_ [_prefix tree_](https://en.wikipedia.org/wiki/Trie) (or just [_Radix tree_](https://en.wikipedia.org/wiki/Radix_tree)). Nodes with a common prefix also share a common parent. Here is a short example what the routing tree for the `GET` request method could look like:
149145

150146
```
151147
Priority Path Handle
@@ -161,7 +157,7 @@ Priority Path Handle
161157
1 └contact\ *<8>
162158
```
163159

164-
Every `*<num>` represents the memory address of a handler function (a pointer). If you follow a path trough the tree from the root to the leaf, you get the complete route path, e.g `\blog\:post\`, where `:post` is just a placeholder ([*parameter*](#named-parameters)) for an actual post name. Unlike hash-maps, a tree structure also allows us to use dynamic parts like the `:post` parameter, since we actually match against the routing patterns instead of just comparing hashes. [As benchmarks show][benchmark], this works very well and efficient.
160+
Every `*<num>` represents the memory address of a handler function (a pointer). If you follow a path trough the tree from the root to the leaf, you get the complete route path, e.g `\blog\:post\`, where `:post` is just a placeholder ([_parameter_](#named-parameters)) for an actual post name. Unlike hash-maps, a tree structure also allows us to use dynamic parts like the `:post` parameter, since we actually match against the routing patterns instead of just comparing hashes. [As benchmarks show][benchmark], this works very well and efficient.
165161

166162
Since URL paths have a hierarchical structure and make use only of a limited set of characters (byte values), it is very likely that there are a lot of common prefixes. This allows us to easily reduce the routing into ever smaller problems. Moreover the router manages a separate tree for every request method. For one thing it is more space efficient than holding a method->handle map in every single node, for another thing is also allows us to greatly reduce the routing problem before even starting the look-up in the prefix-tree.
167163

@@ -188,7 +184,7 @@ Fasthttp works with [RequestHandler](https://godoc.org/github.com/valyala/fastht
188184

189185
Just try it out for yourself, the usage of Router is very straightforward. The package is compact and minimalistic, but also probably one of the easiest routers to set up.
190186

191-
## Where can I find Middleware *X*?
187+
## Where can I find Middleware _X_?
192188

193189
This package just provides a very efficient request router with a few extra features. The router is just a [`fasthttp.RequestHandler`](https://godoc.org/github.com/valyala/fasthttp#RequestHandler), you can chain any `fasthttp.RequestHandler` compatible middleware before the router. Or you could [just write your own](https://justinas.org/writing-http-middleware-in-go/), it's very easy!
194190

@@ -204,6 +200,7 @@ Have a look at these middleware examples:
204200
You can use another [http.Handler](http://golang.org/pkg/net/http/#Handler), for example another router, to handle requests which could not be matched by this router by using the [Router.NotFound](http://godoc.org/github.com/fasthttp/router#Router.NotFound) handler. This allows chaining.
205201

206202
### Static files
203+
207204
The `NotFound` handler can for example be used to serve static files from the root path `/` (like an index.html file along with other assets):
208205

209206
```go

examples/auth/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Example of FastHttpRouter
1+
# Example of Router
22

33
These examples show you the usage of `router`. You can easily build a web application with it. Or you can make your own midwares such as custom logger, metrics, or any one you want.
44

examples/basic/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Example of FastHttpRouter
1+
# Example of Router
22

33
These examples show you the usage of `router`. You can easily build a web application with it. Or you can make your own midwares such as custom logger, metrics, or any one you want.
44

examples/hosts/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Example of FastHttpRouter
1+
# Example of Router
22

33
These examples show you the usage of `router`. You can easily build a web application with it. Or you can make your own midwares such as custom logger, metrics, or any one you want.
44

0 commit comments

Comments
 (0)