bunrouter

package module
Version: v1.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2021 License: MIT Imports: 9 Imported by: 3

README

Fast and flexible HTTP router for Go

build workflow PkgGoDev Documentation Chat

TLDR BunRouter is as fast as httprouter, but supports middlewares, routing rules priority, and error handling.

BunRouter is an extremely fast HTTP router for Go with unique combination of features:

  • Middlewares allow to extract common operations from HTTP handlers into reusable functions.
  • Error handling allows to further reduce the size of HTTP handlers by handling errors in middlewares.
  • Routes priority enables meaningful matching priority for routing rules: first static nodes, then named nodes, lastly wildcard nodes.
  • net/http compatible API which means using minimal API without constructing huge wrappers that try to do everything: from serving static files to XML generation (for example, gin.Context or echo.Context).
Router Middlewares Error handling Routes priority net/http API
BunRouter ✔️ ✔️ ✔️ ✔️
httprouter ✔️
Chi ✔️ ✔️ ✔️
Echo ✔️ ✔️
Gin ✔️ ✔️

Learn:

Examples:

Projects using BunRouter:

Benchmarks:

Benchmark results
BenchmarkGin_Param               	16019718	        74.16 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_Param        	12560001	        95.04 ns/op	      32 B/op	       1 allocs/op
BenchmarkBunrouter_Param         	50015306	        23.81 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_Param5              	 8997234	       131.5 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_Param5       	 4809441	       261.3 ns/op	     160 B/op	       1 allocs/op
BenchmarkBunrouter_Param5        	10789635	       114.0 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_Param20             	 3953041	       302.4 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_Param20      	 1661373	       743.3 ns/op	     640 B/op	       1 allocs/op
BenchmarkBunrouter_Param20       	 2462354	       482.8 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_ParamWrite          	 9258986	       128.0 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_ParamWrite   	 9908178	       123.0 ns/op	      32 B/op	       1 allocs/op
BenchmarkBunrouter_ParamWrite    	15511226	        70.62 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GithubStatic        	12781513	        94.17 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_GithubStatic 	30077443	        37.36 ns/op	       0 B/op	       0 allocs/op
BenchmarkBunrouter_GithubStatic  	37160334	        32.41 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GithubParam         	 6971791	       169.2 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_GithubParam  	 5464755	       217.4 ns/op	      96 B/op	       1 allocs/op
BenchmarkBunrouter_GithubParam   	12047902	       101.2 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GithubAll           	   32758	     37382 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_GithubAll    	   27324	     43932 ns/op	   13792 B/op	     167 allocs/op
BenchmarkBunrouter_GithubAll     	   57910	     20914 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GPlusStatic         	17788194	        69.13 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_GPlusStatic  	60191341	        19.84 ns/op	       0 B/op	       0 allocs/op
BenchmarkBunrouter_GPlusStatic   	87114368	        14.06 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GPlusParam          	10075399	       119.5 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_GPlusParam   	 8272046	       149.2 ns/op	      64 B/op	       1 allocs/op
BenchmarkBunrouter_GPlusParam    	37359979	        32.43 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GPlus2Params        	 7375279	       162.9 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_GPlus2Params 	 6538942	       186.7 ns/op	      64 B/op	       1 allocs/op
BenchmarkBunrouter_GPlus2Params  	19681939	        61.51 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GPlusAll            	  647716	      1752 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_GPlusAll     	  590356	      2085 ns/op	     640 B/op	      11 allocs/op
BenchmarkBunrouter_GPlusAll      	 1685287	       712.8 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_ParseStatic         	14566458	        76.58 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_ParseStatic  	52994076	        21.02 ns/op	       0 B/op	       0 allocs/op
BenchmarkBunrouter_ParseStatic   	50583933	        23.83 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_ParseParam          	13443874	        90.66 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_ParseParam   	 8825664	       135.6 ns/op	      64 B/op	       1 allocs/op
BenchmarkBunrouter_ParseParam    	38058278	        31.33 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_Parse2Params        	10179813	       118.1 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_Parse2Params 	 7801735	       152.9 ns/op	      64 B/op	       1 allocs/op
BenchmarkBunrouter_Parse2Params  	23704574	        50.78 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_ParseAll            	  394884	      3073 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_ParseAll     	  410238	      3011 ns/op	     640 B/op	      16 allocs/op
BenchmarkBunrouter_ParseAll      	  810908	      1487 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_StaticAll           	   50658	     23699 ns/op	       0 B/op	       0 allocs/op
BenchmarkHttpRouter_StaticAll    	  105313	     11518 ns/op	       0 B/op	       0 allocs/op
BenchmarkBunrouter_StaticAll     	   99674	     12188 ns/op	       0 B/op	       0 allocs/op

Quickstart

Install:

go get github.com/uptrace/bunrouter

Run the example:

package main

import (
	"html/template"
	"log"
	"net/http"

	"github.com/uptrace/bunrouter"
	"github.com/uptrace/bunrouter/extra/reqlog"
)

