1 // 2 // Package chi is a small, idiomatic and composable router for building HTTP services. 3 // 4 // chi requires Go 1.10 or newer. 5 // 6 // Example: 7 // package main 8 // 9 // import ( 10 // "net/http" 11 // 12 // "github.com/go-chi/chi" 13 // "github.com/go-chi/chi/middleware" 14 // ) 15 // 16 // func main() { 17 // r := chi.NewRouter() 18 // r.Use(middleware.Logger) 19 // r.Use(middleware.Recoverer) 20 // 21 // r.Get("/", func(w http.ResponseWriter, r *http.Request) { 22 // w.Write([]byte("root.")) 23 // }) 24 // 25 // http.ListenAndServe(":3333", r) 26 // } 27 // 28 // See github.com/go-chi/chi/_examples/ for more in-depth examples. 29 // 30 // URL patterns allow for easy matching of path components in HTTP 31 // requests. The matching components can then be accessed using 32 // chi.URLParam(). All patterns must begin with a slash. 33 // 34 // A simple named placeholder {name} matches any sequence of characters 35 // up to the next / or the end of the URL. Trailing slashes on paths must 36 // be handled explicitly. 37 // 38 // A placeholder with a name followed by a colon allows a regular 39 // expression match, for example {number:\\d+}. The regular expression 40 // syntax is Go's normal regexp RE2 syntax, except that regular expressions 41 // including { or } are not supported, and / will never be 42 // matched. An anonymous regexp pattern is allowed, using an empty string 43 // before the colon in the placeholder, such as {:\\d+} 44 // 45 // The special placeholder of asterisk matches the rest of the requested 46 // URL. Any trailing characters in the pattern are ignored. This is the only 47 // placeholder which will match / characters. 48 // 49 // Examples: 50 // "/user/{name}" matches "/user/jsmith" but not "/user/jsmith/info" or "/user/jsmith/" 51 // "/user/{name}/info" matches "/user/jsmith/info" 52 // "/page/*" matches "/page/intro/latest" 53 // "/page/*/index" also matches "/page/intro/latest" 54 // "/date/{yyyy:\\d\\d\\d\\d}/{mm:\\d\\d}/{dd:\\d\\d}" matches "/date/2017/04/01" 55 // 56 package chi 57 58 import "net/http" 59 60 // NewRouter returns a new Mux object that implements the Router interface. 61 func NewRouter() *Mux { 62 return NewMux() 63 } 64 65 // Router consisting of the core routing methods used by chi's Mux, 66 // using only the standard net/http. 67 type Router interface { 68 http.Handler 69 Routes 70 71 // Use appends one or more middlewares onto the Router stack. 72 Use(middlewares ...func(http.Handler) http.Handler) 73 74 // With adds inline middlewares for an endpoint handler. 75 With(middlewares ...func(http.Handler) http.Handler) Router 76 77 // Group adds a new inline-Router along the current routing 78 // path, with a fresh middleware stack for the inline-Router. 79 Group(fn func(r Router)) Router 80 81 // Route mounts a sub-Router along a `pattern`` string. 82 Route(pattern string, fn func(r Router)) Router 83 84 // Mount attaches another http.Handler along ./pattern/* 85 Mount(pattern string, h http.Handler) 86 87 // Handle and HandleFunc adds routes for `pattern` that matches 88 // all HTTP methods. 89 Handle(pattern string, h http.Handler) 90 HandleFunc(pattern string, h http.HandlerFunc) 91 92 // Method and MethodFunc adds routes for `pattern` that matches 93 // the `method` HTTP method. 94 Method(method, pattern string, h http.Handler) 95 MethodFunc(method, pattern string, h http.HandlerFunc) 96 97 // HTTP-method routing along `pattern` 98 Connect(pattern string, h http.HandlerFunc) 99 Delete(pattern string, h http.HandlerFunc) 100 Get(pattern string, h http.HandlerFunc) 101 Head(pattern string, h http.HandlerFunc) 102 Options(pattern string, h http.HandlerFunc) 103 Patch(pattern string, h http.HandlerFunc) 104 Post(pattern string, h http.HandlerFunc) 105 Put(pattern string, h http.HandlerFunc) 106 Trace(pattern string, h http.HandlerFunc) 107 108 // NotFound defines a handler to respond whenever a route could 109 // not be found. 110 NotFound(h http.HandlerFunc) 111 112 // MethodNotAllowed defines a handler to respond whenever a method is 113 // not allowed. 114 MethodNotAllowed(h http.HandlerFunc) 115 } 116 117 // Routes interface adds two methods for router traversal, which is also 118 // used by the `docgen` subpackage to generation documentation for Routers. 119 type Routes interface { 120 // Routes returns the routing tree in an easily traversable structure. 121 Routes() []Route 122 123 // Middlewares returns the list of middlewares in use by the router. 124 Middlewares() Middlewares 125 126 // Match searches the routing tree for a handler that matches 127 // the method/path - similar to routing a http request, but without 128 // executing the handler thereafter. 129 Match(rctx *Context, method, path string) bool 130 } 131 132 // Middlewares type is a slice of standard middleware handlers with methods 133 // to compose middleware chains and http.Handler's. 134 type Middlewares []func(http.Handler) http.Handler 135