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

Runtime updates: 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.

Automatic OPTIONS responses: Inspired from httprouter, the router has built-in native support for OPTIONS requests.

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) {
	_ = c.String(http.StatusOK, "%s %s\n", h.Say, c.Param("name"))
}

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

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

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

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

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 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) {
    cc := c.Clone()
    // cp := c.Params().Clone()
    go func() {
        time.Sleep(2 * time.Second)
        log.Println(cc.Param("name")) // Safe
    }()
    _ = 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"
	"fmt"
	"github.com/tigerwill90/fox"
	"log"
	"net/http"
	"strings"
)

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

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

	if path == "" || method == "" {
		http.Error(c.Writer(), "missing method or path", http.StatusBadRequest)
		return
	}

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

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

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

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) {
	log.Printf("matched handler path: %s", c.Path())
	_ = c.Stream(
		http.StatusOK,
		fox.MIMETextHTMLCharsetUTF8,
		strings.NewReader(string(h.Template)),
	)
}

func main() {
	f := fox.New()
	go Reload(f)
	log.Fatalln(http.ListenAndServe(":8080", f))
}

func Reload(r *fox.Router) {
	for ; true; <-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 t.Has(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) {
    c.Fox().Tree().Lock()
    defer c.Fox().Tree().Unlock()
}

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) {
    c.Tree().Lock()
    defer c.Tree().Unlock()
}

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

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

Wrapping an http.Handler compatible middleware

