package httprouter

import "github.com/julienschmidt/httprouter"

Package httprouter is a trie based high performance HTTP request router.

A trivial example is:

package main

import (
    "fmt"
    "github.com/julienschmidt/httprouter"
    "net/http"
    "log"
)

func Index(w http.ResponseWriter, r *http.Request, _ map[string]string) {
    fmt.Fprint(w, "Welcome!\n")
}

func Hello(w http.ResponseWriter, r *http.Request, vars map[string]string) {
    fmt.Fprintf(w, "hello, %s!\n", vars["name"])
}

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

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

The router matches incoming requests by the request method and the path. If a handle is registered for this path and method, the router delegates the request to that function. For the methods GET, POST, PUT, PATCH and DELETE shortcut functions exist to register handles, for all other methods router.Handle can be used.

The registered path, against which the router matches incoming requests, can contain two types of wildcards:

Syntax    Type
:name     Parameter
*name     CatchAll

The value of wildcards is saved in a map as vars["name"] = value. The map is passed to the Handle func as a parameter.

Parameters are variable path segments. They match anything until the next '/' or the path end:

Path: /blog/:category/:post

Requests:
 /blog/go/request-routers            match: category="go", post="request-routers"
 /blog/go/request-routers/           no match, but the router would redirect
 /blog/go/                           no match
 /blog/go/request-routers/comments   no match

CatchAll wildcards match anything until the path end, including the directory index (the '/” before the CatchAll). Since they match anything until the end, CatchAll wildcards must always be the final path element.

Path: /files/*filepath

Requests:
 /files/                             match: filepath="/"
 /files/LICENSE                      match: filepath="/LICENSE"
 /files/templates/article.html       match: filepath="/templates/article.html"
 /files                              no match, but the router would redirect

Index ¶

• func CleanPath(p string) string
• func NotFound(w http.ResponseWriter, req *http.Request)
• type Handle
• type Router
• func New() *Router
• func (r *Router) DELETE(path string, handle Handle)
• func (r *Router) GET(path string, handle Handle)
• func (r *Router) Handle(method, path string, handle Handle)
• func (r *Router) HandlerFunc(method, path string, handler http.HandlerFunc)
• func (r *Router) PATCH(path string, handle Handle)
• func (r *Router) POST(path string, handle Handle)
• func (r *Router) PUT(path string, handle Handle)
• func (r *Router) ServeFiles(path string, root http.FileSystem)
• func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

Functions ¶

func CleanPath ¶

func CleanPath(p string) string

CleanPath is the URL version of path.Clean, it returns a canonical URL path for p, eliminating . and .. elements.

The following rules are applied iteratively until no further processing can be done:

1. Replace multiple slashes with a single slash.
2. Eliminate each . path name element (the current directory).
3. Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
4. Eliminate .. elements that begin a rooted path: that is, replace "/.." by "/" at the beginning of a path.

If the result of this process is an empty string, "/" is returned

func NotFound ¶

func NotFound(w http.ResponseWriter, req *http.Request)

NotFound is the default HTTP handler func for routes that can't be matched with an existing route. NotFound tries to redirect to a canonical URL generated with CleanPath. Otherwise the request is delegated to http.NotFound.

Types ¶

type Handle ¶

type Handle func(http.ResponseWriter, *http.Request, map[string]string)

Handle is a function that can be registered to a route to handle HTTP requests. Like http.HandlerFunc, but has a third parameter for the values of wildcards (variables).

type Router ¶

type Router struct {

	// Enables automatic redirection if the current route can't be matched but a
	// handler for the path with (without) the trailing slash exists.
	// For example if /foo/ is requested but a route only exists for /foo, the
	// client is redirected to /foo with http status code 301.
	RedirectTrailingSlash bool

	// Enables automatic redirection if the current route can't be matched but a
	// case-insensitive lookup of the path finds a handler.
	// The router then permanent redirects (http status code 301) to the
	// corrected path.
	// For example /FOO and /Foo could be redirected to /foo.
	RedirectCaseInsensitive bool

	// Configurable handler func which is used when no matching route is found.
	// Default is the NotFound func of this package.
	NotFound http.HandlerFunc

	// Handler func to handle panics recovered from http handlers.
	// It should be used to generate a error page and return the http error code
	// "500 - Internal Server Error".
	// The handler can be used to keep your server from crashing because of
	// unrecovered panics.
	PanicHandler func(http.ResponseWriter, *http.Request, interface{})
	// contains filtered or unexported fields
}

Router is a http.Handler which can be used to dispatch requests to different handler functions via configurable routes

func New ¶

func New() *Router

New returnes a new initialized Router. The router can be configured to also match the requested HTTP method or the requested Host.

func (*Router) DELETE ¶

func (r *Router) DELETE(path string, handle Handle)

DELETE is a shortcut for router.Handle("DELETE", path, handle)

func (*Router) GET ¶

func (r *Router) GET(path string, handle Handle)

GET is a shortcut for router.Handle("GET", path, handle)

func (*Router) Handle ¶

func (r *Router) Handle(method, path string, handle Handle)

Handle registers a new request handle with the given path and method.

For GET, POST, PUT, PATCH and DELETE requests the respective shortcut functions can be used.

This function is intended for bulk loading and to allow the usage of less frequently used, non-standardized or custom methods (e.g. for internal communication with a proxy).

func (*Router) HandlerFunc ¶

func (r *Router) HandlerFunc(method, path string, handler http.HandlerFunc)

HandlerFunc is an adapter which allows the usage of a http.HandlerFunc as a request handle.

func (*Router) PATCH ¶

func (r *Router) PATCH(path string, handle Handle)

PATCH is a shortcut for router.Handle("PATCH", path, handle)

func (*Router) POST ¶

func (r *Router) POST(path string, handle Handle)

POST is a shortcut for router.Handle("POST", path, handle)

func (*Router) PUT ¶

func (r *Router) PUT(path string, handle Handle)

PUT is a shortcut for router.Handle("PUT", path, handle)

func (*Router) ServeFiles ¶

func (r *Router) ServeFiles(path string, root http.FileSystem)

ServeFiles serves files from the given file system root. The path must end with "/*filepath", files are then served from the local path /defined/root/dir/*filepath. For example if root is "/etc" and *filepath is "passwd", the local file "/etc/passwd" would be served. Internally a http.FileServer is used, therefore http.NotFound is used instead of the Router's NotFound handler. To use the operating system's file system implementation, use http.Dir:

router.ServeFiles("/src/*filepath", http.Dir("/var/www"))

func (*Router) ServeHTTP ¶

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

Make the router implement the http.Handler interface.

Source Files ¶

path.go router.go tree.go