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/v5"
13//  	"github.com/go-chi/chi/v5/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//
56package chi
57
58import "net/http"
59
60// NewRouter returns a new Mux object that implements the Router interface.
61func 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.
67type 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.
119type 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.
134type Middlewares []func(http.Handler) http.Handler
135