route

README

Route

Host("localhost") && Method("POST") && Path("/v1")
Host("localhost") && Method("POST") && Path("/v1") && Header("Content-Type", "application/<string>")

HTTP request routing language and library.

Features:

• Trie based matching
• Regexp based matching
• Matches hosts, headers, methods and paths
• Flexible matching language

Documentation:

http://godoc.org/github.com/mailgun/route

Documentation

Overview

package route provides http package-compatible routing library. It can route http requests by by hostname, method, path and headers.

Route defines simple language for matching requests based on Go syntax. Route provides series of matchers that follow the syntax:

Matcher("value")          // matches value using trie
Matcher("<string>.value") // uses trie-based matching for a.value and b.value
MatcherRegexp(".*value")  // uses regexp-based matching

Host matcher:

Host("<subdomain>.localhost") // trie-based matcher for a.localhost, b.localhost, etc.
HostRegexp(".*localhost")     // regexp based matcher

Path matcher:

Path("/hello/<value>")   // trie-based matcher for raw request path
PathRegexp("/hello/.*")  // regexp-based matcher for raw request path

Method matcher:

Method("GET")            // trie-based matcher for request method
MethodRegexp("POST|PUT") // regexp based matcher for request method

Header matcher:

Header("Content-Type", "application/<subtype>") // trie-based matcher for headers
HeaderRegexp("Content-Type", "application/.*")  // regexp based matcher for headers

Matchers can be combined using && operator:

Host("localhost") && Method("POST") && Path("/v1")

Route library will join the trie-based matchers into one trie matcher when possible, for example:

Host("localhost") && Method("POST") && Path("/v1")
Host("localhost") && Method("GET") && Path("/v2")

Will be combined into one trie for performance. If you add a third route:

Host("localhost") && Method("GET") && PathRegexp("/v2/.*")

It wont be joined ito the trie, and would be matched separatedly instead.

Index

• func IsValid(expr string) bool
• type Mux
  • func NewMux() *Mux
  • func (m *Mux) Handle(expr string, handler http.Handler) error
  • func (m *Mux) HandleFunc(expr string, handler func(http.ResponseWriter, *http.Request)) error
  • func (m *Mux) Remove(expr string) error
  • func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type NotFound
  • func (NotFound) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Router
  • func New() Router

Functions

func IsValid

func IsValid(expr string) bool

IsValid checks whether expression is valid

Types

type Mux

type Mux struct {
	// NotFound sets handler for routes that are not found
	NotFound http.Handler
	// contains filtered or unexported fields
}

Mux implements router compatible with http.Handler

func NewMux

func NewMux() *Mux

NewMux returns new Mux router

func (*Mux) Handle

func (m *Mux) Handle(expr string, handler http.Handler) error

Handle adds http handler for route expression

func (*Mux) HandleFunc

func (m *Mux) HandleFunc(expr string, handler func(http.ResponseWriter, *http.Request)) error

Handle adds http handler function for route expression

func (*Mux) Remove

func (m *Mux) Remove(expr string) error

func (*Mux) ServeHTTP

func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP routes the request and passes it to handler

type NotFound

type NotFound struct {
}

NotFound is a generic http.Handler for request

func (NotFound) ServeHTTP

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

ServeHTTP returns a simple 404 Not found response

type Router

type Router interface {
	// GetRoute returns a route by a given expression, returns nil if expresison is not found
	GetRoute(string) interface{}

	// AddRoute adds a route to match by expression, returns error if the expression already defined, or route expression is incorrect
	AddRoute(string, interface{}) error

	// RemoveRoute removes a route for a given expression
	RemoveRoute(string) error

	// UpsertRoute updates an existing route or adds a new route by given expression
	UpsertRoute(string, interface{}) error

	// Route takes a request and matches it against requests, returns matched route in case if found, nil if there's no matching route or error in case of internal error.
	Route(*http.Request) (interface{}, error)
}

Router implements http request routing and operations. It is a generic router not conforming to http.Handler interface, to get a handler conforming to http.Handler interface, use Mux router instead.

func New

func New() Router

New creates a new Router instance