1 // Copyright 2012 The Gorilla Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
14 "github.com/fsouza/go-dockerclient/external/github.com/gorilla/context"
17 // NewRouter returns a new router instance.
18 func NewRouter() *Router {
19 return &Router{namedRoutes: make(map[string]*Route), KeepContext: false}
22 // Router registers routes to be matched and dispatches a handler.
24 // It implements the http.Handler interface, so it can be registered to serve
27 // var router = mux.NewRouter()
30 // http.Handle("/", router)
33 // Or, for Google App Engine, register it in a init() function:
36 // http.Handle("/", router)
39 // This will send all incoming requests to the router.
41 // Configurable Handler to be used when no route matches.
42 NotFoundHandler http.Handler
43 // Parent route, if this is a subrouter.
45 // Routes to be matched, in order.
47 // Routes by name for URL building.
48 namedRoutes map[string]*Route
49 // See Router.StrictSlash(). This defines the flag for new routes.
51 // If true, do not clear the request context after handling the request
55 // Match matches registered routes against the request.
56 func (r *Router) Match(req *http.Request, match *RouteMatch) bool {
57 for _, route := range r.routes {
58 if route.Match(req, match) {
63 // Closest match for a router (includes sub-routers)
64 if r.NotFoundHandler != nil {
65 match.Handler = r.NotFoundHandler
71 // ServeHTTP dispatches the handler registered in the matched route.
73 // When there is a match, the route variables can be retrieved calling
75 func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request) {
76 // Clean path to canonical form and redirect.
77 if p := cleanPath(req.URL.Path); p != req.URL.Path {
79 // Added 3 lines (Philip Schlump) - It was dropping the query string and #whatever from query.
80 // This matches with fix in go 1.2 r.c. 4 for same problem. Go Issue:
81 // http://code.google.com/p/go/issues/detail?id=5252
86 w.Header().Set("Location", p)
87 w.WriteHeader(http.StatusMovedPermanently)
91 var handler http.Handler
92 if r.Match(req, &match) {
93 handler = match.Handler
94 setVars(req, match.Vars)
95 setCurrentRoute(req, match.Route)
98 handler = http.NotFoundHandler()
101 defer context.Clear(req)
103 handler.ServeHTTP(w, req)
106 // Get returns a route registered with the given name.
107 func (r *Router) Get(name string) *Route {
108 return r.getNamedRoutes()[name]
111 // GetRoute returns a route registered with the given name. This method
112 // was renamed to Get() and remains here for backwards compatibility.
113 func (r *Router) GetRoute(name string) *Route {
114 return r.getNamedRoutes()[name]
117 // StrictSlash defines the trailing slash behavior for new routes. The initial
120 // When true, if the route path is "/path/", accessing "/path" will redirect
121 // to the former and vice versa. In other words, your application will always
122 // see the path as specified in the route.
124 // When false, if the route path is "/path", accessing "/path/" will not match
125 // this route and vice versa.
127 // Special case: when a route sets a path prefix using the PathPrefix() method,
128 // strict slash is ignored for that route because the redirect behavior can't
129 // be determined from a prefix alone. However, any subrouters created from that
130 // route inherit the original StrictSlash setting.
131 func (r *Router) StrictSlash(value bool) *Router {
132 r.strictSlash = value
136 // ----------------------------------------------------------------------------
138 // ----------------------------------------------------------------------------
140 // getNamedRoutes returns the map where named routes are registered.
141 func (r *Router) getNamedRoutes() map[string]*Route {
142 if r.namedRoutes == nil {
144 r.namedRoutes = r.parent.getNamedRoutes()
146 r.namedRoutes = make(map[string]*Route)
152 // getRegexpGroup returns regexp definitions from the parent route, if any.
153 func (r *Router) getRegexpGroup() *routeRegexpGroup {
155 return r.parent.getRegexpGroup()
160 func (r *Router) buildVars(m map[string]string) map[string]string {
162 m = r.parent.buildVars(m)
167 // ----------------------------------------------------------------------------
169 // ----------------------------------------------------------------------------
171 // NewRoute registers an empty route.
172 func (r *Router) NewRoute() *Route {
173 route := &Route{parent: r, strictSlash: r.strictSlash}
174 r.routes = append(r.routes, route)
178 // Handle registers a new route with a matcher for the URL path.
179 // See Route.Path() and Route.Handler().
180 func (r *Router) Handle(path string, handler http.Handler) *Route {
181 return r.NewRoute().Path(path).Handler(handler)
184 // HandleFunc registers a new route with a matcher for the URL path.
185 // See Route.Path() and Route.HandlerFunc().
186 func (r *Router) HandleFunc(path string, f func(http.ResponseWriter,
187 *http.Request)) *Route {
188 return r.NewRoute().Path(path).HandlerFunc(f)
191 // Headers registers a new route with a matcher for request header values.
192 // See Route.Headers().
193 func (r *Router) Headers(pairs ...string) *Route {
194 return r.NewRoute().Headers(pairs...)
197 // Host registers a new route with a matcher for the URL host.
199 func (r *Router) Host(tpl string) *Route {
200 return r.NewRoute().Host(tpl)
203 // MatcherFunc registers a new route with a custom matcher function.
204 // See Route.MatcherFunc().
205 func (r *Router) MatcherFunc(f MatcherFunc) *Route {
206 return r.NewRoute().MatcherFunc(f)
209 // Methods registers a new route with a matcher for HTTP methods.
210 // See Route.Methods().
211 func (r *Router) Methods(methods ...string) *Route {
212 return r.NewRoute().Methods(methods...)
215 // Path registers a new route with a matcher for the URL path.
217 func (r *Router) Path(tpl string) *Route {
218 return r.NewRoute().Path(tpl)
221 // PathPrefix registers a new route with a matcher for the URL path prefix.
222 // See Route.PathPrefix().
223 func (r *Router) PathPrefix(tpl string) *Route {
224 return r.NewRoute().PathPrefix(tpl)
227 // Queries registers a new route with a matcher for URL query values.
228 // See Route.Queries().
229 func (r *Router) Queries(pairs ...string) *Route {
230 return r.NewRoute().Queries(pairs...)
233 // Schemes registers a new route with a matcher for URL schemes.
234 // See Route.Schemes().
235 func (r *Router) Schemes(schemes ...string) *Route {
236 return r.NewRoute().Schemes(schemes...)
239 // BuildVars registers a new route with a custom function for modifying
240 // route variables before building a URL.
241 func (r *Router) BuildVarsFunc(f BuildVarsFunc) *Route {
242 return r.NewRoute().BuildVarsFunc(f)
245 // Walk walks the router and all its sub-routers, calling walkFn for each route
246 // in the tree. The routes are walked in the order they were added. Sub-routers
247 // are explored depth-first.
248 func (r *Router) Walk(walkFn WalkFunc) error {
249 return r.walk(walkFn, []*Route{})
252 // SkipRouter is used as a return value from WalkFuncs to indicate that the
253 // router that walk is about to descend down to should be skipped.
254 var SkipRouter = errors.New("skip this router")
256 // WalkFunc is the type of the function called for each route visited by Walk.
257 // At every invocation, it is given the current route, and the current router,
258 // and a list of ancestor routes that lead to the current route.
259 type WalkFunc func(route *Route, router *Router, ancestors []*Route) error
261 func (r *Router) walk(walkFn WalkFunc, ancestors []*Route) error {
262 for _, t := range r.routes {
263 if t.regexp == nil || t.regexp.path == nil || t.regexp.path.template == "" {
267 err := walkFn(t, r, ancestors)
268 if err == SkipRouter {
271 for _, sr := range t.matchers {
272 if h, ok := sr.(*Router); ok {
273 err := h.walk(walkFn, ancestors)
279 if h, ok := t.handler.(*Router); ok {
280 ancestors = append(ancestors, t)
281 err := h.walk(walkFn, ancestors)
285 ancestors = ancestors[:len(ancestors)-1]
291 // ----------------------------------------------------------------------------
293 // ----------------------------------------------------------------------------
295 // RouteMatch stores information about a matched route.
296 type RouteMatch struct {
299 Vars map[string]string
305 varsKey contextKey = iota
309 // Vars returns the route variables for the current request, if any.
310 func Vars(r *http.Request) map[string]string {
311 if rv := context.Get(r, varsKey); rv != nil {
312 return rv.(map[string]string)
317 // CurrentRoute returns the matched route for the current request, if any.
318 // This only works when called inside the handler of the matched route
319 // because the matched route is stored in the request context which is cleared
320 // after the handler returns, unless the KeepContext option is set on the
322 func CurrentRoute(r *http.Request) *Route {
323 if rv := context.Get(r, routeKey); rv != nil {
329 func setVars(r *http.Request, val interface{}) {
331 context.Set(r, varsKey, val)
335 func setCurrentRoute(r *http.Request, val interface{}) {
337 context.Set(r, routeKey, val)
341 // ----------------------------------------------------------------------------
343 // ----------------------------------------------------------------------------
345 // cleanPath returns the canonical path for p, eliminating . and .. elements.
346 // Borrowed from the net/http package.
347 func cleanPath(p string) string {
355 // path.Clean removes trailing slash except for root;
356 // put the trailing slash back if necessary.
357 if p[len(p)-1] == '/' && np != "/" {
363 // uniqueVars returns an error if two slices contain duplicated strings.
364 func uniqueVars(s1, s2 []string) error {
365 for _, v1 := range s1 {
366 for _, v2 := range s2 {
368 return fmt.Errorf("mux: duplicated route variable %q", v2)
375 // checkPairs returns the count of strings passed in, and an error if
376 // the count is not an even number.
377 func checkPairs(pairs ...string) (int, error) {
380 return length, fmt.Errorf(
381 "mux: number of parameters must be multiple of 2, got %v", pairs)
386 // mapFromPairsToString converts variadic string parameters to a
387 // string to string map.
388 func mapFromPairsToString(pairs ...string) (map[string]string, error) {
389 length, err := checkPairs(pairs...)
393 m := make(map[string]string, length/2)
394 for i := 0; i < length; i += 2 {
395 m[pairs[i]] = pairs[i+1]
400 // mapFromPairsToRegex converts variadic string paramers to a
401 // string to regex map.
402 func mapFromPairsToRegex(pairs ...string) (map[string]*regexp.Regexp, error) {
403 length, err := checkPairs(pairs...)
407 m := make(map[string]*regexp.Regexp, length/2)
408 for i := 0; i < length; i += 2 {
409 regex, err := regexp.Compile(pairs[i+1])
418 // matchInArray returns true if the given string value is in the array.
419 func matchInArray(arr []string, value string) bool {
420 for _, v := range arr {
428 // matchMapWithString returns true if the given key/value pairs exist in a given map.
429 func matchMapWithString(toCheck map[string]string, toMatch map[string][]string, canonicalKey bool) bool {
430 for k, v := range toCheck {
431 // Check if key exists.
433 k = http.CanonicalHeaderKey(k)
435 if values := toMatch[k]; values == nil {
438 // If value was defined as an empty string we only check that the
439 // key exists. Otherwise we also check for equality.
441 for _, value := range values {
455 // matchMapWithRegex returns true if the given key/value pairs exist in a given map compiled against
457 func matchMapWithRegex(toCheck map[string]*regexp.Regexp, toMatch map[string][]string, canonicalKey bool) bool {
458 for k, v := range toCheck {
459 // Check if key exists.
461 k = http.CanonicalHeaderKey(k)
463 if values := toMatch[k]; values == nil {
466 // If value was defined as an empty string we only check that the
467 // key exists. Otherwise we also check for equality.
469 for _, value := range values {
470 if v.MatchString(value) {