f := fox.New(fox.DefaultOptions(), fox.WithMiddleware(fox.WrapM(httpRateLimiter.RateLimit, false)))
f.MustHandle(http.MethodGet, "/articles/{id}", func(c fox.Context) {
    _ = 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 routes (including 404, 405, etc...).

package main

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

func Logger(next fox.HandlerFunc) fox.HandlerFunc {
	return func(c fox.Context) {
		start := time.Now()
		next(c)
		log.Printf("route: %s, latency: %s, status: %d, size: %d",
			c.Path(),
			time.Since(start),
			c.Writer().Status(),
			c.Writer().Size(),
		)
	}
}

func main() {
	f := fox.New(fox.WithMiddleware(Logger))

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

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

Additionally, fox.WithMiddlewareFor option provide a more fine-grained control over where a middleware is applied, such as only for 404 or 405 handlers. Possible scopes include fox.RouteHandlers (regular routes), fox.NoRouteHandler, fox.NoMethodHandler, fox.RedirectHandler, fox.OptionsHandler and any combination of these.

f := fox.New(
    fox.WithMethodNotAllowed(true),
    fox.WithMiddlewareFor(fox.RouteHandlers, fox.Recovery(fox.DefaultHandleRecovery), Logger),
    fox.WithMiddlewareFor(fox.NoRouteHandler|fox.NoMethodHandler, SpecialLogger),
)

Official middlewares

• tigerwill90/otelfox: Distributed tracing with OpenTelemetry

Handling OPTIONS Requests and CORS Automatically

The WithAutoOptions setting or the WithOptionsHandler registration enable automatic responses to OPTIONS requests. This feature can be particularly useful in the context of Cross-Origin Resource Sharing (CORS).

An OPTIONS request is a type of HTTP request that is used to determine the communication options available for a given resource or API endpoint. These requests are commonly used as "preflight" requests in CORS to check if the CORS protocol is understood and to get permission to access data based on origin.

When automatic OPTIONS responses is enabled, the router will automatically respond to preflight OPTIONS requests and set the Allow header with the appropriate value. To customize how OPTIONS requests are handled (e.g. adding CORS headers), you may register a middleware for the fox.OptionsHandler scope or override the default handler.

f := fox.New(
    fox.WithOptionsHandler(func(c fox.Context) {
        if c.Header("Access-Control-Request-Method") != "" {
            // Setting CORS headers.
            c.SetHeader("Access-Control-Allow-Methods", c.Writer().Header().Get("Allow"))
            c.SetHeader("Access-Control-Allow-Origin", "*")
        }

        // Respond with a 204 status code.
        c.Writer().WriteHeader(http.StatusNoContent)
    }),
)

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: 1

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: 1

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: 1

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.
• The router API is influenced by popular routers such as gin and echo.

Documentation

Index

• Constants
• Variables
• func CleanPath(p string) string
• func DefaultHandleRecovery(c Context, err any)
• 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 HandlerFunc
  • func DefaultMethodNotAllowedHandler() HandlerFunc
  • func DefaultNotFoundHandler() HandlerFunc
  • func WrapF(f http.HandlerFunc) HandlerFunc
  • func WrapH(h http.Handler) HandlerFunc
  • func WrapTestContext(next HandlerFunc) 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, useOriginalWriter bool) MiddlewareFunc
• type MiddlewareScope
• type Option
  • func DefaultOptions() Option
  • func WithAutoOptions(enable bool) Option
  • func WithMiddleware(m ...MiddlewareFunc) Option
  • func WithMiddlewareFor(scope MiddlewareScope, m ...MiddlewareFunc) Option
  • func WithNoMethod(enable bool) Option
  • func WithNoMethodHandler(handler HandlerFunc) Option
  • func WithNoRouteHandler(handler HandlerFunc) Option
  • func WithOptionsHandler(handler HandlerFunc) Option
  • func WithRedirectTrailingSlash(enable bool) 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) Has(method, path string) bool
  • func (t *Tree) Lookup(method, path string, lazy bool) (handler HandlerFunc, cc ContextCloser, tsr bool)
  • func (t *Tree) LookupMethods(path string) (methods []string)
  • func (t *Tree) Methods() []string
  • 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
• Tree.Lookup
• WithMiddleware
• WrapM

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"
	HeaderETag                = "ETag"

	// 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 DefaultHandleRecovery

func DefaultHandleRecovery(c Context, err any)

DefaultHandleRecovery is a default implementation of the RecoveryFunc. It logs the recovered panic error to stderr, including the stack trace. If the response has not been written yet and the error is not caused by a broken connection, it sets the status code to http.StatusInternalServerError and writes a generic error message.

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 {
	// Ctx returns the context associated with the current request.
	Ctx() ctx.Context
	// Request returns the current *http.Request.
	Request() *http.Request
	// SetRequest sets the *http.Request.
	SetRequest(r *http.Request)
	// Writer method returns a custom ResponseWriter implementation. The returned ResponseWriter object implements additional
	// http.Flusher, http.Hijacker, io.ReaderFrom interfaces for HTTP/1.x requests and http.Flusher, http.Pusher interfaces
	// for HTTP/2 requests. These additional interfaces provide extra functionality and are used by underlying HTTP protocols
	// for specific tasks.
	//
	// In actual workload scenarios, the custom ResponseWriter satisfies interfaces for HTTP/1.x and HTTP/2 protocols,
	// however, if testing with e.g. httptest.Recorder, only the http.Flusher is available to the underlying ResponseWriter.
	// Therefore, while asserting interfaces like http.Hijacker will not fail, invoking Hijack method will panic if the
	// underlying ResponseWriter does not implement this interface.
	//
	// To facilitate testing with e.g. httptest.Recorder, use the WrapTestContext helper function which only exposes the
	// http.Flusher interface for the ResponseWriter.
	Writer() ResponseWriter
	// SetWriter sets the ResponseWriter.
	SetWriter(w ResponseWriter)
	// TeeWriter append an additional writer (sink) to which the response body will be written.
	// This API is EXPERIMENTAL and is likely to change in future release.
	TeeWriter(w io.Writer)
	// 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
	// SetHeader sets the response header for the given key to the specified value.
	SetHeader(key, value string)
	// Header retrieves the value of the request header for the given key.
	Header(key 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
	// Reset resets the Context to its initial state, attaching the provided Router,
	// http.ResponseWriter, and *http.Request.
	Reset(fox *Router, w http.ResponseWriter, r *http.Request)
}

Context represents the context of the current HTTP request. It provides methods to access request data and to write a response. Be aware that the Context API is not thread-safe and its lifetime should be limited to the duration of the HandlerFunc execution, as the underlying implementation may be reused a soon as the handler return. (see Clone method).

func NewTestContextOnly

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

NewTestContextOnly returns a new Context associated with the provided Router, designed only for testing purpose.

type ContextCloser

type ContextCloser interface {
	Context
	Close()
}

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

type HandlerFunc

type HandlerFunc func(c Context)

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

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 DefaultMethodNotAllowedHandler

func DefaultMethodNotAllowedHandler() HandlerFunc

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

func DefaultNotFoundHandler

func DefaultNotFoundHandler() HandlerFunc

DefaultNotFoundHandler 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.

func WrapTestContext

func WrapTestContext(next HandlerFunc) HandlerFunc

WrapTestContext method is a helper function provided for testing purposes. It wraps the provided HandlerFunc, returning a new HandlerFunc that only exposes the http.Flusher interface of the ResponseWriter. This is useful when testing implementations that rely on interface assertions with e.g. httptest.Recorder, since its only supports the http.Flusher interface.

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, useOriginalWriter bool) MiddlewareFunc

WrapM is an adapter for converting http.Handler middleware into a MiddlewareFunc. The boolean parameter, useOriginalWriter, determines how the middleware interacts with the ResponseWriter:

• If useOriginalWriter is false, the middleware is provided with the ResponseWriter from the Fox router. This is suitable for middlewares that may write a response and stop further execution (like an authorization middleware). The Fox's ResponseWriter allows to keep track of the response status and size.
• If useOriginalWriter is true, the middleware is provided with the original http.ResponseWriter from Go's net/http package. This is required for middlewares that need to wrap the ResponseWriter with their own implementation (like a gzip middleware). The Wrap function is used to ensure that the Fox's ResponseWriter wraps the middleware's ResponseWriter implementation.

This API is EXPERIMENTAL and is likely to change in future release.

Example

This example demonstrates the usage of the WrapM function which is used to wrap an http.Handler middleware and returns a MiddlewareFunc function compatible with Fox.

// Case 1: Middleware that may write a response and stop execution.
// This is commonly seen in middleware that implements authorization checks. If the check does not pass,
// the middleware can stop the execution of the subsequent handlers and write an error response.
// The "authorizationMiddleware" in this example checks for a specific token in the request's Authorization header.
// If the token is not the expected value, it sends an HTTP 401 Unauthorized error and stops the execution.
// In this case, the WrapM function is used with the "useOriginalWriter" set to false, as we want to use
// the custom ResponseWriter provided by the Fox framework to capture the status code and response size.
authorizationMiddleware := func(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		token := r.Header.Get("Authorization")
		if token != "valid-token" {
			http.Error(w, "Invalid token", http.StatusUnauthorized)
			return
		}
		next.ServeHTTP(w, r)
	})
}

