Powerful URL router and dispatcher for golang

chi-like router built on httprouter with dependency injection based middleware wrappers

# nchi - http router with speed, flexbility, and elegance

[![GoDoc](https://godoc.org/github.com/muir/nchi?status.png)](https://pkg.go.dev/github.com/muir/nchi)
![unit tests](https://github.com/muir/nchi/actions/workflows/go.yml/badge.svg)
[![report card](https://goreportcard.com/badge/github.com/muir/nchi)](https://goreportcard.com/report/github.com/muir/nchi)
[![codecov](https://codecov.io/gh/muir/nchi/branch/main/graph/badge.svg)](https://codecov.io/gh/muir/nchi)



`nchi` is a lightweight, elegant, and fast router for building Go HTTP services. It's
especially good at helping you write large REST API services that are kept maintainable as your
project grows and changes. `nchi` is built on top of the 
[nject](https://github.com/muir/nject) dependency injection framework and 
the fastest Go http router, [httprouter](https://github.com/julienschmidt/httprouter).
`nchi` is a straight-up rip-off of [chi](https://github.com/go-chi/chi)
substituting nject for context and in the process making it easier to write middleware and
and endpoints.

`nchi` can use standard middleware and it can use dependency-injection middleware. See:

- [nvelope](https://github.com/muir/nvelope) for nject-based middleware
- [chi](https://pkg.go.dev/github.com/go-chi/chi/middleware) for chi's middleware collection

Note: if you're using `nvelope.DeferredWriter`, avoid other middleware that replaces
the `http.ResponseWriter`.

"Standard" middlewhare has one of the following shapes:

- `func(http.HandlerFunc) http.HandlerFunc`
- `func(http.Handler) http.Handler`

`nchi` automatically detects standard middleware and translates it for use in
an nject-based framework.

## Install

	go get github.com/muir/nchi

## Examples

**As easy as:**

```go
package main

import (
	"net/http"

	"github.com/muir/nchi"
	"github.com/go-chi/chi/v5/middleware"
)

func main() {
	r := nchi.NewRouter()
	r.Use(middleware.Logger)
	r.Get("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("welcome"))
	})
	http.ListenAndServe(":3000", r)
}
```

**REST Preview:**

Here is a little preview of how routing looks like with `nchi`. 

```go
import (
 //...
 "github.com/muir/nchi"
 "github.com/muir/nvelope"
 "github.com/muir/nject/v2"
 "github.com/go-chi/chi/v5/middleware"
)

func main() {
 r := nchi.NewRouter()

 // A good base middleware stack
 r.Use(
 middleware.RequestID, 
 middleware.RealIP, 
 middleware.Logger,
 nchi.DecodeJSON,
 )

 r.Use(func(inner func() error, w http.ResponseWriter) {
 err := inner()
 if err == nil { 
 return
 }
 code := nvelope.GetReturnCode(err)
 w.WriteHeader(code)
 w.Write([]byte(err.Error()))
 })

 // Set a timeout value on the request context (ctx), that will signal
 // through ctx.Done() that the request has timed out and further
 // processing should be stopped.
 r.Use(middleware.Timeout(60 * time.Second))

 r.Get("/", func(w http.ResponseWriter) {
 w.Write([]byte("hi"))
 })

 // RESTy routes for "articles" resource
 r.Route("/articles", func(r nchi.Router) {
 r.With(paginate).Get("/", listArticles) // GET /articles
 r.With(paginate).Get("/:month/:day/:year", listArticlesByDate) // GET /articles/01-16-2017

 r.Post("/", createArticle) // POST /articles
 r.Get("/search", searchArticles) // GET /articles/search

 r.Get("/:articleSlug", getArticleBySlug) // GET /articles/home-is-toronto

 // Subrouters:
 r.Route("/:articleID", func(r nchi.Router) {
 r.Use(LoadArticle)
 r.Get("/", getArticle) // GET /articles/123
 r.Put("/", updateArticle) // PUT /articles/123
 r.Delete("/", deleteArticle) // DELETE /articles/123
 })
 })

 // Mount the admin sub-router
 r.Mount("/admin", adminRouter())

 http.ListenAndServe(":3333", r)
}

func LoadArticle(params nchi.Params) (*Article, nject.TerminalError) {
 articleID := params.ByName("articleID")
 article, err := dbGetArticle(articleID)
 if errors.Is(err, sql.NotFound) {
 return nil, nvelope.NotFound(err)
 }
 return article, err
}

func getArticle(article *Article, w http.ResponseWriter) {
 w.Write([]byte(fmt.Sprintf("title:%s", article.Title)))
}
```

## Developement status

`nchi` seems to be working fine for the time being so not much is changing. Please file
an issue if there is something you would like changed.

nchi

Performant, stand-alone, HTTP compliant URL Router for go web applications

# Vestigo - A Standalone Golang URL Router

[![Join the chat at https://gitter.im/husobee/vestigo](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/husobee/vestigo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://travis-ci.org/husobee/vestigo.svg)](https://travis-ci.org/husobee/vestigo)
[![Coverage Status](https://coveralls.io/repos/husobee/vestigo/badge.svg?branch=master&service=github)](https://coveralls.io/github/husobee/vestigo?branch=master)
[![GoDoc](https://godoc.org/github.com/husobee/vestigo?status.svg)](https://godoc.org/github.com/husobee/vestigo)

## Abstract

Many fast Golang URL routers are often embedded inside frameworks.  Vestigo is a stand alone url router
which has respectable performance that passes URL parameters to handlers by embedding them into the request's
Form.

There is such an abundance of parts and pieces that can be fit together for go web services, it seems like a
shame to have a very fast URL router require the use of one framework, and one context model.  This library
aims to give the world a fast, and featureful URL router that can stand on it's own, without being forced into
a particular web framework.

## Design

1. Radix Tree Based
2. Attach URL Parameters into Request (PAT style) instead of context
3. HTTP Compliance (TRACE, OPTIONS, HEAD)
4. CORS Enabled (per resource access-controls)

### TODOs for V1

- [x] Router functioning with a resource concept attached to leaf nodes
- [x] Use resources to drive responses to particular Methods (not found v not allowed)
- [x] Implement Resource and Globally scoped CORS preflights
- [x] Fix bug in router where handler.allowedMethods is getting populated where it shouldn't be
- [x] Validate with Tests RFC 2616 Compliance (OPTIONS, etc)

### TODOs for V2
- [ ] Validators for URL params
- [ ] Implement RFC 6570 URI Parameters

## Performance

Initial implementation on a fork of [standard http performance testing library][http-perf-test] shows the following:

```
BenchmarkVestigo_GithubAll         20000             75763 ns/op            9280 B/op        339 allocs/op
```

I should mention that the above performance is about 2x slower than the fastest URL router I have tested (Echo/Gin), and
is slightly worse than HTTPRouter, but I am happy with this performance considering this implementation is the fastest
implementation that can handle standard http.HandlerFunc handlers, without forcing end users to use a particular context,
or use a non-standard handler function, locking them into an implementation.

## Examples

```go
package main

import (
	"log"
	"net/http"
	"time"

	"github.com/husobee/vestigo"
)

func main() {
	router := vestigo.NewRouter()
	// you can enable trace by setting this to true
	vestigo.AllowTrace = true

	// Setting up router global  CORS policy
	// These policy guidelines are overriddable at a per resource level shown below
	router.SetGlobalCors(&vestigo.CorsAccessControl{
		AllowOrigin:      []string{"*", "test.com"},
		AllowCredentials: true,
		ExposeHeaders:    []string{"X-Header", "X-Y-Header"},
		MaxAge:           3600 * time.Second,
		AllowHeaders:     []string{"X-Header", "X-Y-Header"},
	})

	// setting two methods on the same resource
	router.Get("/welcome", GetWelcomeHandler)
	router.Post("/welcome", PostWelcomeHandler)

	// URL parameter "name"
	router.Post("/welcome/:name", PostWelcomeHandler)

	// Catch-All methods to allow easy migration from http.ServeMux
	router.HandleFunc("/general", GeneralHandler)

	// Below Applies Local CORS capabilities per Resource (both methods covered)
	// by default this will merge the "GlobalCors" settings with the resource
	// cors settings.  Without specifying the AllowMethods, the router will
	// accept any Request-Methods that have valid handlers associated
	router.SetCors("/welcome", &vestigo.CorsAccessControl{
		AllowMethods: []string{"GET"},                    // only allow cors for this resource on GET calls
		AllowHeaders: []string{"X-Header", "X-Z-Header"}, // Allow this one header for this resource
	})

	log.Fatal(http.ListenAndServe(":1234", router))
}

func PostWelcomeHandler(w http.ResponseWriter, r *http.Request) {
	name := vestigo.Param(r, "name") // url params live in the request
	w.WriteHeader(200)
	w.Write([]byte("welcome " + name + "!"))
}

func GetWelcomeHandler(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(200)
	w.Write([]byte("welcome!"))
}

func GeneralHandler(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(200)
	w.Write([]byte("Gotta catch em all!"))
}
```

## Middleware

Router helper methods (Get, Post, ...) support optional middleware (vestigo provides only middleware type, it is up to
the user to create one).

```go
router.Get("/welcome", GetWelcomeHandler, someMiddleware)

someMiddleware := func(f http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// before
		f(w, r)
		// after
	}
}
```

To break the chain (for example in case of authentication middleware, we don't want to continue execution), just do not
call passed handler function. Example:

```go
auth := func(f http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if authSuccessful() {
			f(w, r)
		}
	}
}
```

## App Performance with net/http/pprof

It is often very helpful to view profiling information from your web application.
Below is an example of hooking up net/http/pprof with vestigo serving the routes:

```go
// Load the routes.
func Load(router *vestigo.Router) {
	router.Get("/debug/pprof/", Index)
	router.Get("/debug/pprof/:pprof", Profile)
}

// Index shows the profile index.
func Index(w http.ResponseWriter, r *http.Request) {
	pprof.Index(w, r)
}

// Profile shows the individual profiles.
func Profile(w http.ResponseWriter, r *http.Request) {
	switch vestigo.Param(r, "pprof") {
	case "cmdline":
		pprof.Cmdline(w, r)
	case "profile":
		pprof.Profile(w, r)
	case "symbol":
		pprof.Symbol(w, r)
	case "trace":
		pprof.Trace(w, r)
	default:
		Index(w, r)
	}
}
```

Note on wildcards: if you want to get the actual path matched by the wildcard
you can perform `vestigo.Param(*http.Request, "_name")` to get the matched path, example below:

```go
router.Get("/*", func(w http.ResponseWriter, r *http.Request) {
	fmt.Println(vestigo.Param(r, "_name"))
})
```

## Licensing

* Portions of the URL Router were taken from [Echo][echo-main] and are covered under their [License][echo-main-license].
* Portions of the Tests were taken from [julienschmidt's go-http-routing-benchmark][http-perf-test] and are covered under
this [license][http-perf-test-license]
* The rest of the implementation is covered under *The MIT License* covered under this [License][vestigo-main-license].

# Contributing

If you wish to contribute, please fork this repository, submit an issue, or pull request with your suggestions.
_Please use gofmt and golint before trying to contribute._


[echo-main]: https://github.com/labstack/echo
[echo-main-license]: https://github.com/labstack/echo/blob/master/LICENSE
[vestigo-main-license]: https://github.com/husobee/vestigo/blob/master/LICENSE
[http-perf-test]: https://github.com/julienschmidt/go-http-routing-benchmark
[http-perf-test-license]: https://github.com/julienschmidt/go-http-routing-benchmark/blob/master/LICENSE


vestigo

[![GoDoc](https://godoc.org/github.com/nbari/violetear?status.svg)](https://godoc.org/github.com/nbari/violetear)
[![test](https://github.com/nbari/violetear/actions/workflows/test.yml/badge.svg)](https://github.com/nbari/violetear/actions/workflows/test.yml)
[![Coverage Status](https://coveralls.io/repos/nbari/violetear/badge.svg?branch=develop&service=github)](https://coveralls.io/github/nbari/violetear?branch=develop)
[![Go Report Card](https://goreportcard.com/badge/github.com/nbari/violetear)](https://goreportcard.com/report/github.com/nbari/violetear)

# violetear
Go HTTP router

http://violetear.org

### Design Goals
* Keep it simple and small, avoiding extra complexity at all cost. [KISS](https://en.wikipedia.org/wiki/KISS_principle)
* Support for static and dynamic routing.
* Easy middleware compatibility so that it satisfies the http.Handler interface.
* Common context between middleware.
* Trace Request-ID per request.
* HTTP/2 native support [Push Example](https://gist.github.com/nbari/e19f195c233c92061e27f5beaaae45a3)
* Versioning based on Accept header `application/vnd.*`

Package [GoDoc](https://godoc.org/github.com/nbari/violetear)


How it works
------------

The router is capable off handle any kind or URI, static,
dynamic or catchall and based on the
[HTTP request Method](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)
accept or discard the request.

For example, suppose we have an API that exposes a service that allow to ping
any IP address.

To handle only "GET" request for any IPv4 addresss:

 http://api.violetear.org/command/ping/127.0.0.1
 \______/\___/\________/
 | | |
 static |
 dynamic

The router ``HandlerFunc`` would be:

 router.HandleFunc("/command/ping/:ip", ip_handler, "GET")

For this to work, first the regex matching ``:ip`` should be added:

 router.AddRegex(":ip", `^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$`)

Now let's say you also want to be available to ping ipv6 or any host:

 http://api.violetear.org/command/ping/*
 \______/\___/\_/
 | | |
 static |
 catch-all

A catch-all could be used and also a different handler, for example:

 router.HandleFunc("/command/ping/*", any_handler, "GET, HEAD")

The ``*`` indicates the router to behave like a catch-all therefore it
will match anything after the ``/command/ping/`` if no other condition matches
before.

Notice also the "GET, HEAD", that indicates that only does HTTP methods will be
accepted, and any other will not be allowed, router will return a 405 the one
can also be customised.


Usage
-----

Requirementes go >= 1.7 (https://golang.org/pkg/context/ required)

 import "github.com/nbari/violetear"


**HandleFunc**:

 func HandleFunc(path string, handler http.HandlerFunc, http_methods ...string)

**Handle** (useful for middleware):

 func Handle(path string, handler http.Handler, http_methods ...string)

**http_methods** is a comma separted list of allowed HTTP methods, example:

 router.HandleFunc("/view", handleView, "GET, HEAD")

**AddRegex** adds a ":named" regular expression to the dynamicRoutes, example:

 router.AddRegex(":ip", `^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$`)


Basic example:

```go
package main

import (
 "github.com/nbari/violetear"
 "log"
 "net/http"
)

func catchAll(w http.ResponseWriter, r *http.Request) {
 w.Write([]byte("I'm catching all\n"))
}

func handleGET(w http.ResponseWriter, r *http.Request) {
 w.Write([]byte("I handle GET requests\n"))
}

func handlePOST(w http.ResponseWriter, r *http.Request) {
 w.Write([]byte("I handle POST requests\n"))
}

func handleUUID(w http.ResponseWriter, r *http.Request) {
 w.Write([]byte("I handle dynamic requests\n"))
}

func main() {
 router := violetear.New()
 router.LogRequests = true
 router.RequestID = "Request-ID"

 router.AddRegex(":uuid", `[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}`)

 router.HandleFunc("*", catchAll)
 router.HandleFunc("/method", handleGET, "GET")
 router.HandleFunc("/method", handlePOST, "POST")
 router.HandleFunc("/:uuid", handleUUID, "GET,HEAD")

 srv := &http.Server{
 Addr: ":8080",
 Handler: router,
 ReadTimeout: 5 * time.Second,
 WriteTimeout: 7 * time.Second,
 MaxHeaderBytes: 1 << 20,
 }
 log.Fatal(srv.ListenAndServe())

}
```

Running this code will show something like this:

```sh
$ go run test.go
2015/10/22 17:14:18 Adding path: * [ALL]
2015/10/22 17:14:18 Adding path: /method [GET]
2015/10/22 17:14:18 Adding path: /method [POST]
2015/10/22 17:14:18 Adding path: /:uuid [GET,HEAD]
```

Using ``router.Verbose = false`` will omit printing the paths.

> test.go contains the code show above

Testing using curl or [http](https://github.com/jkbrzt/httpie)

Any request 'catch-all':

```sh
$ http POST http://localhost:8080/
HTTP/1.1 200 OK
Content-Length: 17
Content-Type: text/plain; charset=utf-8
Date: Thu, 22 Oct 2015 15:18:49 GMT
Request-Id: POST-1445527129854964669-1

I'm catching all
```

A GET request:

```sh
$ http http://localhost:8080/method
HTTP/1.1 200 OK
Content-Length: 22
Content-Type: text/plain; charset=utf-8
Date: Thu, 22 Oct 2015 15:43:25 GMT
Request-Id: GET-1445528605902591921-1

I handle GET requests
```

A POST request:

```sh
$ http POST http://localhost:8080/method
HTTP/1.1 200 OK
Content-Length: 23
Content-Type: text/plain; charset=utf-8
Date: Thu, 22 Oct 2015 15:44:28 GMT
Request-Id: POST-1445528668557478433-2

I handle POST requests
```

A dynamic request using an [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) as the URL resource:

```sh
$ http http://localhost:8080/50244127-45F6-4210-A89D-FFB0DA039425
HTTP/1.1 200 OK
Content-Length: 26
Content-Type: text/plain; charset=utf-8
Date: Thu, 22 Oct 2015 15:45:33 GMT
Request-Id: GET-1445528733916239110-5

I handle dynamic requests
```

Trying to use POST on the ``/:uuid`` resource will cause a
*Method not Allowed 405* this because only ``GET`` and ``HEAD``
methods are allowed:

```sh
$ http POST http://localhost:8080/50244127-45F6-4210-A89D-FFB0DA039425
HTTP/1.1 405 Method Not Allowed
Content-Length: 19
Content-Type: text/plain; charset=utf-8
Date: Thu, 22 Oct 2015 15:47:19 GMT
Request-Id: POST-1445528839403536403-6
X-Content-Type-Options: nosniff

Method Not Allowed
```

RequestID
---------

To keep track of the "requests" an existing "request ID" header can be used, if
the header name for example is **Request-ID** therefore to continue using it,
the router needs to know the name, example:

 router := violetear.New()
 router.RequestID = "X-Appengine-Request-Log-Id"

If the proxy is using another name, for example "RID" then use something like:

 router := violetear.New()
 router.RequestID = "RID"

If ``router.RequestID`` is not set, no "request ID" is going to be added to the
headers. This can be extended using a middleware same has the logger check the
AppEngine example.


NotFoundHandler
---------------

For defining a custom ``http.Handler`` to handle **404 Not Found** example:

 ...

 func my404() http.Handler {
 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 http.Error(w, "ne ne ne", 404)
 })
 }

 func main() {
 router := violetear.New()
 router.NotFoundHandler = my404()
 ...

NotAllowedHandler
-----------------

For defining a custom ``http.Handler`` to handle **405 Method Not Allowed**.

PanicHandler
------------

For using a custom http.HandlerFunc to handle panics

Middleware
----------

Violetear uses [Alice](http://justinas.org/alice-painless-middleware-chaining-for-go/) to handle [middleware](middleware).

Example:

```go
package main

import (
	"context"
	"log"
	"net/http"

	"github.com/nbari/violetear"
	"github.com/nbari/violetear/middleware"
)

func commonHeaders(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("X-app-Version", "1.0")
		next.ServeHTTP(w, r)
	})
}

func middlewareOne(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		log.Println("Executing middlewareOne")
		ctx := context.WithValue(r.Context(), "m1", "m1")
		ctx = context.WithValue(ctx, "key", 1)
		next.ServeHTTP(w, r.WithContext(ctx))
		log.Println("Executing middlewareOne again")
	})
}

func middlewareTwo(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		log.Println("Executing middlewareTwo")
		if r.URL.Path != "/" {
			return
		}
		ctx := context.WithValue(r.Context(), "m2", "m2")
		next.ServeHTTP(w, r.WithContext(ctx))
		log.Println("Executing middlewareTwo again")
	})
}

func catchAll(w http.ResponseWriter, r *http.Request) {
	log.Printf("Executing finalHandler\nm1:%s\nkey:%d\nm2:%s\n",
		r.Context().Value("m1"),
		r.Context().Value("key"),
		r.Context().Value("m2"),
	)
	w.Write([]byte("I catch all"))
}

func foo(w http.ResponseWriter, r *http.Request) {
	panic("this will never happen, because of the return")
}

func main() {
	router := violetear.New()

	stdChain := middleware.New(commonHeaders, middlewareOne, middlewareTwo)

	router.Handle("/", stdChain.ThenFunc(catchAll), "GET,HEAD")
	router.Handle("/foo", stdChain.ThenFunc(foo), "GET,HEAD")
	router.HandleFunc("/bar", foo)

	log.Fatal(http.ListenAndServe(":8080", router))
}
```

> Notice the use or router.Handle and router.HandleFunc when using middleware
you normally would use route.Handle

Request output example:

```sh
$ http http://localhost:8080/
HTTP/1.1 200 OK
Content-Length: 11
Content-Type: text/plain; charset=utf-8
Date: Thu, 22 Oct 2015 16:08:18 GMT
Request-Id: GET-1445530098002701428-3
X-App-Version: 1.0

I catch all
```

On the server you will see something like this:

```sh
$ go run test.go
2016/08/17 18:08:42 Adding path: / [GET,HEAD]
2016/08/17 18:08:42 Adding path: /foo [GET,HEAD]
2016/08/17 18:08:42 Adding path: /bar [ALL]
2016/08/17 18:08:47 Executing middlewareOne
2016/08/17 18:08:47 Executing middlewareTwo
2016/08/17 18:08:47 Executing finalHandler
m1:m1
key:1
m2:m2
2016/08/17 18:08:47 Executing middlewareTwo again
2016/08/17 18:08:47 Executing middlewareOne again
```

AppEngine
---------

The app.yaml file:

```yaml
application: 'app-name'
version: 1
runtime: go
api_version: go1

handlers:

- url: /.*
 script: _go_app
```

The app.go file:

```go
package app

import (
 "appengine"
 "github.com/nbari/violetear"
 "github.com/nbari/violetear/middleware"
 "net/http"
)

func init() {
 router := violetear.New()
 stdChain := middleware.New(requestID)
 router.Handle("*", stdChain.ThenFunc(index), "GET, HEAD")
 http.Handle("/", router)
}

func requestID(next http.Handler) http.Handler {
 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 c := appengine.NewContext(r)
 w.Header().Set("Request-ID", appengine.RequestID(c))
 next.ServeHTTP(w, r)
 })
}

func index(w http.ResponseWriter, r *http.Request) {
 w.Write([]byte("Hello world!"))
}
```

Demo: http://api.violetear.org

Using ``curl`` or ``http``:

```sh
$ http http://api.violetear.org
HTTP/1.1 200 OK
Cache-Control: private
Content-Encoding: gzip
Content-Length: 32
Content-Type: text/html; charset=utf-8
Date: Sun, 25 Oct 2015 06:14:55 GMT
Request-Id: 562c735f00ff0902f823e514a90001657e76696f6c65746561722d31313037000131000100
Server: Google Frontend

Hello world!
```

Context & Named parameters
==========================

In some cases there is a need to pass data across
handlers/middlewares, for doing this **Violetear** uses
[net/context](https://godoc.org/golang.org/x/net/context).

When using dynamic routes `:regex`, you can use `GetParam` or `GetParams`, see below.

Example:

```go
package main

import (
 "context"
 "fmt"
 "log"
 "net/http"

 "github.com/nbari/violetear"
)

func catchAll(w http.ResponseWriter, r *http.Request) {
 // Get & print the content of named-param *
 params := r.Context().Value(violetear.ParamsKey).(violetear.Params)
 fmt.Fprintf(w, "CatchAll value:, %q", params["*"])
}

func handleUUID(w http.ResponseWriter, r *http.Request) {
 // get router params
 params := r.Context().Value(violetear.ParamsKey).(violetear.Params)
 // using GetParam
 uuid := violetear.GetParam("uuid", r)
 // add a key-value pair to the context
 ctx := context.WithValue(r.Context(), "key", "my-value")
 // print current value for :uuid
 fmt.Fprintf(w, "Named parameter: %q, uuid; %q, key: %s",
 params[":uuid"],
 uuid,
 ctx.Value("key"),
 )
}

func main() {
 router := violetear.New()

 router.AddRegex(":uuid", `[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}`)

 router.HandleFunc("*", catchAll)
 router.HandleFunc("/:uuid", handleUUID, "GET,HEAD")

 srv := &http.Server{
 Addr: ":8080",
 Handler: router,
 ReadTimeout: 5 * time.Second,
 WriteTimeout: 7 * time.Second,
 MaxHeaderBytes: 1 << 20,
 }
 log.Fatal(srv.ListenAndServe())
}
```

## Duplicated named parameters

In cases where the same named parameter is used multiple times, example:

 /test/:uuid/:uuid/

An slice is created, for getting the values you need to do something like:

 params := r.Context().Value(violetear.ParamsKey).(violetear.Params)
 uuid := params[":uuid"].([]string)

> Notice the ``:`` prefix when getting the named_parameters

Or by using `GetParams`:

 uuid := violetear.GetParams("uuid")

After this you can access the slice like normal:

 fmt.Println(uuid[0], uuid[1])

violetear

High performance muxer based on `httprouter` with `net/context` support

# Xmux

[![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/rs/xmux) [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/rs/xmux/master/LICENSE) [![Build Status](https://travis-ci.org/rs/xmux.svg?branch=master)](https://travis-ci.org/rs/xmux) [![Coverage](http://gocover.io/_badge/github.com/rs/xmux)](http://gocover.io/github.com/rs/xmux)

Xmux is a lightweight high performance HTTP request muxer on top [xhandler](https://github.com/rs/xhandler). Xmux gets its speed from the fork of the amazing [httprouter](https://github.com/julienschmidt/httprouter). Route parameters are stored in `context` instead of being passed as an additional parameter.

In contrast to the [default mux](http://golang.org/pkg/net/http/#ServeMux) of Go's `net/http` package, this muxer supports variables in the routing pattern and matches against the request method. It also scales better.

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

## Features

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

**Stop caring about trailing slashes:** Choose the URL style you like, the muxer automatically redirects the client if a trailing slash is missing or if there is one extra. Of course it only does so, if the new path has a handler. If you don't like it, you can [turn off this behavior](http://godoc.org/github.com/rs/xmux#Mux.RedirectTrailingSlash).

**Path auto-correction:** Besides detecting the missing or additional trailing slash at no extra cost, the muxer can also fix wrong cases and remove superfluous path elements (like `../` or `//`). Is [CAPTAIN CAPS LOCK](http://www.urbandictionary.com/define.php?term=Captain+Caps+Lock) one of your users? Xmux can help him by making a case-insensitive look-up and redirecting him to the correct URL.

**Parameters in your routing pattern:** Stop parsing the requested URL path, just give the path segment a name and the router delivers the dynamic value to you. Because of the design of the router, path parameters are very cheap.

**RouteGroups:** A way to create [groups of routes](http://godoc.org/github.com/rs/xmux#Mux.NewGroup) without incurring any per-request overhead.

**Zero Garbage:** The matching and dispatching process generates zero bytes of garbage. In fact, the only heap allocations that are made, is by building the slice of the key-value pairs for path parameters and the `context` instance to store them in the context. If the request path contains no parameters, not a single heap allocation is necessary.

**No more server crashes:** You can set a [Panic handler](http://godoc.org/github.com/rs/xmux#Mux.PanicHandler) to deal with panics occurring during handling a HTTP request. The router then recovers and lets the `PanicHandler` log what happened and deliver a nice error page.

Of course you can also set **custom [NotFound](http://godoc.org/github.com/rs/xmux#Mux.NotFound) and [MethodNotAllowed](http://godoc.org/github.com/rs/xmux#Mux.MethodNotAllowed) handlers**.

## Usage

This is just a quick introduction, view the [GoDoc](http://godoc.org/github.com/rs/xmux) for details.

Let's start with a trivial example:
```go
package main

import (
	"fmt"
	"log"
	"net/http"
	"context"

	"github.com/rs/xhandler"
	"github.com/rs/xmux"
)

func Index(ctx context.Context, w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "Welcome!\n")
}

func Hello(ctx context.Context, w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "hello, %s!\n", xmux.Param(ctx, "name"))
}

func main() {
	mux := xmux.New()
	mux.GET("/", xhandler.HandlerFuncC(Index))
	mux.GET("/hello/:name", xhandler.HandlerFuncC(Hello))

	log.Fatal(http.ListenAndServe(":8080", xhandler.New(context.Background(), mux)))
}
```

You may also chain middleware using `xhandler.Chain`:

```go
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/rs/xhandler"
	"github.com/rs/xmux"
)

func main() {
	c := xhandler.Chain{}

	// Append a context-aware middleware handler
	c.UseC(xhandler.CloseHandler)

	// Another context-aware middleware handler
	c.UseC(xhandler.TimeoutHandler(2 * time.Second))

	mux := xmux.New()

	// Use c.Handler to terminate the chain with your final handler
	mux.GET("/welcome/:name", xhandler.HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome %s!", xmux.Param(ctx, "name"))
	}))

	if err := http.ListenAndServe(":8080", c.Handler(mux)); err != nil {
		log.Fatal(err)
	}
}
```

### Named parameters

As you can see, `:name` is a *named parameter*. The values are accessible via `xmux.Params(ctx)`, which returns `xmux.ParamHolder`.
You can get the value of a parameter by its name using `Get(name)` method:

```go
user := xmux.Params(ctx).Get("user")
```

or using `xmux.Param(ctx, name)` shortcut:

```go
user := xmux.Param(ctx, "user")
```

Named parameters only match a single path segment:

```
Pattern: /user/:user

 /user/gordon match
 /user/you match
 /user/gordon/profile no match
 /user/ no match
```

**Note:** Since this muxer has only explicit matches, you can not register static routes and parameters for the same path segment. For example you can not register the patterns `/user/new` and `/user/:user` for the same request method at the same time. The routing of different request methods is independent from each other.

### Catch-All parameters

The second type are *catch-all* parameters and have the form `*name`. Like the name suggests, they match everything. Therefore they must always be at the **end** of the pattern:

```
Pattern: /src/*filepath

 /src/ match
 /src/somefile.go match
 /src/subdir/somefile.go match
```

## Benchmarks

Thanks to [Julien Schmidt](https://github.com/julienschmidt) excellent [HTTP routing benchmark](https://github.com/julienschmidt/go-http-routing-benchmark), we can see that xhandler's muxer is pretty close to `httprouter` as it is a fork of it. The small overhead is due to the `context` allocation used to store route parameters. It still outperform other routers, thanks to amazing `httprouter`'s radix tree based matcher.

```
BenchmarkXhandler_APIStatic-8 	50000000	 39.6 ns/op	 0 B/op	 0 allocs/op
BenchmarkChi_APIStatic-8 	 3000000	 439 ns/op	 144 B/op	 5 allocs/op
BenchmarkGoji_APIStatic-8 	 5000000	 272 ns/op	 0 B/op	 0 allocs/op
BenchmarkHTTPRouter_APIStatic-8 	50000000	 37.3 ns/op	 0 B/op	 0 allocs/op

BenchmarkXhandler_APIParam-8 	 5000000	 328 ns/op	 160 B/op	 4 allocs/op
BenchmarkChi_APIParam-8 	 2000000	 675 ns/op	 432 B/op	 6 allocs/op
BenchmarkGoji_APIParam-8 	 2000000	 692 ns/op	 336 B/op	 2 allocs/op
BenchmarkHTTPRouter_APIParam-8 	10000000	 166 ns/op	 64 B/op	 1 allocs/op

BenchmarkXhandler_API2Params-8 	 5000000	 362 ns/op	 160 B/op	 4 allocs/op
BenchmarkChi_API2Params-8 	 2000000	 814 ns/op	 432 B/op	 6 allocs/op
BenchmarkGoji_API2Params-8 	 2000000	 680 ns/op	 336 B/op	 2 allocs/op
BenchmarkHTTPRouter_API2Params-8	10000000	 183 ns/op	 64 B/op	 1 allocs/op

BenchmarkXhandler_APIAll-8 	 200000	 6473 ns/op	 2176 B/op	 64 allocs/op
BenchmarkChi_APIAll-8 	 100000	 17261 ns/op	 8352 B/op	 146 allocs/op
BenchmarkGoji_APIAll-8 	 100000	 15052 ns/op	 5377 B/op	 32 allocs/op
BenchmarkHTTPRouter_APIAll-8 	 500000	 3716 ns/op	 640 B/op	 16 allocs/op

BenchmarkXhandler_Param1-8 	 5000000	 271 ns/op	 128 B/op	 4 allocs/op
BenchmarkChi_Param1-8 	 2000000	 620 ns/op	 432 B/op	 6 allocs/op
BenchmarkGoji_Param1-8 	 3000000	 522 ns/op	 336 B/op	 2 allocs/op
BenchmarkHTTPRouter_Param1-8 	20000000	 112 ns/op	 32 B/op	 1 allocs/op

BenchmarkXhandler_Param5-8 	 3000000	 414 ns/op	 256 B/op	 4 allocs/op
BenchmarkChi_Param5-8 	 1000000	 1204 ns/op	 432 B/op	 6 allocs/op
BenchmarkGoji_Param5-8 	 2000000	 847 ns/op	 336 B/op	 2 allocs/op
BenchmarkHTTPRouter_Param5-8 	 5000000	 247 ns/op	 160 B/op	 1 allocs/op

BenchmarkXhandler_Param20-8 	 2000000	 747 ns/op	 736 B/op	 4 allocs/op
BenchmarkChi_Param20-8 	 2000000	 746 ns/op	 736 B/op	 4 allocs/op
BenchmarkGoji_Param20-8 	 500000	 2439 ns/op	 1247 B/op	 2 allocs/op
BenchmarkHTTPRouter_Param20-8 	 3000000	 585 ns/op	 640 B/op	 1 allocs/op

BenchmarkXhandler_ParamWrite-8 	 5000000	 404 ns/op	 144 B/op	 5 allocs/op
BenchmarkChi_ParamWrite-8 	 3000000	 407 ns/op	 144 B/op	 5 allocs/op
BenchmarkGoji_ParamWrite-8 	 2000000	 594 ns/op	 336 B/op	 2 allocs/op
BenchmarkHTTPRouter_ParamWrite-8	10000000	 166 ns/op	 32 B/op	 1 allocs/op
```

You can run this benchmark by executing the following commands at the root of `xmux` repository:

```go
go get -t ./bench/routers
go test ./bench/routers -bench .
```

## How does it work?

The muxer relies on a tree structure which makes heavy use of *common prefixes*, it is basically a *compact* [*prefix tree*](http://en.wikipedia.org/wiki/Trie) (or just [*Radix tree*](http://en.wikipedia.org/wiki/Radix_tree)). Nodes with a common prefix also share a common parent. Here is a short example what the routing tree for the `GET` request method could look like:

```
Priority Path Handle
9 \ *<1>
3 ├s nil
2 |├earch\ *<2>
1 |└upport\ *<3>
2 ├blog\ *<4>
1 | └:post nil
1 | └\ *<5>
2 ├about-us\ *<6>
1 | └team\ *<7>
1 └contact\ *<8>
```

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

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

For even better scalability, the child nodes on each tree level are ordered by priority, where the priority is just the number of handles registered in sub nodes (children, grandchildren, and so on..). This helps in two ways:

1. Nodes which are part of the most routing paths are evaluated first. This helps to make as much routes as possible to be reachable as fast as possible.
2. It is some sort of cost compensation. The longest reachable path (highest cost) can always be evaluated first. The following scheme visualizes the tree structure. Nodes are evaluated from top to bottom and from left to right.

```
├------------
├---------
├-----
├----
├--
├--
└-
```

## Why doesn't this work with http.Handler?

**It does!** The router itself implements the http.Handler interface. Moreover the router provides convenient [adapters for http.Handler](http://godoc.org/github.com/rs/xmux#Mux.Handle)s and [http.HandlerFunc](http://godoc.org/github.com/rs/xmux#Mux.HandleFunc)s which allows them to be used as a [xhandler.HandlerC](http://godoc.org/github.com/rs/xhandler#HandlerC) when registering a route. The only disadvantage is, that no `context` and thus no parameter values can be retrieved when a `http.Handler` or `http.HandlerFunc` is used.

## Where can I find Middleware *X*?

This package just provides a very efficient request muxer with a few extra features. The muxer is just a [xhandler.HandlerC](https://godoc.org/github.com/rs/xhandler#HandlerC), you can chain any `http.Handler` or `xhandler.HandlerC` compatible middleware before the router, for example the [Gorilla handlers](http://www.gorillatoolkit.org/pkg/handlers). Or you could [just write your own](http://justinas.org/writing-http-middleware-in-go/), it's very easy!

### Multi-domain / Sub-domains

Here is a quick example: Does your server serve multiple domains / hosts? You want to use sub-domains? Define a router per host!

```go
// We need an object that implements the xhandler.HandlerC interface.
// Therefore we need a type for which we implement the ServeHTTP method.
// We just use a map here, in which we map host names (with port) to xhandler.HandlerC
type HostSwitch map[string]xhandler.HandlerC

// Implement the ServerHTTP method on our new type
func (hs HostSwitch) ServeHTTPC(ctx context.Context, w http.ResponseWriter, r *http.Request) {
	// Check if a xhandler.HandlerC is registered for the given host.
	// If yes, use it to handle the request.
	if handler := hs[r.Host]; handler != nil {
		handler.ServeHTTPC(ctx, w, r)
	} else {
		// Handle host names for wich no handler is registered
		http.Error(w, "Forbidden", 403) // Or Redirect?
	}
}

func main() {
	c := xhandler.Chain{}

	// Initialize a muxer as usual
	mux := xmux.New()
	mux.GET("/", Index)
	mux.GET("/hello/:name", Hello)

	// Make a new HostSwitch and insert the muxer (our http handler)
	// for example.com and port 12345
	hs := make(HostSwitch)
	hs["example.com:12345"] = mux

	// Use the HostSwitch to listen and serve on port 12345
	if err := http.ListenAndServe(":12345", c.Handler(hs)); err != nil {
		log.Fatal(err)
	}
}
```

### Basic Authentication
Another quick example: Basic Authentication (RFC 2617) for handles:

```go
package main

import (
	"bytes"
	"context"
	"encoding/base64"
	"fmt"
	"log"
	"net/http"
	"strings"

	"github.com/rs/xhandler"
	"github.com/rs/xmux"
)

func BasicAuth(user, pass []byte, next xhandler.HandlerC) xhandler.HandlerC {
	return xhandler.HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
		const basicAuthPrefix string = "Basic "

		// Get the Basic Authentication credentials
		auth := r.Header.Get("Authorization")
		if strings.HasPrefix(auth, basicAuthPrefix) {
			// Check credentials
			payload, err := base64.StdEncoding.DecodeString(auth[len(basicAuthPrefix):])
			if err == nil {
				pair := bytes.SplitN(payload, []byte(":"), 2)
				if len(pair) == 2 &&
					bytes.Equal(pair[0], user) &&
					bytes.Equal(pair[1], pass) {

					// Delegate request to the next handler
					next.ServeHTTPC(ctx, w, r)
					return
				}
			}
		}

		// Request Basic Authentication otherwise
		w.Header().Set("WWW-Authenticate", "Basic realm=Restricted")
		http.Error(w, http.StatusText(http.StatusUnauthorized), http.StatusUnauthorized)
	})
}

func Index(ctx context.Context, w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "Not protected!\n")
}

func Protected(ctx context.Context, w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "Protected!\n")
}

func main() {
	user := []byte("gordon")
	pass := []byte("secret!")

	c := xhandler.Chain{}
	mux := xmux.New()
	mux.GET("/", xhandler.HandlerFuncC(Index))
	mux.GET("/protected/", BasicAuth(user, pass, xhandler.HandlerFuncC(Protected)))

	log.Fatal(http.ListenAndServe(":8080", c.Handler(mux)))
}
```

## Licenses

All source code is licensed under the [BSD License](https://raw.github.com/rs/xhandler/master/LICENSE).

Xmux is forked from [httprouter](https://github.com/julienschmidt/httprouter) with [BSD License](https://github.com/julienschmidt/httprouter/blob/master/LICENSE).

xmux

# gorouter [![GoDoc](https://godoc.org/github.com/xujiajun/gorouter?status.svg)](https://godoc.org/github.com/xujiajun/gorouter) <a href="https://travis-ci.org/xujiajun/gorouter"><img src="https://travis-ci.org/xujiajun/gorouter.svg?branch=master" alt="Build Status"></a> [![Go Report Card](https://goreportcard.com/badge/github.com/xujiajun/gorouter)](https://goreportcard.com/report/github.com/xujiajun/gorouter) [![Coverage Status](https://s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg)](https://coveralls.io/github/xujiajun/gorouter?branch=master) [![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/xujiajun/gorouter/master/LICENSE) [![Release](https://img.shields.io/badge/release-v1.1.0-blue.svg?style=flat-square)](https://github.com/xujiajun/gorouter/releases/tag/v1.0.1) [![Awesome](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#routers) 
`xujiajun/gorouter` is a simple and fast HTTP router for Go. It is easy to build RESTful APIs and your web framework.

## Motivation

I wanted a simple and fast HTTP GO router, which supports regexp. I prefer to support regexp is because otherwise it will need the logic to check the URL parameter type, thus increasing the program complexity. So I did some searching on Github and found the wonderful `julienschmidt/httprouter`: it is very fast，unfortunately it does not support regexp. Later I found out about `gorilla/mux`: it is powerful as well，but a written benchmark shows me that it is somewhat slow. So I tried to develop a new router which both supports regexp and should be fast. Finally I did it and named `xujiajun/gorouter`. By the way, this is my first GO open source project. It may be the fastest GO HTTP router which supports regexp, and regarding its performance please refer to my latest [Benchmarks](#benchmarks).

## Features

* Fast - see [Benchmarks](#benchmarks)
* [URL parameters](#url-parameters)
* [Regex parameters](#regex-parameters)
* [Routes groups](#routes-groups)
* [Reverse Routing](#reverse-routing)
* [Custom NotFoundHandler](#custom-notfoundhandler)
* [Custom PanicHandler](#custom-panichandler)
* [Middleware Chain Support](#middlewares-chain)
* [Serve Static Files](#serve-static-files)
* [Pattern Rule Familiar](#pattern-rule)
* HTTP Method Get、Post、Delete、Put、Patch Support
* No external dependencies (just Go stdlib)


## Requirements

* golang 1.8+

## Installation

```
go get -u github.com/xujiajun/gorouter
```

## Usage

### Static routes

```golang
package main

import (
	"log"
	"net/http"

	"github.com/xujiajun/gorouter"
)

func main() {
	mux := gorouter.New()
	mux.GET("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("hello world"))
	})
	log.Fatal(http.ListenAndServe(":8181", mux))
}

```

### URL Parameters

```golang
package main

import (
	"log"
	"net/http"

	"github.com/xujiajun/gorouter"
)

func main() {
	mux := gorouter.New()
	//url parameters match
	mux.GET("/user/:id", func(w http.ResponseWriter, r *http.Request) {
		//get one URL parameter
		id := gorouter.GetParam(r, "id")
		//get all URL parameters
		//id := gorouter.GetAllParams(r)
		//fmt.Println(id)
		w.Write([]byte("match user/:id ! get id:" + id))
	})

	log.Fatal(http.ListenAndServe(":8181", mux))
}
```

### Regex Parameters

```golang
package main

import (
	"log"
	"net/http"

	"github.com/xujiajun/gorouter"
)

func main() {
	mux := gorouter.New()
	//url regex match
	mux.GET("/user/{id:[0-9]+}", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("match user/{id:[0-9]+} !"))
	})

	log.Fatal(http.ListenAndServe(":8181", mux))
}
```


### Routes Groups

```golang
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/xujiajun/gorouter"
)

func usersHandler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "/api/users")
}

func main() {
	mux := gorouter.New()
	mux.Group("/api").GET("/users", usersHandler)

	log.Fatal(http.ListenAndServe(":8181", mux))
}
```

### Reverse Routing

```golang
package main

import (
	"fmt"
	"net/http"

	"github.com/xujiajun/gorouter"
)

func main() {
	mux := gorouter.New()

	routeName1 := "user_event"
	mux.GETAndName("/users/:user/events", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("/users/:user/events"))
	}, routeName1)

	routeName2 := "repos_owner"
	mux.GETAndName("/repos/{owner:\\w+}/{repo:\\w+}", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("/repos/{owner:\\w+}/{repo:\\w+}"))
	}, routeName2)

	params := make(map[string]string)
	params["user"] = "xujiajun"
	fmt.Println(mux.Generate(http.MethodGet, routeName1, params)) // /users/xujiajun/events <nil>

	params = make(map[string]string)
	params["owner"] = "xujiajun"
	params["repo"] = "xujiajun_repo"
	fmt.Println(mux.Generate(http.MethodGet, routeName2, params)) // /repos/xujiajun/xujiajun_repo <nil>
}

```

### Custom NotFoundHandler

```golang
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/xujiajun/gorouter"
)

func notFoundFunc(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusNotFound)
	fmt.Fprint(w, "404 page !!!")
}

func main() {
	mux := gorouter.New()
	mux.NotFoundFunc(notFoundFunc)
	mux.GET("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("hello world"))
	})

	log.Fatal(http.ListenAndServe(":8181", mux))
}
```

### Custom PanicHandler

```golang
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/xujiajun/gorouter"
)

func main() {
	mux := gorouter.New()
	mux.PanicHandler = func(w http.ResponseWriter, req *http.Request, err interface{}) {
		w.WriteHeader(http.StatusInternalServerError)
		fmt.Println("err from recover is :", err)
		fmt.Fprint(w, "received a panic")
	}
	mux.GET("/panic", func(w http.ResponseWriter, r *http.Request) {
		panic("panic")
	})

	log.Fatal(http.ListenAndServe(":8181", mux))
}

```

### Middlewares Chain

```golang
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/xujiajun/gorouter"
)

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (rec *statusRecorder) WriteHeader(code int) {
	rec.status = code
	rec.ResponseWriter.WriteHeader(code)
}

//https://upgear.io/blog/golang-tip-wrapping-http-response-writer-for-middleware/
func withStatusRecord(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		rec := statusRecorder{w, http.StatusOK}
		next.ServeHTTP(&rec, r)
		log.Printf("response status: %v\n", rec.status)
	}
}

func notFoundFunc(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusNotFound)
	fmt.Fprint(w, "Not found page !")
}

func withLogging(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		log.Printf("Logged connection from %s", r.RemoteAddr)
		next.ServeHTTP(w, r)
	}
}

func withTracing(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		log.Printf("Tracing request for %s", r.RequestURI)
		next.ServeHTTP(w, r)
	}
}

func main() {
	mux := gorouter.New()
	mux.NotFoundFunc(notFoundFunc)
	mux.Use(withLogging, withTracing, withStatusRecord)
	mux.GET("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("hello world"))
	})

	log.Fatal(http.ListenAndServe(":8181", mux))
}
```

## Serve static files

```golang
package main

import (
	"log"
	"net/http"
	"os"
	
	"github.com/xujiajun/gorouter"
)

//ServeFiles serve static resources
func ServeFiles(w http.ResponseWriter, r *http.Request) {
	wd, err := os.Getwd()
	if err != nil {
		log.Fatal(err)
	}

	dir := wd + "/examples/serveStaticFiles/files"
	http.StripPrefix("/files/", http.FileServer(http.Dir(dir))).ServeHTTP(w, r)
}

func main() {
	mux := gorouter.New()
	mux.GET("/hi", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("hi"))
	})
	//defined prefix
	mux2 := mux.Group("/files")
	//http://127.0.0.1:8181/files/demo.txt
	//will match
	mux2.GET("/{filename:[0-9a-zA-Z_.]+}", func(w http.ResponseWriter, r *http.Request) {
		ServeFiles(w, r)
	})

	//http://127.0.0.1:8181/files/a/demo2.txt
	//http://127.0.0.1:8181/files/a/demo.txt
	//will match
	mux2.GET("/{fileDir:[0-9a-zA-Z_.]+}/{filename:[0-9a-zA-Z_.]+}", func(w http.ResponseWriter, r *http.Request) {
		ServeFiles(w, r)
	})

	log.Fatal(http.ListenAndServe(":8181", mux))
}
```
Detail see [serveStaticFiles example](https://github.com/xujiajun/gorouter/blob/master/examples/serveStaticFiles/main.go)

## Pattern Rule

The syntax here is modeled after [julienschmidt/httprouter](https://github.com/julienschmidt/httprouter) and [gorilla/mux](https://github.com/gorilla/mux)

| Syntax | Description | Example |
|--------|------|-------|
| `:name` | named parameter | /user/:name |
| `{name:regexp}` | named with regexp parameter | /user/{name:[0-9a-zA-Z]+} |
| `:id` | named with regexp parameter | /user/:id |

And `:id` is short for `{id:[0-9]+}`, `:name` are short for `{name:[0-9a-zA-Z_]+}`

> if use default regex checks unless you know what you're doing

 
## Benchmarks

the benchmarks code for gorouter be found in the [gorouter-bench](https://github.com/xujiajun/gorouter-bench) repository.

> go test -bench=.

### Benchmark System:

* Go Version : go1.11.2 darwin/amd64
* OS: Mac OS X 10.13.6
* Architecture: x86_64
* 16 GB 2133 MHz LPDDR3
* CPU: 3.1 GHz Intel Core i7

### Tested routers:

* [beego/mux](https://github.com/beego/mux)
* [go-zoo/bone](https://github.com/go-zoo/bone)
* [go-chi/chi](https://github.com/go-chi/chi)
* [julienschmidt/httprouter](https://github.com/julienschmidt/httprouter)
* [gorilla/mux](https://github.com/gorilla/mux)
* [trie-mux/mux](https://github.com/teambition/trie-mux)
* [xujiajun/gorouter](https://github.com/xujiajun/gorouter)


Thanks the author of httprouter: [@julienschmidt](https://github.com/julienschmidt) give me advise about benchmark [issues/24](https://github.com/xujiajun/gorouter/issues/24)

## Result:

Given some routing matching syntax differences, divide GithubAPI into two groups：

### Using GithubAPI Result：

```
BenchmarkBeegoMuxRouterWithGithubAPI-8 	 10000	 142398 ns/op	 134752 B/op	 1038 allocs/op
BenchmarkBoneRouterWithGithubAPI-8 	 1000	 2104486 ns/op	 720160 B/op	 8620 allocs/op
BenchmarkTrieMuxRouterWithGithubAPI-8 	 20000	 80845 ns/op	 65856 B/op	 537 allocs/op
BenchmarkHttpRouterWithGithubAPI-8 	 50000	 30169 ns/op	 13792 B/op	 167 allocs/op
BenchmarkGoRouter1WithGithubAPI-8 	 30000	 57793 ns/op	 13832 B/op	 406 allocs/op

```
### Using GithubAPI2 Result：

```
BenchmarkGoRouter2WithGithubAPI2-8 	 30000	 57613 ns/op	 13832 B/op	 406 allocs/op
BenchmarkChiRouterWithGithubAPI2-8 	 10000	 143224 ns/op	 104436 B/op	 1110 allocs/op
BenchmarkMuxRouterWithGithubAPI2-8 	 300	 4450731 ns/op	 61463 B/op	 995 allocs/op
```

### All togther Result：

```
➜ gorouter git:(master) go test -bench=.
GithubAPI Routes: 203
GithubAPI2 Routes: 203
 BeegoMuxRouter: 111072 Bytes
 BoneRouter: 100992 Bytes
 ChiRouter: 71512 Bytes
 HttpRouter: 37016 Bytes
 trie-mux: 131128 Bytes
 MuxRouter: 1378496 Bytes
 GoRouter1: 83824 Bytes
 GoRouter2: 85584 Bytes
goos: darwin
goarch: amd64
pkg: github.com/xujiajun/gorouter
BenchmarkBeegoMuxRouterWithGithubAPI-8 	 10000	 142398 ns/op	 134752 B/op	 1038 allocs/op
BenchmarkBoneRouterWithGithubAPI-8 	 1000	 2104486 ns/op	 720160 B/op	 8620 allocs/op
BenchmarkTrieMuxRouterWithGithubAPI-8 	 20000	 80845 ns/op	 65856 B/op	 537 allocs/op
BenchmarkHttpRouterWithGithubAPI-8 	 50000	 30169 ns/op	 13792 B/op	 167 allocs/op
BenchmarkGoRouter1WithGithubAPI-8 	 30000	 57793 ns/op	 13832 B/op	 406 allocs/op
BenchmarkGoRouter2WithGithubAPI2-8 	 30000	 57613 ns/op	 13832 B/op	 406 allocs/op
BenchmarkChiRouterWithGithubAPI2-8 	 10000	 143224 ns/op	 104436 B/op	 1110 allocs/op
BenchmarkMuxRouterWithGithubAPI2-8 	 300	 4450731 ns/op	 61463 B/op	 995 allocs/op
PASS
ok 	github.com/xujiajun/gorouter	15.918s

```

### Conclusions:

* Performance (xujiajun/gorouter,julienschmidt/httprouter and teambition/trie-mux are fast)

* Memory Consumption (xujiajun/gorouter and julienschmidt/httprouter are fewer) 

* Features (julienschmidt/httprouter not supports regexp，but others support it)

> if you want a high performance router which supports regexp, maybe [xujiajun/gorouter](https://github.com/xujiajun/gorouter) is good choice.

> if you want a high performance router which not supports regexp, maybe [julienschmidt/httprouter](https://github.com/julienschmidt/httprouter) is good choice.

In the end, as julienschmidt said `performance can not be the (only) criterion for choosing a router. Play around a bit with some of the routers, and choose the one you like best.`

## Contributing

If you'd like to help out with the project. You can put up a Pull Request. Thanks to all [contributors](https://github.com/xujiajun/gorouter/graphs/contributors).

## Author

* [xujiajun](https://github.com/xujiajun)

## License

The gorouter is open-sourced software licensed under the [MIT Licensed](http://www.opensource.org/licenses/MIT)

## Acknowledgements

This package is inspired by the following:

* [httprouter](https://github.com/julienschmidt/httprouter)
* [bone](https://github.com/go-zoo/bone)
* [trie-mux](https://github.com/teambition/trie-mux)
* [alien](https://github.com/gernest/alien)

xujiajun/gorouter

# Bellt 
> Simple Golang HTTP router

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Go Report Card](https://goreportcard.com/badge/github.com/GuilhermeCaruso/bellt)](https://goreportcard.com/report/github.com/GuilhermeCaruso/bellt) [![codecov](https://codecov.io/gh/GuilhermeCaruso/bellt/branch/master/graph/badge.svg)](https://codecov.io/gh/GuilhermeCaruso/bellt) [![Build Status](https://travis-ci.com/GuilhermeCaruso/bellt.svg?branch=master)](https://travis-ci.com/GuilhermeCaruso/bellt) ![GitHub](https://img.shields.io/badge/golang%20->=1.7-blue.svg) [![GoDoc](https://godoc.org/github.com/GuilhermeCaruso/bellt?status.svg)](https://godoc.org/github.com/GuilhermeCaruso/bellt) 


 <img width="150" src="./assets/logo.png">


Bellt Package implements a request router with the aim of managing controller actions based on fixed and parameterized routes.

The project so far has the following functionalities:

* Standard definition of route "/health", in order to prepare the service developed with bellt to act as microservice.
* Providing the creation of parameterized routes, simple or segmented (groups).
* All requests can be made through fixed patterns, querystrings and parameters.
* Obtaining the requisition parameters in the controller functions.
---
# Summary
 * [Install](#install)
 * [Guide](#guide)
	* [Router](#router)
		* [HandleFunc](#handleFunc)
		* [HandleGroup](#handleGroup)
		* [SubHandleFunc](#subHandleFunc)
	* [Middleware](#middleware)
		* [Use](#use)
	* [Parameterized Routes](#parameterized-routes)
		* [Route Variables](#route-variables)
			* [GetVar](#getVar)
 * [Full Example](#full-example)
 * [Benchmark](#benchmark)
 * [Author](#author)
 * [Presentation](#presentation)
 * [License](#license)

# Install


To get Bellt

##### > Go CLI
```sh
go get -u github.com/GuilhermeCaruso/bellt
```
##### > Go DEP
```sh
dep ensure -add github.com/GuilhermeCaruso/bellt
```
##### > Govendor
```sh
govendor fetch github.com/GuilhermeCaruso/bellt
```

# Guide

## Router

To initialize our router
```go
var router = bellt.NewRouter()
```

```go
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/GuilhermeCaruso/bellt"
)

func main() {
	router := bellt.NewRouter()

	log.Fatal(http.ListenAndServe(":8080", nil))
}

```

### HandleFunc 

HandleFunc function responsible for initializing a common route or built through the Router. All non-grouped routes must be initialized by this method.

```go
/*
	[path] - Endpoint string
	[handlerFunc] - Function that will be called on the request
	[methods] - Slice for endpoint methods ("GET", "POST", "PUT", "DELETE")
*/

router.HandleFunc(path, handlerFunc, methods)
 
```
```go
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/GuilhermeCaruso/bellt"
)

func main() {
	router := bellt.NewRouter()

	router.HandleFunc("/bellt", belltHandler, "GET")

	log.Fatal(http.ListenAndServe(":8080", nil))
}

func belltHandle(w http.ResponseWriter, r *http.Request){
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("Simple Golang HTTP router")
}

```

### HandleGroup 

HandleGroup is responsible for creating a group of routes. The main path can be set for all other routes.

```go
/*
	[mainPath] - Main route used in all subr-outes
	
	[subHandleFunc] - SubHandleFunc function responsiblefor initializing a common route or
	built through the Router. All grouped routes must be initialized by this method
*/

router.HandleGroup(mainPath, ...SubHandleFunc)
 
```

### SubHandleFunc 

SubHandleFunc is responsible for initializing a common or built route. Its use must be made within the scope of the HandleGroup method, where the main path will be declared.

```go
/*
	[path] - Endpoint string
	[handlerFunc] - Function that will be called on the request
	[methods] - Slice for endpoint methods ("GET", "POST", "PUT", "DELETE")
*/

router.SubHandleFunc(path, handlerFunc, methods)
 
```
```go
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/GuilhermeCaruso/bellt"
)

func main() {
	router := bellt.NewRouter()

	router.HandleGroup("/api",
		router.SubHandleFunc("/bellt", belltHandle, "GET"),
		router.SubHandleFunc("/check", checkHandle, "GET"),
	)

	log.Fatal(http.ListenAndServe(":8080", nil))
}

func belltHandle(w http.ResponseWriter, r *http.Request){
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("Simple Golang HTTP router")
}

func checkHandle(w http.ResponseWriter, r *http.Request){
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("Ok!")
}

```

## Middleware

The declaration of middlewares in HandleFunc or SubHandleFunc should be done using the *Use* method

### Use

```go
/*
	handlerFunc - Function that will be called on the request 
	middlewareList - Slice of middleware that will be used in the request (Middleware)
*/
bellt.Use(handlerFunc, ...middlewareList)
```

The middleware type has a following signature


```go
type Middleware func(http.HandlerFunc) http.HandlerFunc
```

Applying middlewares to routes

```go
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/GuilhermeCaruso/bellt"
)

func main() {

	router := bellt.NewRouter()

	router.HandleFunc("/hello", bellt.Use(
		exampleHandler,
		middlewareOne,
		middlewareTwo,
	), "GET")

	router.HandleGroup("/api",
		router.SubHandleFunc("/hello", bellt.Use(
			exampleHandler,
			middlewareOne,
			middlewareTwo,
		), "GET"),
	)

	log.Fatal(http.ListenAndServe(":8080", nil))
}

func exampleHandler(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(`Hello Middleware!`))
}

func middlewareOne(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		fmt.Println("Step One")
		next.ServeHTTP(w, r)
	}
}

func middlewareTwo(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		fmt.Println("Step Two")
		next.ServeHTTP(w, r)
	}
}
```

## Parameterized Routes

Route parameters must be passed using `{}` as scope limiter

```go
router.HandleFunc("/hello/{name}", handlerFunc, "GET")

router.HandleGroup("/api", 
	SubHandleFunc("/item/{id}", handlerFunc, "GET")
)
```

### Route Variables

RouteVariables used to capture and store parameters passed to built routes.

Need to pass the *Request of the HandlerFunc used in the HandleFunc method.

```go
/*
	r = *Request of the HandlerFunc
*/
rv := bellt.RouteVariables(r)
```

The declaration must be made within the HandlerFunc

```go
func exampleHandler(w http.ResponseWriter, r *http.Request) {
	rv := bellt.RouteVariables(r)
	/*[...]*/
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("Hello!"))
}
```

#### GetVar

GetVar returns the parameter value of the route

```go
/*
	r = *Request of the HandlerFunc
	param = Parameter name string
*/
rv := bellt.RouteVariables(r)

rv.GetVar(param)
```

```go
func exampleHandler(w http.ResponseWriter, r *http.Request) {
	rv := bellt.RouteVariables(r)
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(fmt.Sprintf(`Hello %v gopher!`, rv.GetVar("color")))))
}
```

The complete implementation of parameterized routes should look like this:

```go
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/GuilhermeCaruso/bellt"
)

func main() {

	router := bellt.NewRouter()

	router.HandleFunc("/contact/{id}/{user}", exampleHandler, "GET")

	router.HandleGroup("/api",
		router.SubHandleFunc("/check/{id}/{user}", exampleHandler, "GET"),
	)

	log.Fatal(http.ListenAndServe(":8080", nil))
}

func exampleHandler(w http.ResponseWriter, r *http.Request) {
	rv := bellt.RouteVariables(r)

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(fmt.Sprintf(`{"id": %v, "user": %v}`, rv.GetVar("user"), rv.GetVar("id"))))
}
```


# Full Example

```go
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/GuilhermeCaruso/bellt"
)

func main() {

	router := bellt.NewRouter()

	router.HandleFunc("/contact/{id}/{user}", bellt.Use(
		exampleHandler,
		middlewareOne,
		middlewareTwo,
	), "GET")

	router.HandleFunc("/contact", bellt.Use(
		exampleNewHandler,
		middlewareOne,
		middlewareTwo,
	), "GET")

	router.HandleGroup("/api",
		router.SubHandleFunc("/check", bellt.Use(
			exampleNewHandler,
			middlewareOne,
			middlewareTwo,
		), "GET"),
		router.SubHandleFunc("/check/{id}/{user}", bellt.Use(
			exampleHandler,
			middlewareOne,
			middlewareTwo,
		), "GET"),
	)

	log.Fatal(http.ListenAndServe(":8080", nil))
}

func exampleHandler(w http.ResponseWriter, r *http.Request) {

	rv := bellt.RouteVariables(r)

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(fmt.Sprintf(`{"id": %v, "user": %v}`, rv.GetVar("user"), rv.GetVar("id"))))
}

func exampleNewHandler(w http.ResponseWriter, r *http.Request) {
	rv := bellt.RouteVariables(r)

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(`{"msg": "Works"}`))
}

func middlewareOne(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		fmt.Println("Step One")

		next.ServeHTTP(w, r)
	}
}

func middlewareTwo(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		fmt.Println("Step Two")

		next.ServeHTTP(w, r)
	}
}
```

# Benchmark

Applying requisition performance tests, the following results were obtained, showing the initial potency of the Bellt package.


 <img width="800" src="./assets/benchmark.png">


# Author
Guilherme Caruso [@guicaruso_](https://twitter.com/guicaruso_) on twitter

# Presentation
Guilherme Caruso - Cabify- GolangSP Meetup 2 - 21/03/2019 - São Paulo /Brazil 

Slides - [Construindo Rotas Parametrizadas em GO](https://www.slideshare.net/guimartinscaruso/criando-rotas-parametrizadas-em-go)

Video - [GolangSP Meetup 2](https://www.youtube.com/watch?v=nxsfyadxzmI)

# License
MIT licensed. See the LICENSE file for details.

bellt

Lightweight and fast http router from outer space

# Alien [![Coverage Status](https://coveralls.io/repos/github/gernest/alien/badge.svg?branch=master)](https://coveralls.io/github/gernest/alien?branch=master) [![Build Status](https://travis-ci.org/gernest/alien.svg?branch=master)](https://travis-ci.org/gernest/alien) [![GoDoc](https://godoc.org/github.com/gernest/alien?status.svg)](https://godoc.org/github.com/gernest/alien) [![Go Report Card](https://goreportcard.com/badge/github.com/gernest/alien)](https://goreportcard.com/report/github.com/gernest/alien)

Alien is a lightweight http router( multiplexer) for Go( Golang ), made for
humans who don't like magic.

Documentation [docs](https://godoc.org/github.com/gernest/alien)

# Features

* fast ( see the benchmarks, or run them yourself)
* lightweight ( just [a single file](alien.go) read all of it in less than a minute)
* safe( designed with concurrency in mind)
* middleware support.
* routes groups
* no external dependency( only the standard library )


# Motivation
I wanted a simple, fast, and lightweight router that has no unnecessary overhead
using the standard library only, following good practices and well tested code(
Over 90% coverage)

# Installation

```bash
go get github.com/gernest/alien
```

# Usage

## normal static routes

```go

package main

import (
	"log"
	"net/http"

	"github.com/gernest/alien"
)

func main() {
	m := alien.New()
	m.Get("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("hello world"))
	})
	log.Fatal(http.ListenAndServe(":8090", m))
}
```

visiting your localhost at path `/` will print `hello world`

## named params

```go

package main

import (
	"log"
	"net/http"

	"github.com/gernest/alien"
)

func main() {
	m := alien.New()
	m.Get("/hello/:name", func(w http.ResponseWriter, r *http.Request) {
		p := alien.GetParams(r)
		w.Write([]byte(p.Get("name")))
	})
	log.Fatal(http.ListenAndServe(":8090", m))
}
```

visiting your localhost at path `/hello/tanzania` will print `tanzania`

## catch all params
```go
package main

import (
	"log"
	"net/http"

	"github.com/gernest/alien"
)

func main() {
	m := alien.New()
	m.Get("/hello/*name", func(w http.ResponseWriter, r *http.Request) {
		p := alien.GetParams(r)
		w.Write([]byte(p.Get("name")))
	})
	log.Fatal(http.ListenAndServe(":8090", m))
}
```

visiting your localhost at path `/hello/my/margicl/sheeplike/ship` will print 
`my/margical/sheeplike/ship`

## middlewares
Middlewares are anything that satisfy the interface
`func(http.Handler)http.Handler` . Meaning you have thousands of middlewares at
your disposal, you can use middlewares from many golang http frameworks on
alien(most support the interface).


```go

package main

import (
	"log"
	"net/http"

	"github.com/gernest/alien"
)

func middleware(h http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("hello middlware"))
	})
}

func main() {
	m := alien.New()
	m.Use(middleware)
	m.Get("/", func(_ http.ResponseWriter, _ *http.Request) {
	})
	log.Fatal(http.ListenAndServe(":8090", m))
}
```

visiting your localhost at path `/` will print `hello middleware`

## groups

You can group routes

```go
package main

import (
	"log"
	"net/http"

	"github.com/gernest/alien"
)

func main() {
	m := alien.New()
	g := m.Group("/home")
	m.Use(middleware)
	g.Get("/alone", func(w http.ResponseWriter, _ *http.Request) {
		w.Write([]byte("home alone"))
	})
	log.Fatal(http.ListenAndServe(":8090", m))
}
```

visiting your localhost at path `/home/alone` will print `home alone`

# Contributing
Start with clicking the star button to make the author and his neighbors happy. Then fork the repository and submit a pull request for whatever change you want to be added to this project.

If you have any questions, just open an issue.

# Author
Geofrey Ernest  [@gernesti](https://twitter.com/gernesti) on twitter

# Licence
MIT see [LICENSE](LICENSE)


alien

Small, fast and expressive HTTP router built on net/context

High performance router forked from `httprouter`. The first router fit for `fasthttp`

# FastHttpRouter
[![Build Status](https://travis-ci.org/buaazp/fasthttprouter.svg?branch=master)](https://travis-ci.org/buaazp/fasthttprouter)
[![Coverage Status](https://coveralls.io/repos/buaazp/fasthttprouter/badge.svg?branch=master&service=github)](https://coveralls.io/github/buaazp/fasthttprouter?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/buaazp/fasthttprouter)](https://goreportcard.com/report/github.com/buaazp/fasthttprouter)
[![GoDoc](http://godoc.org/github.com/buaazp/fasthttprouter?status.svg)](http://godoc.org/github.com/buaazp/fasthttprouter)
[![GitHub release](https://img.shields.io/github/release/buaazp/fasthttprouter.svg)](https://github.com/buaazp/fasthttprouter/releases)

FastHttpRouter is forked from [httprouter](https://github.com/julienschmidt/httprouter) which is a lightweight high performance HTTP request router
(also called *multiplexer* or just *mux* for short) for [fasthttp](https://github.com/valyala/fasthttp).

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

#### License Related

- The author of `httprouter` [@julienschmidt](https://github.com/julienschmidt) did almost all the hard work of this router.
- I respect the laws of open source. So LICENSE of `httprouter` is alway stay here: [HttpRouterLicense](HttpRouterLicense).
- What I do is just fit for `fasthttp`. I have no hope to build a huge but toxic go web framwork like [iris](https://github.com/kataras/iris). 
- I fork this repo is just because there is no router for `fasthttp` at that time. And `fasthttprouter` is the FIRST router for `fasthttp`. 
- `fasthttprouter` has been used in my online production and processes 17 million requests per day. It is fast and stable, so I decide to release a stable version.

#### Releases

- [2016.10.24] [v0.1.0](https://github.com/buaazp/fasthttprouter/releases/tag/v0.1.0) The first release version of `fasthttprouter`.

## Features

**Best Performance:** FastHttpRouter is **one of the fastest** go web frameworks in the [go-web-framework-benchmark](https://github.com/smallnest/go-web-framework-benchmark). Even faster than httprouter itself.

- Basic Test: The first test case is to mock 0 ms, 10 ms, 100 ms, 500 ms processing time in handlers. The concurrency clients are 5000.

![](http://ww3.sinaimg.cn/large/4c422e03jw1f2p6nyqh9ij20mm0aktbj.jpg)

- Concurrency Test: In 30 ms processing time, the test result for 100, 1000, 5000 clients is:

![](http://ww4.sinaimg.cn/large/4c422e03jw1f2p6o1cdbij20lk09sack.jpg)

See below for technical details of the implementation.

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

**Stop caring about trailing slashes:** Choose the URL style you like, the
router automatically redirects the client if a trailing slash is missing or if
there is one extra. Of course it only does so, if the new path has a handler.
If you don't like it, you can [turn off this behavior](http://godoc.org/github.com/buaazp/fasthttprouter#Router.RedirectTrailingSlash).

**Path auto-correction:** Besides detecting the missing or additional trailing
slash at no extra cost, the router can also fix wrong cases and remove
superfluous path elements (like `../` or `//`).
Is [CAPTAIN CAPS LOCK](http://www.urbandictionary.com/define.php?term=Captain+Caps+Lock) one of your users?
FastHttpRouter can help him by making a case-insensitive look-up and redirecting him
to the correct URL.

**Parameters in your routing pattern:** Stop parsing the requested URL path,
just give the path segment a name and the router delivers the dynamic value to
you. Because of the design of the router, path parameters are very cheap.

**Zero Garbage:** The matching and dispatching process generates zero bytes of
garbage. In fact, the only heap allocations that are made, is by building the
slice of the key-value pairs for path parameters. If the request path contains
no parameters, not a single heap allocation is necessary.

**No more server crashes:** You can set a [Panic handler](http://godoc.org/github.com/buaazp/fasthttprouter#Router.PanicHandler) to deal with panics
occurring during handling a HTTP request. The router then recovers and lets the
PanicHandler log what happened and deliver a nice error page.

**Perfect for APIs:** The router design encourages to build sensible, hierarchical
RESTful APIs. Moreover it has builtin native support for [OPTIONS requests](http://zacstewart.com/2012/04/14/http-options-method.html)
and `405 Method Not Allowed` replies.

Of course you can also set **custom [NotFound](http://godoc.org/github.com/buaazp/fasthttprouter#Router.NotFound) and [MethodNotAllowed](http://godoc.org/github.com/buaazp/fasthttprouter#Router.MethodNotAllowed) handlers** and [**serve static files**](http://godoc.org/github.com/buaazp/fasthttprouter#Router.ServeFiles).

## Usage

This is just a quick introduction, view the [GoDoc](http://godoc.org/github.com/buaazp/fasthttprouter) for details:

Let's start with a trivial example:

```go
package main

import (
	"fmt"
	"log"

	"github.com/buaazp/fasthttprouter"
	"github.com/valyala/fasthttp"
)

func Index(ctx *fasthttp.RequestCtx) {
	fmt.Fprint(ctx, "Welcome!\n")
}

func Hello(ctx *fasthttp.RequestCtx) {
	fmt.Fprintf(ctx, "hello, %s!\n", ctx.UserValue("name"))
}

func main() {
	router := fasthttprouter.New()
	router.GET("/", Index)
	router.GET("/hello/:name", Hello)

	log.Fatal(fasthttp.ListenAndServe(":8080", router.Handler))
}
```

### Named parameters

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

Named parameters only match a single path segment:

```
Pattern: /user/:user

 /user/gordon match
 /user/you match
 /user/gordon/profile no match
 /user/ no match
```

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

### Catch-All parameters

The second type are *catch-all* parameters and have the form `*name`.
Like the name suggests, they match everything.
Therefore they must always be at the **end** of the pattern:

```
Pattern: /src/*filepath

 /src/ match
 /src/somefile.go match
 /src/subdir/somefile.go match
```

## How does it work?

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

```
Priority Path Handle
9 \ *<1>
3 ├s nil
2 |├earch\ *<2>
1 |└upport\ *<3>
2 ├blog\ *<4>
1 | └:post nil
1 | └\ *<5>
2 ├about-us\ *<6>
1 | └team\ *<7>
1 └contact\ *<8>
```

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

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

For even better scalability, the child nodes on each tree level are ordered by priority, where the priority is just the number of handles registered in sub nodes (children, grandchildren, and so on..). This helps in two ways:

1. Nodes which are part of the most routing paths are evaluated first. This helps to make as much routes as possible to be reachable as fast as possible.
2. It is some sort of cost compensation. The longest reachable path (highest cost) can always be evaluated first. The following scheme visualizes the tree structure. Nodes are evaluated from top to bottom and from left to right.

```
├------------
├---------
├-----
├----
├--
├--
└-
```

## Why doesn't this work with `http.Handler`?

Because fasthttp doesn't provide http.Handler. See this [description](https://github.com/valyala/fasthttp#switching-from-nethttp-to-fasthttp).

Fasthttp works with [RequestHandler](https://godoc.org/github.com/valyala/fasthttp#RequestHandler) functions instead of objects implementing Handler interface. So a FastHttpRouter provides a [Handler](https://godoc.org/github.com/buaazp/fasthttprouter#Router.Handler) interface to implement the fasthttp.ListenAndServe interface.

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

## Where can I find Middleware *X*?

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

Have a look at these middleware examples:

- [Auth Middleware](examples/auth)
- [Multi Hosts Middleware](examples/hosts)

## Chaining with the NotFound handler

**NOTE: It might be required to set [Router.HandleMethodNotAllowed](http://godoc.org/github.com/buaazp/fasthttprouter#Router.HandleMethodNotAllowed) to `false` to avoid problems.**

You can use another [http.Handler](http://golang.org/pkg/net/http/#Handler), for example another router, to handle requests which could not be matched by this router by using the [Router.NotFound](http://godoc.org/github.com/buaazp/fasthttprouter#Router.NotFound) handler. This allows chaining.

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

```go
// Serve static files from the ./public directory
router.NotFound = fasthttp.FSHandler("./public", 0)
```

But this approach sidesteps the strict core rules of this router to avoid routing problems. A cleaner approach is to use a distinct sub-path for serving files, like `/static/*filepath` or `/files/*filepath`.

## Web Frameworks based on FastHttpRouter

If the HttpRouter is a bit too minimalistic for you, you might try one of the following more high-level 3rd-party web frameworks building upon the HttpRouter package:

- Waiting for you to do this...

fasthttprouter

HTTP router with type-safe generic handlers, automatic OpenAPI 3.1 generation from code, and RFC 9457 error responses

fursy

[English](https://github.com/bmf-san/goblin) [日本語](https://github.com/bmf-san/goblin/blob/master/README-ja.md)

# goblin
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![GitHub release](https://img.shields.io/github/release/bmf-san/goblin.svg)](https://github.com/bmf-san/goblin/releases)
[![CircleCI](https://circleci.com/gh/bmf-san/goblin/tree/master.svg?style=svg)](https://circleci.com/gh/bmf-san/goblin/tree/master)
[![Go Report Card](https://goreportcard.com/badge/github.com/bmf-san/goblin)](https://goreportcard.com/report/github.com/bmf-san/goblin)
[![codecov](https://codecov.io/gh/bmf-san/goblin/branch/master/graph/badge.svg?token=ZLOLQKUD39)](https://codecov.io/gh/bmf-san/goblin)
[![GitHub license](https://img.shields.io/github/license/bmf-san/goblin)](https://github.com/bmf-san/goblin/blob/master/LICENSE)
[![Go Reference](https://pkg.go.dev/badge/github.com/bmf-san/goblin.svg)](https://pkg.go.dev/github.com/bmf-san/goblin)
[![Sourcegraph](https://sourcegraph.com/github.com/bmf-san/goblin/-/badge.svg)](https://sourcegraph.com/github.com/bmf-san/goblin?badge)

A golang http router based on trie tree.

<img src="https://storage.googleapis.com/gopherizeme.appspot.com/gophers/d654ddf2b81c2b4123684f93071af0cf559eb0b5.png" alt="goblin" title="goblin" width="250px">

This logo was created by [gopherize.me](https://gopherize.me/gopher/d654ddf2b81c2b4123684f93071af0cf559eb0b5).

# Table of contents
- [goblin](#goblin)
- [Table of contents](#table-of-contents)
- [Features](#features)
- [Install](#install)
- [Example](#example)
- [Usage](#usage)
 - [Method based routing](#method-based-routing)
 - [Named parameter routing](#named-parameter-routing)
 - [Regular expression based routing](#regular-expression-based-routing)
 - [Middleware](#middleware)
 - [Customizable error handlers](#customizable-error-handlers)
 - [Default OPTIONS handler](#default-options-handler)
- [Benchmark tests](#benchmark-tests)
- [Design](#design)
- [Wiki](#wiki)
- [Contribution](#contribution)
- [Sponsor](#sponsor)
- [Stargazers](#stargazers)
- [Forkers](#forkers)
- [License](#license)
- [Author](#author)

# Features
- Go1.21 >= 1.16
- Simple data structure based on trie tree
- Lightweight
 - Lines of codes: 2428
 - Package size: 140K
- No dependencies other than standard packages
- Compatible with net/http
- More advanced than net/http's [Servemux](https://pkg.go.dev/net/http#ServeMux)
 - Method based routing
 - Named parameter routing
 - Regular expression based routing
 - Middleware
 - Customizable error handlers
 - Default OPTIONS handler
- 0allocs
 - Achieve 0 allocations in static routing
 - About 3allocs for named routes
 - Heap allocation occurs when creating parameter slices and storing parameters in context

# Install
```sh
go get -u github.com/bmf-san/goblin
```

# Example
A sample implementation is available.

Please refer to [example_goblin_test.go](https://github.com/bmf-san/goblin/blob/master/example_goblin_test.go).

# Usage
## Method based routing
Routing can be defined based on any HTTP method.

The following HTTP methods are supported.
`GET/POST/PUT/PATCH/DELETE/OPTIONS`

```go
r := goblin.NewRouter()

r.Methods(http.MethodGet).Handler(`/`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintf(w, "/")
}))

r.Methods(http.MethodGet, http.MethodPost).Handler(`/methods`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 if r.Method == http.MethodGet {
 fmt.Fprintf(w, "GET")
 }
 if r.Method == http.MethodPost {
 fmt.Fprintf(w, "POST")
 }
}))

http.ListenAndServe(":9999", r)
```

## Named parameter routing
You can define routing with named parameters (`:paramName`).

```go
r := goblin.NewRouter()

r.Methods(http.MethodGet).Handler(`/foo/:id`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 id := goblin.GetParam(r.Context(), "id")
 fmt.Fprintf(w, "/foo/%v", id)
}))

r.Methods(http.MethodGet).Handler(`/foo/:name`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 name := goblin.GetParam(r.Context(), "name")
 fmt.Fprintf(w, "/foo/%v", name)
}))

http.ListenAndServe(":9999", r)
```

## Regular expression based routing
By using regular expressions for named parameters (`:paramName[pattern]`), you can define routing using regular expressions.

```go
r.Methods(http.MethodGet).Handler(`/foo/:id[^\d+$]`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 id := goblin.GetParam(r.Context(), "id")
 fmt.Fprintf(w, "/foo/%v", id)
}))
```

## Middleware
Supports middleware to help pre-process requests and post-process responses.

Middleware can be defined for any routing.

Middleware can also be configured globally. If a middleware is configured globally, the middleware will be applied to all routing.

More than one middleware can be configured.

Middleware must be defined as a function that returns http.

```go
// Implement middleware as a function that returns http.Handl
func global(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "global: before\n")
		next.ServeHTTP(w, r)
		fmt.Fprintf(w, "global: after\n")
	})
}

func first(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "first: before\n")
		next.ServeHTTP(w, r)
		fmt.Fprintf(w, "first: after\n")
	})
}

func second(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "second: before\n")
		next.ServeHTTP(w, r)
		fmt.Fprintf(w, "second: after\n")
	})
}

func third(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "third: before\n")
		next.ServeHTTP(w, r)
		fmt.Fprintf(w, "third: after\n")
	})
}

r := goblin.NewRouter()

// Set middleware globally
r.UseGlobal(global)
r.Methods(http.MethodGet).Handler(`/globalmiddleware`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintf(w, "/globalmiddleware\n")
}))

// Use methods can be used to apply middleware
r.Methods(http.MethodGet).Use(first).Handler(`/middleware`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintf(w, "middleware\n")
}))

// Multiple middleware can be configured
r.Methods(http.MethodGet).Use(second, third).Handler(`/middlewares`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintf(w, "middlewares\n")
}))

http.ListenAndServe(":9999", r)
```

A request to `/globalmiddleware` gives the following results.

```
global: before
/globalmiddleware
global: after
```

A request to `/middleware` gives the following results.

```
global: before
first: before
middleware
first: after
global: after
```

A request to `/middlewares` gives the following results.

```
global: before
second: before
third: before
middlewares
third: after
second: after
global: after
```

## Customizable error handlers
You can define your own error handlers.

The following two types of error handlers can be defined

- NotFoundHandler
 - Handler that is executed when no result matching the routing is obtained
- MethodNotAllowedHandler
 - Handler that is executed when no matching method is found

```go
func customMethodNotFound() http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "customMethodNotFound")
	})
}

func customMethodAllowed() http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "customMethodNotAllowed")
	})
}

r := goblin.NewRouter()
r.NotFoundHandler = customMethodNotFound()
r.MethodNotAllowedHandler = customMethodAllowed()

http.ListenAndServe(":9999", r)
```

## Default OPTIONS handler
You can define a default handler that will be executed when a request is made with the OPTIONS method.

```go
func DefaultOPTIONSHandler(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 w.WriteHeader(http.StatusNoContent)
	})
}

r := goblin.NewRouter()
r.DefaultOPTIONSHandler = DefaultOPTIONSHandler()

http.ListenAndServe(":9999", r)
```

The default OPTIONS handler is useful, for example, in handling CORS OPTIONS requests (preflight requests).

# Benchmark tests
We have a command to run a goblin benchmark test.

Please refer to [Makefile](https://github.com/bmf-san/goblin/blob/master/Makefile).

Curious about benchmark comparison results with other HTTP Routers?

Please see here!
[bmf-san/go-router-benchmark](https://github.com/bmf-san/go-router-benchmark)

# Design
This section describes the internal data structure of goblin.

While [radix tree](https://en.wikipedia.org/wiki/Radix_tree) is often employed in performance-optimized HTTP Routers, goblin uses [trie tree](https://en.wikipedia.org/wiki/Trie).

Compared to radix trees, trie tree have a disadvantage in terms of performance due to inferior memory usage. However, the simplicity of the algorithm and ease of understanding are overwhelmingly in favor of the trie tree.

HTTP Router may seem like a simple application with a simple specification, but it is surprisingly complex. You can see this by looking at the test cases.
(If you have an idea for a better-looking test case implementation, please let us know.)

One advantage of using a simple algorithm is that it contributes to code maintainability. (This may sound like an excuse for the difficulty of implementing a radix tree... in fact, the difficulty of implementing an HTTP Router based on a radix tree frustrated me once...)

Using the source code of [_examples](https://github.com/bmf-san/goblin/blob/master/_examples) as an example, I will explain the internal data structure of goblin.

The routing definitions are represented in a table as follows.

| Method | Path | Handler | Middleware |
| -- | -- | -- | -- |
| GET | / | RootHandler | N/A |
| GET | /foo | FooHandler | CORS |
| POST | /foo | FooHandler | CORS |
| GET | /foo/bar | FooBarHandler | N/A |
| GET | /foo/bar/:name | FooBarNameHandler | N/A |
| POST | /foo/:name | FooNameHandler | N/A|
| GET | /baz | BazHandler | CORS |

In gobin, such routing is represented as the following tree structure.

```
legend：<HTTP Method>,[Node]

<GET>
 ├── [/]
 |
 ├── [/foo]
 | |
 | └── [/bar]
 | |
 | └── [/:name]
 |
 └── [/baz]

<POST>
 └── [/foo]
 |
 └── [/:name]
```

The tree is constructed for each HTTP method.

Each node has handler and middleware definitions as data.

In order to simplify the explanation, data such as named routing data and global middleware data are omitted here.

Various other data is held in the internally constructed tree.

If you want to know more, use the debugger to take a peek at the internal structure.

If you have any ideas for improvements, please let us know!

# Wiki
References are listed on the [wiki](https://github.com/bmf-san/goblin/wiki).

# Contribution
Issues and Pull Requests are always welcome.

We would be happy to receive your contributions.

Please review the following documents before making a contribution.

- [CODE_OF_CONDUCT](https://github.com/bmf-san/goblin/blob/master/.github/CODE_OF_CONDUCT.md)
- [CONTRIBUTING](https://github.com/bmf-san/goblin/blob/master/.github/CONTRIBUTING.md)

# Sponsor
If you like it, I would be happy to have you sponsor it!

[GitHub Sponsors - bmf-san](https://github.com/sponsors/bmf-san)

Or I would be happy to get a STAR.

It motivates me to keep up with ongoing maintenance :D

# Stargazers
[![Stargazers repo roster for @bmf-san/goblin](https://reporoster.com/stars/bmf-san/goblin)](https://github.com/bmf-san/goblin/stargazers)

# Forkers
[![Forkers repo roster for @bmf-san/goblin](https://reporoster.com/forks/bmf-san/goblin)](https://github.com/bmf-san/goblin/network/members)

# License
Based on the MIT License.

[LICENSE](https://github.com/bmf-san/goblin/blob/master/LICENSE)

# Author
[bmf-san](https://github.com/bmf-san)

- Email
 - bmf.infomation@gmail.com
- Blog
 - [bmf-tech.com](http://bmf-tech.com)
- Twitter
 - [bmf-san](https://twitter.com/bmf-san)

goblin

# gocraft/web [![GoDoc](https://godoc.org/github.com/gocraft/web?status.png)](https://godoc.org/github.com/gocraft/web)


gocraft/web is a Go mux and middleware package. We deal with casting and reflection so YOUR code can be statically typed. And we're fast.

## Getting Started
From your GOPATH:

```bash
go get github.com/gocraft/web
```

Add a file ```server.go``` - for instance, ```src/myapp/server.go```

```go
package main

import (
	"github.com/gocraft/web"
	"fmt"
	"net/http"
	"strings"
)

type Context struct {
	HelloCount int
}

func (c *Context) SetHelloCount(rw web.ResponseWriter, req *web.Request, next web.NextMiddlewareFunc) {
	c.HelloCount = 3
	next(rw, req)
}

func (c *Context) SayHello(rw web.ResponseWriter, req *web.Request) {
	fmt.Fprint(rw, strings.Repeat("Hello ", c.HelloCount), "World!")
}

func main() {
	router := web.New(Context{}). // Create your router
		Middleware(web.LoggerMiddleware). // Use some included middleware
		Middleware(web.ShowErrorsMiddleware). // ...
		Middleware((*Context).SetHelloCount). // Your own middleware!
		Get("/", (*Context).SayHello) // Add a route
	http.ListenAndServe("localhost:3000", router) // Start the server!
}
```

Run the server. It will be available on ```localhost:3000```:

```bash
go run src/myapp/server.go
```

## Features
* **Super fast and scalable**. Added latency is from 3-9μs per request. Routing performance is O(log(N)) in the number of routes.
* **Your own contexts**. Easily pass information between your middleware and handler with strong static typing.
* **Easy and powerful routing**. Capture path variables. Validate path segments with regexps. Lovely API.
* **Middleware**. Middleware can express almost any web-layer feature. We make it easy.
* **Nested routers, contexts, and middleware**. Your app has an API, and admin area, and a logged out view. Each view needs different contexts and different middleware. We let you express this hierarchy naturally.
* **Embrace Go's net/http package**. Start your server with http.ListenAndServe(), and work directly with http.ResponseWriter and http.Request.
* **Minimal**. The core of gocraft/web is lightweight and minimal. Add optional functionality with our built-in middleware, or write your own middleware.

## Performance
Performance is a first class concern. Every update to this package has its performance measured and tracked in [BENCHMARK_RESULTS](https://github.com/gocraft/web/blob/master/BENCHMARK_RESULTS).

For minimal 'hello world' style apps, added latency is about 3μs. This grows to about 10μs for more complex apps (6 middleware functions, 3 levels of contexts, 150+ routes).


One key design choice we've made is our choice of routing algorithm. Most competing libraries use simple O(N) iteration over all routes to find a match. This is fine if you have only a handful of routes, but starts to break down as your app gets bigger. We use a tree-based router which grows in complexity at O(log(N)).

## Application Structure

### Making your router
The first thing you need to do is make a new router. Routers serve requests and execute middleware.

```go
router := web.New(YourContext{})
```

### Your context
Wait, what is YourContext{} and why do you need it? It can be any struct you want it to be. Here's an example of one:

```go
type YourContext struct {
 User *User // Assumes you've defined a User type as well
}
```

Your context can be empty or it can have various fields in it. The fields can be whatever you want - it's your type! When a new request comes into the router, we'll allocate an instance of this struct and pass it to your middleware and handlers. This allows, for instance, a SetUser middleware to set a User field that can be read in the handlers.

### Routes and handlers
Once you have your router, you can add routes to it. Standard HTTP verbs are supported.

```go
router := web.New(YourContext{})
router.Get("/users", (*YourContext).UsersList)
router.Post("/users", (*YourContext).UsersCreate)
router.Put("/users/:id", (*YourContext).UsersUpdate)
router.Delete("/users/:id", (*YourContext).UsersDelete)
router.Patch("/users/:id", (*YourContext).UsersUpdate)
router.Get("/", (*YourContext).Root)
```

What is that funny ```(*YourContext).Root``` notation? It's called a method expression. It lets your handlers look like this:

```go
func (c *YourContext) Root(rw web.ResponseWriter, req *web.Request) {
	if c.User != nil {
		fmt.Fprint(rw, "Hello,", c.User.Name)
	} else {
		fmt.Fprint(rw, "Hello, anonymous person")
	}
}
```

All method expressions do is return a function that accepts the type as the first argument. So your handler can also look like this:

```go
func Root(c *YourContext, rw web.ResponseWriter, req *web.Request) {}
```

Of course, if you don't need a context for a particular action, you can also do that:

```go
func Root(rw web.ResponseWriter, req *web.Request) {}
```

Note that handlers always need to accept two input parameters: web.ResponseWriter, and *web.Request, both of which wrap the standard http.ResponseWriter and *http.Request, respectively.

### Middleware
You can add middleware to a router:

```go
router := web.New(YourContext{})
router.Middleware((*YourContext).UserRequired)
// add routes, more middleware
```

This is what a middleware handler looks like:

```go
func (c *YourContext) UserRequired(rw web.ResponseWriter, r *web.Request, next web.NextMiddlewareFunc) {
	user := userFromSession(r) // Pretend like this is defined. It reads a session cookie and returns a *User or nil.
	if user != nil {
		c.User = user
		next(rw, r)
	} else {
		rw.Header().Set("Location", "/")
		rw.WriteHeader(http.StatusMovedPermanently)
		// do NOT call next()
	}
}
```

Some things to note about the above example:
* We set fields in the context for future middleware / handlers to use.
* We can call next(), or not. Not calling next() effectively stops the middleware stack.

Of course, generic middleware without contexts is supported:

```go
func GenericMiddleware(rw web.ResponseWriter, r *web.Request, next web.NextMiddlewareFunc) {
	// ...
}
```

### Nested routers
Nested routers let you run different middleware and use different contexts for different parts of your app. Some common scenarios:
* You want to run an AdminRequired middleware on all your admin routes, but not on API routes. Your context needs a CurrentAdmin field.
* You want to run an OAuth middleware on your API routes. Your context needs an AccessToken field.
* You want to run session handling middleware on ALL your routes. Your context needs a Session field.

Let's implement that. Your contexts would look like this:

```go
type Context struct {
	Session map[string]string
}

type AdminContext struct {
	*Context
	CurrentAdmin *User
}

type ApiContext struct {
	*Context
	AccessToken string
}
```

Note that we embed a pointer to the parent context in each subcontext. This is required.

Now that we have our contexts, let's create our routers:

```go
rootRouter := web.New(Context{})
rootRouter.Middleware((*Context).LoadSession)

apiRouter := rootRouter.Subrouter(ApiContext{}, "/api")
apiRouter.Middleware((*ApiContext).OAuth)
apiRouter.Get("/tickets", (*ApiContext).TicketsIndex)

adminRouter := rootRouter.Subrouter(AdminContext{}, "/admin")
adminRouter.Middleware((*AdminContext).AdminRequired)

// Given the path namesapce for this router is "/admin", the full path of this route is "/admin/reports"
adminRouter.Get("/reports", (*AdminContext).Reports)
```

Note that each time we make a subrouter, we need to supply the context as well as a path namespace. The context CAN be the same as the parent context, and the namespace CAN just be "/" for no namespace.

### Request lifecycle
The following is a detailed account of the request lifecycle:

1. A request comes in. Yay! (follow along in ```router_serve.go``` if you'd like)
2. Wrap the default Go http.ResponseWriter and http.Request in a web.ResponseWriter and web.Request, respectively (via structure embedding).
3. Allocate a new root context. This context is passed into your root middleware.
4. Execute middleware on the root router. We do this before we find a route!
5. After all of the root router's middleware is executed, we'll run a 'virtual' routing middleware that determines the target route.
 * If the there's no route found, we'll execute the NotFound handler if supplied. Otherwise, we'll write a 404 response and start unwinding the root middlware.
6. Now that we have a target route, we can allocate the context tree of the target router.
7. Start executing middleware on the nested middleware leading up to the final router/route.
8. After all middleware is executed, we'll run another 'virtual' middleware that invokes the final handler corresponding to the target route.
9. Unwind all middleware calls (if there's any code after next() in the middleware, obviously that's going to run at some point).

### Capturing path params; regexp conditions
You can capture path variables like this:

```go
router.Get("/suggestions/:suggestion_id/comments/:comment_id")
```

In your handler, you can access them like this:

```go
func (c *YourContext) Root(rw web.ResponseWriter, req *web.Request) {
	fmt.Fprint(rw, "Suggestion ID:", req.PathParams["suggestion_id"])
	fmt.Fprint(rw, "Comment ID:", req.PathParams["comment_id"])
}
```

You can also validate the format of your path params with a regexp. For instance, to ensure the 'ids' start with a digit:

```go
router.Get("/suggestions/:suggestion_id:\\d.*/comments/:comment_id:\\d.*")
```

You can match any route past a certain point like this:

```go
router.Get("/suggestions/:suggestion_id/comments/:comment_id/:*")
```

The path params will contain a “*” member with the rest of your path. It is illegal to add any more paths past the “*” path param, as it’s meant to match every path afterwards, in all cases.

For Example:
 /suggestions/123/comments/321/foo/879/bar/834

Elicits path params:
 * “suggestion_id”: 123,
 * “comment_id”: 321,
 * “*”: “foo/879/bar/834”


One thing you CANNOT currently do is use regexps outside of a path segment. For instance, optional path segments are not supported - you would have to define multiple routes that both point to the same handler. This design decision was made to enable efficient routing.

### Not Found handlers
If a route isn't found, by default we'll return a 404 status and render the text "Not Found".

You can supply a custom NotFound handler on your root router:

```go
router.NotFound((*Context).NotFound)
```

Your handler can optionally accept a pointer to the root context. NotFound handlers look like this:

```go
func (c *Context) NotFound(rw web.ResponseWriter, r *web.Request) {
	rw.WriteHeader(http.StatusNotFound) // You probably want to return 404. But you can also redirect or do whatever you want.
	fmt.Fprintf(rw, "My Not Found") // Render you own HTML or something!
}
```

### OPTIONS handlers
If an [OPTIONS request](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing#Preflight_example) is made and routes with other methods are found for the requested path, then by default we'll return an empty response with an appropriate `Access-Control-Allow-Methods` header.

You can supply a custom OPTIONS handler on your root router:

```go
router.OptionsHandler((*Context).OptionsHandler)
```

Your handler can optionally accept a pointer to the root context. OPTIONS handlers look like this:

```go
func (c *Context) OptionsHandler(rw web.ResponseWriter, r *web.Request, methods []string) {
	rw.Header().Add("Access-Control-Allow-Methods", strings.Join(methods, ", "))
	rw.Header().Add("Access-Control-Allow-Origin", "*")
}
```

### Error handlers
By default, if there's a panic in middleware or a handler, we'll return a 500 status and render the text "Application Error".

If you use the included middleware ```web.ShowErrorsMiddleware```, a panic will result in a pretty backtrace being rendered in HTML. This is great for development.

You can also supply a custom Error handler on any router (not just the root router):

```go
router.Error((*Context).Error)
```

Your handler can optionally accept a pointer to its corresponding context. Error handlers look like this:

```go
func (c *Context) Error(rw web.ResponseWriter, r *web.Request, err interface{}) {
	rw.WriteHeader(http.StatusInternalServerError)
	fmt.Fprint(w, "Error", err)
}
```

### Included middleware
We ship with three basic pieces of middleware: a logger, an exception printer, and a static file server. To use them:

```go
router := web.New(Context{})
router.Middleware(web.LoggerMiddleware).
	Middleware(web.ShowErrorsMiddleware)

// The static middleware serves files. Examples:
// "GET /" will serve an index file at pwd/public/index.html
// "GET /robots.txt" will serve the file at pwd/public/robots.txt
// "GET /images/foo.gif" will serve the file at pwd/public/images/foo.gif
currentRoot, _ := os.Getwd()
router.Middleware(web.StaticMiddleware(path.Join(currentRoot, "public"), web.StaticOption{IndexFile: "index.html"}))
```

NOTE: You might not want to use web.ShowErrorsMiddleware in production. You can easily do something like this:
```go
router := web.New(Context{})
router.Middleware(web.LoggerMiddleware)
if MyEnvironment == "development" {
	router.Middleware(web.ShowErrorsMiddleware)
}
// ...
```

### Starting your server
Since web.Router implements http.Handler (eg, ServeHTTP(ResponseWriter, *Request)), you can easily plug it in to the standard Go http machinery:

```go
router := web.New(Context{})
// ... Add routes and such.
http.ListenAndServe("localhost:8080", router)
```

### Rendering responses
So now you routed a request to a handler. You have a web.ResponseWriter (http.ResponseWriter) and web.Request (http.Request). Now what?

```go
// You can print to the ResponseWriter!
fmt.Fprintf(rw, "<html>I'm a web page!</html>")
```

This is currently where the implementation of this library stops. I recommend you read the documentation of [net/http](http://golang.org/pkg/net/http/).

## Extra Middlware
This package is going to keep the built-in middlware simple and lean. Extra middleware can be found across the web:
* [https://github.com/corneldamian/json-binding](https://github.com/corneldamian/json-binding) - mapping JSON request into a struct and response to json

If you'd like me to link to your middleware, let me know with a pull request to this README.

## gocraft

gocraft offers a toolkit for building web apps. Currently these packages are available:

* [gocraft/web](https://github.com/gocraft/web) - Go Router + Middleware. Your Contexts.
* [gocraft/dbr](https://github.com/gocraft/dbr) - Additions to Go's database/sql for super fast performance and convenience.
* [gocraft/health](https://github.com/gocraft/health) - Instrument your web apps with logging and metrics.
* [gocraft/work](https://github.com/gocraft/work) - Process background jobs in Go.

These packages were developed by the [engineering team](https://eng.uservoice.com) at [UserVoice](https://www.uservoice.com) and currently power much of its infrastructure and tech stack.

## Thanks & Authors
I use code/got inspiration from these excellent libraries:
* [Revel](https://github.com/robfig/revel) - pathtree routing.
* [Traffic](https://github.com/pilu/traffic) - inspiration, show errors middleware.
* [Martini](https://github.com/codegangsta/martini) - static file serving.
* [gorilla/mux](http://www.gorillatoolkit.org/pkg/mux) - inspiration.

Authors:
* Jonathan Novak -- [https://github.com/cypriss](https://github.com/cypriss)
* Sponsored by [UserVoice](https://eng.uservoice.com)

gocraft/web

Goji is a minimalistic and flexible HTTP request multiplexer with support for `net/context`

Goji
====

[![GoDoc](https://godoc.org/goji.io?status.svg)](https://godoc.org/goji.io) [![Build Status](https://travis-ci.org/goji/goji.svg?branch=master)](https://travis-ci.org/goji/goji)

Goji is a HTTP request multiplexer, similar to [`net/http.ServeMux`][servemux].
It compares incoming requests to a list of registered [Patterns][pattern], and
dispatches to the [http.Handler][handler] that corresponds to the first matching
Pattern. Goji also supports [Middleware][middleware] (composable shared
functionality applied to every request) and uses the standard
[`context`][context] package to store request-scoped values.

[servemux]: https://golang.org/pkg/net/http/#ServeMux
[pattern]: https://godoc.org/goji.io#Pattern
[handler]: https://golang.org/pkg/net/http/#Handler
[middleware]: https://godoc.org/goji.io#Mux.Use
[context]: https://golang.org/pkg/context


Quick Start
-----------

```go
package main

import (
        "fmt"
        "net/http"

        "goji.io"
        "goji.io/pat"
)

func hello(w http.ResponseWriter, r *http.Request) {
        name := pat.Param(r, "name")
        fmt.Fprintf(w, "Hello, %s!", name)
}

func main() {
        mux := goji.NewMux()
        mux.HandleFunc(pat.Get("/hello/:name"), hello)

        http.ListenAndServe("localhost:8000", mux)
}
```

Please refer to [Goji's GoDoc Documentation][godoc] for a full API reference.

[godoc]: https://godoc.org/goji.io


Stability
---------

Goji's API was recently updated to use the new `net/http` and `context`
integration, and is therefore some of its interfaces are in a state of flux. We
don't expect any further changes to the API, and expect to be able to announce
API stability soon. Goji is suitable for use in production.

Prior to Go 1.7, Goji promised API stability with a different API to the one
that is offered today. The author broke this promise, and does not take this
breach of trust lightly. While stability is obviously extremely important, the
author and community have decided to follow the broader Go community in
standardizing on the standard library copy of the `context` package.

Users of the old API can find that familiar API on the `net-context` branch. The
author promises to maintain both the `net-context` branch and `master` for the
forseeable future.


Community / Contributing
------------------------

Goji maintains a mailing list, [gojiberries][berries], where you should feel
welcome to ask questions about the project (no matter how simple!), to announce
projects or libraries built on top of Goji, or to talk about Goji more
generally. Goji's author (Carl Jackson) also loves to hear from users directly
at his personal email address, which is available on his GitHub profile page.

Contributions to Goji are welcome, however please be advised that due to Goji's
stability guarantees interface changes are unlikely to be accepted.

All interactions in the Goji community will be held to the high standard of the
broader Go community's [Code of Conduct][conduct].

[berries]: https://groups.google.com/forum/#!forum/gojiberries
[conduct]: https://golang.org/conduct


Goji

GoLobby Router is a lightweight yet powerful HTTP router for the Go programming language

[![Go Reference](https://pkg.go.dev/badge/github.com/golobby/router.svg)](https://pkg.go.dev/github.com/golobby/router)
[![CI](https://github.com/golobby/router/actions/workflows/ci.yml/badge.svg)](https://github.com/golobby/router/actions/workflows/ci.yml)
[![CodeQL](https://github.com/golobby/router/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/golobby/router/actions/workflows/codeql-analysis.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/golobby/router)](https://goreportcard.com/report/github.com/golobby/router)
[![Coverage Status](https://coveralls.io/repos/github/golobby/router/badge.svg?r=2)](https://coveralls.io/github/golobby/router?branch=master)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 

# GoLobby Router
GoLobby Router is a lightweight yet powerful HTTP router for the Go programming language.
It's built on top of the Go HTTP package and uses radix tree to provide the following features:
* Routing based on HTTP method and URI
* Route parameters and parameter patterns
* Route wildcards
* Middleware
* HTTP Responses (such as JSON, XML, Text, Empty, File, and Redirect)
* Static file serving
* No footprint!
* Zero-dependency!

## Documentation
### Required Go Version
It requires Go `v1.11` or newer versions.

### Installation
To install this package, run the following command in your project directory.

```bash
go get github.com/golobby/router
```

### Quick Start
The following example demonstrates a simple example of using the router package.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 r.GET("/", func(c router.Context) error {
 // c.Request() is original http.Request
 // c.Response() is original http.ResponseWriter
 return c.Text(http.StatusOK, "Hello from GoLobby Router!")
 })
 
 r.PUT("/products/:id", func(c router.Context) error {
 return c.Text(http.StatusOK, "Update product with ID: "+c.Parameter("id"))
 })
 
 log.Fatalln(r.Start(":8000"))
}
```

### HTTP Methods
You can use the `Map()` method to declare routes.
It gets HTTP methods and paths (URIs).
There are also some methods available for the most used HTTP methods.
These methods are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS`.
The `Any()` method defines routes that handles any HTTP method.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func Handler(c router.Context) error {
 return c.Text(http.StatusOK, "Hello from GoLobby Router!")
}

func main() {
 r := router.New()
 
 r.GET("/", Handler)
 r.POST("/", Handler)
 r.PUT("/", Handler)
 r.PATCH("/", Handler)
 r.DELETE("/", Handler)
 r.HEAD("/", Handler)
 r.OPTIONS("/", Handler)
 
 r.Any("/page", Handler)
 
 r.Map("GET", "/", Handler)
 r.Map("CUSTOM", "/", Handler)
 
 log.Fatalln(r.Start(":8000"))
}
```

### Route Parameters
To specify route parameters, prepend a colon like `:id`.
In default, parameters could be anything but you can determine a regex pattern using the `Define()` method. Of course, regex patterns slow down your application, and it is recommended not to use them if possible.
To catch and check route parameters in your handlers, you'll have the `Parameters()`, `Parameter()`, and `HasParameter()` methods.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 // "id" parameters must be numeric
 r.Define("id", "[0-9]+")
 
 // a route with one parameter
 r.GET("/posts/:id", func(c router.Context) error {
 return c.Text(http.StatusOK, c.Parameter("id"))
 })
 
 // a route with multiple parameters
 r.GET("/posts/:id/comments/:cid", func(c router.Context) error {
 return c.JSON(http.StatusOK, c.Parameters())
 })
 
 log.Fatalln(r.Start(":8000"))
}
```

### Wildcard Routes
Wildcard routes match any URI with the specified prefix.
The following example shows how it works.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 // Other routes with the same pattern should come first.
 r.GET("/pages/contact", ContactHandler)
 
 r.GET("/pages/*", PagesHandler)
 // It matches:
 // - /pages/
 // - /pages/about
 // - /pages/about/us
 // - /pages/help
 
 log.Fatalln(r.Start(":8000"))
}
```

### Serving Static Files
The `Files` method is provided to serve static files directly.
The example below demonstrate how to use it.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 // Other routes with the same pattern should come first.
 r.GET("/api", YourApiHandler)
 
 // The path (URI) must end with `*`.
 r.Files("/*", "./files")
 // example.com/ ==> ./files/index.html
 // example.com/photo.jpg ==> ./files/photo.jpg
 // example.com/notes/1.txt ==> ./files/notes/1.txt
 
 log.Fatalln(r.Start(":8000"))
}
```

### Named Routes
Named routes allow the convenient generation of URLs or redirects for specific routes.
You may specify a name for a route by chaining the `SetName()` method onto the route definition:

```go
package main

import (
 "github.com/golobby/router"
 "github.com/golobby/router/pkg/response"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 r.GET("/", func(c router.Context) error {
 return c.Text(http.StatusOK, "I am the home!")
 }).SetName("home")
 
 r.GET("/posts/:id", func(c router.Context) error {
 return c.Text(http.StatusOK, "I am a post!")
 }).SetName("post")
 
 r.GET("/links", func(c router.Context) error {
 return c.JSON(http.StatusOK, response.M{
 "home": c.URL("home", nil), // "/"
 "post-1": c.URL("post", map[string]string{"id": "1"}), // "/posts/1"
 "post-2": c.URL("post", map[string]string{"id": "2"}), // "/posts/2"
 })
 })
 
 log.Fatalln(r.Start(":8000"))
}
```

### Responses
The router comes with `Empty`, `Redirect`, `Text`, `HTML`, `JSON`, `PrettyJSON`, `XML`, `PrettyXML`, and `Bytes` responses out of the box.
The examples below demonstrate how to use built-in and custom responses.

```go
package main

import (
 "github.com/golobby/router"
 "github.com/golobby/router/pkg/response"
 "log"
 "net/http"
)

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

 r.GET("/empty", func(c router.Context) error {
 return c.Empty(204)
 })

 r.GET("/redirect", func(c router.Context) error {
 return c.Redirect(301, "https://github.com/golobby/router")
 })

 r.GET("/text", func(c router.Context) error {
 return c.Text(200, "A text response")
 })

 r.GET("/html", func(c router.Context) error {
 return c.HTML(200, "A HTML response")
 })

 r.GET("/json", func(c router.Context) error {
 return c.JSON(200, User{"id": 13})
 })

 r.GET("/json", func(c router.Context) error {
 return c.JSON(200, response.M{"message": "Using response.M helper"})
 })

 r.GET("/json-pretty", func(c router.Context) error {
 return c.PrettyJSON(200, response.M{"message": "A pretty JSON response!"})
 })

 r.GET("/xml", func(c router.Context) error {
 return c.XML(200, User{"id": 13})
 })

 r.GET("/xml-pretty", func(c router.Context) error {
 return c.PrettyXML(200, User{"id": 13})
 })

 r.GET("/bytes", func(c router.Context) error {
 return c.Bytes(200, []bytes("Some bytes!"))
 })

 r.GET("/file", func(c router.Context) error {
	return c.File(200, "text/plain", "text.txt")
 })

 r.GET("/custom", func(c router.Context) error {
 c.Response().Header().Set("Content-Type", "text/csv")
 return c.Bytes(200, []bytes("Column 1, Column 2, Column 3"))
 })

 log.Fatalln(r.Start(":8000"))
}
```

### Groups
You may put routes with similar attributes in groups.
Currently, prefix and middleware attributes are supported.

#### Group by prefix
The example below demonstrates how to group routes with the same prefix.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 r.WithPrefix("/blog", func() {
 r.GET("/posts", PostsHandler) // "/blog/posts"
 r.GET("/posts/:id", PostHandler) // "/blog/posts/:id"
 r.WithPrefix("/pages", func() {
 r.GET("/about", AboutHandler) // "/blog/pages/about"
 r.GET("/contact", ContactHandler) // "/blog/pages/contact"
 })
 })
 
 log.Fatalln(r.Start(":8000"))
}
```

#### Group by middleware
The example below demonstrates how to group routes with the same middleware.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func AdminMiddleware(next router.Handler) router.Handler {
 return func(c router.Context) error {
 // Check user roles...
 return next(c)
 }
}

func main() {
 r := router.New()
 
 r.WithMiddleware(AdminMiddleware, func() {
 r.GET("/admin/users", UsersHandler)
 r.GET("/admin/products", ProductsHandler)
 })
 
 log.Fatalln(r.Start(":8000"))
}
```

#### Group by middlewares
The example below demonstrates how to group routes with the same middlewares.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 middlewares := []router.Middleware{Middleware1, Middleware2, Middleware3}
 r.WithMiddlewares(middlewares, func() {
 r.GET("/posts", PostsIndexHandler)
 })
 
 log.Fatalln(r.Start(":8000"))
}
```

#### Group by multiple attributes
The `group()` method helps you create a group of routes with the same prefix and middlewares.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 r.Group("/blog", []router.Middleware{Middleware1, Middleware2}, func() {
 r.GET("/posts", PostsHandler)
 r.GET("/posts/:id/comments", CommentsHandler)
 })
 
 log.Fatalln(r.Start(":8000"))
}
```

### Basic Attributes
Your application might need a base prefix or global middlewares.
In this case, you can set up these base attributes before defining routes.

#### Base prefix
The following example shows how to set a base prefix for all routes.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 // Add a prefix to all routes
 r.AddPrefix("/blog")

 r.GET("/posts", PostsHandler)
 r.GET("/posts/:id/comments", CommentsHandler)
 
 log.Fatalln(r.Start(":8000"))
}
```

#### Base middlewares
The following example shows how to set a base middlewares for all routes.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 // Add a single middleware
 r.AddMiddleware(LoggerMiddleware)
 
 // Add multiple middlewares at once
 r.AddMiddlewares([]router.Middleware{AuthMiddleware, ThrottleMiddleware})

 r.GET("/users", UsersHandler)
 r.GET("/users/:id/files", FilesHandler)
 
 log.Fatalln(r.Start(":8000"))
}
```

### 404 Handler
In default, the router returns the following HTTP 404 response when a requested URI doesn't match any route.

```json
{"message": "Not found."}
```

You can set your custom handler like the following example.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 // Custom (HTML) Not Found Handler
 r.SetNotFoundHandler(func(c router.Context) error {
 return c.HTML(404, "404 Not Found")
 })

 r.GET("/", Handler)
 
 log.Fatalln(r.Start(":8000"))
}
```

### Error Handling
Your handlers might return an error while processing the HTTP request.
This error can be produced by your application logic or failure in the HTTP response.
By default, the router logs it using Golang's built-in logger into the standard output and returns the HTTP 500 response below.

```json
{"message": "Internal error."}
```

It's a good practice to add a global middleware to catch all these errors, log and handle them the way you need.
The example below demonstrates how to add middleware for handling errors.

```go
package main

import (
 "github.com/golobby/router"
 "log"
 "net/http"
)

func main() {
 r := router.New()
 
 // Error Handler
 r.AddMiddleware(func (next router.Handler) router.Handler {
 return func(c router.Context) error {
 if err := next(c); err != nil {
 myLogger.log(err)
 return c.HTML(500, "Something went wrong")
 }
 
 // No error will raise to the router base handler
 return nil
 }
 })

 r.GET("/", Handler)
 
 log.Fatalln(r.Start(":8000"))
}
```

## License
GoLobby Router is released under the [MIT License](http://opensource.org/licenses/mit-license.php).

GoLobby/Router

Lightning fast HTTP router fully compatible with the net/http.Handler interface

# [![gowww](https://avatars.githubusercontent.com/u/18078923?s=20)](https://github.com/gowww) router [![GoDoc](https://godoc.org/github.com/gowww/router?status.svg)](https://godoc.org/github.com/gowww/router) [![Build](https://travis-ci.org/gowww/router.svg?branch=master)](https://travis-ci.org/gowww/router) [![Coverage](https://coveralls.io/repos/github/gowww/router/badge.svg?branch=master)](https://coveralls.io/github/gowww/router?branch=master) [![Go Report](https://goreportcard.com/badge/github.com/gowww/router)](https://goreportcard.com/report/github.com/gowww/router) ![Status Stable](https://img.shields.io/badge/status-stable-brightgreen.svg)

Package [router](https://godoc.org/github.com/gowww/router) provides a lightning fast HTTP router.

- [Features](#features)
- [Installing](#installing)
- [Usage](#usage)
	- [Parameters](#parameters)
		- [Named](#named)
		- [Regular expressions](#regular-expressions)
		- [Wildcard](#wildcard)
	- [Static files](#static-files)
	- [Custom "not found" handler](#custom-not-found-handler)

## Features

- Extreme performance: [sub-microsecond routing](https://gist.github.com/xthezealot/bb632f6b104deb2a50ce476c25f7bec2) in most cases
- Full compatibility with the [http.Handler](https://golang.org/pkg/net/http/#Handler) interface
- Generic: no magic methods, bring your own handlers
- Path parameters, regular expressions and wildcards
- Smart prioritized routes
- Zero memory allocations during serving (but for parameters)
- Respecting the principle of least surprise
- Tested and used in production

## Installing

1. Get package:

	```Shell
	go get -u github.com/gowww/router
	```

2. Import it in your code:

	```Go
	import "github.com/gowww/router"
	```

## Usage

1. Make a new router:

	```Go
	rt := router.New()
	```

2. Make a route:

	```Go
	rt.Handle("GET", "/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprint(w, "Hello")
	}))
	```

	Remember that HTTP methods are case-sensitive and uppercase by convention ([RFC 7231 4.1](https://tools.ietf.org/html/rfc7231#section-4.1)). 
	So you can directly use the built-in shortcuts for standard HTTP methods: [Router.Get](https://godoc.org/github.com/gowww/router#Router.Get), [Router.Post](https://godoc.org/github.com/gowww/router#Router.Post), [Router.Put](https://godoc.org/github.com/gowww/router#Router.Put), [Router.Patch](https://godoc.org/github.com/gowww/router#Router.Patch) and [Router.Delete](https://godoc.org/github.com/gowww/router#Router.Delete).

3. Give the router to the server:

	```Go
	http.ListenAndServe(":8080", rt)
	```

### Parameters

#### Named

A named parameter begins with `:` and matches any value until the next `/` or end of path.

To retrieve the value (stored in request's context), ask [Parameter](https://godoc.org/github.com/gowww/router#Parameter). 
It will return the value as a string.

Example, with a parameter `id`:

```Go
rt.Get("/users/:id", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	id := router.Parameter(r, "id")
	fmt.Fprintf(w, "Page of user #%s", id)
}))
```

<details>
<summary>No surprise</summary>

A parameter can be used on the same level as a static route, without conflict:

```Go
rt.Get("/users/all", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "All users page")
}))

rt.Get("/users/:id", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	id := router.Parameter(r, "id")
	fmt.Fprintf(w, "Page of user #%s", id)
}))
```
</details>

#### Regular expressions

If a parameter must match an exact pattern (digits only, for example), you can also set a [regular expression](https://golang.org/pkg/regexp/syntax) constraint just after the parameter name and another `:`:

```Go
rt.Get(`/users/:id:^\d+$`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	id := router.Parameter(r, "id")
	fmt.Fprintf(w, "Page of user #%s", id)
}))
```

If you don't need to retrieve the parameter value but only use a regular expression, you can omit the parameter name:

```Go
rt.Get(`/shows/::^prison-break-s06-.+`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "Prison Break S06 — Coming soon…")
}))
```

Don't forget that regular expressions can significantly reduce performance.

<details>
<summary>No surprise</summary>

A parameter with a regular expression can be used on the same level as a simple parameter, without conflict:

```Go
rt.Get(`/users/:id:^\d+$`, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	id := router.Parameter(r, "id")
	fmt.Fprintf(w, "Page of user #%s", id)
}))

rt.Get("/users/:name", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	name := router.Parameter(r, "name")
	fmt.Fprintf(w, "Page of %s", name)
}))
```
</details>

#### Wildcard

A trailing slash in a route path is significant. 
It behaves like a wildcard by matching the beginning of the request path. 
The rest of the request path becomes the parameter value of `*`:

```Go
rt.Get("/files/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	filepath := router.Parameter(r, "*")
	fmt.Fprintf(w, "Get file %s", filepath)
}))
```

Note that a trailing slash in a request path is always trimmed and the client redirected. 
For example, a request for `/files/` will be redirected to `/files` and will never match a `/files/` route. 
In other words, `/files` and `/files/` are two different routes.

<details>
<summary>No surprise</summary>

Deeper route paths with the same prefix as the wildcard will take precedence, without conflict:

```Go
// Will match:
// 	/files/one
// 	/files/two
// 	...
rt.Get("/files/:name", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {kv
	name := router.Parameter(r, "name")
	fmt.Fprintf(w, "Get root file #%s", name)
}))

// Will match:
// 	/files/one/...
// 	/files/two/...
// 	...
rt.Get("/files/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	filepath := router.Parameter(r, "*")
	fmt.Fprintf(w, "Get file %s", filepath)
}))

// Will match:
// 	/files/movies/one
// 	/files/movies/two
// 	...
rt.Get("/files/movies/:name", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	name := router.Parameter(r, "name")
	fmt.Fprintf(w, "Get movie #%s", name)
}))
```
</details>

### Static files

For serving static files, like for other routes, just bring your own handler.

Example, with the standard [net/http.FileServer](https://golang.org/pkg/net/http#FileServer):

```Go
rt.Get("/static/", http.StripPrefix("/static/", http.FileServer(http.Dir("static"))))
```

### Custom "not found" handler

When a request match no route, the response status is set to 404 and an empty body is sent by default.

But you can set your own "not found" handler. 
In this case, it's up to you to set the response status code (normally 404):

```Go
rt.NotFoundHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	http.NotFound(w, r)
})
```

gowww/router

High performance router. Use this and the standard http handlers to form a very high performance web framework

# HttpRouter [![Coverage Status](https://coveralls.io/repos/github/julienschmidt/httprouter/badge.svg?branch=master)](https://coveralls.io/github/julienschmidt/httprouter?branch=master) [![Docs](https://godoc.org/github.com/julienschmidt/httprouter?status.svg)](http://pkg.go.dev/github.com/julienschmidt/httprouter)

HttpRouter is a lightweight high performance HTTP request router (also called *multiplexer* or just *mux* for short) for [Go](https://golang.org/).

In contrast to the [default mux](https://golang.org/pkg/net/http/#ServeMux) of Go's `net/http` package, this router supports variables in the routing pattern and matches against the request method. It also scales better.

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

## Features

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

**Stop caring about trailing slashes:** Choose the URL style you like, the router automatically redirects the client if a trailing slash is missing or if there is one extra. Of course it only does so, if the new path has a handler. If you don't like it, you can [turn off this behavior](https://godoc.org/github.com/julienschmidt/httprouter#Router.RedirectTrailingSlash).

**Path auto-correction:** Besides detecting the missing or additional trailing slash at no extra cost, the router can also fix wrong cases and remove superfluous path elements (like `../` or `//`). Is [CAPTAIN CAPS LOCK](http://www.urbandictionary.com/define.php?term=Captain+Caps+Lock) one of your users? HttpRouter can help him by making a case-insensitive look-up and redirecting him to the correct URL.

**Parameters in your routing pattern:** Stop parsing the requested URL path, just give the path segment a name and the router delivers the dynamic value to you. Because of the design of the router, path parameters are very cheap.

**Zero Garbage:** The matching and dispatching process generates zero bytes of garbage. The only heap allocations that are made are building the slice of the key-value pairs for path parameters, and building new context and request objects (the latter only in the standard `Handler`/`HandlerFunc` API). In the 3-argument API, if the request path contains no parameters not a single heap allocation is necessary.

**Best Performance:** [Benchmarks speak for themselves](https://github.com/julienschmidt/go-http-routing-benchmark). See below for technical details of the implementation.

**No more server crashes:** You can set a [Panic handler](https://godoc.org/github.com/julienschmidt/httprouter#Router.PanicHandler) to deal with panics occurring during handling a HTTP request. The router then recovers and lets the `PanicHandler` log what happened and deliver a nice error page.

**Perfect for APIs:** The router design encourages to build sensible, hierarchical RESTful APIs. Moreover it has built-in native support for [OPTIONS requests](http://zacstewart.com/2012/04/14/http-options-method.html) and `405 Method Not Allowed` replies.

Of course you can also set **custom [`NotFound`](https://godoc.org/github.com/julienschmidt/httprouter#Router.NotFound) and [`MethodNotAllowed`](https://godoc.org/github.com/julienschmidt/httprouter#Router.MethodNotAllowed) handlers** and [**serve static files**](https://godoc.org/github.com/julienschmidt/httprouter#Router.ServeFiles).

## Usage

This is just a quick introduction, view the [Docs](http://pkg.go.dev/github.com/julienschmidt/httprouter) for details.

 $ go get github.com/julienschmidt/httprouter

and use it, like in this trivial example:

```go
package main

import (
 "fmt"
 "net/http"
 "log"

 "github.com/julienschmidt/httprouter"
)

func Index(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 fmt.Fprint(w, "Welcome!\n")
}

func Hello(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
 fmt.Fprintf(w, "hello, %s!\n", ps.ByName("name"))
}

func main() {
 router := httprouter.New()
 router.GET("/", Index)
 router.GET("/hello/:name", Hello)

 log.Fatal(http.ListenAndServe(":8080", router))
}
```

### Named parameters

As you can see, `:name` is a *named parameter*. The values are accessible via `httprouter.Params`, which is just a slice of `httprouter.Param`s. You can get the value of a parameter either by its index in the slice, or by using the `ByName(name)` method: `:name` can be retrieved by `ByName("name")`.

When using a `http.Handler` (using `router.Handler` or `http.HandlerFunc`) instead of HttpRouter's handle API using a 3rd function parameter, the named parameters are stored in the `request.Context`. See more below under [Why doesn't this work with http.Handler?](#why-doesnt-this-work-with-httphandler).

Named parameters only match a single path segment:

```
Pattern: /user/:user

 /user/gordon match
 /user/you match
 /user/gordon/profile no match
 /user/ no match
```

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

### Catch-All parameters

The second type are *catch-all* parameters and have the form `*name`. Like the name suggests, they match everything. Therefore they must always be at the **end** of the pattern:

```
Pattern: /src/*filepath

 /src/ match
 /src/somefile.go match
 /src/subdir/somefile.go match
```

## How does it work?

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

```
Priority Path Handle
9 \ *<1>
3 ├s nil
2 |├earch\ *<2>
1 |└upport\ *<3>
2 ├blog\ *<4>
1 | └:post nil
1 | └\ *<5>
2 ├about-us\ *<6>
1 | └team\ *<7>
1 └contact\ *<8>
```

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

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

For even better scalability, the child nodes on each tree level are ordered by priority, where the priority is just the number of handles registered in sub nodes (children, grandchildren, and so on..). This helps in two ways:

1. Nodes which are part of the most routing paths are evaluated first. This helps to make as much routes as possible to be reachable as fast as possible.
2. It is some sort of cost compensation. The longest reachable path (highest cost) can always be evaluated first. The following scheme visualizes the tree structure. Nodes are evaluated from top to bottom and from left to right.

```
├------------
├---------
├-----
├----
├--
├--
└-
```

## Why doesn't this work with `http.Handler`?

**It does!** The router itself implements the `http.Handler` interface. Moreover the router provides convenient [adapters for `http.Handler`](https://godoc.org/github.com/julienschmidt/httprouter#Router.Handler)s and [`http.HandlerFunc`](https://godoc.org/github.com/julienschmidt/httprouter#Router.HandlerFunc)s which allows them to be used as a [`httprouter.Handle`](https://godoc.org/github.com/julienschmidt/httprouter#Router.Handle) when registering a route.

Named parameters can be accessed `request.Context`:

```go
func Hello(w http.ResponseWriter, r *http.Request) {
 params := httprouter.ParamsFromContext(r.Context())

 fmt.Fprintf(w, "hello, %s!\n", params.ByName("name"))
}
```

Alternatively, one can also use `params := r.Context().Value(httprouter.ParamsKey)` instead of the helper function.

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

## Automatic OPTIONS responses and CORS

One might wish to modify automatic responses to OPTIONS requests, e.g. to support [CORS preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/preflight_request) or to set other headers.
This can be achieved using the [`Router.GlobalOPTIONS`](https://godoc.org/github.com/julienschmidt/httprouter#Router.GlobalOPTIONS) handler:

```go
router.GlobalOPTIONS = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 if r.Header.Get("Access-Control-Request-Method") != "" {
 // Set CORS headers
 header := w.Header()
 header.Set("Access-Control-Allow-Methods", header.Get("Allow"))
 header.Set("Access-Control-Allow-Origin", "*")
 }

 // Adjust status code to 204
 w.WriteHeader(http.StatusNoContent)
})
```

## Where can I find Middleware *X*?

This package just provides a very efficient request router with a few extra features. The router is just a [`http.Handler`](https://golang.org/pkg/net/http/#Handler), you can chain any http.Handler compatible middleware before the router, for example the [Gorilla handlers](http://www.gorillatoolkit.org/pkg/handlers). Or you could [just write your own](https://justinas.org/writing-http-middleware-in-go/), it's very easy!

Alternatively, you could try [a web framework based on HttpRouter](#web-frameworks-based-on-httprouter).

### Multi-domain / Sub-domains

Here is a quick example: Does your server serve multiple domains / hosts?
You want to use sub-domains?
Define a router per host!

```go
// We need an object that implements the http.Handler interface.
// Therefore we need a type for which we implement the ServeHTTP method.
// We just use a map here, in which we map host names (with port) to http.Handlers
type HostSwitch map[string]http.Handler

// Implement the ServeHTTP method on our new type
func (hs HostSwitch) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// Check if a http.Handler is registered for the given host.
	// If yes, use it to handle the request.
	if handler := hs[r.Host]; handler != nil {
		handler.ServeHTTP(w, r)
	} else {
		// Handle host names for which no handler is registered
		http.Error(w, "Forbidden", 403) // Or Redirect?
	}
}

func main() {
	// Initialize a router as usual
	router := httprouter.New()
	router.GET("/", Index)
	router.GET("/hello/:name", Hello)

	// Make a new HostSwitch and insert the router (our http handler)
	// for example.com and port 12345
	hs := make(HostSwitch)
	hs["example.com:12345"] = router

	// Use the HostSwitch to listen and serve on port 12345
	log.Fatal(http.ListenAndServe(":12345", hs))
}
```

### Basic Authentication

Another quick example: Basic Authentication (RFC 2617) for handles:

```go
package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/julienschmidt/httprouter"
)

func BasicAuth(h httprouter.Handle, requiredUser, requiredPassword string) httprouter.Handle {
	return func(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
		// Get the Basic Authentication credentials
		user, password, hasAuth := r.BasicAuth()

		if hasAuth && user == requiredUser && password == requiredPassword {
			// Delegate request to the given handle
			h(w, r, ps)
		} else {
			// Request Basic Authentication otherwise
			w.Header().Set("WWW-Authenticate", "Basic realm=Restricted")
			http.Error(w, http.StatusText(http.StatusUnauthorized), http.StatusUnauthorized)
		}
	}
}

func Index(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
	fmt.Fprint(w, "Not protected!\n")
}

func Protected(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
	fmt.Fprint(w, "Protected!\n")
}

func main() {
	user := "gordon"
	pass := "secret!"

	router := httprouter.New()
	router.GET("/", Index)
	router.GET("/protected/", BasicAuth(Protected, user, pass))

	log.Fatal(http.ListenAndServe(":8080", router))
}
```

## Chaining with the NotFound handler

**NOTE: It might be required to set [`Router.HandleMethodNotAllowed`](https://godoc.org/github.com/julienschmidt/httprouter#Router.HandleMethodNotAllowed) to `false` to avoid problems.**

You can use another [`http.Handler`](https://golang.org/pkg/net/http/#Handler), for example another router, to handle requests which could not be matched by this router by using the [`Router.NotFound`](https://godoc.org/github.com/julienschmidt/httprouter#Router.NotFound) handler. This allows chaining.

### Static files

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

```go
// Serve static files from the ./public directory
router.NotFound = http.FileServer(http.Dir("public"))
```

But this approach sidesteps the strict core rules of this router to avoid routing problems. A cleaner approach is to use a distinct sub-path for serving files, like `/static/*filepath` or `/files/*filepath`.

## Web Frameworks based on HttpRouter

If the HttpRouter is a bit too minimalistic for you, you might try one of the following more high-level 3rd-party web frameworks building upon the HttpRouter package:

* [Ace](https://github.com/plimble/ace): Blazing fast Go Web Framework
* [api2go](https://github.com/manyminds/api2go): A JSON API Implementation for Go
* [Gin](https://github.com/gin-gonic/gin): Features a martini-like API with much better performance
* [Goat](https://github.com/bahlo/goat): A minimalistic REST API server in Go
* [goMiddlewareChain](https://github.com/TobiEiss/goMiddlewareChain): An express.js-like-middleware-chain
* [Hikaru](https://github.com/najeira/hikaru): Supports standalone and Google AppEngine
* [Hitch](https://github.com/nbio/hitch): Hitch ties httprouter, [httpcontext](https://github.com/nbio/httpcontext), and middleware up in a bow
* [httpway](https://github.com/corneldamian/httpway): Simple middleware extension with context for httprouter and a server with gracefully shutdown support
* [intake](https://github.com/dbubel/intake): intake is a minimal http framework with enphasis on middleware groups
* [Jett](https://github.com/saurabh0719/jett): A lightweight framework with subrouters, graceful shutdown and middleware at all levels.
* [kami](https://github.com/guregu/kami): A tiny web framework using x/net/context
* [Medeina](https://github.com/imdario/medeina): Inspired by Ruby's Roda and Cuba
* [nchi](https://github.com/muir/nchi): provides a [chi](https://github.com/go-chi/chi)-like framework using [nject](https://github.com/muir/nject) for flexibility and ease-of-use
* [Neko](https://github.com/rocwong/neko): A lightweight web application framework for Golang
* [pbgo](https://github.com/chai2010/pbgo): pbgo is a mini RPC/REST framework based on Protobuf
* [River](https://github.com/abiosoft/river): River is a simple and lightweight REST server
* [siesta](https://github.com/VividCortex/siesta): Composable HTTP handlers with contexts
* [xmux](https://github.com/rs/xmux): xmux is a httprouter fork on top of xhandler (net/context aware)

httprouter

High-speed, flexible tree-based HTTP router for Go. Inspiration from httprouter

httptreemux  [![Build Status](https://travis-ci.org/dimfeld/httptreemux.png?branch=master)](https://travis-ci.org/dimfeld/httptreemux) [![GoDoc](https://godoc.org/github.com/dimfeld/httptreemux?status.svg)](https://godoc.org/github.com/dimfeld/httptreemux)
===========

> [!WARNING]  
> This project is no longer maintained.

High-speed, flexible, tree-based HTTP router for Go.

This is inspired by [Julien Schmidt's httprouter](https://www.github.com/julienschmidt/httprouter), in that it uses a patricia tree, but the implementation is rather different. Specifically, the routing rules are relaxed so that a single path segment may be a wildcard in one route and a static token in another. This gives a nice combination of high performance with a lot of convenience in designing the routing patterns. In [benchmarks](https://github.com/julienschmidt/go-http-routing-benchmark), httptreemux is close to, but slightly slower than, httprouter.

Release notes may be found using the [Github releases tab](https://github.com/dimfeld/httptreemux/releases). Version numbers are compatible with the [Semantic Versioning 2.0.0](http://semver.org/) convention, and a new release is made after every change to the code.

## Installing with Go Modules

When using Go Modules, import this repository with `import "github.com/dimfeld/httptreemux/v5"` to ensure that you get the right version.

## Why?
There are a lot of good routers out there. But looking at the ones that were really lightweight, I couldn't quite get something that fit with the route patterns I wanted. The code itself is simple enough, so I spent an evening writing this.

## Handler
The handler is a simple function with the prototype `func(w http.ResponseWriter, r *http.Request, params map[string]string)`. The params argument contains the parameters parsed from wildcards and catch-alls in the URL, as described below. This type is aliased as httptreemux.HandlerFunc.

### Using http.HandlerFunc
Due to the inclusion of the [context](https://godoc.org/context) package as of Go 1.7, `httptreemux` now supports handlers of type [http.HandlerFunc](https://godoc.org/net/http#HandlerFunc). There are two ways to enable this support.

#### Adapting an Existing Router

The `UsingContext` method will wrap the router or group in a new group at the same path, but adapted for use with `context` and `http.HandlerFunc`.

```go
router := httptreemux.New()

group := router.NewGroup("/api")
group.GET("/v1/:id", func(w http.ResponseWriter, r *http.Request, params map[string]string) {
    id := params["id"]
    fmt.Fprintf(w, "GET /api/v1/%s", id)
})

// UsingContext returns a version of the router or group with context support.
ctxGroup := group.UsingContext() // sibling to 'group' node in tree
ctxGroup.GET("/v2/:id", func(w http.ResponseWriter, r *http.Request) {
    ctxData := httptreemux.ContextData(r.Context())
    params := ctxData.Params()
    id := params["id"]

    // Useful for middleware to see which route was hit without dealing with wildcards
    routePath := ctxData.Route()

    // Prints GET /api/v2/:id id=...
    fmt.Fprintf(w, "GET %s id=%s", routePath, id)
})

http.ListenAndServe(":8080", router)
```

#### New Router with Context Support

The `NewContextMux` function returns a router preconfigured for use with `context` and `http.HandlerFunc`.

```go
router := httptreemux.NewContextMux()

router.GET("/:page", func(w http.ResponseWriter, r *http.Request) {
    params := httptreemux.ContextParams(r.Context())
    fmt.Fprintf(w, "GET /%s", params["page"])
})

group := router.NewGroup("/api")
group.GET("/v1/:id", func(w http.ResponseWriter, r *http.Request) {
    ctxData := httptreemux.ContextData(r.Context())
    params := ctxData.Params()
    id := params["id"]

    // Useful for middleware to see which route was hit without dealing with wildcards
    routePath := ctxData.Route()

    // Prints GET /api/v1/:id id=...
    fmt.Fprintf(w, "GET %s id=%s", routePath, id)
})

http.ListenAndServe(":8080", router)
```



## Routing Rules
The syntax here is also modeled after httprouter. Each variable in a path may match on one segment only, except for an optional catch-all variable at the end of the URL.

Some examples of valid URL patterns are:
* `/post/all`
* `/post/:postid`
* `/post/:postid/page/:page`
* `/post/:postid/:page`
* `/images/*path`
* `/favicon.ico`
* `/:year/:month/`
* `/:year/:month/:post`
* `/:page`

Note that all of the above URL patterns may exist concurrently in the router.

Path elements starting with `:` indicate a wildcard in the path. A wildcard will only match on a single path segment. That is, the pattern `/post/:postid` will match on `/post/1` or `/post/1/`, but not `/post/1/2`.

A path element starting with `*` is a catch-all, whose value will be a string containing all text in the URL matched by the wildcards. For example, with a pattern of `/images/*path` and a requested URL `images/abc/def`, path would contain `abc/def`. A catch-all path will not match an empty string, so in this example a separate route would need to be installed if you also want to match `/images/`.

#### Using : and * in routing patterns

The characters `:` and `*` can be used at the beginning of a path segment by escaping them with a backslash. A double backslash at the beginning of a segment is interpreted as a single backslash. These escapes are only checked at the very beginning of a path segment; they are not necessary or processed elsewhere in a token.

```go
router.GET("/foo/\\*starToken", handler) // matches /foo/*starToken
router.GET("/foo/star*inTheMiddle", handler) // matches /foo/star*inTheMiddle
router.GET("/foo/starBackslash\\*", handler) // matches /foo/starBackslash\*
router.GET("/foo/\\\\*backslashWithStar") // matches /foo/\*backslashWithStar
```

### Routing Groups
Lets you create a new group of routes with a given path prefix.  Makes it easier to create clusters of paths like:
* `/api/v1/foo`
* `/api/v1/bar`

To use this you do:
```go
router = httptreemux.New()
api := router.NewGroup("/api/v1")
api.GET("/foo", fooHandler) // becomes /api/v1/foo
api.GET("/bar", barHandler) // becomes /api/v1/bar
```

### Routing Priority
The priority rules in the router are simple.

1. Static path segments take the highest priority. If a segment and its subtree are able to match the URL, that match is returned.
2. Wildcards take second priority. For a particular wildcard to match, that wildcard and its subtree must match the URL.
3. Finally, a catch-all rule will match when the earlier path segments have matched, and none of the static or wildcard conditions have matched. Catch-all rules must be at the end of a pattern.

So with the following patterns adapted from [simpleblog](https://www.github.com/dimfeld/simpleblog), we'll see certain matches:
```go
router = httptreemux.New()
router.GET("/:page", pageHandler)
router.GET("/:year/:month/:post", postHandler)
router.GET("/:year/:month", archiveHandler)
router.GET("/images/*path", staticHandler)
router.GET("/favicon.ico", staticHandler)
```

#### Example scenarios

- `/abc` will match `/:page`
- `/2014/05` will match `/:year/:month`
- `/2014/05/really-great-blog-post` will match `/:year/:month/:post`
- `/images/CoolImage.gif` will match `/images/*path`
- `/images/2014/05/MayImage.jpg` will also match `/images/*path`, with all the text after `/images` stored in the variable path.
- `/favicon.ico` will match `/favicon.ico`

### Special Method Behavior
If TreeMux.HeadCanUseGet is set to true, the router will call the GET handler for a pattern when a HEAD request is processed, if no HEAD handler has been added for that pattern. This behavior is enabled by default.

Go's http.ServeContent and related functions already handle the HEAD method correctly by sending only the header, so in most cases your handlers will not need any special cases for it.

By default TreeMux.OptionsHandler is a null handler that doesn't affect your routing. If you set the handler, it will be called on OPTIONS requests to a path already registered by another method. If you set a path specific handler by using `router.OPTIONS`, it will override the global Options Handler for that path.

### Trailing Slashes
The router has special handling for paths with trailing slashes. If a pattern is added to the router with a trailing slash, any matches on that pattern without a trailing slash will be redirected to the version with the slash. If a pattern does not have a trailing slash, matches on that pattern with a trailing slash will be redirected to the version without.

The trailing slash flag is only stored once for a pattern. That is, if a pattern is added for a method with a trailing slash, all other methods for that pattern will also be considered to have a trailing slash, regardless of whether or not it is specified for those methods too.
However this behavior can be turned off by setting TreeMux.RedirectTrailingSlash to false. By default it is set to true.

One exception to this rule is catch-all patterns. By default, trailing slash redirection is disabled on catch-all patterns, since the structure of the entire URL and the desired patterns can not be predicted. If trailing slash removal is desired on catch-all patterns, set TreeMux.RemoveCatchAllTrailingSlash to true.

```go
router = httptreemux.New()
router.GET("/about", pageHandler)
router.GET("/posts/", postIndexHandler)
router.POST("/posts", postFormHandler)

GET /about will match normally.
GET /about/ will redirect to /about.
GET /posts will redirect to /posts/.
GET /posts/ will match normally.
POST /posts will redirect to /posts/, because the GET method used a trailing slash.
```

### Custom Redirects

RedirectBehavior sets the behavior when the router redirects the request to the canonical version of the requested URL using RedirectTrailingSlash or RedirectClean. The default behavior is to return a 301 status, redirecting the browser to the version of the URL that matches the given pattern.

These are the values accepted for RedirectBehavior. You may also add these values to the RedirectMethodBehavior map to define custom per-method redirect behavior.

* Redirect301 - HTTP 301 Moved Permanently; this is the default.
* Redirect307 - HTTP/1.1 Temporary Redirect
* Redirect308 - RFC7538 Permanent Redirect
* UseHandler - Don't redirect to the canonical path. Just call the handler instead.

### Case Insensitive Routing

You can optionally allow case-insensitive routing by setting the _CaseInsensitive_ property on the router to true. 
This allows you to make all routes case-insensitive. For example:
```go
router := httptreemux.New()
router.CaseInsensitive
router.GET("/My-RoUtE", pageHandler)
```
In this example, performing a GET request to /my-route will match the route and execute the _pageHandler_ functionality. 
It's important to note that when using case-insensitive routing, the CaseInsensitive property must be set before routes are defined or there may be unexpected side effects. 

#### Rationale/Usage
On a POST request, most browsers that receive a 301 will submit a GET request to the redirected URL, meaning that any data will likely be lost. If you want to handle and avoid this behavior, you may use Redirect307, which causes most browsers to resubmit the request using the original method and request body.

Since 307 is supposed to be a temporary redirect, the new 308 status code has been proposed, which is treated the same, except it indicates correctly that the redirection is permanent. The big caveat here is that the RFC is relatively recent, and older or non-compliant browsers will not handle it. Therefore its use is not recommended unless you really know what you're doing.

Finally, the UseHandler value will simply call the handler function for the pattern, without redirecting to the canonical version of the URL.

### RequestURI vs. URL.Path

#### Escaped Slashes
Go automatically processes escaped characters in a URL, converting + to a space and %XX to the corresponding character. This can present issues when the URL contains a %2f, which is unescaped to '/'. This isn't an issue for most applications, but it will prevent the router from correctly matching paths and wildcards.

For example, the pattern `/post/:post` would not match on `/post/abc%2fdef`, which is unescaped to `/post/abc/def`. The desired behavior is that it matches, and the `post` wildcard is set to `abc/def`.

Therefore, this router defaults to using the raw URL, stored in the Request.RequestURI variable. Matching wildcards and catch-alls are then unescaped, to give the desired behavior.

TL;DR: If a requested URL contains a %2f, this router will still do the right thing. Some Go HTTP routers may not due to [Go issue 3659](https://code.google.com/p/go/issues/detail?id=3659).

#### Escaped Characters

As mentioned above, characters in the URL are not unescaped when using RequestURI to determine the matched route. If this is a problem for you and you are unable to switch to URL.Path for the above reasons, you may set `router.EscapeAddedRoutes` to `true`. This option will run each added route through the `URL.EscapedPath` function, and add an additional route if the escaped version differs.

#### http Package Utility Functions

Although using RequestURI avoids the issue described above, certain utility functions such as `http.StripPrefix` modify URL.Path, and expect that the underlying router is using that field to make its decision. If you are using some of these functions, set the router's `PathSource` member to `URLPath`. This will give up the proper handling of escaped slashes described above, while allowing the router to work properly with these utility functions.

## Concurrency

The router contains an `RWMutex` that arbitrates access to the tree. This allows routes to be safely added from multiple goroutines at once.

No concurrency controls are needed when only reading from the tree, so the default behavior is to not use the `RWMutex` when serving a request. This avoids a theoretical slowdown under high-usage scenarios from competing atomic integer operations inside the `RWMutex`. If your application adds routes to the router after it has begun serving requests, you should avoid potential race conditions by setting `router.SafeAddRoutesWhileRunning` to `true` to use the `RWMutex` when serving requests.

## Error Handlers

### NotFoundHandler
TreeMux.NotFoundHandler can be set to provide custom 404-error handling. The default implementation is Go's `http.NotFound` function.

### MethodNotAllowedHandler
If a pattern matches, but the pattern does not have an associated handler for the requested method, the router calls the MethodNotAllowedHandler. The default
version of this handler just writes the status code `http.StatusMethodNotAllowed` and sets the response header's `Allowed` field appropriately.

### Panic Handling
TreeMux.PanicHandler can be set to provide custom panic handling. The `SimplePanicHandler` just writes the status code `http.StatusInternalServerError`. The function `ShowErrorsPanicHandler`, adapted from [gocraft/web](https://github.com/gocraft/web), will print panic errors to the browser in an easily-readable format.

## Unexpected Differences from Other Routers

This router is intentionally light on features in the name of simplicity and
performance. When coming from another router that does heavier processing behind
the scenes, you may encounter some unexpected behavior. This list is by no means
exhaustive, but covers some nonobvious cases that users have encountered.

### gorilla/pat query string modifications

When matching on parameters in a route, the `gorilla/pat` router will modify
`Request.URL.RawQuery` to make it appear like the parameters were in the
query string. `httptreemux` does not do this. See [Issue #26](https://github.com/dimfeld/httptreemux/issues/26) for more details and a
code snippet that can perform this transformation for you, should you want it.

### httprouter and catch-all parameters

When using `httprouter`, a route with a catch-all parameter (e.g. `/images/*path`) will match on URLs like `/images/` where the catch-all parameter is empty. This router does not match on empty catch-all parameters, but the behavior can be duplicated by adding a route without the catch-all (e.g. `/images/`).

## Middleware
This package provides no middleware. But there are a lot of great options out there and it's pretty easy to write your own. The router provides the `Use` and `UseHandler` functions to ease the creation of middleware chains. (Real documentation of these functions coming soon.)

# Acknowledgements

* Inspiration from Julien Schmidt's [httprouter](https://github.com/julienschmidt/httprouter)
* Show Errors panic handler from [gocraft/web](https://github.com/gocraft/web)


httptreemux

Is a lightweight, fast and extensible zero allocation HTTP router for Go used to create customizable frameworks

## LARS
<img align="right" src="https://raw.githubusercontent.com/go-playground/lars/master/_examples/README/test.gif">![Project status](https://img.shields.io/badge/version-4.0.1-green.svg)
[![Build Status](https://semaphoreci.com/api/v1/projects/4351aa2d-2f94-40be-a6ef-85c248490378/679708/badge.svg)](https://semaphoreci.com/joeybloggs/lars)
[![Coverage Status](https://coveralls.io/repos/github/go-playground/lars/badge.svg?branch=master)](https://coveralls.io/github/go-playground/lars?branch=master)
[![Go Report Card](https://goreportcard.com/badge/go-playground/lars)](https://goreportcard.com/report/go-playground/lars)
[![GoDoc](https://godoc.org/github.com/go-playground/lars?status.svg)](https://godoc.org/github.com/go-playground/lars)
![License](https://img.shields.io/dub/l/vibe-d.svg)
[![Gitter](https://badges.gitter.im/go-playground/lars.svg)](https://gitter.im/go-playground/lars?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

LARS is a fast radix-tree based, zero allocation, HTTP router for Go. [ view examples](https://github.com/go-playground/lars/tree/master/_examples). If looking for a more pure Go solution, be sure to check out [pure](https://github.com/go-playground/pure) which is essentially a pure version of lars

Why Another HTTP Router?
------------------------
Have you ever been painted into a corner by a framework, **ya me too!** and I've noticed that allot of routers out there, IMHO, are adding so much functionality that they are turning into Web Frameworks, (which is fine, frameworks are important) however, not at the expense of flexibility and configurability. So with no further ado, introducing LARS an HTTP router that can be your launching pad in creating a framework for your needs. How? Context is an interface [see example here](https://github.com/go-playground/lars/blob/master/_examples/all-in-one/main.go), where you can add as little or much as you want or need and most importantly...**under your control**.

Key & Unique Features 
--------------
- [x] **Context is an interface** - this allows passing of framework/globals/application specific variables. [example](https://github.com/go-playground/lars/blob/master/_examples/all-in-one/main.go)
- [x] **Smart Route Logic** - helpful logic to help prevent adding bad routes, keeping your url's consistent. i.e. /user/:id and /user/:user_id - the second one will fail to add letting you know that :user_id should be :id
- [x] **Uber simple middleware + handlers** - middleware and handlers actually have the exact same definition!
- [x] **Custom Handlers** - can register custom handlers for making other middleware + handler patterns usable with this router; the best part about this is can register one for your custom context and not have to do type casting everywhere [see here](https://github.com/go-playground/lars/blob/master/examples/custom-handler/main.go)
- [x] **Diverse handler support** - Full support for standard/native http Handler + HandlerFunc + some others [see here](https://github.com/go-playground/lars/blob/master/_examples/native/main.go)
 * When Parsing a form call Context's ParseForm amd ParseMulipartForm functions and the URL params will be added into the Form object, just like query parameters are, so no extra work
- [x] **Fast & Efficient** - lars uses a custom version of [httprouter](https://github.com/julienschmidt/httprouter) so incredibly fast and efficient.

Installation
-----------

```shell
go get -u github.com/go-playground/lars
```

Usage
------
Below is a simple example, for a full example [see here](https://github.com/go-playground/lars/blob/master/_examples/all-in-one/main.go)
```go
package main

import (
	"fmt"
	"net/http"

	"github.com/go-playground/lars"
	mw "github.com/go-playground/lars/_examples/middleware/logging-recovery"
)

func main() {
	l := lars.New()
	// LoggingAndRecovery is just an example copy paste and modify to your needs
	l.Use(mw.LoggingAndRecovery)

	l.Get("/", HelloWorld)

	http.ListenAndServe(":3007", l.Serve())
}

// HelloWorld ...
func HelloWorld(c lars.Context) {
	c.Response().Write([]byte("Hello World"))

	// this will also work, Response() complies with http.ResponseWriter interface
	fmt.Fprint(c.Response(), "Hello World")
}
```

URL Params
----------

```go
l := l.New()

// the matching param will be stored in the Context's params with name "id"
l.Get("/user/:id", UserHandler)

// serve css, js etc.. c.Param(lars.WildcardParam) will return the remaining path if 
// you need to use it in a custom handler...
l.Get("/static/*", http.StripPrefix("/static/", http.FileServer(http.Dir("static")))) 

...
```

**Note:** Since this router has only explicit matches, you can not register static routes and parameters for the same path segment. For example you can not register the patterns /user/new and /user/:user for the same request method at the same time. The routing of different request methods is independent from each other. I was initially against this, and this router allowed it in a previous version, however it nearly cost me in a big app where the dynamic param value say :type actually could have matched another static route and that's just too dangerous, so it is no longer allowed.

Groups
-----
```go

l.Use(LoggingAndRecovery)
...
l.Post("/users/add", ...)

// creates a group for user + inherits all middleware registered using l.Use()
user := l.Group("/user/:userid")
user.Get("", ...)
user.Post("", ...)
user.Delete("/delete", ...)

contactInfo := user.Group("/contact-info/:ciid")
contactinfo.Delete("/delete", ...)

// creates a group for others + inherits all middleware registered using l.Use() + adds 
// OtherHandler to middleware
others := l.GroupWithMore("/others", OtherHandler)

// creates a group for admin WITH NO MIDDLEWARE... more can be added using admin.Use()
admin := l.GroupWithNone("/admin")
admin.Use(SomeAdminSecurityMiddleware)
...
```

Custom Context + Avoid Type Casting / Custom Handlers
------
```go
...
// MyContext is a custom context
type MyContext struct {
	*lars.Ctx // a little dash of Duck Typing....
}

// CustomContextFunction is a function that is specific to your applications needs that you added
func (mc *MyContext) CustomContextFunction() {
	// do something
}

// newContext is the function that creates your custom context +
// contains lars's default context
func newContext(l *lars.LARS) lars.Context {
	return &MyContext{
		Ctx: lars.NewContext(l),
	}
}

// casts custom context and calls you custom handler so you don;t have to type cast lars.Context everywhere
func castCustomContext(c lars.Context, handler lars.Handler) {
	// could do it in all one statement, but in long form for readability
	h := handler.(func(*MyContext))
	ctx := c.(*MyContext)

	h(ctx)
}

func main() {
	l := lars.New()
	l.RegisterContext(newContext) // all gets cached in pools for you
	l.RegisterCustomHandler(func(*MyContext) {}, castCustomContext)
	l.Use(Logger)

	l.Get("/", Home)

	http.ListenAndServe(":3007", l.Serve())
}

// Home ...notice the receiver is *MyContext, castCustomContext handled the type casting for us
// quite the time saver if you ask me.
func Home(c *MyContext) {
	c.CustomContextFunction()
	...
}
```

Decoding Body
-------------
For full example see [here](https://github.com/go-playground/lars/blob/master/_examples/decode/main.go).
currently JSON, XML, FORM + Multipart Form's are support out of the box.
```go
	// first argument denotes yes or no I would like URL query parameter fields
	// to be included. i.e. 'id' in route '/user/:id' should it be included.
	// run, then change to false and you'll see user.ID is not populated.
	if err := c.Decode(true, maxBytes, &user); err != nil {
		log.Println(err)
	}
```

Misc
-----
```go
...
// can register multiple handlers, the last is considered the last in the chain and others 
// considered middleware, but just for this route and not added to middleware like l.Use() does.
l.Get(/"home", AdditionalHandler, HomeHandler)

// set custom 404 ( not Found ) handler
l.Register404(404Handler)

// Redirect to or from ending slash if route not found, default is true
l.SetRedirectTrailingSlash(true)

// Handle 405 ( Method Not allowed ), default is false
l.SetHandle405MethodNotAllowed(false)

// automatically handle OPTION requests; manually configured
// OPTION handlers take precedence. default true
l.SetAutomaticallyHandleOPTIONS(set bool)

// register custom context
l.RegisterContext(ContextFunc)

// Register custom handler type, see https://github.com/go-playground/lars/blob/master/util.go#L62
// for example handler creation
l.RegisterCustomHandler(interface{}, CustomHandlerFunc)

// NativeChainHandler is used as a helper to create your own custom handlers, or use custom handlers 
// that already exist an example usage can be found here 
// https://github.com/go-playground/lars/blob/master/util.go#L86, below is an example using nosurf CSRF middleware

l.Use(nosurf.NewPure(lars.NativeChainHandler))


// Context has 2 methods of which you should be aware of ParseForm and ParseMulipartForm, they just call the 
// default http functions but provide one more additional feature, they copy the URL params to the request 
// Forms variables, just like Query parameters would have been.
// The functions are for convenience and are totally optional.
```

Special Note
-------------
I don't know if it was an oversight or just an assumption about how middleware would be used with Go 1.7's new
`context` integration into the `*http.Request` but there are a few quirks. As you know lars handles multiple handler
types, including the native handler, this functionality is possible because of the way lar handles the middleware; lars
does not `chain` the middleware in the normal way, but rather calles each in sequence; because of this all you have to 
do is call c.Next() or it has already been wrapped to do so for you transparently. OK getting back to the point, if you
are not using `lars.Context` to set the context information you will have to set the request object so that the information
gets back to the calling package. eg.

```go
// because 'r' is a copy of a pointer to allow the information to get
// back to the caller, need to set the value of 'r' as below with '*r'
func(w http.ResponseWriter, r *http.Request) {
	*r = *r.WithContext(context.WithValue(r.Context(), 0, "testval1"))
}
```

this is not an issue specific to lars, but a quirk of the way `context` is tied to the `http.Request` object.

Middleware
-----------
There are some pre-defined middlewares within the middleware folder; NOTE: that the middleware inside will
comply with the following rule(s):

* Are completely reusable by the community without modification

Other middleware will be listed under the _examples/middleware/... folder for a quick copy/paste modify. as an example a logging or
recovery middleware are very application dependent and therefore will be listed under the _examples/middleware/...

Benchmarks
-----------
Run on MacBook Pro (15-inch, 2017) 3.1 GHz Intel Core i7 16GB DDR3 using Go version go1.9.2 darwin/amd64

NOTICE: lars uses a custom version of [httprouter](https://github.com/julienschmidt/httprouter), benchmarks can be found [here](https://github.com/joeybloggs/go-http-routing-benchmark/tree/lars-only)

```go
go test -bench=. -benchmem=true
#GithubAPI Routes: 203
 LARS: 49032 Bytes

#GPlusAPI Routes: 13
 LARS: 3640 Bytes

#ParseAPI Routes: 26
 LARS: 6632 Bytes

#Static Routes: 157
 LARS: 30120 Bytes

goos: darwin
goarch: amd64
pkg: github.com/joeybloggs/go-http-routing-benchmark
BenchmarkLARS_Param 	20000000	 51.6 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_Param5 	20000000	 85.7 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_Param20 	10000000	 215 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_ParamWrite 	20000000	 94.3 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_GithubStatic 	20000000	 68.7 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_GithubParam 	20000000	 103 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_GithubAll 	 100000	 21066 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_GPlusStatic 	30000000	 53.1 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_GPlusParam 	20000000	 70.3 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_GPlus2Params 	20000000	 84.4 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_GPlusAll 	 2000000	 894 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_ParseStatic 	20000000	 53.5 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_ParseParam 	20000000	 60.4 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_Parse2Params 	20000000	 68.7 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_ParseAll 	 1000000	 1602 ns/op	 0 B/op	 0 allocs/op
BenchmarkLARS_StaticAll 	 100000	 13777 ns/op	 0 B/op	 0 allocs/op
```

Package Versioning
----------
I'm jumping on the vendoring bandwagon, you should vendor this package as I will not
be creating different version with gopkg.in like allot of my other libraries.

Why? because my time is spread pretty thin maintaining all of the libraries I have + LIFE,
it is so freeing not to worry about it and will help me keep pouring out bigger and better
things for you the community.

This package is inspired by the following 
-----------
- [httptreemux](https://github.com/dimfeld/httptreemux)
- [httprouter](https://github.com/julienschmidt/httprouter)
- [echo](https://github.com/labstack/echo)
- [gin](https://github.com/gin-gonic/gin)

Licenses
--------
- [MIT License](https://raw.githubusercontent.com/go-playground/lars/master/LICENSE) (MIT), Copyright (c) 2015 Dean Karn
- [BSD License](https://raw.githubusercontent.com/julienschmidt/httprouter/master/LICENSE), Copyright (c) 2013 Julien Schmidt. All rights reserved.

lars

An extremely fast Go (golang) HTTP router that supports regular expression route matching. Comes with full support for building RESTful APIs

# ozzo-routing

[![GoDoc](https://godoc.org/github.com/go-ozzo/ozzo-routing?status.png)](http://godoc.org/github.com/go-ozzo/ozzo-routing)
[![Build Status](https://travis-ci.org/go-ozzo/ozzo-routing.svg?branch=master)](https://travis-ci.org/go-ozzo/ozzo-routing)
[![Coverage Status](https://coveralls.io/repos/github/go-ozzo/ozzo-routing/badge.svg?branch=master)](https://coveralls.io/github/go-ozzo/ozzo-routing?branch=master)
[![Go Report](https://goreportcard.com/badge/github.com/go-ozzo/ozzo-routing)](https://goreportcard.com/report/github.com/go-ozzo/ozzo-routing)

**You may consider using [go-rest-api](https://github.com/qiangxue/go-rest-api) to jumpstart your new RESTful applications with ozzo-routing.**

## Description

ozzo-routing is a Go package that provides high performance and powerful HTTP routing capabilities for Web applications.
It has the following features:

* middleware pipeline architecture, similar to that of the [Express framework](http://expressjs.com).
* extremely fast request routing with zero dynamic memory allocation (the performance is comparable to that of [httprouter](https://github.com/julienschmidt/httprouter) and
[gin](https://github.com/gin-gonic/gin), see the [performance comparison below](#benchmarks))
* modular code organization through route grouping
* flexible URL path matching, supporting URL parameters and regular expressions
* URL creation according to the predefined routes
* compatible with `http.Handler` and `http.HandlerFunc`
* ready-to-use handlers sufficient for building RESTful APIs
* graceful shutdown

If you are using [fasthttp](https://github.com/valyala/fasthttp), you may use a similar routing package [fasthttp-routing](https://github.com/qiangxue/fasthttp-routing) which is adapted from ozzo-routing.

## Requirements

Go 1.13 or above.

## Installation

In your Go project using `go mod`, run the following command to install the package:

```
go get github.com/go-ozzo/ozzo-routing/v2
```

## Getting Started

For a complete RESTful application boilerplate based on ozzo-routing, please refer to the [golang-restful-starter-kit](https://github.com/qiangxue/golang-restful-starter-kit). Below we describe how to create a simple REST API using ozzo-routing.

Create a `server.go` file with the following content:

```go
package main

import (
	"log"
	"net/http"
	"github.com/go-ozzo/ozzo-routing/v2"
	"github.com/go-ozzo/ozzo-routing/v2/access"
	"github.com/go-ozzo/ozzo-routing/v2/slash"
	"github.com/go-ozzo/ozzo-routing/v2/content"
	"github.com/go-ozzo/ozzo-routing/v2/fault"
	"github.com/go-ozzo/ozzo-routing/v2/file"
)

func main() {
	router := routing.New()

	router.Use(
		// all these handlers are shared by every route
		access.Logger(log.Printf),
		slash.Remover(http.StatusMovedPermanently),
		fault.Recovery(log.Printf),
	)

	// serve RESTful APIs
	api := router.Group("/api")
	api.Use(
		// these handlers are shared by the routes in the api group only
		content.TypeNegotiator(content.JSON, content.XML),
	)
	api.Get("/users", func(c *routing.Context) error {
		return c.Write("user list")
	})
	api.Post("/users", func(c *routing.Context) error {
		return c.Write("create a new user")
	})
	api.Put(`/users/<id:\d+>`, func(c *routing.Context) error {
		return c.Write("update user " + c.Param("id"))
	})

	// serve index file
	router.Get("/", file.Content("ui/index.html"))
	// serve files under the "ui" subdirectory
	router.Get("/*", file.Server(file.PathMap{
		"/": "/ui/",
	}))

	http.Handle("/", router)
	http.ListenAndServe(":8080", nil)
}
```

Create an HTML file `ui/index.html` with any content.

Now run the following command to start the Web server:

```
go run server.go
```

You should be able to access URLs such as `http://localhost:8080`, `http://localhost:8080/api/users`.


### Routes

ozzo-routing works by building a routing table in a router and then dispatching HTTP requests to the matching handlers 
found in the routing table. An intuitive illustration of a routing table is as follows:


Routes | Handlers
--------------------|-----------------
`GET /users` | m1, m2, h1, ...
`POST /users` | m1, m2, h2, ...
`PUT /users/<id>` | m1, m2, h3, ...
`DELETE /users/<id>`| m1, m2, h4, ...


For an incoming request `GET /users`, the first route would match and the handlers m1, m2, and h1 would be executed.
If the request is `PUT /users/123`, the third route would match and the corresponding handlers would be executed.
Note that the token `<id>` can match any number of non-slash characters and the matching part can be accessed as 
a path parameter value in the handlers.

**If an incoming request matches multiple routes in the table, the route added first to the table will take precedence.
All other matching routes will be ignored.**

The actual implementation of the routing table uses a variant of the radix tree data structure, which makes the routing
process as fast as working with a hash table, thanks to the inspiration from [httprouter](https://github.com/julienschmidt/httprouter).

To add a new route and its handlers to the routing table, call the `To` method like the following:
 
```go
router := routing.New()
router.To("GET", "/users", m1, m2, h1)
router.To("POST", "/users", m1, m2, h2)
```

You can also use shortcut methods, such as `Get`, `Post`, `Put`, etc., which are named after the HTTP method names:
 
```go
router.Get("/users", m1, m2, h1)
router.Post("/users", m1, m2, h2)
```

If you have multiple routes with the same URL path but different HTTP methods, like the above example, you can 
chain them together as follows,

```go
router.Get("/users", m1, m2, h1).Post(m1, m2, h2)
```

If you want to use the same set of handlers to handle the same URL path but different HTTP methods, you can take
the following shortcut:

```go
router.To("GET,POST", "/users", m1, m2, h)
```

A route may contain parameter tokens which are in the format of `<name:pattern>`, where `name` stands for the parameter
name, and `pattern` is a regular expression which the parameter value should match. A token `<name>` is equivalent
to `<name:[^/]*>`, i.e., it matches any number of non-slash characters. At the end of a route, an asterisk character
can be used to match any number of arbitrary characters. Below are some examples:

* `/users/<username>`: matches `/users/admin`
* `/users/accnt-<id:\d+>`: matches `/users/accnt-123`, but not `/users/accnt-admin`
* `/users/<username>/*`: matches `/users/admin/profile/address`

When a URL path matches a route, the matching parameters on the URL path can be accessed via `Context.Param()`:

```go
router := routing.New()

router.Get("/users/<username>", func (c *routing.Context) error {
	fmt.Fprintf(c.Response, "Name: %v", c.Param("username"))
	return nil
})
```


### Route Groups

Route group is a way of grouping together the routes which have the same route prefix. The routes in a group also
share the same handlers that are registered with the group via its `Use` method. For example,

```go
router := routing.New()
api := router.Group("/api")
api.Use(m1, m2)
api.Get("/users", h1).Post(h2)
api.Put("/users/<id>", h3).Delete(h4)
```

The above `/api` route group establishes the following routing table:


Routes | Handlers
------------------------|-------------
`GET /api/users` | m1, m2, h1, ...
`POST /api/users` | m1, m2, h2, ...
`PUT /api/users/<id>` | m1, m2, h3, ...
`DELETE /api/users/<id>`| m1, m2, h4, ...


As you can see, all these routes have the same route prefix `/api` and the handlers `m1` and `m2`. In other similar
routing frameworks, the handlers registered with a route group are also called *middlewares*.

Route groups can be nested. That is, a route group can create a child group by calling the `Group()` method. The router
serves as the top level route group. A child group inherits the handlers registered with its parent group. For example, 

```go
router := routing.New()
router.Use(m1)

api := router.Group("/api")
api.Use(m2)

users := api.Group("/users")
users.Use(m3)
users.Put("/<id>", h1)
```

Because the router serves as the parent of the `api` group which is the parent of the `users` group, 
the `PUT /api/users/<id>` route is associated with the handlers `m1`, `m2`, `m3`, and `h1`.


### Router

Router manages the routing table and dispatches incoming requests to appropriate handlers. A router instance is created
by calling the `routing.New()` method.

Because `Router` implements the `http.Handler` interface, it can be readily used to serve subtrees on existing Go servers.
For example,

```go
router := routing.New()
http.Handle("/", router)
http.ListenAndServe(":8080", nil)
```


### Handlers

A handler is a function with the signature `func(*routing.Context) error`. A handler is executed by the router if
the incoming request URL path matches the route that the handler is associated with. Through the `routing.Context` 
parameter, you can access the request information in handlers.

A route may be associated with multiple handlers. These handlers will be executed in the order that they are registered
to the route. The execution sequence can be terminated in the middle using one of the following two methods:

* A handler returns an error: the router will skip the rest of the handlers and handle the returned error.
* A handler calls `Context.Abort()`: the router will simply skip the rest of the handlers. There is no error to be handled.
 
A handler can call `Context.Next()` to explicitly execute the rest of the unexecuted handlers and take actions after
they finish execution. For example, a response compression handler may start the output buffer, call `Context.Next()`,
and then compress and send the output to response.


### Context

For each incoming request, a `routing.Context` object is populated with the request information and passed through
the handlers that need to handle the request. Handlers can get the request information via `Context.Request` and
send a response back via `Context.Response`. The `Context.Param()` method allows handlers to access the URL path
parameters that match the current route.

Using `Context.Get()` and `Context.Set()`, handlers can share data between each other. For example, an authentication
handler can store the authenticated user identity by calling `Context.Set()`, and other handlers can retrieve back
the identity information by calling `Context.Get()`.


### Reading Request Data

Context provides a few shortcut methods to read query parameters. The `Context.Query()` method returns
the named URL query parameter value; the `Context.PostForm()` method returns the named parameter value in the POST or
PUT body parameters; and the `Context.Form()` method returns the value from either POST/PUT or URL query parameters.

The `Context.Read()` method supports reading data from the request body and populating it into an object.
The method will check the `Content-Type` HTTP header and parse the body data as the corresponding format.
For example, if `Content-Type` is `application/json`, the request body will be parsed as JSON data.
The public fields in the object being populated will receive the parsed data if the data contains the same named fields.
For example,

```go
func foo(c *routing.Context) error {
 data := &struct{
 A string
 B bool
 }{}

 // assume the body data is: {"A":"abc", "B":true}
 // data will be populated as: {A: "abc", B: true}
 if err := c.Read(&data); err != nil {
 return err
 }
}
```

By default, `Context` supports reading data that are in JSON, XML, form, and multipart-form data.
You may modify `routing.DataReaders` to add support for other data formats.

Note that when the data is read as form data, you may use struct tag named `form` to customize
the name of the corresponding field in the form data. The form data reader also supports populating
data into embedded objects which are either named or anonymous.

### Writing Response Data

The `Context.Write()` method can be used to write data of arbitrary type to the response.
By default, if the data being written is neither a string nor a byte array, the method will
will call `fmt.Fprint()` to write the data into the response.

You can call `Context.SetWriter()` to replace the default data writer with a customized one.
For example, the `content.TypeNegotiator` will negotiate the content response type and set the data
writer with an appropriate one.

### Error Handling

A handler may return an error indicating some erroneous condition. Sometimes, a handler or the code it calls may cause
a panic. Both should be handled properly to ensure best user experience. It is recommended that you use 
the `fault.Recover` handler or a similar error handler to handle these errors.

If an error is not handled by any handler, the router will handle it by calling its `handleError()` method which
simply sets an appropriate HTTP status code and writes the error message to the response.

When an incoming request has no matching route, the router will call the handlers registered via the `Router.NotFound()`
method. All the handlers registered via `Router.Use()` will also be called in advance. By default, the following two
handlers are registered with `Router.NotFound()`:

* `routing.MethodNotAllowedHandler`: a handler that sends an `Allow` HTTP header indicating the allowed HTTP methods for a requested URL
* `routing.NotFoundHandler`: a handler triggering 404 HTTP error

## Serving Static Files

Static files can be served with the help of `file.Server` and `file.Content` handlers. The former serves files
under the specified directories, while the latter serves the content of a single file. For example,

```go
import (
	"github.com/go-ozzo/ozzo-routing/v2"
	"github.com/go-ozzo/ozzo-routing/v2/file"
)

router := routing.NewRouter()

// serve index file
router.Get("/", file.Content("ui/index.html"))
// serve files under the "ui" subdirectory
router.Get("/*", file.Server(file.PathMap{
	"/": "/ui/",
}))
```

## Handlers

ozzo-routing comes with a few commonly used handlers in its subpackages:

Handler name 					| Description
--------------------------------|--------------------------------------------
[access.Logger](https://godoc.org/github.com/go-ozzo/ozzo-routing/access) | records an entry for every incoming request
[auth.Basic](https://godoc.org/github.com/go-ozzo/ozzo-routing/auth) | provides authentication via HTTP Basic
[auth.Bearer](https://godoc.org/github.com/go-ozzo/ozzo-routing/auth) | provides authentication via HTTP Bearer
[auth.Query](https://godoc.org/github.com/go-ozzo/ozzo-routing/auth) | provides authentication via token-based query parameter
[auth.JWT](https://godoc.org/github.com/go-ozzo/ozzo-routing/auth) | provides JWT-based authentication
[content.TypeNegotiator](https://godoc.org/github.com/go-ozzo/ozzo-routing/content) | supports content negotiation by response types
[content.LanguageNegotiator](https://godoc.org/github.com/go-ozzo/ozzo-routing/content) | supports content negotiation by accepted languages
[cors.Handler](https://godoc.org/github.com/go-ozzo/ozzo-routing/cors) | implements the CORS (Cross Origin Resource Sharing) specification from the W3C
[fault.Recovery](https://godoc.org/github.com/go-ozzo/ozzo-routing/fault) | recovers from panics and handles errors returned by handlers
[fault.PanicHandler](https://godoc.org/github.com/go-ozzo/ozzo-routing/fault) | recovers from panics happened in the handlers
[fault.ErrorHandler](https://godoc.org/github.com/go-ozzo/ozzo-routing/fault) | handles errors returned by handlers by writing them in an appropriate format to the response
[file.Server](https://godoc.org/github.com/go-ozzo/ozzo-routing/file) | serves the files under the specified folder as response content
[file.Content](https://godoc.org/github.com/go-ozzo/ozzo-routing/file) | serves the content of the specified file as the response
[slash.Remover](https://godoc.org/github.com/go-ozzo/ozzo-routing/slash) | removes the trailing slashes from the request URL and redirects to the proper URL

The following code shows how these handlers may be used:

```go
import (
	"log"
	"net/http"
	"github.com/go-ozzo/ozzo-routing/v2"
	"github.com/go-ozzo/ozzo-routing/v2/access"
	"github.com/go-ozzo/ozzo-routing/v2/slash"
	"github.com/go-ozzo/ozzo-routing/v2/fault"
)

router := routing.New()

router.Use(
	access.Logger(log.Printf),
	slash.Remover(http.StatusMovedPermanently),
	fault.Recovery(log.Printf),
)

...
```

### Third-party Handlers


The following third-party handlers are specifically designed for ozzo-routing:

Handler name 					| Description
--------------------------------|--------------------------------------------
[jwt.JWT](https://github.com/vvv-v13/ozzo-jwt) | supports JWT Authorization


ozzo-routing also provides adapters to support using third-party `http.HandlerFunc` or `http.Handler` handlers. 
For example,

```go
router := routing.New()

// using http.HandlerFunc
router.Use(routing.HTTPHandlerFunc(http.NotFound))

// using http.Handler
router.Use(routing.HTTPHandler(http.NotFoundHandler))
```

## 3rd-Party Extensions and Code Examples

* [Simple Standard Service Endpoints (SE4)](https://github.com/jdamick/ozzo-se4)
* [ozzo examples](https://github.com/marshyski/go-ozzo-examples)

## Benchmarks

*Last updated on Jan 6, 2017*

Ozzo-routing is very fast, thanks to the radix tree data structure and the usage of `sync.Pool` (the idea was
originally from HttpRouter and Gin). The following table (by running [go-http-routing-benchmark](https://github.com/qiangxue/go-http-routing-benchmark))
shows how ozzo-routing compares with Gin, HttpRouter, and Martini in performance.

```
BenchmarkOzzo_GithubAll 50000 37989 ns/op 0 B/op 0 allocs/op
BenchmarkEcho_GithubAll 20000 91003 ns/op 6496 B/op 203 allocs/op
BenchmarkGin_GithubAll 50000 26717 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_GithubAll 50000 36052 ns/op 13792 B/op 167 allocs/op
BenchmarkMartini_GithubAll 300 4162283 ns/op 228216 B/op 2483 allocs/op

BenchmarkOzzo_GPlusAll 1000000 1732 ns/op 0 B/op 0 allocs/op
BenchmarkEcho_GPlusAll 300000 4523 ns/op 416 B/op 13 allocs/op
BenchmarkGin_GPlusAll 1000000 1171 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_GPlusAll 1000000 1533 ns/op 640 B/op 11 allocs/op
BenchmarkMartini_GPlusAll 20000 75634 ns/op 14448 B/op 165 allocs/op

BenchmarkOzzo_ParseAll 500000 3318 ns/op 0 B/op 0 allocs/op
BenchmarkEcho_ParseAll 200000 7336 ns/op 832 B/op 26 allocs/op
BenchmarkGin_ParseAll 1000000 2075 ns/op 0 B/op 0 allocs/op
BenchmarkHttpRouter_ParseAll 1000000 2034 ns/op 640 B/op 16 allocs/op
BenchmarkMartini_ParseAll 10000 122002 ns/op 25600 B/op 276 allocs/op
```

## Credits

ozzo-routing has referenced many popular routing frameworks, including [Express](http://expressjs.com/), 
[Martini](https://github.com/go-martini/martini), [httprouter](https://github.com/julienschmidt/httprouter), and
[gin](https://github.com/gin-gonic/gin).

ozzo-routing

Is a lightweight HTTP router that sticks to the std "net/http" implementation

package pure
============
<img align="right" src="https://raw.githubusercontent.com/go-playground/pure/master/logo.png">![Project status](https://img.shields.io/badge/version-5.3.0-green.svg)
[![Build Status](https://travis-ci.org/go-playground/pure.svg?branch=master)](https://travis-ci.org/go-playground/pure)
[![Coverage Status](https://coveralls.io/repos/github/go-playground/pure/badge.svg?branch=master)](https://coveralls.io/github/go-playground/pure?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/go-playground/pure)](https://goreportcard.com/report/github.com/go-playground/pure)
[![GoDoc](https://godoc.org/github.com/go-playground/pure?status.svg)](https://pkg.go.dev/github.com/go-playground/pure)
![License](https://img.shields.io/dub/l/vibe-d.svg)
[![Gitter](https://badges.gitter.im/go-playground/pure.svg)](https://gitter.im/go-playground/pure?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

Pure is a fast radix-tree based HTTP router that sticks to the native implementations of Go's "net/http" package;
in essence, keeping the handler implementations 'pure' by using Go 1.7's "context" package.

This makes heavy usage of `github.com/go-playground/pkg/v5` for HTTP abstractions.

Why Another HTTP Router?
------------------------
I initially created [lars](https://github.com/go-playground/lars), which I still maintain, that wraps the native implementation, think of this package as a Go pure implementation of [lars](https://github.com/go-playground/lars)

Key & Unique Features 
--------------
- [x] It sticks to Go's native implementations while providing helper functions for convenience
- [x] **Fast & Efficient** - pure uses a custom version of [httprouter](https://github.com/julienschmidt/httprouter)'s radix tree, so incredibly fast and efficient.

Installation
-----------

Use go get 

```shell
go get -u github.com/go-playground/pure/v5
```

Usage
------
```go
package main

import (
	"net/http"

	"github.com/go-playground/pure/v5"
	mw "github.com/go-playground/pure/v5/_examples/middleware/logging-recovery"
)

func main() {

	p := pure.New()
	p.Use(mw.LoggingAndRecovery(true))

	p.Get("/", helloWorld)

	http.ListenAndServe(":3007", p.Serve())
}

func helloWorld(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("Hello World"))
}
```

RequestVars
-----------
This is an interface that is used to pass request scoped variables and functions using `context.Context`.
It is implemented in this way because retrieving values from `context` isn't the fastest, and so using this 
the router can store multiple pieces of information while reducing lookup time to a single stored `RequestVars`.

Currently only the URL/SEO params are stored on the `RequestVars` but if/when more is added they can merely be added
to the `RequestVars` and there will be no additional lookup time.

URL Params
----------

```go
p := p.New()

// the matching param will be stored in the context's params with name "id"
p.Get("/user/:id", UserHandler)

// extract params like so
rv := pure.RequestVars(r) // done this way so only have to extract from context once, read above
rv.URLParam(paramname)

// serve css, js etc.. pure.RequestVars(r).URLParam(pure.WildcardParam) will return the remaining path if 
// you need to use it in a custom handler...
p.Get("/static/*", http.StripPrefix("/static/", http.FileServer(http.Dir("static"))).ServeHTTP)

...
```

**Note:** Since this router has only explicit matches, you can not register static routes and parameters for the same path segment. For example you can not register the patterns /user/new and /user/:user for the same request method at the same time. The routing of different request methods is independent from each other. I was initially against this, however it nearly cost me in a large web application where the dynamic param value say :type actually could have matched another static route and that's just too dangerous and so it is not allowed.

Groups
-----
```go

p.Use(LoggingAndRecovery, Gzip...)
...
p.Post("/users/add", ...)

// creates a group for /user/:userid + inherits all middleware registered previously by p
user := p.Group("/user/:userid")
user.Get("", ...)
user.Post("", ...)
user.Delete("/delete", ...)

contactInfo := user.Group("/contact-info/:cid")
contactinfo.Delete("/delete", ...)

// creates a group for /others, inherits all middleware registered previously by p + adds 
// OtherHandler to middleware
others := p.GroupWithMore("/others", OtherHandler)

// creates a group for /admin WITH NO MIDDLEWARE... more can be added using admin.Use()
admin := p.GroupWithNone("/admin")
admin.Use(SomeAdminSecurityMiddleware)
...
```

Decoding Body
-------------
currently JSON, XML, FORM, Multipart Form and url.Values are support out of the box; there are also 
individual functions for each as well when you know the Content-Type.
```go
	// second argument denotes yes or no I would like URL query parameter fields
	// to be included. i.e. 'id' and 'id2' in route '/user/:id?id2=val' should it be included.
	if err := pure.Decode(r, true, maxBytes, &user); err != nil {
		log.Println(err)
	}
```

Misc
-----
```go

// set custom 404 ( not Found ) handler
p.Register404(404Handler, middleware_like_logging)

// Redirect to or from ending slash if route not found, default is true
p.SetRedirectTrailingSlash(true)

// Handle 405 ( Method Not allowed ), default is false
p.RegisterMethodNotAllowed(middleware)

// automatically handle OPTION requests; manually configured
// OPTION handlers take precedence. default false
p.RegisterAutomaticOPTIONS(middleware)

```

Middleware
-----------
There are some pre-defined middlewares within the middleware folder; NOTE: that the middleware inside will
comply with the following rule(s):

* Are completely reusable by the community without modification

Other middleware will be listed under the _examples/middleware/... folder for a quick copy/paste modify. As an example a LoddingAndRecovery middleware is very application dependent and therefore will be listed under the _examples/middleware/...

Benchmarks
-----------
Run on i5-7600 16 GB DDR4-2400 using Go version go1.12.5 darwin/amd64

NOTICE: pure uses a custom version of [httprouter](https://github.com/julienschmidt/httprouter)'s radix tree, benchmarks can be found [here](https://github.com/deankarn/go-http-routing-benchmark/tree/pure-and-lars) the slowdown is with the use of the `context` package, as you can see when no SEO params are defined, and therefore no need to store anything in the context, it is faster than even lars.

```go
go test -bench=. -benchmem=true ./...
#GithubAPI Routes: 203
 Pure: 37096 Bytes

#GPlusAPI Routes: 13
 Pure: 2792 Bytes

#ParseAPI Routes: 26
 Pure: 5040 Bytes

#Static Routes: 157
 HttpServeMux: 14992 Bytes
 Pure: 21096 Bytes


goos: darwin
goarch: arm64
BenchmarkPure_Param 11965519 100.4 ns/op 256 B/op 1 allocs/op
BenchmarkPure_Param5 8756385 138.6 ns/op 256 B/op 1 allocs/op
BenchmarkPure_Param20 4335284 276.5 ns/op 256 B/op 1 allocs/op
BenchmarkPure_ParamWrite 9980685 120.0 ns/op 256 B/op 1 allocs/op
BenchmarkPure_GithubStatic 47743062 24.77 ns/op 0 B/op 0 allocs/op
BenchmarkPure_GithubParam 8514968 139.8 ns/op 256 B/op 1 allocs/op
BenchmarkPure_GithubAll 42250 28333 ns/op 42753 B/op 167 allocs/op
BenchmarkPure_GPlusStatic 87363000 13.39 ns/op 0 B/op 0 allocs/op
BenchmarkPure_GPlusParam 10398274 113.0 ns/op 256 B/op 1 allocs/op
BenchmarkPure_GPlus2Params 9235220 128.7 ns/op 256 B/op 1 allocs/op
BenchmarkPure_GPlusAll 792037 1526 ns/op 2816 B/op 11 allocs/op
BenchmarkPure_ParseStatic 79194198 14.96 ns/op 0 B/op 0 allocs/op
BenchmarkPure_ParseParam 11391336 104.5 ns/op 256 B/op 1 allocs/op
BenchmarkPure_Parse2Params 10103078 116.2 ns/op 256 B/op 1 allocs/op
BenchmarkPure_ParseAll 498306 2417 ns/op 4096 B/op 16 allocs/op
BenchmarkPure_StaticAll 219930 5225 ns/op 0 B/op 0 allocs/op
```

Licenses
--------
- [MIT License](https://raw.githubusercontent.com/go-playground/pure/master/LICENSE) (MIT), Copyright (c) 2016 Dean Karn
- [BSD License](https://raw.githubusercontent.com/julienschmidt/httprouter/master/LICENSE), Copyright (c) 2013 Julien Schmidt. All rights reserved.

pure

Composable framework to write middleware and handlers

# siesta

[![GoDoc](https://godoc.org/github.com/VividCortex/siesta?status.svg)](https://godoc.org/github.com/VividCortex/siesta)
![build](https://github.com/VividCortex/siesta/workflows/build/badge.svg)
[![codecov](https://codecov.io/gh/VividCortex/siesta/branch/master/graph/badge.svg)](https://codecov.io/gh/VividCortex/siesta)

Siesta is a framework for writing composable HTTP handlers in Go. It supports typed URL parameters, middleware chains, and context passing.

## Getting started

Siesta offers a `Service` type, which is a collection of middleware chains and handlers rooted at a base URI. There is no distinction between a middleware function and a handler function; they are all considered to be handlers and have access to the same arguments.

Siesta accepts many types of handlers. Refer to the [GoDoc](https://godoc.org/github.com/VividCortex/siesta#Service.Route) documentation for `Service.Route` for more information.

Here is the `simple` program in the examples directory. It demonstrates the use of a `Service`, routing, middleware, and a `Context`.

```go
package main

import (
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/VividCortex/siesta"
)

func main() {
	// Create a new Service rooted at "/"
	service := siesta.NewService("/")

	// Route accepts normal http.Handlers.
	// The arguments are the method, path, description,
	// and the handler.
	service.Route("GET", "/", "Sends 'Hello, world!'",
		func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "Hello, world!")
	})

	// Let's create some simple "middleware."
	// This handler will accept a Context argument and will add the current
	// time to it.
	timestamper := func(c siesta.Context, w http.ResponseWriter, r *http.Request) {
		c.Set("start", time.Now())
	}

	// This is the handler that will actually send data back to the client.
	// It also takes a Context argument so it can get the timestamp from the
	// previous handler.
	timeHandler := func(c siesta.Context, w http.ResponseWriter, r *http.Request) {
		start := c.Get("start").(time.Time)
		delta := time.Now().Sub(start)
		fmt.Fprintf(w, "That took %v.\n", delta)
	}

	// We can compose these handlers together.
	timeHandlers := siesta.Compose(timestamper, timeHandler)

	// Finally, we'll add the new handler we created using composition to a new route.
	service.Route("GET", "/time", "Sends how long it took to send a message", timeHandlers)

	// service is an http.Handler, so we can pass it directly to ListenAndServe.
	log.Fatal(http.ListenAndServe(":8080", service))
}
```

Siesta also provides utilities to manage URL parameters similar to the flag package. Refer to the `params` [example](https://github.com/VividCortex/siesta/blob/master/examples/params/main.go) for a demonstration.

## Contributing

We only accept pull requests for minor fixes or improvements. This includes:

* Small bug fixes
* Typos
* Documentation or comments

Please open issues to discuss new features. Pull requests for new features will be rejected,
so we recommend forking the repository and making changes in your fork for your use case.

## License

Siesta is licensed under the MIT license. The router, which is adapted from [httprouter](https://github.com/julienschmidt/httprouter), is licensed [separately](https://github.com/VividCortex/siesta/blob/6ce42bf31875cc845310b1f4775129edfc8d9967/tree.go#L2-L24).


Siesta

Simple and fast HTTP router for Go. It works with routes of varying difficulty, length and nesting. And he knows how to create a URL from the received parameters

Bxog is a simple and fast HTTP router for Go (HTTP request multiplexer).

[![API documentation](https://godoc.org/github.com/claygod/Bxog?status.svg)](https://godoc.org/github.com/claygod/Bxog)
[![Go Report Card](https://goreportcard.com/badge/github.com/claygod/Bxog)](https://goreportcard.com/report/github.com/claygod/Bxog)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

# Usage

An example of using the multiplexer:
```go
package main

import (
	"io"
	"net/http"

	bx "github.com/claygod/Bxog"
)

// Handlers
func IHandler(w http.ResponseWriter, req *http.Request, r *bx.Router) {
	io.WriteString(w, "Welcome to Bxog!")
}
func THandler(w http.ResponseWriter, req *http.Request, r *bx.Router) {
	params := r.Params(req, "/abc/:par")
	io.WriteString(w, "Params:\n")
	io.WriteString(w, " 'par' -> "+params["par"]+"\n")
}
func PHandler(w http.ResponseWriter, req *http.Request, r *bx.Router) {
	// Getting parameters from URL
	params := r.Params(req, "country")
	io.WriteString(w, "Country:\n")
	io.WriteString(w, " 'name' -> "+params["name"]+"\n")
	io.WriteString(w, " 'capital' -> "+params["city"]+"\n")
	io.WriteString(w, " 'valuta' -> "+params["money"]+"\n")
	// Creating an URL string
	io.WriteString(w, "Creating an URL from the current route (This is an example of creating an another URL):\n")
	io.WriteString(w, r.Create("country", map[string]string{"name": "Russia", "city": "Moscow", "money": "rouble"}))
}

// Main
func main() {
	m := bx.New()
	m.Add("/", IHandler)
	m.Add("/abc/:par", THandler)
	m.Add("/country/:name/capital/:city/valuta/:money", PHandler).
		Id("country"). // For a convinience you can indicate a short ID
		Method("GET") // It is not necessary to indicate the GET method here as the GET method is used by default but this way is used to set an allowed method
	m.Test()
	m.Start(":9999")
}

```

Click URLs:
- http://localhost:9999
- http://localhost:9999/abc/123
- http://localhost:9999/country/USA/capital/Washington/valuta/dollar

# Settings

Necessary changes in the configuration of the multiplexer can be made in the configuration file [config.go](https://github.com/claygod/Bxog/blob/master/config.go)

# Perfomance

Bxog is the fastest router, showing the speed of query processing. Its speed is comparable to the speed of the popular multiplexers: Bone, Httprouter, Gorilla, Zeus. The test is done on a computer with a i3-6320 3.7GHz processor and 8 GB RAM. In short (less time, the better):

- Bxog 163 ns/op
- HttpRouter 183 ns/op
- Zeus 12302 ns/op
- GorillaMux 14928 ns/op
- GorillaPat 618 ns/op
- Bone 47333 ns/op

Detailed benchmark [here](https://github.com/claygod/BxogTest)

# API

Methods:
- *New* - create a new multiplexer
- *Add* - add a rule specifying the handler (the default method - GET, ID - as a string to this rule)
- *Start* - start the server indicating the listening port
- *Params* - extract parameters from URL
- *Create* - generate URL of the available options
- *Shutdown* - graceful stop the server
- *Stop* - aggressive stop the server
- *Test* - Start analogue (for testing only)

Example:
`
	m := bxog.New()
	m.Add("/", IHandler)
`

# Named parameters

Arguments in the rules designated route colon. Example route: */abc/:param* , where *abc* is a static section and *:param* - the dynamic section(argument).

# Static files

The directory path to the file and its nickname as part of URL specified in the configuration file. This constants *FILE_PREF* and *FILE_PATH*

# Copyright

Copyright © 2016-2022 Eduard Sesigin. All rights reserved. Contacts: <claygod@yandex.ru>

Bxog

bone [![GoDoc](https://godoc.org/github.com/squiidz/bone?status.png)](http://godoc.org/github.com/go-zoo/bone) [![Build Status](https://travis-ci.org/go-zoo/bone.svg)](https://travis-ci.org/go-zoo/bone) [![Go Report Card](https://goreportcard.com/badge/go-zoo/bone)](https://goreportcard.com/report/go-zoo/bone)
=======

## What is bone ?

Bone is a lightweight and lightning fast HTTP Multiplexer for Golang. It support :

- URL Parameters
- REGEX Parameters
- Wildcard routes
- Router Prefix
- Route params validators
- Sub Router, `mux.SubRoute()`, support most standard router (bone, gorilla/mux, httpRouter etc...)
- Http method declaration
- Support for `http.Handler` and `http.HandlerFunc`
- Custom NotFound handler
- Respect the Go standard `http.Handler` interface

![alt tag](https://c2.staticflickr.com/2/1070/540747396_5542b42cca_z.jpg)

## Speed

```
- BenchmarkBoneMux        10000000               118 ns/op
- BenchmarkZeusMux          100000               144 ns/op
- BenchmarkHttpRouterMux  10000000               134 ns/op
- BenchmarkNetHttpMux      3000000               580 ns/op
- BenchmarkGorillaMux       300000              3333 ns/op
- BenchmarkGorillaPatMux   1000000              1889 ns/op
```

 These tests are just for fun, all these routers are great and efficient.
 Bone isn't the fastest router for every job.

## Example

``` go

package main

import(
  "net/http"

  "github.com/go-zoo/bone"
)

func main () {
  mux := bone.New()

  mux.RegisterValidatorFunc("isNum", func(s string) bool {
    if _, err := strconv.Atoi(s); err == nil {
      return true
    }
    return false
  })

  // mux.Get, Post, etc ... takes http.Handler
  // validator for route parameter
  mux.Get("/home/:id|isNum", http.HandlerFunc(HomeHandler))
  // multiple parameter
  mux.Get("/profil/:id/:var", http.HandlerFunc(ProfilHandler))
  mux.Post("/data", http.HandlerFunc(DataHandler))

  // Support REGEX Route params
  mux.Get("/index/#id^[0-9]$", http.HandlerFunc(IndexHandler))

  // Handle take http.Handler
  mux.Handle("/", http.HandlerFunc(RootHandler))

  // GetFunc, PostFunc etc ... takes http.HandlerFunc
  mux.GetFunc("/test", Handler)

  http.ListenAndServe(":8080", mux)
}

func Handler(rw http.ResponseWriter, req *http.Request) {
  // Get the value of the "id" parameters.
  val := bone.GetValue(req, "id")

  rw.Write([]byte(val))
}

```

## Blog Posts
- http://www.peterbe.com/plog/my-favorite-go-multiplexer
- https://harshladha.xyz/my-first-library-in-go-language-hasty-791b8e2b9e69

## Libs
- Errors dump for Go : [Trash](https://github.com/go-zoo/trash)
- Middleware Chaining module : [Claw](https://github.com/go-zoo/claw)


Bone

a fast, flexible HTTP router written in Go

# FastRouter

FastRouter is a fast, flexible HTTP router written in Go.

FastRouter contains some customizable options, such as `TrailingSlashesPolicy`, `PanicHandler`, `OptionsHandler`,
 `MethodNotAllowedHandler`, `NotFoundHandler` and so on.

FastRouter also provides some useful features, such as **grouping** and **middleware**.

[![GoDoc](https://godoc.org/github.com/razonyang/fastrouter?status.svg)](https://godoc.org/github.com/razonyang/fastrouter)
[![Build Status](https://travis-ci.org/razonyang/fastrouter.svg?branch=master)](https://travis-ci.org/razonyang/fastrouter)
[![Go Report Card](https://goreportcard.com/badge/github.com/razonyang/fastrouter)](https://goreportcard.com/report/github.com/razonyang/fastrouter)
[![Coverage Status](https://coveralls.io/repos/github/razonyang/fastrouter/badge.svg?branch=master)](https://coveralls.io/github/razonyang/fastrouter?branch=master)

# Features

**Fast**: See [Go Web Framework Benchmark](https://github.com/razonyang/go-web-framework-benchmark)

**Flexible**: FastRouter provides some customizable options for you:
- TrailingSlashesPolicy:
    - IgnoreTrailingSlashes: ignore trailing slashes.
    - AppendTrailingSlashes: append trailing slashes and redirect if request path is not end with '/'.
    - RemoveTrailingSlashes: remove trailing slashes and redirect if request path is end with '/'.
    - StrictTrailingSlashes: remove or append trailing slashes according to corresponding pattern.
- PanicHandler
- OptionsHandler
- MethodNotAllowedHandler
- NotFoundHandler

**Compatible**: FastRouter is an implementation of http.Handler, so it is compatible with third-party packages.

**Middleware**: Middleware is a chaining tool for chaining `http.Handler`,
 see [Middleware](https://godoc.org/github.com/razonyang/fastrouter#Middleware).

**Grouping**: Grouping is an useful feature of FastRouter, it allows to nest and specify middleware of group,
 see [Grouping](https://godoc.org/github.com/razonyang/fastrouter#Router.Group).


# Documentation

See [Documentation](https://godoc.org/github.com/razonyang/fastrouter)
 for details.

# Examples

- [Basic example](https://godoc.org/github.com/razonyang/fastrouter#example-package)
- [Grouping example](https://godoc.org/github.com/razonyang/fastrouter#example-Router-Group)
- [Middleware example](https://godoc.org/github.com/razonyang/fastrouter#example-Middleware)
- [Serve static files example](https://godoc.org/github.com/razonyang/fastrouter#example-Router-ServeFiles)

See [Examples](https://godoc.org/github.com/razonyang/fastrouter#example-package) for details.

FastRouter

Simple yet powerful HTTP request multiplexer

<div align="center">
 
[![Build Status](https://travis-ci.com/goroute/route.svg?branch=master)](https://travis-ci.com/goroute/route)
[![codecov](https://codecov.io/gh/goroute/route/branch/master/graph/badge.svg)](https://codecov.io/gh/goroute/route) 
[![GoDoc](https://godoc.org/github.com/goroute/route?status.svg)](http://godoc.org/github.com/goroute/route) 
[![Go Report Card](https://goreportcard.com/badge/github.com/goroute/route)](https://goreportcard.com/report/github.com/goroute/route)

</div>

## Few main features

* Minimal core.
* No external runtime dependencies. Custom middlewares which requires 3th party dependecies are places in separates repositories under goroute org.
* HTTP Routing.
* Middlewares support.
* Global error handling.

## Getting Started

### Prerequisites

You need to have at least go 1.11 installed on you local machine.

### Installing

Install go route package with go get

```
go get -u github.com/goroute/route
```

Start your first server. Create main.go file and add:
```go
package main

import (
 "net/http"
 "log"
 "github.com/goroute/route"
)

type helloResponse struct {
	Title string `json:"title"`
}

func main() {
	mux := route.NewServeMux()
	
	mux.Use(func(c route.Context, next route.HandlerFunc) error {
	 log.Println("Hello, Middleware!")
	 return next(c)
	})
	
	mux.GET("/", func(c route.Context) error {
	 return c.JSON(http.StatusOK, &helloResponse{Title:"Hello, JSON!"})
	})
	
	log.Fatal(http.ListenAndServe(":9000", mux))
}

```

Run it

```
go run main.go
```

## More examples

See [examples](https://github.com/goroute/route/tree/master/examples)

## Built With

* [Go](https://www.golang.org/)

## Contributing

Please read [CONTRIBUTING.md](https://github.com/goroute/route/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/goroute/route/tags). 

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE) file for details

## Acknowledgments

* This project is largely inspired by [echo](https://echo.labstack.com/). Parts of the code are adopted from echo. See NOTICE.

goroute

GoRouter is a Server/API micro framework, HTTP request router, multiplexer, mux that provides request router with middleware supporting `net/context`

🍃 gorouter
================
[![Build Status](https://travis-ci.com/vardius/gorouter.svg?branch=master)](https://travis-ci.com/vardius/gorouter)
[![Go Report Card](https://goreportcard.com/badge/github.com/vardius/gorouter)](https://goreportcard.com/report/github.com/vardius/gorouter)
[![codecov](https://codecov.io/gh/vardius/gorouter/branch/master/graph/badge.svg)](https://codecov.io/gh/vardius/gorouter)
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fvardius%2Fgorouter.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fvardius%2Fgorouter?ref=badge_shield)
[![](https://godoc.org/github.com/vardius/gorouter?status.svg)](https://pkg.go.dev/github.com/vardius/gorouter)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/vardius/gorouter/blob/master/LICENSE.md)

<img align="right" height="180px" src="website/src/static/img/logo.png" alt="logo" />

Go Server/API micro framework, HTTP request router, multiplexer, mux.

📖 ABOUT
==================================================
Contributors:

* [Rafał Lorenz](https://rafallorenz.com)

Want to contribute ? Feel free to send pull requests!

Have problems, bugs, feature ideas?
We are using the github [issue tracker](https://github.com/vardius/gorouter/issues) to manage them.

## 📚 Documentation

For **documentation** (_including examples_), **visit [rafallorenz.com/gorouter](https://rafallorenz.com/gorouter)**

For **GoDoc** reference, **visit [pkg.go.dev](https://pkg.go.dev/github.com/vardius/gorouter)**

## 🚅 Benchmark

```go
➜ gorouter git:(master) ✗ go test -bench=. -cpu=4 -benchmem
test
goos: darwin
goarch: amd64
pkg: github.com/vardius/gorouter/v4
BenchmarkNetHTTP-4 	65005786	 17.9 ns/op	 0 B/op	 0 allocs/op
BenchmarkFastHTTP-4 	69810878	 16.5 ns/op	 0 B/op	 0 allocs/op
PASS
ok 	github.com/vardius/gorouter/v4	3.808s
```

👉 **[Click here](https://rafallorenz.com/gorouter/docs/benchmark)** to see all benchmark results.

## Features
- Routing System
- Middleware System
- Authentication
- Fast HTTP
- Serving Files
- Multidomain
- HTTP2 Support
- Low memory usage
- [Documentation](https://rafallorenz.com/gorouter/)

🚏 HOW TO USE
==================================================

- [Basic example](https://rafallorenz.com/gorouter/docs/basic-example)
- [net/http](https://rafallorenz.com/gorouter/docs/basic-example#nethttp)
- [valyala/fasthttp](https://rafallorenz.com/gorouter/docs/basic-example#fasthttp)

## 🖥️ API example setup

- **[Go Server/API boilerplate](https://github.com/vardius/go-api-boilerplate)** using best practices DDD CQRS ES.

📜 [License](LICENSE.md)
-------

This package is released under the MIT license. See the complete license in the package:

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fvardius%2Fgorouter.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fvardius%2Fgorouter?ref=badge_large)

GoRouter

# ngamux
Simple HTTP router for Go

[![made-with-Go](https://img.shields.io/badge/Made%20with-Go-1f425f.svg)](http://golang.org)
[![Go Version](https://img.shields.io/github/go-mod/go-version/ngamux/ngamux.svg)](https://github.com/ngamux/ngamux)
[![GoDoc Reference](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/ngamux/ngamux)
[![GoReportCard](https://goreportcard.com/badge/github.com/ngamux/ngamux)](https://goreportcard.com/report/github.com/ngamux/ngamux)
[![Coverage Status](https://codecov.io/gh/ngamux/ngamux/branch/master/graph/badge.svg?token=7ORUPOWS3I)](https://codecov.io/gh/ngamux/ngamux)
---

* [Installation](#installation)
* [Examples](#examples)
* [Provided Middlewares](#provided-middlewares)
* [License](#license)

---

# Installation
Run this command with correctly configured Go toolchain.
```bash
go get github.com/ngamux/ngamux
```

# Examples
```go
package main

import(
  "net/http"
  "github.com/ngamux/ngamux"
)

func main() {
  mux := ngamux.New()
  mux.Get("/", func(rw http.ResponseWriter, r *http.Request) error {
    return ngamux.Res(rw).
      Status(http.StatusOK).
      Json(ngamux.Map{
        "message": "welcome!",
      })
  })
  
  http.ListenAndServe(":8080", mux)
}
```

See more [examples](https://github.com/ngamux/ngamux-example)!

# Provided Middlewares
* [CORS](https://github.com/ngamux/middleware/tree/master/cors)
* [Recover](https://github.com/ngamux/middleware/tree/master/recover)
* [File Upload](https://github.com/ngamux/middleware/tree/master/fileupload)
* [Log](https://github.com/ngamux/middleware/tree/master/log)
* [Auth JWT](https://github.com/ngamux/middleware/tree/master/authjwt)
* [No Cache](https://github.com/ngamux/middleware/tree/master/nocache)
* [Ping](https://github.com/ngamux/middleware/tree/master/ping)
* [Redirect](https://github.com/ngamux/middleware/tree/master/redirect)

# License
This project is licensed under the [Mozilla Public License 2.0](https://github.com/ngamux/ngamux/blob/master/LICENSE).

# Contributors
Thanks to all contributors!

[![Contributors](https://contrib.rocks/image?repo=ngamux/ngamux)](https://github.com/ngamux/ngamux/graphs/contributors)


The Best Go Libraries For Web Frameworks - Routers (28)

mux