func main() {
	router := bunrouter.New(
		bunrouter.WithMiddleware(reqlog.NewMiddleware()),
	)

	router.GET("/", indexHandler)

	router.WithGroup("/api", func(g *bunrouter.Group) {
		g.GET("/users/:id", debugHandler)
		g.GET("/users/current", debugHandler)
		g.GET("/users/*path", debugHandler)
	})

	log.Println("listening on http://localhost:9999")
	log.Println(http.ListenAndServe(":9999", router))
}

func indexHandler(w http.ResponseWriter, req bunrouter.Request) error {
	return indexTemplate().Execute(w, nil)
}

func debugHandler(w http.ResponseWriter, req bunrouter.Request) error {
	return bunrouter.JSON(w, bunrouter.H{
		"route":  req.Route(),
		"params": req.Params().Map(),
	})
}

var indexTmpl = `
<html>
  <h1>Welcome</h1>
  <ul>
    <li><a href="/api/users/123">/api/users/123</a></li>
    <li><a href="/api/users/current">/api/users/current</a></li>
    <li><a href="/api/users/foo/bar">/api/users/foo/bar</a></li>
  </ul>
</html>
`

func indexTemplate() *template.Template {
	return template.Must(template.New("index").Parse(indexTmpl))
}

See the documentation for details.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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 JSON

func JSON(w http.ResponseWriter, value interface{}) error

JSON marshals the value as JSON and writes it to the response writer.

Don't hesitate to copy-paste this function to your project and customize it as necessary.

func Version

func Version() string

Version is the current release version.

Types

type CompatGroup

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

CompatGroup is like Group, but it works with http.HandlerFunc instead of bunrouter handler.

func (CompatGroup) DELETE

func (g CompatGroup) DELETE(path string, handler http.HandlerFunc)

func (CompatGroup) GET

func (g CompatGroup) GET(path string, handler http.HandlerFunc)

func (CompatGroup) HEAD

func (g CompatGroup) HEAD(path string, handler http.HandlerFunc)

func (CompatGroup) Handle

func (g CompatGroup) Handle(method string, path string, handler http.HandlerFunc)

func (CompatGroup) NewGroup

func (g CompatGroup) NewGroup(path string, opts ...GroupOption) *CompatGroup

func (CompatGroup) OPTIONS

func (g CompatGroup) OPTIONS(path string, handler http.HandlerFunc)

func (CompatGroup) PATCH

func (g CompatGroup) PATCH(path string, handler http.HandlerFunc)

func (CompatGroup) POST

func (g CompatGroup) POST(path string, handler http.HandlerFunc)

func (CompatGroup) PUT

func (g CompatGroup) PUT(path string, handler http.HandlerFunc)

func (CompatGroup) WithGroup

func (g CompatGroup) WithGroup(path string, fn func(g *CompatGroup))

func (CompatGroup) WithMiddleware

func (g CompatGroup) WithMiddleware(middleware MiddlewareFunc) *CompatGroup

type CompatRouter

type CompatRouter struct {
	*Router
	*CompatGroup
}

type Group

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

Group is a group of routes and middlewares.

func (*Group) Compat

func (g *Group) Compat() *CompatGroup

func (*Group) DELETE

func (g *Group) DELETE(path string, handler HandlerFunc)

Syntactic sugar for Handle("DELETE", path, handler)

func (*Group) GET

func (g *Group) GET(path string, handler HandlerFunc)

Syntactic sugar for Handle("GET", path, handler)

func (*Group) HEAD

func (g *Group) HEAD(path string, handler HandlerFunc)

Syntactic sugar for Handle("HEAD", path, handler)

func (*Group) Handle

func (g *Group) Handle(meth string, path string, handler HandlerFunc)

func (*Group) NewGroup

func (g *Group) NewGroup(path string, opts ...GroupOption) *Group

NewGroup adds a sub-group to this group.

func (*Group) OPTIONS

func (g *Group) OPTIONS(path string, handler HandlerFunc)

Syntactic sugar for Handle("OPTIONS", path, handler)

func (*Group) PATCH

func (g *Group) PATCH(path string, handler HandlerFunc)

Syntactic sugar for Handle("PATCH", path, handler)

func (*Group) POST

func (g *Group) POST(path string, handler HandlerFunc)

Syntactic sugar for Handle("POST", path, handler)

func (*Group) PUT

func (g *Group) PUT(path string, handler HandlerFunc)

Syntactic sugar for Handle("PUT", path, handler)

func (*Group) Verbose

func (g *Group) Verbose() *VerboseGroup

func (*Group) WithGroup

func (g *Group) WithGroup(path string, fn func(g *Group))

func (*Group) WithMiddleware

func (g *Group) WithMiddleware(middleware MiddlewareFunc) *Group

type GroupOption

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

func WithGroup

func WithGroup(fn func(g *Group)) GroupOption