_ = New(WithMiddleware(WrapM(authorizationMiddleware, false)))

// Case 2: Middleware that wraps the ResponseWriter with its own implementation.
// This is typically used in middleware that transforms the response in some way, for instance by applying gzip compression.
// The "gzipMiddleware" in this example wraps the original ResponseWriter with a gzip writer, which compresses the response data.
// In this case, the WrapM function is used with the "useOriginalWriter" set to true, as the middleware needs to wrap the original
// http.ResponseWriter with its own implementation. After wrapping, the Fox framework's ResponseWriter is updated to the new ResponseWriter.
gzipMiddleware := func(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		gz := gzip.NewWriter(w)
		defer gz.Close()

		// Create a new ResponseWriter that writes to the gzip writer
		gzw := gzipResponseWriter{Writer: gz, ResponseWriter: w}
		r.Header.Set("Content-Encoding", "gzip")
		next.ServeHTTP(gzw, r)
	})
}

_ = New(WithMiddleware(WrapM(gzipMiddleware, true)))

type MiddlewareScope

type MiddlewareScope uint8

MiddlewareScope is a type that represents different scopes for applying middleware.

const (
	// RouteHandlers scope applies middleware only to regular routes registered in the router.
	RouteHandlers MiddlewareScope = 1 << (8 - 1 - iota)
	// NoRouteHandler scope applies middleware to the NoRoute handler.
	NoRouteHandler
	// NoMethodHandler scope applies middleware to the NoMethod handler.
	NoMethodHandler
	// RedirectHandler scope applies middleware to the internal redirect trailing slash handler.
	RedirectHandler
	// OptionsHandler scope applies middleware to the internal automatic OPTIONS handler.
	OptionsHandler
	// AllHandlers is a combination of all the above scopes, which means the middleware will be applied to all types of handlers.
	AllHandlers = RouteHandlers | NoRouteHandler | NoMethodHandler | RedirectHandler | OptionsHandler
)

type Option

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

func DefaultOptions

func DefaultOptions() Option

DefaultOptions configure the router to use the Recovery middleware for the RouteHandlers scope and enable automatic OPTIONS response. Note that DefaultOptions push the Recovery middleware to the first position of the middleware chains.

func WithAutoOptions

func WithAutoOptions(enable bool) Option

WithAutoOptions enables automatic response to OPTIONS requests with, by default, a 200 OK status code. Use the WithOptionsHandler option to customize the response. When this option is enabled, the router automatically determines the "Allow" header value based on the methods registered for the given route. Note that custom OPTIONS handler take priority over automatic replies. This option is automatically enabled when providing a custom handler with the option WithOptionsHandler. This api is EXPERIMENTAL and is likely to change in future release.

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 this option apply middleware to all handler, including NotFound, MethodNotAllowed and the internal redirect handler.

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) {
		start := time.Now()
		next(c)
		log.Printf(
			"url=%s; route=%s; time=%d; status=%d",
			c.Request().URL,
			c.Path(),
			time.Since(start),
			c.Writer().Status(),
		)
	}
}

r := New(WithMiddleware(metrics))

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

func WithMiddlewareFor

func WithMiddlewareFor(scope MiddlewareScope, m ...MiddlewareFunc) Option

WithMiddlewareFor attaches middleware to the router for a specified scope. Middlewares provided will be chained in the order they were added. The scope parameter determines which types of handlers the middleware will be applied to. Possible scopes include RouteHandlers (regular routes), NoRouteHandler, NoMethodHandler, RedirectHandler, and any combination of these. Use this option when you need fine-grained control over where the middleware is applied. This api is EXPERIMENTAL and is likely to change in future release.

func WithNoMethod

func WithNoMethod(enable bool) Option

WithNoMethod enable to returns 405 Method Not Allowed instead of 404 Not Found when the route exist for another http verb. The "Allow" header it automatically set before calling the handler. Note that this option is automatically enabled when providing a custom handler with the option WithNoMethodHandler.

func WithNoMethodHandler

func WithNoMethodHandler(handler HandlerFunc) Option

WithNoMethodHandler 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. By default, the DefaultMethodNotAllowedHandler is used. Note that this option automatically enable WithNoMethod.

func WithNoRouteHandler

func WithNoRouteHandler(handler HandlerFunc) Option

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

func WithOptionsHandler

func WithOptionsHandler(handler HandlerFunc) Option

WithOptionsHandler register an HandlerFunc which is called on automatic OPTIONS requests. By default, the router respond with a 200 OK status code. The "Allow" header it automatically set before calling the handler. Note that custom OPTIONS handler take priority over automatic replies. This option automatically enable WithAutoOptions. This api is EXPERIMENTAL and is likely to change in future release.

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.

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
	// Wrap replaces the underlying http.ResponseWriter for the current ResponseWriter. It does not reset the status,
	// written state, or response size of the current ResponseWriter. Caution: You should pass the original
	// http.ResponseWriter to this method, not the ResponseWriter itself, to avoid wrapping the ResponseWriter within itself.
	Wrap(w http.ResponseWriter)
	// WriteString writes the provided string to the underlying connection
	// as part of an HTTP reply. The method returns the number of bytes written
	// and an error, if any.
	WriteString(s string) (int, error)
}

