fox

README

Fox

Fox is a zero allocation, 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 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: Comes with a ready-to-use, efficient Recovery middleware that gracefully handles panics.

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.

Only explicit matches: A request can only match exactly one route or no route at all. Fox strikes a balance between routing flexibility, performance and clarity by enforcing clear priority rules, ensuring that there are no unintended matches and maintaining high performance even for complex routing pattern.

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 (
	"github.com/tigerwill90/fox"
	"log"
	"net/http"
)

type Greeting struct {
	Say string
}

func (h *Greeting) Greet(c fox.Context) error {
	return c.String(http.StatusOK, "%s %s\n", h.Say, c.Param("name"))
}

func main() {
	r := fox.New(fox.DefaultOptions())

	err := r.Handle(http.MethodGet, "/", func(c fox.Context) error {
		return c.String(http.StatusOK, "Welcome\n")
	})
	if err != nil {
		panic(err)
	}

	h := Greeting{Say: "Hello"}
	r.MustHandle(http.MethodGet, "/hello/{name}", h.Greet)

	log.Fatalln(http.ListenAndServe(":8080", r))
}

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)
    }
}

In addition, Fox also provides a centralized way to handle errors that may occur during the execution of a HandlerFunc.

var MyCustomError = errors.New("my custom error")

r := fox.New(
    fox.WithRouteError(func(c fox.Context, err error) {
        if !c.Writer().Written() {
            if errors.Is(err, MyCustomError) {
                http.Error(c.Writer(), err.Error(), http.StatusInternalServerError)
                return
            }
            http.Error(c.Writer(), http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
            return
        }
    }),
)

r.MustHandle(http.MethodGet, "/hello/{name}", func(c fox.Context) error {
    return MyCustomError
})

Named parameters

A route can be defined using placeholder (e.g {name}). The matching segment are recorder into the fox.Params slice accessible via fox.Context. The Param and Get methods are helpers 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:123             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 regular named parameter (e.g. *{name}).

Pattern /src/*{filepath}

/src/                       match
/src/conf.txt               match
/src/dir/config.txt         match

Patter /src/file=*{path}

/src/file=                  match
/src/file=config.txt        match
/src/file=/dir/config.txt   match

Priority rules

Routes are prioritized based on specificity, with static segments taking precedence over wildcard segments. A wildcard segment (named parameter or catch all) can only overlap with static segments, for the same HTTP method. For instance, GET /users/{id} and GET /users/{name}/profile cannot coexist, as the {id} and {name} segments are overlapping. These limitations help to minimize the number of branches that need to be evaluated in order to find the right match, thereby maintaining high-performance routing.

For example, the followings route are allowed:

GET /*{filepath}
GET /users/{id}
GET /users/{id}/emails
GET /users/{id}/{actions}
POST /users/{name}/emails

Warning about context

The fox.Context instance is freed once the request handler function returns to optimize resource allocation. If you need to retain fox.Context or fox.Params beyond the scope of the handler, use the Clone methods.

func Hello(c fox.Context) error {
    cc := c.Clone()
    // cp := c.Params().Clone()
    go func() {
        time.Sleep(2 * time.Second)
        log.Println(cc.Param("name")) // Safe
    }()
    return c.String(http.StatusOK, "Hello %s\n", c.Param("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"
	"errors"
	"fmt"
	"github.com/tigerwill90/fox"
	"log"
	"net/http"
	"strings"
)

func Action(c fox.Context) error {
	var data map[string]string
	if err := json.NewDecoder(c.Request().Body).Decode(&data); err != nil {
		return fox.NewHTTPError(http.StatusBadRequest, err)
	}

	method := strings.ToUpper(data["method"])
	path := data["path"]
	text := data["text"]

	if path == "" || method == "" {
		return fox.NewHTTPError(http.StatusBadRequest, errors.New("missing method or path"))
	}

	var err error
	action := c.Param("action")
	switch action {
	case "add":
		err = c.Fox().Handle(method, path, func(c fox.Context) error {
			return c.String(http.StatusOK, text)
		})
	case "update":
		err = c.Fox().Update(method, path, func(c fox.Context) error {
			return c.String(http.StatusOK, text)
		})
	case "delete":
		err = c.Fox().Remove(method, path)
	default:
		return fox.NewHTTPError(http.StatusBadRequest, fmt.Errorf("action %q is not allowed", action))
	}
	if err != nil {
		return fox.NewHTTPError(http.StatusConflict, err)
	}

	return c.String(http.StatusOK, "%s route [%s] %s: success\n", action, method, path)
}

func main() {
	r := fox.New()
	r.MustHandle(http.MethodPost, "/routes/{action}", Action)
	log.Fatalln(http.ListenAndServe(":8080", r))
}

Tree swapping

Fox also enables you to replace the entire tree in a single atomic operation using the 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"
	"log"
	"net/http"
	"strings"
	"time"
)

type HtmlRenderer struct {
	Template template.HTML
}

func (h *HtmlRenderer) Render(c fox.Context) error {
	log.Printf("matched handler path: %s", c.Path())
	return c.Stream(
		http.StatusInternalServerError,
		fox.MIMETextHTMLCharsetUTF8,
		strings.NewReader(string(h.Template)),
	)
}

func main() {
	r := fox.New()

	routes := db.GetRoutes()

	for _, rte := range routes {
		h := HtmlRenderer{Template: rte.Template}
		r.MustHandle(rte.Method, rte.Path, h.Render)
	}

	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 {
			h := HtmlRenderer{Template: rte.Template}
			if err := tree.Handle(rte.Method, rte.Path, h.Render); err != nil {
				log.Printf("error reloading route: %s\n", err)
				continue
			}
		}
		// Swap the currently in-use routing tree with the new provided.
		r.Swap(tree)
		log.Println("route reloaded")
	}
}

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.HandlerFunc) error {
    t.Lock()
    defer t.Unlock()
    if fox.Has(t, method, path) {
        return t.Update(method, path, handler)
    }
    return t.Handle(method, path, handler)
}

Concurrent safety and proper usage of Tree APIs

When working with the Tree API, it's important to keep some considerations in mind. Each instance has its own sync.Mutex that can be used to serialize writes. However, unlike the router API, the lower-level Tree API does not automatically lock the tree when writing to it. Therefore, it is the user's responsibility to ensure all writes are executed serially.

Moreover, since the router tree may be swapped at any given time, you MUST always copy the pointer locally to avoid inadvertently 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()

// Dramatically bad, may cause deadlock
func handle(c fox.Context) error {
    c.Fox().Tree().Lock()
    defer c.Fox().Tree().Unlock()
    return nil
}

Note that fox.Context carries a local copy of the Tree that is being used to serve the handler, thereby eliminating the risk of deadlock when using the Tree within the context.

// Ok
func handle(c fox.Context) error {
    c.Tree().Lock()
    defer c.Tree().Unlock()
    return nil
}

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, fox.WrapH and fox.WrapM adapter to be use with http.Handler.

Wrapping an http.Handler

articles := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    _, _ = fmt.Fprintln(w, "get articles")
})

r := fox.New(fox.DefaultOptions())
r.MustHandle(http.MethodGet, "/articles", fox.WrapH(httpRateLimiter.RateLimit(articles)))

Wrapping an http.Handler compatible middleware

r := fox.New(fox.DefaultOptions(), fox.WithMiddleware(fox.WrapM(httpRateLimiter.RateLimit)))
r.MustHandle(http.MethodGet, "/articles/{id}", func(c fox.Context) error {
    return c.String(http.StatusOK, "Article id: %s\n", c.Param("id"))
})

Middleware

Middlewares can be registered globally using the fox.WithMiddleware option. The example below demonstrates how to create and apply automatically a simple logging middleware to all route.

package main

import (
	"fmt"
	"github.com/tigerwill90/fox"
	"log"
	"net/http"
	"time"
)

var logger = fox.MiddlewareFunc(func(next fox.HandlerFunc) fox.HandlerFunc {
	return func(c fox.Context) error {
		start := time.Now()
		err := next(c)
		msg := fmt.Sprintf("route: %s, latency: %s, status: %d, size: %d",
			c.Path(),
			time.Since(start),
			c.Writer().Status(),
			c.Writer().Size(),
		)
		if err != nil {
			msg += fmt.Sprintf(", error: %s", err)
		}
		log.Println(msg)
		return err
	}
})

func main() {
	r := fox.New(fox.WithMiddleware(logger))

	r.MustHandle(http.MethodGet, "/", func(c fox.Context) error {
		resp, err := http.Get("https://api.coindesk.com/v1/bpi/currentprice.json")
		if err != nil {
			return fox.NewHTTPError(http.StatusInternalServerError)
		}
		defer resp.Body.Close()
		return c.Stream(http.StatusOK, fox.MIMEApplicationJSON, resp.Body)
	})

	log.Fatalln(http.ListenAndServe(":8080", r))
}

Benchmark

The primary goal of Fox is to be a lightweight, high performance router which allow routes modification at runtime. The following benchmarks attempt to compare Fox to various popular alternatives, including both fully-featured web frameworks and lightweight request routers. These benchmarks are based on the julienschmidt/go-http-routing-benchmark repository.

Please note that these benchmarks should not be taken too seriously, as the comparison may not be entirely fair due to the differences in feature sets offered by each framework. Performance should be evaluated in the context of your specific use case and requirements. While Fox aims to excel in performance, it's important to consider the trade-offs and functionality provided by different web frameworks and routers when making your selection.

Config

GOOS:   Linux
GOARCH: amd64
GO:     1.20
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: 1

BenchmarkHttpRouter_StaticAll     161659              7570 ns/op               0 B/op          0 allocs/op
BenchmarkHttpTreeMux_StaticAll    132446              8836 ns/op               0 B/op          0 allocs/op
BenchmarkFox_StaticAll            102577             11348 ns/op               0 B/op          0 allocs/op
BenchmarkStdMux_StaticAll          91304             13382 ns/op               0 B/op          0 allocs/op
BenchmarkGin_StaticAll             78224             15433 ns/op               0 B/op          0 allocs/op
BenchmarkEcho_StaticAll            77923             15739 ns/op               0 B/op          0 allocs/op
BenchmarkBeego_StaticAll           10000            101094 ns/op           55264 B/op        471 allocs/op
BenchmarkGorillaMux_StaticAll       2283            525683 ns/op          113041 B/op       1099 allocs/op
BenchmarkMartini_StaticAll          1330            936928 ns/op          129210 B/op       2031 allocs/op
BenchmarkTraffic_StaticAll          1064           1140959 ns/op          753611 B/op      14601 allocs/op
BenchmarkPat_StaticAll               967           1230424 ns/op          602832 B/op      12559 allocs/op

In this benchmark, Fox performs as well as Gin and Echo which are both 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 with and without the *SafeAddRouteFlag (concurrent reads and writes) and Fox in parallel benchmark.

GOMAXPROCS: 16

Route: all

BenchmarkFox_StaticAll-16                          99322             11369 ns/op               0 B/op          0 allocs/op
BenchmarkFox_StaticAllParallel-16                 831354              1422 ns/op               0 B/op          0 allocs/op
BenchmarkHttpTreeMux_StaticAll-16                 135560              8861 ns/op               0 B/op          0 allocs/op
BenchmarkHttpTreeMux_StaticAllParallel-16*        172714              6916 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: 1

BenchmarkFox_Param              33024534                36.61 ns/op            0 B/op          0 allocs/op
BenchmarkEcho_Param             31472508                38.71 ns/op            0 B/op          0 allocs/op
BenchmarkGin_Param              25826832                52.88 ns/op            0 B/op          0 allocs/op
BenchmarkHttpRouter_Param       21230490                60.83 ns/op           32 B/op          1 allocs/op
BenchmarkHttpTreeMux_Param       3960292                280.4 ns/op          352 B/op          3 allocs/op
BenchmarkBeego_Param             2247776                518.9 ns/op          352 B/op          3 allocs/op
BenchmarkPat_Param               1603902                676.6 ns/op          512 B/op         10 allocs/op
BenchmarkGorillaMux_Param        1000000                 1011 ns/op         1024 B/op          8 allocs/op
BenchmarkTraffic_Param            648986                 1686 ns/op         1848 B/op         21 allocs/op
BenchmarkMartini_Param            485839                 2446 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

BenchmarkFox_Param5             16608495                72.84 ns/op            0 B/op          0 allocs/op
BenchmarkGin_Param5             13098740                92.22 ns/op            0 B/op          0 allocs/op
BenchmarkEcho_Param5            12025460                96.33 ns/op            0 B/op          0 allocs/op
BenchmarkHttpRouter_Param5       8233530                148.1 ns/op          160 B/op          1 allocs/op
BenchmarkHttpTreeMux_Param5      1986019                616.9 ns/op          576 B/op          6 allocs/op
BenchmarkBeego_Param5            1836229                655.3 ns/op          352 B/op          3 allocs/op
BenchmarkGorillaMux_Param5        757936                 1572 ns/op         1088 B/op          8 allocs/op
BenchmarkPat_Param5               645847                 1724 ns/op          800 B/op         24 allocs/op
BenchmarkTraffic_Param5           424431                 2729 ns/op         2200 B/op         27 allocs/op
BenchmarkMartini_Param5           424806                 2772 ns/op         1256 B/op         13 allocs/op


BenchmarkGin_Param20             4636416               244.6 ns/op             0 B/op          0 allocs/op
BenchmarkFox_Param20             4667533               250.7 ns/op             0 B/op          0 allocs/op
BenchmarkEcho_Param20            4352486               277.1 ns/op             0 B/op          0 allocs/op
BenchmarkHttpRouter_Param20      2618958               455.2 ns/op           640 B/op          1 allocs/op
BenchmarkBeego_Param20            847029                1688 ns/op           352 B/op          3 allocs/op
BenchmarkHttpTreeMux_Param20      369500                2972 ns/op          3195 B/op         10 allocs/op
BenchmarkGorillaMux_Param20       318134                3561 ns/op          3195 B/op         10 allocs/op
BenchmarkMartini_Param20          223070                5117 ns/op          3619 B/op         15 allocs/op
BenchmarkPat_Param20              157380                7442 ns/op          4094 B/op         73 allocs/op
BenchmarkTraffic_Param20          119677                9864 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                 16707409                72.53 ns/op            0 B/op          0 allocs/op
BenchmarkHttpRouter_ParamWrite          16478174                73.30 ns/op           32 B/op          1 allocs/op
BenchmarkGin_ParamWrite                 15828385                75.73 ns/op            0 B/op          0 allocs/op
BenchmarkEcho_ParamWrite                13187766                95.18 ns/op            8 B/op          1 allocs/op
BenchmarkHttpTreeMux_ParamWrite          4132832               279.9 ns/op           352 B/op          3 allocs/op
BenchmarkBeego_ParamWrite                2172572               554.3 ns/op           360 B/op          4 allocs/op
BenchmarkPat_ParamWrite                  1200334               996.8 ns/op           936 B/op         14 allocs/op
BenchmarkGorillaMux_ParamWrite           1000000              1005 ns/op            1024 B/op          8 allocs/op
BenchmarkMartini_ParamWrite               454255              2667 ns/op            1168 B/op         16 allocs/op
BenchmarkTraffic_ParamWrite               511766              2021 ns/op            2272 B/op         25 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.Context slice) containing the matching parameters in order to remove completely heap allocation.

Github

Finally, this benchmark execute a request for each GitHub API route (203 routes).

GOMAXPROCS: 0

BenchmarkFox_GithubAll             63984             18555 ns/op               0 B/op          0 allocs/op
BenchmarkEcho_GithubAll            49312             23353 ns/op               0 B/op          0 allocs/op
BenchmarkGin_GithubAll             48422             24926 ns/op               0 B/op          0 allocs/op
BenchmarkHttpRouter_GithubAll      45706             26818 ns/op           14240 B/op        171 allocs/op
BenchmarkHttpTreeMux_GithubAll     14731             80133 ns/op           67648 B/op        691 allocs/op
BenchmarkBeego_GithubAll            7692            137926 ns/op           72929 B/op        625 allocs/op
BenchmarkTraffic_GithubAll           636           1916586 ns/op          845114 B/op      14634 allocs/op
BenchmarkMartini_GithubAll           530           2205947 ns/op          238546 B/op       2813 allocs/op
BenchmarkGorillaMux_GithubAll        529           2246380 ns/op          203844 B/op       1620 allocs/op
BenchmarkPat_GithubAll               424           2899405 ns/op         1843501 B/op      29064 allocs/op

Road to v1

• Update route syntax @v0.6.0
• Route overlapping @v0.7.0
• Improving performance and polishing

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 implementing your own "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: some feature that implements Fox are inspired from Julien Schmidt's router. Most notably, this package uses the optimized httprouter.Cleanpath function.

Documentation

Index

• Constants
• Variables
• func CleanPath(p string) string
• func Has(t *Tree, method, path string) bool
• func NewTestContext(w http.ResponseWriter, r *http.Request) (*Router, Context)
• func Reverse(t *Tree, method, path string) string
• func Walk(tree *Tree, fn WalkFunc) error
• type Context
  • func NewTestContextOnly(fox *Router, w http.ResponseWriter, r *http.Request) Context
• type ContextCloser
• type ErrorHandlerFunc
  • func RouteErrorHandler() ErrorHandlerFunc
• type HTTPError
  • func NewHTTPError(code int, err ...error) HTTPError
  • func (e HTTPError) Error() string
• type HandlerFunc
  • func MethodNotAllowedHandler() HandlerFunc
  • func NotFoundHandler() HandlerFunc
  • func WrapF(f http.HandlerFunc) HandlerFunc
  • func WrapH(h http.Handler) HandlerFunc
• type Iterator
  • func NewIterator(t *Tree) *Iterator
  • func (it *Iterator) Handler() HandlerFunc
  • 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 MiddlewareFunc
  • func Recovery(handle RecoveryFunc) MiddlewareFunc
  • func WrapM(m func(handler http.Handler) http.Handler) MiddlewareFunc
• type Option
  • func DefaultOptions() Option
  • func WithHandleMethodNotAllowed(enable bool) Option
  • func WithMethodNotAllowed(handler HandlerFunc, m ...MiddlewareFunc) Option
  • func WithMiddleware(m ...MiddlewareFunc) Option
  • func WithRedirectFixedPath(enable bool) Option
  • func WithRedirectTrailingSlash(enable bool) Option
  • func WithRouteError(handler ErrorHandlerFunc) Option
  • func WithRouteNotFound(handler HandlerFunc, m ...MiddlewareFunc) Option
• type Param
• type Params
  • func (p Params) Clone() Params
  • func (p Params) Get(name string) string
• type RecoveryFunc
• type ResponseWriter
• type RouteConflictError
  • func (e *RouteConflictError) Error() string
  • func (e *RouteConflictError) Unwrap() error
• type Router
  • func New(opts ...Option) *Router
  • func (fox *Router) Handle(method, path string, handler HandlerFunc) error
  • func (fox *Router) MustHandle(method, path string, handler HandlerFunc)
  • 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 HandlerFunc) error
• type Tree
  • func (t *Tree) Handle(method, path string, handler HandlerFunc) error
  • func (t *Tree) Remove(method, path string) error
  • func (t *Tree) Update(method, path string, handler HandlerFunc) error
• type WalkFunc

Examples

• New
• NewIterator
• Router.Tree
• WithMiddleware

Constants

const (
	MIMEApplicationJSON                  = "application/json"
	MIMEApplicationJSONCharsetUTF8       = MIMEApplicationJSON + "; " + charsetUTF8
	MIMEApplicationJavaScript            = "application/javascript"
	MIMEApplicationJavaScriptCharsetUTF8 = MIMEApplicationJavaScript + "; " + charsetUTF8
	MIMEApplicationXML                   = "application/xml"
	MIMEApplicationXMLCharsetUTF8        = MIMEApplicationXML + "; " + charsetUTF8
	MIMETextXML                          = "text/xml"
	MIMETextXMLCharsetUTF8               = MIMETextXML + "; " + charsetUTF8
	MIMEApplicationForm                  = "application/x-www-form-urlencoded"
	MIMEApplicationProtobuf              = "application/protobuf"
	MIMEApplicationMsgpack               = "application/msgpack"
	MIMETextHTML                         = "text/html"
	MIMETextHTMLCharsetUTF8              = MIMETextHTML + "; " + charsetUTF8
	MIMETextPlain                        = "text/plain"
	MIMETextPlainCharsetUTF8             = MIMETextPlain + "; " + charsetUTF8
	MIMEMultipartForm                    = "multipart/form-data"
	MIMEOctetStream                      = "application/octet-stream"
)

MIME types

const (
	HeaderAccept         = "Accept"
	HeaderAcceptEncoding = "Accept-Encoding"
	// HeaderAllow is the name of the "Allow" header field used to list the set of methods
	// advertised as supported by the target resource. Returning an Allow header is mandatory
	// for status 405 (method not found) and useful for the OPTIONS method in responses.
	// See RFC 7231: https://datatracker.ietf.org/doc/html/rfc7231#section-7.4.1
	HeaderAllow               = "Allow"
	HeaderAuthorization       = "Authorization"
	HeaderContentDisposition  = "Content-Disposition"
	HeaderContentEncoding     = "Content-Encoding"
	HeaderContentLength       = "Content-Length"
	HeaderContentType         = "Content-Type"
	HeaderCookie              = "Cookie"
	HeaderSetCookie           = "Set-Cookie"
	HeaderIfModifiedSince     = "If-Modified-Since"
	HeaderLastModified        = "Last-Modified"
	HeaderLocation            = "Location"
	HeaderRetryAfter          = "Retry-After"
	HeaderUpgrade             = "Upgrade"
	HeaderVary                = "Vary"
	HeaderWWWAuthenticate     = "WWW-Authenticate"
	HeaderXForwardedFor       = "X-Forwarded-For"
	HeaderXForwardedProto     = "X-Forwarded-Proto"
	HeaderXForwardedProtocol  = "X-Forwarded-Protocol"
	HeaderXForwardedSsl       = "X-Forwarded-Ssl"
	HeaderXUrlScheme          = "X-Url-Scheme"
	HeaderXHTTPMethodOverride = "X-HTTP-Method-Override"
	HeaderXRealIP             = "X-Real-Ip"
	HeaderXRequestID          = "X-Request-Id"
	HeaderXCorrelationID      = "X-Correlation-Id"
	HeaderXRequestedWith      = "X-Requested-With"
	HeaderServer              = "Server"
	HeaderOrigin              = "Origin"
	HeaderCacheControl        = "Cache-Control"
	HeaderConnection          = "Connection"

	// Access control
	HeaderAccessControlRequestMethod    = "Access-Control-Request-Method"
	HeaderAccessControlRequestHeaders   = "Access-Control-Request-Headers"
	HeaderAccessControlAllowOrigin      = "Access-Control-Allow-Origin"
	HeaderAccessControlAllowMethods     = "Access-Control-Allow-Methods"
	HeaderAccessControlAllowHeaders     = "Access-Control-Allow-Headers"
	HeaderAccessControlAllowCredentials = "Access-Control-Allow-Credentials"
	HeaderAccessControlExposeHeaders    = "Access-Control-Expose-Headers"
	HeaderAccessControlMaxAge           = "Access-Control-Max-Age"

	// Security
	HeaderStrictTransportSecurity         = "Strict-Transport-Security"
	HeaderXContentTypeOptions             = "X-Content-Type-Options"
	HeaderXXSSProtection                  = "X-XSS-Protection"
	HeaderXFrameOptions                   = "X-Frame-Options"
	HeaderContentSecurityPolicy           = "Content-Security-Policy"
	HeaderContentSecurityPolicyReportOnly = "Content-Security-Policy-Report-Only"
	// nolint:gosec
	HeaderXCSRFToken     = "X-CSRF-Token"
	HeaderReferrerPolicy = "Referrer-Policy"
)

Headers

Variables

var (
	ErrRouteNotFound           = errors.New("route not found")
	ErrRouteExist              = errors.New("route already registered")
	ErrRouteConflict           = errors.New("route conflict")
	ErrInvalidRoute            = errors.New("invalid route")
	ErrDiscardedResponseWriter = errors.New("discarded response writer")
	ErrInvalidRedirectCode     = errors.New("invalid redirect code")
)

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

func CleanPath(p string) string

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:

1. Replace multiple slashes with a single slash.
2. Eliminate each . path name element (the current directory).
3. Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
4. 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

func Has(t *Tree, method, path string) bool

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 NewTestContext

func NewTestContext(w http.ResponseWriter, r *http.Request) (*Router, Context)

NewTestContext returns a new Router and its associated Context, designed only for testing purpose.

func Reverse

func Reverse(t *Tree, method, path string) string

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

func Walk(tree *Tree, fn WalkFunc) error

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 Context

type Context interface {
	// Done returns a channel that closes when the request's context is
	// cancelled or times out.
	Done() <-chan struct{}
	// Request returns the current *http.Request.
	Request() *http.Request
	// SetRequest sets the *http.Request.
	SetRequest(r *http.Request)
	// Writer returns the ResponseWriter.
	Writer() ResponseWriter
	// SetWriter sets the ResponseWriter.
	SetWriter(w ResponseWriter)
	// Path returns the registered path for the handler.
	Path() string
	// Params returns a Params slice containing the matched
	// wildcard parameters.
	Params() Params
	// Param retrieve a matching wildcard parameter by name.
	Param(name string) string
	// QueryParams parses the Request RawQuery and returns the corresponding values.
	QueryParams() url.Values
	// QueryParam returns the first query value associated with the given key.
	QueryParam(name string) string
	// String sends a formatted string with the specified status code.
	String(code int, format string, values ...any) error
	// Blob sends a byte slice with the specified status code and content type.
	Blob(code int, contentType string, buf []byte) error
	// Stream sends data from an io.Reader with the specified status code and content type.
	Stream(code int, contentType string, r io.Reader) error
	// Redirect sends an HTTP redirect response with the given status code and URL.
	Redirect(code int, url string) error
	// Clone returns a copy of the Context that is safe to use after the HandlerFunc returns.
	Clone() Context
	// Tree is a local copy of the Tree in use to serve the request.
	Tree() *Tree
	// Fox returns the Router in use to serve the request.
	Fox() *Router
}

Context represents the context of the current HTTP request. It provides methods to access request data and to write a response.

func NewTestContextOnly

func NewTestContextOnly(fox *Router, w http.ResponseWriter, r *http.Request) Context

type ContextCloser

type ContextCloser interface {
	Context
	Close()
}

ContextCloser extends Context for manually created instances, adding a Close method to release resources after use.

type ErrorHandlerFunc

type ErrorHandlerFunc func(c Context, err error)

ErrorHandlerFunc is a function type that handles errors returned by a HandlerFunc. It receives the Context and the error returned by the HandlerFunc, allowing centralized error management and custom error handling.

func RouteErrorHandler

func RouteErrorHandler() ErrorHandlerFunc

RouteErrorHandler returns an ErrorHandlerFunc that handle HandlerFunc error.

type HTTPError

type HTTPError struct {
	Err  error
	Code int
}

HTTPError represents an HTTP error with a status code (HTTPErrorCode) and an optional error message. If no error message is provided, the default error message for the status code will be used.

func NewHTTPError

func NewHTTPError(code int, err ...error) HTTPError

NewHTTPError creates a new HTTPError with the given status code and an optional error message.

func (HTTPError) Error

func (e HTTPError) Error() string

Error returns the error message associated with the HTTPError, or the default error message for the status code if none is provided.

type HandlerFunc

type HandlerFunc func(c Context) error

HandlerFunc is a function type that responds to an HTTP request. It enforces the same contract as http.Handler but provides additional feature like matched wildcard route segments via the Context type. The Context is freed once the HandlerFunc returns and may be reused later to save resources. If you need to hold the context longer, you have to copy it (see Clone method).

The function may return an error that can be propagated through the middleware chain and handled by the registered ErrorHandlerFunc, which is set using the WithRouteError option.

Similar to http.Handler, to abort a HandlerFunc so the client sees an interrupted response, panic with the value http.ErrAbortHandler.

HandlerFunc functions should be thread-safe, as they will be called concurrently.

func MethodNotAllowedHandler

func MethodNotAllowedHandler() HandlerFunc

MethodNotAllowedHandler returns a simple HandlerFunc that replies to each request with a “405 Method Not Allowed” reply.

func NotFoundHandler

func NotFoundHandler() HandlerFunc

NotFoundHandler returns a simple HandlerFunc that replies to each request with a “404 page not found” reply.

func WrapF

func WrapF(f http.HandlerFunc) HandlerFunc

WrapF is an adapter for wrapping http.HandlerFunc and returns a HandlerFunc function.

func WrapH

func WrapH(h http.Handler) HandlerFunc

WrapH is an adapter for wrapping http.Handler and returns a HandlerFunc function.

type Iterator

type Iterator struct {
	// contains filtered or unexported fields
}

func NewIterator

func NewIterator(t *Tree) *Iterator

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())
}

func (*Iterator) Handler

func (it *Iterator) Handler() HandlerFunc

Handler return the registered handler for the current route.

func (*Iterator) Method

func (it *Iterator) Method() string

Method returns the http method for the current route.

func (*Iterator) Next

func (it *Iterator) Next()

Next advance the iterator to the next route. Always check it.Valid() after a it.Next().

func (*Iterator) Path

func (it *Iterator) Path() string

Path returns the registered path for the current route.

func (*Iterator) Rewind

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

func (it *Iterator) SeekMethod(method string)

SeekMethod reset the iterator cursor to the first route for the given method. It does not keep tracking of previous seek.

func (*Iterator) SeekMethodPrefix

func (it *Iterator) SeekMethodPrefix(method, key string)

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

func (it *Iterator) SeekPrefix(key string)

SeekPrefix reset the iterator cursor to the first route starting with key. It does not keep tracking of previous seek.

func (*Iterator) Valid

func (it *Iterator) Valid() bool

Valid returns false when iteration is done.

type MiddlewareFunc

type MiddlewareFunc func(next HandlerFunc) HandlerFunc

MiddlewareFunc is a function type for implementing HandlerFunc middleware. The returned HandlerFunc usually wraps the input HandlerFunc, allowing you to perform operations before and/or after the wrapped HandlerFunc is executed. MiddlewareFunc functions should be thread-safe, as they will be called concurrently.

func Recovery

func Recovery(handle RecoveryFunc) MiddlewareFunc

Recovery is a middleware that captures panics and recovers from them. It takes a custom handle function that will be called with the Context and the value recovered from the panic. Note that the middleware check if the panic is caused by http.ErrAbortHandler and re-panic if true allowing the http server to handle it as an abort.

func WrapM

func WrapM(m func(handler http.Handler) http.Handler) MiddlewareFunc

WrapM is an adapter for wrapping http.Handler middleware and returns a MiddlewareFunc function.

type Option

type Option interface {
	// contains filtered or unexported methods
}

func DefaultOptions

func DefaultOptions() Option

DefaultOptions configure the router to use the Recovery middleware.

func WithHandleMethodNotAllowed

func WithHandleMethodNotAllowed(enable bool) Option

WithHandleMethodNotAllowed enable to returns 405 Method Not Allowed instead of 404 Not Found when the route exist for another http verb.

func WithMethodNotAllowed

func WithMethodNotAllowed(handler HandlerFunc, m ...MiddlewareFunc) Option

WithMethodNotAllowed register an HandlerFunc 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. Set WithHandleMethodNotAllowed to enable this option. By default, the MethodNotAllowedHandler is used.

func WithMiddleware

func WithMiddleware(m ...MiddlewareFunc) Option

WithMiddleware attaches a global middleware to the router. Middlewares provided will be chained in the order they were added. Note that it does NOT apply the middlewares to the NotFound and MethodNotAllowed handlers.

Example

// Define a custom middleware to measure the time taken for request processing and
// log the URL, route, time elapsed, and status code
metrics := func(next HandlerFunc) HandlerFunc {
	return func(c Context) error {
		start := time.Now()
		err := next(c)
		log.Printf("url=%s; route=%s; time=%d; status=%d", c.Request().URL, c.Path(), time.Since(start), c.Writer().Status())
		return err
	}
}

r := New(WithMiddleware(metrics))

r.MustHandle(http.MethodGet, "/hello/{name}", func(c Context) error {
	return c.String(200, "Hello %s\n", c.Param("name"))
})

func WithRedirectFixedPath

func WithRedirectFixedPath(enable bool) Option

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

func WithRedirectTrailingSlash(enable bool) Option

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 WithRouteError

func WithRouteError(handler ErrorHandlerFunc) Option

WithRouteError register an ErrorHandlerFunc which is called when an HandlerFunc returns an error. By default, the RouteErrorHandler is used.

func WithRouteNotFound

func WithRouteNotFound(handler HandlerFunc, m ...MiddlewareFunc) Option

WithRouteNotFound register an HandlerFunc which is called when no matching route is found. By default, the NotFoundHandler is used.

type Param

type Param struct {
	Key   string
	Value string
}

type Params

type Params []Param

func (Params) Clone

func (p Params) Clone() Params

Clone make a copy of Params.

func (Params) Get

func (p Params) Get(name string) string

Get the matching wildcard segment by name.

type RecoveryFunc

type RecoveryFunc func(c Context, err any)

RecoveryFunc is a function type that defines how to handle panics that occur during the handling of an HTTP request.

type ResponseWriter

type ResponseWriter interface {
	http.ResponseWriter
	// Status recorded after Write and WriteHeader.
	Status() int
	// Written returns true if the response has been written.
	Written() bool
	// Size returns the size of the written response.
	Size() int
	// Unwrap returns the underlying http.ResponseWriter.
	Unwrap() http.ResponseWriter
}

ResponseWriter extends http.ResponseWriter and provides methods to retrieve the recorded status code, written state, and response size.

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

func New(opts ...Option) *Router

New returns a ready to use instance of Fox router.

Example

This example demonstrates how to create a simple router using the default options, which include the Recovery middleware. A basic route is defined, along with a custom middleware to log the request metrics.

// Create a new router with default options, which include the Recovery middleware
r := New(DefaultOptions())

// Define a custom middleware to measure the time taken for request processing and
// log the URL, route, time elapsed, and status code
metrics := func(next HandlerFunc) HandlerFunc {
	return func(c Context) error {
		start := time.Now()
		err := next(c)
		log.Printf("url=%s; route=%s; time=%d; status=%d", c.Request().URL, c.Path(), time.Since(start), c.Writer().Status())
		return err
	}
}

// Define a route with the path "/hello/{name}", apply the custom "metrics" middleware,
// and set a simple handler that greets the user by their name
r.MustHandle(http.MethodGet, "/hello/{name}", metrics(func(c Context) error {
	return c.String(200, "Hello %s\n", c.Param("name"))
}))

// Start the HTTP server using the router as the handler and listen on port 8080
log.Fatalln(http.ListenAndServe(":8080", r))

func (*Router) Handle

func (fox *Router) Handle(method, path string, handler HandlerFunc) error

Handle 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) MustHandle

func (fox *Router) MustHandle(method, path string, handler HandlerFunc)

MustHandle registers a new handler for the given method and path. This function is a convenience wrapper for the Handle function. It will panic if the route is already registered or conflicts with another route. 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 goroutines. To override an existing route, use Update.

func (*Router) NewTree

func (fox *Router) NewTree() *Tree

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

func (fox *Router) Remove(method, path string) error

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) ServeHTTP

func (fox *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Router) Swap

func (fox *Router) Swap(new *Tree) (old *Tree)

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

func (fox *Router) Tree() *Tree

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 HandlerFunc) error {
	tree.Lock()
	defer tree.Unlock()
	if Has(tree, method, path) {
		return tree.Update(method, path, handler)
	}
	return tree.Handle(method, path, handler)
}

_ = upsert(http.MethodGet, "/foo/bar", func(c Context) error {
	// Note the tree accessible from fox.Context is already a local copy so the golden rule above does not apply.
	c.Tree().Lock()
	defer c.Tree().Unlock()
	return c.String(200, "foo bar")
})

// Bad, instead make a local copy of the tree!
upsert = func(method, path string, handler HandlerFunc) error {
	r.Tree().Lock()
	defer r.Tree().Unlock()
	if Has(r.Tree(), method, path) {
		return r.Tree().Update(method, path, handler)
	}
	return r.Tree().Handle(method, path, handler)
}

func (*Router) Update

func (fox *Router) Update(method, path string, handler HandlerFunc) error

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 Handle method.

type Tree

type Tree struct {
	sync.Mutex
	// contains filtered or unexported fields
}

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 that may be used to serialize write. Since the router tree may be swapped at any given time, you MUST always copy the pointer locally to avoid inadvertently 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()

func (*Tree) Handle

func (t *Tree) Handle(method, path string, handler HandlerFunc) error

Handle 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

func (t *Tree) Remove(method, path string) error

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

func (t *Tree) Update(method, path string, handler HandlerFunc) error

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 Handle method.

type WalkFunc

type WalkFunc func(method, path string, handler HandlerFunc) error

WalkFunc is the type of the function called by Walk to visit each registered routes.