WithGroup calls the fn with the current Group.

func WithHandler

func WithHandler(fn HandlerFunc) GroupOption

WithHandler is like WithMiddleware, but the handler can't modify the request.

func WithMiddleware

func WithMiddleware(fn MiddlewareFunc) GroupOption

WithMiddleware adds a middleware handler to the Group's middleware stack.

type H

type H map[string]interface{}

type HandlerFunc

type HandlerFunc func(w http.ResponseWriter, req Request) error

func HTTPHandler

func HTTPHandler(handler http.Handler) HandlerFunc

HTTPHandler converts http.Handler to bunrouter.HandlerFunc.

func HTTPHandlerFunc

func HTTPHandlerFunc(handler http.HandlerFunc) HandlerFunc

HTTPHandlerFunc converts http.HandlerFunc to bunrouter.HandlerFunc.

func (HandlerFunc) ServeHTTP added in v1.0.5

func (h HandlerFunc) ServeHTTP(w http.ResponseWriter, req *http.Request)

type MiddlewareFunc

type MiddlewareFunc func(next HandlerFunc) HandlerFunc

type Option

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

func WithMethodNotAllowedHandler

func WithMethodNotAllowedHandler(handler HandlerFunc) Option

MethodNotAllowedHandler is called when a route matches, but that route does not have a handler for the requested method. The default handler just writes the status code http.StatusMethodNotAllowed.

func WithNotFoundHandler

func WithNotFoundHandler(handler HandlerFunc) Option

WithNotFoundHandler is called when there is no a matching pattern. The default NotFoundHandler is http.NotFound.

type Param

type Param struct {
	Key   string
	Value string
}

type Params

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

func ParamsFromContext

func ParamsFromContext(ctx context.Context) Params

func (Params) ByName

func (ps Params) ByName(name string) string

func (Params) Get

func (ps Params) Get(name string) (string, bool)

func (Params) Int32

func (ps Params) Int32(name string) (int32, error)

func (Params) Int64

func (ps Params) Int64(name string) (int64, error)

func (Params) IsZero added in v1.0.5

func (ps Params) IsZero() bool

func (Params) Map

func (ps Params) Map() map[string]string

func (Params) Route

func (ps Params) Route() string

func (Params) Slice

func (ps Params) Slice() []Param

func (Params) Uint32

func (ps Params) Uint32(name string) (uint32, error)

func (Params) Uint64

func (ps Params) Uint64(name string) (uint64, error)

type Request

type Request struct {
	*http.Request
	// contains filtered or unexported fields
}

func NewRequest

func NewRequest(req *http.Request) Request

func (Request) Param

func (req Request) Param(key string) string

func (Request) Params

func (req Request) Params() Params

func (Request) Route

func (req Request) Route() string

func (Request) WithContext

func (req Request) WithContext(ctx context.Context) Request

type Router

type Router struct {
	Group
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) *Router

func (*Router) Compat

func (r *Router) Compat() *CompatRouter

func (*Router) ServeHTTP

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

func (*Router) Verbose

func (r *Router) Verbose() *VerboseRouter

type VerboseGroup

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

VerboseGroup is like Group, but it works with VerboseHandlerFunc instead of bunrouter handler.

func (VerboseGroup) DELETE

func (g VerboseGroup) DELETE(path string, handler VerboseHandlerFunc)

func (VerboseGroup) GET

func (g VerboseGroup) GET(path string, handler VerboseHandlerFunc)

func (VerboseGroup) HEAD

func (g VerboseGroup) HEAD(path string, handler VerboseHandlerFunc)

func (VerboseGroup) Handle

func (g VerboseGroup) Handle(method string, path string, handler VerboseHandlerFunc)

func (VerboseGroup) NewGroup

func (g VerboseGroup) NewGroup(path string, opts ...GroupOption) *VerboseGroup

func (VerboseGroup) OPTIONS

func (g VerboseGroup) OPTIONS(path string, handler VerboseHandlerFunc)

func (VerboseGroup) PATCH

func (g VerboseGroup) PATCH(path string, handler VerboseHandlerFunc)

func (VerboseGroup) POST

func (g VerboseGroup) POST(path string, handler VerboseHandlerFunc)

func (VerboseGroup) PUT

func (g VerboseGroup) PUT(path string, handler VerboseHandlerFunc)

func (VerboseGroup) WithGroup

func (g VerboseGroup) WithGroup(path string, fn func(g *VerboseGroup))

func (VerboseGroup) WithMiddleware

func (g VerboseGroup) WithMiddleware(middleware MiddlewareFunc) *VerboseGroup

type VerboseHandlerFunc

type VerboseHandlerFunc func(w http.ResponseWriter, req *http.Request, ps Params)

type VerboseRouter

type VerboseRouter struct {
	*Router
	*VerboseGroup
}

Directories

Path Synopsis
extra
bunroutergzip Module
bunrouterotel Module
reqlog Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL