README
¶
Fox
Fox is a lightweight high performance HTTP request router for Go. The main difference with other routers is that it supports mutation on its routing tree while handling request concurrently. Internally, Fox use a Concurrent Radix Tree that support lock-free reads while allowing concurrent writes.
The router tree is optimized for high-concurrency and high performance reads, and low-concurrency write. Fox has a small memory footprint, and in many case, it does not do a single heap allocation while handling request.
Fox supports various use cases, but it is especially designed for applications that require changes at runtime to their routing structure based on user input, configuration changes, or other runtime events.
Disclaimer
The current api is not yet stabilize. Breaking changes may occur before v1.0.0 and will be noted on the release note.
Features
Routing mutation: Register, update and remove route handler safely at any time without impact on performance. Fox never block while serving request!
Wildcard pattern: Route can be registered using wildcard parameters. The matched path segment can then be easily retrieved by name. Due to Fox design, wildcard route are cheap and scale really well.
Detect panic: You can register a fallback handler that is fire in case of panics occurring during handling an HTTP request.
Get the current route: You can easily retrieve the route of the matched request. This actually makes it easier to integrate observability middleware like open telemetry (disable by default).
Only explicit matches: Inspired from httprouter, a request can only match exactly one or no route. As a result there are no unintended matches, and it also encourages good RESTful api design.
Redirect trailing slashes: Inspired from httprouter, the router automatically redirects the client, at no extra cost, if another route match with or without a trailing slash (disable by default).
Path auto-correction: Inspired from httprouter, the router can remove superfluous path
elements like ../ or // and automatically redirect the client if the cleaned path match a handler (disable by default).
Of course, you can also register custom NotFound and MethodNotAllowed handlers.
Getting started
Installation
go get -u github.com/tigerwill90/fox
Basic example
package main
import (
"fmt"
"github.com/tigerwill90/fox"
"log"
"net/http"
)
var WelcomeHandler = fox.HandlerFunc(func(w http.ResponseWriter, r *http.Request, params fox.Params) {
_, _ = fmt.Fprint(w, "Welcome!\n")
})
type HelloHandler struct{}
func (h *HelloHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, params fox.Params) {
_, _ = fmt.Fprintf(w, "Hello %s\n", params.Get("name"))
}
func main() {
r := fox.New()
Must(r.Handler(http.MethodGet, "/", WelcomeHandler))
Must(r.Handler(http.MethodGet, "/hello/:name", new(HelloHandler)))
log.Fatalln(http.ListenAndServe(":8080", r))
}
func Must(err error) {
if err != nil {
panic(err)
}
}
Error handling
Since new route may be added at any given time, Fox, unlike other router, does not panic when a route is malformed or conflicts with another. Instead, it returns the following error values
ErrRouteExist = errors.New("route already registered")
ErrRouteConflict = errors.New("route conflict")
ErrInvalidRoute = errors.New("invalid route")
Conflict error may be unwrapped to retrieve conflicting route.
if errors.Is(err, fox.ErrRouteConflict) {
matched := err.(*fox.RouteConflictError).Matched
for _, route := range matched {
fmt.Println(route)
}
}
Named parameters
A route can be defined using placeholder (e.g :name). The values are accessible via fox.Params, which is just a slice of fox.Param.
The Get method is a helper to retrieve the value using the placeholder name.
Pattern /avengers/:name
/avengers/ironman match
/avengers/thor match
/avengers/hulk/angry no match
/avengers/ no match
Pattern /users/uuid_:id
/users/uuid_xyz match
/users/uuid no match
Catch all parameter
Catch-all parameters can be used to match everything at the end of a route. The placeholder start with * followed by a name.
Pattern /src/*filepath
/src/ match
/src/conf.txt match
/src/dir/config.txt match
Warning about params slice
fox.Params slice is freed once ServeHTTP returns and may be reused later to save resource. Therefore, if you need to hold fox.Params
longer, use the Clone methods.
func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, params fox.Params) {
p := params.Clone()
go func(){
time.Sleep(1 * time.Second)
log.Println(p.Get("name")) // Safe
}()
_, _ = fmt.Fprintf(w, "Hello %s\n", params.Get("name"))
}
Concurrency
Fox implements a Concurrent Radix Tree that supports lock-free reads while allowing concurrent writes, by calculating the changes which would be made to the tree were it mutable, and assembling those changes into a patch, which is then applied to the tree in a single atomic operation.
For example, here we are inserting the new key toast into to the tree which require an existing node to be split:
When traversing the tree during a patch, reading threads will either see the old version or the new version of the (sub-)tree, but both version are consistent view of the tree.
Other key points
- Routing requests is lock-free (reading thread never block, even while writes are ongoing)
- The router always see a consistent version of the tree while routing request
- Reading threads do not block writing threads (adding, updating or removing a handler can be done concurrently)
- Writing threads block each other but never block reading threads
As such threads that route requests should never encounter latency due to ongoing writes or other concurrent readers.
Managing routes a runtime
Routing mutation
In this example, the handler for routes/:action allow to dynamically register, update and remove handler for the
given route and method. Thanks to Fox's design, those actions are perfectly safe and may be executed concurrently.
package main
import (
"encoding/json"
"fmt"
"github.com/tigerwill90/fox"
"log"
"net/http"
"strings"
)
type ActionHandler struct {
fox *fox.Router
}
func (h *ActionHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, params fox.Params) {
var data map[string]string
if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
method := strings.ToUpper(data["method"])
path := data["path"]
text := data["text"]
if path == "" || method == "" {
http.Error(w, "missing method or path", http.StatusBadRequest)
return
}
var err error
action := params.Get("action")
switch action {
case "add":
err = h.fox.Handler(method, path, fox.HandlerFunc(func(w http.ResponseWriter, r *http.Request, params fox.Params) {
_, _ = fmt.Fprintln(w, text)
}))
case "update":
err = h.fox.Update(method, path, fox.HandlerFunc(func(w http.ResponseWriter, r *http.Request, params fox.Params) {
_, _ = fmt.Fprintln(w, text)
}))
case "delete":
err = h.fox.Remove(method, path)
default:
http.Error(w, fmt.Sprintf("action %q is not allowed", action), http.StatusBadRequest)
return
}
if err != nil {
http.Error(w, err.Error(), http.StatusConflict)
return
}
_, _ = fmt.Fprintf(w, "%s route [%s] %s: success\n", action, method, path)
}
func main() {
r := fox.New()
Must(r.Handler(http.MethodPost, "/routes/:action", &ActionHandler{fox: r}))
log.Fatalln(http.ListenAndServe(":8080", r))
}
func Must(err error) {
if err != nil {
panic(err)
}
}
Tree swapping
Fox also enables you to replace the entire tree in a single atomic operation using the Store and Swap methods.
Note that router's options apply automatically on the new tree.
package main
import (
"fox-by-example/db"
"github.com/tigerwill90/fox"
"html/template"
"io"
"log"
"net/http"
"strings"
"time"
)
type HtmlRenderer struct {
Template template.HTML
}
func (h *HtmlRenderer) ServeHTTP(w http.ResponseWriter, r *http.Request, params fox.Params) {
log.Printf("matched route: %s", params.Get(fox.RouteKey))
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_, _ = io.Copy(w, strings.NewReader(string(h.Template)))
}
func main() {
r := fox.New(fox.WithSaveMatchedRoute(true))
routes := db.GetRoutes()
for _, rte := range routes {
Must(r.Handler(rte.Method, rte.Path, &HtmlRenderer{Template: rte.Template}))
}
go Reload(r)
log.Fatalln(http.ListenAndServe(":8080", r))
}
func Reload(r *fox.Router) {
for range time.Tick(10 * time.Second) {
routes := db.GetRoutes()
tree := r.NewTree()
for _, rte := range routes {
if err := tree.Handler(rte.Method, rte.Path, &HtmlRenderer{Template: rte.Template}); err != nil {
log.Printf("error reloading route: %s\n", err)
continue
}
}
// Replace the currently in-use routing tree with the new provided.
r.Use(tree)
log.Println("route reloaded")
}
}
func Must(err error) {
if err != nil {
panic(err)
}
}
Advanced usage: consistent view updates
In certain situations, it's necessary to maintain a consistent view of the tree while performing updates.
The Tree API allow you to take control of the internal sync.Mutex to prevent concurrent writes from
other threads. Remember that all write operation should be run serially.
In the following example, the Upsert function needs to perform a lookup on the tree to check if a handler
is already registered for the provided method and path. By locking the Tree, this operation ensures
atomicity, as it prevents other threads from modifying the tree between the lookup and the write operation.
Note that all read operation on the tree remain lock-free.
func Upsert(t *fox.Tree, method, path string, handler fox.Handler) error {
t.Lock()
defer t.Unlock()
if fox.Has(t, method, path) {
return t.Update(method, path, handler)
}
return t.Handler(method, path, handler)
}
Concurrent safety and proper usage of Tree APIs
Some important consideration to keep in mind when using Tree API. Each instance as its own sync.Mutex and sync.Pool
that may be used to serialize write and reduce memory allocation. Since the router tree may be swapped at any
given time, you MUST always copy the pointer locally to avoid inadvertently releasing Params to the wrong pool
or worst, causing a deadlock by locking/unlocking the wrong Tree.
// Good
t := r.Tree()
t.Lock()
defer t.Unlock()
// Dramatically bad, may cause deadlock:
r.Tree().Lock()
defer r.Tree().Unlock()
This principle also applies to the fox.Lookup function, which requires releasing the fox.Params slice by calling params.Free(tree).
Always ensure that the Tree pointer passed as a parameter to params.Free is the same as the one passed to the fox.Lookup function.
Working with http.Handler
Fox itself implements the http.Handler interface which make easy to chain any compatible middleware before the router. Moreover, the router
provides convenient fox.WrapF and fox.WrapH adapter to be use with http.Handler. Named and catch all parameters are forwarded via the
request context
_ = r.Tree().Handler(http.MethodGet, "/users/:id", fox.WrapF(func(w http.ResponseWriter, r *http.Request) {
params := fox.ParamsFromContext(r.Context())
_, _ = fmt.Fprintf(w, "user id: %s\n", params.Get("id"))
}))
Benchmark
The primary goal of Fox is to be a lightweight, high performance router which allow routes modification while in operation. The following benchmarks attempt to compare Fox to various popular alternatives. Some are fully featured web framework, and other are lightweight request router. This is based on julienschmidt/go-http-routing-benchmark repository.
Config
GOOS: Linux
GOARCH: amd64
GO: 1.19
CPU: Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz
Static Routes
It is just a collection of random static paths inspired by the structure of the Go directory. It might not be a realistic URL-structure.
GOMAXPROCS: 0
BenchmarkDenco_StaticAll 352584 3350 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_StaticAll 159259 7400 ns/op 0 B/op 0 allocs/op
BenchmarkKocha_StaticAll 154405 7793 ns/op 0 B/op 0 allocs/op
BenchmarkFox_StaticAll 130474 8899 ns/op 0 B/op 0 allocs/op
BenchmarkHttpTreeMux_StaticAll 127754 9065 ns/op 0 B/op 0 allocs/op
BenchmarkGin_StaticAll 96139 12393 ns/op 0 B/op 0 allocs/op
BenchmarkBeego_StaticAll 10000 103464 ns/op 55264 B/op 471 allocs/op
BenchmarkGorillaMux_StaticAll 2307 501554 ns/op 113041 B/op 1099 allocs/op
BenchmarkMartini_StaticAll 1357 886524 ns/op 129210 B/op 2031 allocs/op
BenchmarkTraffic_StaticAll 990 1183413 ns/op 753608 B/op 14601 allocs/op
BenchmarkPat_StaticAll 972 1193521 ns/op 602832 B/op 12559 allocs/op
In this benchmark, Fox performs as well as Gin, HttpTreeMux and HttpRouter which are all Radix Tree based routers. An interesting fact is
that HttpTreeMux also support adding route while serving request concurrently.
However, it takes a slightly different approach, by using an optional RWMutex that may not scale as well as Fox under heavy load. The next
test compare HttpTreeMux, HttpTreeMux_SafeAddRouteFlag (concurrent reads and writes), HttpRouter and Fox in parallel benchmark.
GOMAXPROCS: 16
Route: /progs/image_package4.out
BenchmarkHttpRouter_StaticSingleParallel-16 211819790 5.640 ns/op 0 B/op 0 allocs/op
BenchmarkFox_StaticSingleParallel-16 157547185 7.418 ns/op 0 B/op 0 allocs/op
BenchmarkHttpTreeMux_StaticSingleParallel-16 154222639 7.774 ns/op 0 B/op 0 allocs/op
BenchmarkHttpTreeMux_SafeAddRouteFlag_StaticSingleParallel-16 29904204 38.52 ns/op 0 B/op 0 allocs/op
Route: all
BenchmarkHttpRouter_StaticAllParallel-16 1446759 832.1 ns/op 0 B/op 0 allocs/op
BenchmarkHttpTreeMux_StaticAllParallel-16 997074 1100 ns/op 0 B/op 0 allocs/op
BenchmarkFox_StaticAllParallel-16 1000000 1105 ns/op 0 B/op 0 allocs/op
BenchmarkHttpTreeMux_SafeAddRouteFlag_StaticAllParallel-16 197578 6017 ns/op 0 B/op 0 allocs/op
As you can see, this benchmark highlight the cost of using higher synchronisation primitive like RWMutex to be able to register new route while handling requests.
Micro Benchmarks
The following benchmarks measure the cost of some very basic operations.
In the first benchmark, only a single route, containing a parameter, is loaded into the routers. Then a request for a URL matching this pattern is made and the router has to call the respective registered handler function. End.
GOMAXPROCS: 0
BenchmarkFox_Param 29995566 39.04 ns/op 0 B/op 0 allocs/op
BenchmarkGin_Param 30710918 39.08 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_Param 20026911 55.88 ns/op 32 B/op 1 allocs/op
BenchmarkDenco_Param 15964747 70.04 ns/op 32 B/op 1 allocs/op
BenchmarkKocha_Param 8392696 138.5 ns/op 56 B/op 3 allocs/op
BenchmarkHttpTreeMux_Param 4469318 265.6 ns/op 352 B/op 3 allocs/op
BenchmarkBeego_Param 2241368 530.9 ns/op 352 B/op 3 allocs/op
BenchmarkPat_Param 1788819 666.8 ns/op 512 B/op 10 allocs/op
BenchmarkGorillaMux_Param 1208638 995.1 ns/op 1024 B/op 8 allocs/op
BenchmarkTraffic_Param 606530 1700 ns/op 1848 B/op 21 allocs/op
BenchmarkMartini_Param 455662 2419 ns/op 1096 B/op 12 allocs/op
Same as before, but now with multiple parameters, all in the same single route. The intention is to see how the routers scale with the number of parameters.
GOMAXPROCS: 0
BenchmarkGin_Param5 16470636 73.09 ns/op 0 B/op 0 allocs/op
BenchmarkFox_Param5 14716213 82.05 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_Param5 7614333 154.7 ns/op 160 B/op 1 allocs/op
BenchmarkDenco_Param5 6513253 179.5 ns/op 160 B/op 1 allocs/op
BenchmarkKocha_Param5 2073741 604.3 ns/op 440 B/op 10 allocs/op
BenchmarkHttpTreeMux_Param5 1801978 659.2 ns/op 576 B/op 6 allocs/op
BenchmarkBeego_Param5 1764513 669.1 ns/op 352 B/op 3 allocs/op
BenchmarkGorillaMux_Param5 657648 1578 ns/op 1088 B/op 8 allocs/op
BenchmarkPat_Param5 633555 1700 ns/op 800 B/op 24 allocs/op
BenchmarkTraffic_Param5 374895 2744 ns/op 2200 B/op 27 allocs/op
BenchmarkMartini_Param5 403650 2835 ns/op 1256 B/op 13 allocs/op
BenchmarkGin_Param20 6136497 189.9 ns/op 0 B/op 0 allocs/op
BenchmarkFox_Param20 4187372 283.2 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_Param20 2536359 483.4 ns/op 640 B/op 1 allocs/op
BenchmarkDenco_Param20 2110105 567.7 ns/op 640 B/op 1 allocs/op
BenchmarkKocha_Param20 593958 1744 ns/op 1808 B/op 27 allocs/op
BenchmarkBeego_Param20 741110 1747 ns/op 352 B/op 3 allocs/op
BenchmarkHttpTreeMux_Param20 341913 3079 ns/op 3195 B/op 10 allocs/op
BenchmarkGorillaMux_Param20 282345 3671 ns/op 3196 B/op 10 allocs/op
BenchmarkMartini_Param20 210543 5222 ns/op 3619 B/op 15 allocs/op
BenchmarkPat_Param20 151778 7343 ns/op 4096 B/op 73 allocs/op
BenchmarkTraffic_Param20 113230 9989 ns/op 7847 B/op 47 allocs/op
Now let's see how expensive it is to access a parameter. The handler function reads the value (by the name of the parameter, e.g. with a map
lookup; depends on the router) and writes it to /dev/null
GOMAXPROCS: 0
BenchmarkFox_ParamWrite 21061758 56.96 ns/op 0 B/op 0 allocs/op
BenchmarkGin_ParamWrite 17973256 66.54 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_ParamWrite 15953065 74.64 ns/op 32 B/op 1 allocs/op
BenchmarkDenco_ParamWrite 12553562 89.93 ns/op 32 B/op 1 allocs/op
BenchmarkKocha_ParamWrite 7356948 156.7 ns/op 56 B/op 3 allocs/op
BenchmarkHttpTreeMux_ParamWrite 4075486 286.4 ns/op 352 B/op 3 allocs/op
BenchmarkBeego_ParamWrite 2126341 567.4 ns/op 360 B/op 4 allocs/op
BenchmarkPat_ParamWrite 1197910 996.5 ns/op 936 B/op 14 allocs/op
BenchmarkGorillaMux_ParamWrite 1139376 1048 ns/op 1024 B/op 8 allocs/op
BenchmarkTraffic_ParamWrite 496440 2057 ns/op 2272 B/op 25 allocs/op
BenchmarkMartini_ParamWrite 398594 2799 ns/op 1168 B/op 16 allocs/op
In those micro benchmarks, we can see that Fox scale really well, even with long wildcard routes. Like Gin, this router reuse the
data structure (e.g. fox.Params slice) containing the matching parameters in order to remove completely heap allocation. We can also
notice that there is a very small overhead comparing to Gin when the number of parameters scale. This is due to the fact that every tree's node
in Fox are atomic.Pointer and that traversing the tree require to load the underlying node pointer atomically. Despite that, even
with 20 parameters, the performance of Fox is still better than most other contender.
Github
Finally, this benchmark execute a request for each GitHub API route (203 routes).
GOMAXPROCS: 0
BenchmarkGin_GithubAll 68384 17425 ns/op 0 B/op 0 allocs/op
BenchmarkFox_GithubAll 67162 17631 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_GithubAll 44085 27449 ns/op 13792 B/op 167 allocs/op
BenchmarkDenco_GithubAll 35019 33651 ns/op 20224 B/op 167 allocs/op
BenchmarkKocha_GithubAll 19186 62243 ns/op 23304 B/op 843 allocs/op
BenchmarkHttpTreeMuxSafeAddRoute_GithubAll 14907 79919 ns/op 65856 B/op 671 allocs/op
BenchmarkHttpTreeMux_GithubAll 14952 80280 ns/op 65856 B/op 671 allocs/op
BenchmarkBeego_GithubAll 9712 136414 ns/op 71456 B/op 609 allocs/op
BenchmarkTraffic_GithubAll 637 1824477 ns/op 819052 B/op 14114 allocs/op
BenchmarkMartini_GithubAll 572 2042852 ns/op 231419 B/op 2731 allocs/op
BenchmarkGorillaMux_GithubAll 562 2110880 ns/op 199683 B/op 1588 allocs/op
BenchmarkPat_GithubAll 550 2117715 ns/op 1410624 B/op 22515 allocs/op
Contributions
This project aims to provide a lightweight, high performance and easy to use http router. It purposely has a limited set of features and exposes a relatively low-level api. The intention behind these choices is that it can serve as a building block for more "batteries included" frameworks. Feature requests and PRs along these lines are welcome.
Acknowledgements
- npgall/concurrent-trees: Fox design is largely inspired from Niall Gallagher's Concurrent Trees design.
- julienschmidt/httprouter: a lot of feature that implements Fox are inspired from Julien Schmidt's router.
Documentation
¶
Index ¶
- Constants
- Variables
- func CleanPath(p string) string
- func Has(t *Tree, method, path string) bool
- func Lookup(t *Tree, method, path string, lazy bool) (handler Handler, params *Params, tsr bool)
- func Reverse(t *Tree, method, path string) string
- func Walk(tree *Tree, fn WalkFunc) error
- type Handler
- type HandlerFunc
- type Iterator
- func (it *Iterator) Handler() Handler
- func (it *Iterator) Method() string
- func (it *Iterator) Next()
- func (it *Iterator) Path() string
- func (it *Iterator) Rewind()
- func (it *Iterator) SeekMethod(method string)
- func (it *Iterator) SeekMethodPrefix(method, key string)
- func (it *Iterator) SeekPrefix(key string)
- func (it *Iterator) Valid() bool
- type Option
- func WithHandleMethodNotAllowed(enable bool) Option
- func WithNotAllowedHandler(handler http.Handler) Option
- func WithNotFoundHandler(handler http.Handler) Option
- func WithPanicHandler(fn func(http.ResponseWriter, *http.Request, interface{})) Option
- func WithRedirectFixedPath(enable bool) Option
- func WithRedirectTrailingSlash(enable bool) Option
- func WithSaveMatchedRoute(enable bool) Option
- type Param
- type Params
- type RouteConflictError
- type Router
- func (fox *Router) Handler(method, path string, handler Handler) error
- func (fox *Router) NewTree() *Tree
- func (fox *Router) Remove(method, path string) error
- func (fox *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (fox *Router) Swap(new *Tree) (old *Tree)
- func (fox *Router) Tree() *Tree
- func (fox *Router) Update(method, path string, handler Handler) error
- func (fox *Router) Use(new *Tree)
- type Tree
- type WalkFunc
Examples ¶
Constants ¶
const RouteKey = "$k/fox"
Variables ¶
var ( ErrRouteNotFound = errors.New("route not found") ErrRouteExist = errors.New("route already registered") ErrRouteConflict = errors.New("route conflict") ErrInvalidRoute = errors.New("invalid route") )
var ParamsKey = key{}
var SkipMethod = errors.New("skip method")
SkipMethod is used as a return value from WalkFunc to indicate that the method named in the call is to be skipped.
Functions ¶
func CleanPath ¶
CleanPath is the URL version of path.Clean, it returns a canonical URL path for p, eliminating . and .. elements.
The following rules are applied iteratively until no further processing can be done:
- Replace multiple slashes with a single slash.
- Eliminate each . path name element (the current directory).
- Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
- Eliminate .. elements that begin a rooted path: that is, replace "/.." by "/" at the beginning of a path.
If the result of this process is an empty string, "/" is returned
func Has ¶ added in v0.5.0
Has allows to check if the given method and path exactly match a registered route. This function is safe for concurrent use by multiple goroutine and while mutation on Tree are ongoing. This api is EXPERIMENTAL and is likely to change in future release.
func Lookup ¶ added in v0.5.0
Lookup allow to do manual lookup of a route and return the matched handler along with parsed params and trailing slash redirect recommendation. Note that you should always free Params if NOT nil by calling params.Free(t). If lazy is set to true, route params are not parsed. This function is safe for concurrent use by multiple goroutine and while mutation on Tree are ongoing.
Example ¶
This example demonstrates some important considerations when using the Lookup function.
r := New()
_ = r.Handler(http.MethodGet, "/hello/:name", HandlerFunc(func(w http.ResponseWriter, r *http.Request, params Params) {
_, _ = fmt.Fprintf(w, "Hello, %s\n", params.Get("name"))
}))
req := httptest.NewRequest(http.MethodGet, "/hello/fox", nil)
// Each tree as its own sync.Pool that is used to reuse Params slice. Since the router tree may be swapped at
// any given time, it's recommended to copy the pointer locally so when the params is released,
// it returns to the correct pool.
tree := r.Tree()
handler, params, _ := Lookup(tree, http.MethodGet, req.URL.Path, false)
// If not nit, Params should be freed to reduce memory allocation.
if params != nil {
defer params.Free(tree)
}
// Bad, instead make a local copy of the tree!
handler, params, _ = Lookup(r.Tree(), http.MethodGet, req.URL.Path, false)
if params != nil {
defer params.Free(r.Tree())
}
w := httptest.NewRecorder()
handler.ServeHTTP(w, req, nil)
fmt.Print(w.Body.String())
Output:
func Reverse ¶ added in v0.5.0
Reverse perform a lookup on the tree for the given method and path and return the matching registered route if any. This function is safe for concurrent use by multiple goroutine and while mutation on Tree are ongoing. This api is EXPERIMENTAL and is likely to change in future release.
func Walk ¶ added in v0.5.0
Walk allow to walk over all registered route in lexicographical order. If the function return the special value SkipMethod, Walk skips the current method. This function is safe for concurrent use by multiple goroutine and while mutation are ongoing. This api is EXPERIMENTAL and is likely to change in future release.
Types ¶
type Handler ¶
type Handler interface {
ServeHTTP(http.ResponseWriter, *http.Request, Params)
}
Handler respond to an HTTP request.
This interface enforce the same contract as http.Handler except that matched wildcard route segment are accessible via params. Params slice is freed once ServeHTTP returns and may be reused later to save resource. Therefore, if you need to hold params slice longer, you have to copy it (see Clone method).
As for http.Handler interface, to abort a handler so the client sees an interrupted response, panic with the value http.ErrAbortHandler.
func WrapF ¶
func WrapF(f http.HandlerFunc) Handler
WrapF is a helper function for wrapping http.HandlerFunc and returns a Fox Handler. Params are forwarded via the request context. See ParamsFromContext to retrieve parameters.
type HandlerFunc ¶
type HandlerFunc func(http.ResponseWriter, *http.Request, Params)
HandlerFunc is an adapter to allow the use of ordinary functions as HTTP handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Handler that calls f.
func (HandlerFunc) ServeHTTP ¶
func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request, params Params)
ServerHTTP calls f(w, r, params)
type Iterator ¶ added in v0.3.0
type Iterator struct {
// contains filtered or unexported fields
}
func NewIterator ¶ added in v0.5.0
NewIterator returns an Iterator that traverses all registered routes in lexicographic order. An Iterator is safe to use when the router is serving request, when routing updates are ongoing or in parallel with other Iterators. Note that changes that happen while iterating over routes may not be reflected by the Iterator. This api is EXPERIMENTAL and is likely to change in future release.
Example ¶
r := New()
it := NewIterator(r.Tree())
// Iterate over all routes
for it.Rewind(); it.Valid(); it.Next() {
fmt.Println(it.Method(), it.Path())
}
// Iterate over all routes for the GET method
for it.SeekMethod(http.MethodGet); it.Valid(); it.Next() {
fmt.Println(it.Method(), it.Path())
}
// Iterate over all routes starting with /users
for it.SeekPrefix("/users"); it.Valid(); it.Next() {
fmt.Println(it.Method(), it.Path())
}
// Iterate over all route starting with /users for the GET method
for it.SeekMethodPrefix(http.MethodGet, "/user"); it.Valid(); it.Next() {
fmt.Println(it.Method(), it.Path())
}
Output:
func (*Iterator) Handler ¶ added in v0.3.0
Handler return the registered handler for the current route.
func (*Iterator) Next ¶ added in v0.3.0
func (it *Iterator) Next()
Next advance the iterator to the next route. Always check it.Valid() after a it.Next().
func (*Iterator) Rewind ¶ added in v0.3.0
func (it *Iterator) Rewind()
Rewind reset the iterator cursor all the way to zero-th position which is the first method and route. It does not keep track of whether the cursor started with SeekPrefix, SeekMethod or SeekMethodPrefix.
func (*Iterator) SeekMethod ¶ added in v0.3.0
SeekMethod reset the iterator cursor to the first route for the given method. It does not keep tracking of previous seek.
func (*Iterator) SeekMethodPrefix ¶ added in v0.3.0
SeekMethodPrefix reset the iterator cursor to the first route starting with key for the given method. It does not keep tracking of previous seek.
func (*Iterator) SeekPrefix ¶ added in v0.3.0
SeekPrefix reset the iterator cursor to the first route starting with key. It does not keep tracking of previous seek.
type Option ¶ added in v0.5.0
type Option interface {
// contains filtered or unexported methods
}
func WithHandleMethodNotAllowed ¶ added in v0.5.0
WithHandleMethodNotAllowed enable to returns 405 Method Not Allowed instead of 404 Not Found when the route exist for another http verb.
func WithNotAllowedHandler ¶ added in v0.5.0
WithNotAllowedHandler register a http.Handler which is called when the request cannot be routed, but the same route exist for other methods. The "Allow" header it automatically set before calling the handler. Mount WithHandleMethodNotAllowed to enable this option. By default, http.Error with http.StatusMethodNotAllowed is used.
func WithNotFoundHandler ¶ added in v0.5.0
WithNotFoundHandler register a http.Handler which is called when no matching route is found. By default, http.NotFound is used.
func WithPanicHandler ¶ added in v0.5.0
func WithPanicHandler(fn func(http.ResponseWriter, *http.Request, interface{})) Option
WithPanicHandler register a function to handle panics recovered from http handlers.
func WithRedirectFixedPath ¶ added in v0.5.0
WithRedirectFixedPath enable automatic redirection fallback when the current request does not match but another handler is found after cleaning up superfluous path elements (see CleanPath). E.g. /../foo/bar request does not match but /foo/bar would. The client is redirected with a http status code 301 for GET requests and 308 for all other methods.
func WithRedirectTrailingSlash ¶ added in v0.5.0
WithRedirectTrailingSlash enable automatic redirection fallback when the current request does not match but another handler is found with/without an additional trailing slash. E.g. /foo/bar/ request does not match but /foo/bar would match. The client is redirected with a http status code 301 for GET requests and 308 for all other methods.
func WithSaveMatchedRoute ¶ added in v0.5.0
WithSaveMatchedRoute configure the router to make the matched route accessible as a Handler parameter. Usage: p.Get(fox.RouteKey)
type Params ¶
type Params []Param
func ParamsFromContext ¶
ParamsFromContext is a helper function to retrieve parameters from the request context.
type RouteConflictError ¶
type RouteConflictError struct {
Method string
Path string
Matched []string
// contains filtered or unexported fields
}
func (*RouteConflictError) Error ¶
func (e *RouteConflictError) Error() string
func (*RouteConflictError) Unwrap ¶
func (e *RouteConflictError) Unwrap() error
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router is a lightweight high performance HTTP request router that support mutation on its routing tree while handling request concurrently.
func New ¶
New returns a ready to use Router.
Example ¶
When WithSaveMatchedRoute is enabled, the route matching the current request will be available in parameters.
r := New(WithSaveMatchedRoute(true))
metrics := func(next HandlerFunc) Handler {
return HandlerFunc(func(w http.ResponseWriter, r *http.Request, params Params) {
start := time.Now()
next.ServeHTTP(w, r, params)
log.Printf("url=%s; route=%s; time=%d", r.URL, params.Get(RouteKey), time.Since(start))
})
}
_ = r.Handler(http.MethodGet, "/hello/:name", metrics(func(w http.ResponseWriter, r *http.Request, params Params) {
_, _ = fmt.Fprintf(w, "Hello %s\n", params.Get("name"))
}))
Output:
func (*Router) Handler ¶
Handler registers a new handler for the given method and path. This function return an error if the route is already registered or conflict with another. It's perfectly safe to add a new handler while the tree is in use for serving requests. This function is safe for concurrent use by multiple goroutine. To override an existing route, use Update.
func (*Router) NewTree ¶ added in v0.5.0
NewTree returns a fresh routing Tree which allow to register, update and delete route. It's safe to create multiple Tree concurrently. However, a Tree itself is not thread safe and all its APIs should be run serially. Note that a Tree give direct access to the underlying sync.Mutex. This api is EXPERIMENTAL and is likely to change in future release.
func (*Router) Remove ¶
Remove delete an existing handler for the given method and path. If the route does not exist, the function return an ErrRouteNotFound. It's perfectly safe to remove a handler while the tree is in use for serving requests. This function is safe for concurrent use by multiple goroutine.
func (*Router) Swap ¶ added in v0.5.0
Swap atomically replaces the currently in-use routing tree with the provided new tree, and returns the previous tree. This API is EXPERIMENTAL and is likely to change in future release.
func (*Router) Tree ¶ added in v0.5.0
Tree atomically loads and return the currently in-use routing tree. This API is EXPERIMENTAL and is likely to change in future release.
Example ¶
This example demonstrates some important considerations when using the Tree API.
r := New()
// Each tree as its own sync.Mutex that is used to lock write on the tree. Since the router tree may be swapped at
// any given time, you MUST always copy the pointer locally, This ensures that you do not inadvertently cause a
// deadlock by locking/unlocking the wrong tree.
tree := r.Tree()
upsert := func(method, path string, handler Handler) error {
tree.Lock()
defer tree.Unlock()
if Has(tree, method, path) {
return tree.Update(method, path, handler)
}
return tree.Handler(method, path, handler)
}
_ = upsert(http.MethodGet, "/foo/bar", HandlerFunc(func(w http.ResponseWriter, r *http.Request, params Params) {
_, _ = fmt.Fprintln(w, "foo bar")
}))
// Bad, instead make a local copy of the tree!
upsert = func(method, path string, handler Handler) error {
r.Tree().Lock()
defer r.Tree().Unlock()
if Has(r.Tree(), method, path) {
return r.Tree().Update(method, path, handler)
}
return r.Tree().Handler(method, path, handler)
}
Output:
func (*Router) Update ¶
Update override an existing handler for the given method and path. If the route does not exist, the function return an ErrRouteNotFound. It's perfectly safe to update a handler while the tree is in use for serving requests. This function is safe for concurrent use by multiple goroutine. To add new handler, use Handler method.
type Tree ¶ added in v0.5.0
Tree implements a Concurrent Radix Tree that supports lock-free reads while allowing concurrent writes. The caller is responsible for ensuring that all writes are run serially.
IMPORTANT: Each tree as its own sync.Mutex and sync.Pool that may be used to serialize write and reduce memory allocation. Since the router tree may be swapped at any given time, you MUST always copy the pointer locally to avoid inadvertently releasing Params to the wrong pool or worst, causing a deadlock by locking/unlocking the wrong Tree.
Good: t := r.Tree() t.Lock() defer t.Unlock()
Dramatically bad, may cause deadlock r.Tree().Lock() defer r.Tree().Unlock()
This principle also applies to the Lookup function, which requires releasing the Params slice, if not nil, by calling params.Free(tree). Always ensure that the Tree pointer passed as a parameter to params.Free is the same as the one passed to the Lookup function.
func (*Tree) Handler ¶ added in v0.5.0
Handler registers a new handler for the given method and path. This function return an error if the route is already registered or conflict with another. It's perfectly safe to add a new handler while the tree is in use for serving requests. However, this function is NOT thread safe and should be run serially, along with all other Tree's APIs. To override an existing route, use Update.
func (*Tree) Remove ¶ added in v0.5.0
Remove delete an existing handler for the given method and path. If the route does not exist, the function return an ErrRouteNotFound. It's perfectly safe to remove a handler while the tree is in use for serving requests. However, this function is NOT thread safe and should be run serially, along with all other Tree's APIs.
func (*Tree) Update ¶ added in v0.5.0
Update override an existing handler for the given method and path. If the route does not exist, the function return an ErrRouteNotFound. It's perfectly safe to update a handler while the tree is in use for serving requests. However, this function is NOT thread safe and should be run serially, along with all other Tree's APIs. To add new handler, use Handler method.
Source Files