ResponseWriter extends http.ResponseWriter and provides methods to retrieve the recorded status code, written state, and response size. ResponseWriter object implements additional http.Flusher, http.Hijacker, io.ReaderFrom interfaces for HTTP/1.x requests and http.Flusher, http.Pusher interfaces for HTTP/2 requests.

type RouteConflictError

type RouteConflictError struct {
	Method  string
	Path    string
	Matched []string
	// contains filtered or unexported fields
}

RouteConflictError is a custom error type used to represent conflicts when registering or updating routes in the router. It holds information about the conflicting method, path, and the matched routes that caused the conflict.

func (*RouteConflictError) Error

func (e *RouteConflictError) Error() string

Error returns a formatted error message for the RouteConflictError.

func (*RouteConflictError) Unwrap

func (e *RouteConflictError) Unwrap() error

Unwrap returns the sentinel value ErrRouteConflict.

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) {
		start := time.Now()
		next(c)
		log.Printf("url=%s; route=%s; time=%d; status=%d", c.Request().URL, c.Path(), time.Since(start), c.Writer().Status())
	}
}

// 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) {
	_ = 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. It's safe to create multiple Tree concurrently. However, a Tree itself is not thread-safe and all its APIs that perform write operations 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 tree.Has(method, path) {
		return tree.Update(method, path, handler)
	}
	return tree.Handle(method, path, handler)
}

_ = upsert(http.MethodGet, "/foo/bar", func(c Context) {
	// 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()
	_ = c.String(200, "foo bar")
})

// Bad, instead make a local copy of the tree!
_ = func(method, path string, handler HandlerFunc) error {
	r.Tree().Lock()
	defer r.Tree().Unlock()
	if r.Tree().Has(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 APIs that perform write operations. To override an existing route, use Update.

func (*Tree) Has

func (t *Tree) Has(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 (*Tree) Lookup

func (t *Tree) Lookup(method, path string, lazy bool) (handler HandlerFunc, cc ContextCloser, tsr bool)

Lookup allow to do manual lookup of a route for the given method and path and return the matched HandlerFunc along with a ContextCloser and trailing slash redirect recommendation. If lazy is set to true, wildcard parameter are not parsed. You should always close the ContextCloser if NOT nil by calling cc.Close(). Note that the returned ContextCloser does not have a router, request and response writer attached (use the Reset method). 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.

Example

This example demonstrates how to create a custom middleware that cleans the request path and performs a manual lookup on the tree. If the cleaned path matches a registered route, the client is redirected with a 301 status code (Moved Permanently).

redirectFixedPath := MiddlewareFunc(func(next HandlerFunc) HandlerFunc {
	return func(c Context) {
		req := c.Request()

		cleanedPath := CleanPath(req.URL.Path)
		handler, cc, _ := c.Tree().Lookup(req.Method, cleanedPath, true)
		// You should always close a non-nil Context.
		if cc != nil {
			defer cc.Close()
		}

		// 301 redirect and returns.
		if handler != nil {
			req.URL.Path = cleanedPath
			http.Redirect(c.Writer(), req, req.URL.String(), http.StatusMovedPermanently)
			return
		}

		next(c)
	}
})

f := New(
	// Register the middleware for the NoRouteHandler scope.
	WithMiddlewareFor(NoRouteHandler, redirectFixedPath),
)

f.MustHandle(http.MethodGet, "/foo/bar", func(c Context) {
	_ = c.String(http.StatusOK, "foo bar")
})

func (*Tree) LookupMethods

func (t *Tree) LookupMethods(path string) (methods []string)

LookupMethods lookup and returns all HTTP methods associated with a route that match the given path. 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 (*Tree) Methods

func (t *Tree) Methods() []string

Methods returns a sorted slice of HTTP methods that are currently in use to route requests. 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 (*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 APIs that perform write operations.

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 APIs that perform write operations. 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.