Echo Inspired Stand Alone URL Router
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis.yml bumping travis go version to 1.6.3, as well as correcting a test Jul 29, 2016
LICENSE Adding License and README.md Sep 22, 2015
LICENSE-go-http-routing-benchmark adding unit tests, 84% coverage, wip. Adding go-http-routing-benchmar… Sep 22, 2015
README.md Update README.md Apr 29, 2018
common.go Changed ParamNames back and added a new function with the name Trimme… Jan 20, 2017
common_test.go ordering of the slice doesnt matter for TrimmedParamName, and test wa… Apr 4, 2017
cors.go Updated package comments. Feb 13, 2016
cors_test.go moving print tree back to test file, only used in test, created unit … Jun 22, 2016
doc.go linted codebase, corrected linting errors, added better godocs, updat… Sep 28, 2015
examples_test.go linted codebase, corrected linting errors, added better godocs, updat… Sep 28, 2015
handlers.go Assume 200 status if none is written May 14, 2018
handlers_test.go Assume 200 status if none is written May 14, 2018
resource.go Changed hardcoded http methods Jul 28, 2016
router.go changed interceptor to middleware Jun 21, 2017
router_test.go
tree.go renaming parameter in findChild function to reflect new meaning, remo… May 4, 2017
tree_test.go moving print tree back to test file, only used in test, created unit … Jun 22, 2016

README.md

Vestigo - A Standalone Golang URL Router

Join the chat at https://gitter.im/husobee/vestigo Build Status Coverage Status GoDoc

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

  • Router functioning with a resource concept attached to leaf nodes
  • Use resources to drive responses to particular Methods (not found v not allowed)
  • Implement Resource and Globally scoped CORS preflights
  • Fix bug in router where handler.allowedMethods is getting populated where it shouldn't be
  • 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 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

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

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:

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:

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

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

Licensing

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.