gin/gin.go

425 lines
13 KiB
Go
Raw Normal View History

2014-08-29 21:49:50 +04:00
// Copyright 2014 Manu Martinez-Almeida. All rights reserved.
// Use of this source code is governed by a MIT style
// license that can be found in the LICENSE file.
2014-06-18 03:42:34 +04:00
package gin
import (
"html/template"
2015-05-19 01:45:08 +03:00
"net"
2014-06-18 03:42:34 +04:00
"net/http"
2015-05-19 01:45:08 +03:00
"os"
2014-07-06 23:09:23 +04:00
"sync"
2015-03-23 06:41:29 +03:00
"github.com/gin-gonic/gin/render"
2014-06-18 03:42:34 +04:00
)
2016-04-15 02:16:46 +03:00
// Version is Framework's version
2017-04-07 23:18:36 +03:00
const Version = "v1.2"
2015-05-22 17:55:16 +03:00
2015-03-31 22:39:06 +03:00
var default404Body = []byte("404 page not found")
var default405Body = []byte("405 method not allowed")
2016-12-05 13:21:59 +03:00
var defaultAppEngine bool
2014-06-18 03:42:34 +04:00
2015-06-26 17:05:09 +03:00
type HandlerFunc func(*Context)
type HandlersChain []HandlerFunc
// Last returns the last handler in the chain. ie. the last handler is the main own.
2015-06-26 17:05:09 +03:00
func (c HandlersChain) Last() HandlerFunc {
if length := len(c); length > 0 {
2015-06-26 17:05:09 +03:00
return c[length-1]
}
return nil
}
2017-07-05 10:47:36 +03:00
type RouteInfo struct {
Method string
Path string
Handler string
}
2014-06-18 03:42:34 +04:00
2017-07-05 10:47:36 +03:00
type RoutesInfo []RouteInfo
// Engine is the framework's instance, it contains the muxer, middleware and configuration settings.
// Create an instance of Engine, by using New() or Default()
type Engine struct {
RouterGroup
delims render.Delims
secureJsonPrefix string
HTMLRender render.HTMLRender
FuncMap template.FuncMap
allNoRoute HandlersChain
allNoMethod HandlersChain
noRoute HandlersChain
noMethod HandlersChain
pool sync.Pool
trees methodTrees
2017-07-05 10:47:36 +03:00
// 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 for GET requests
// and 307 for all other request methods.
RedirectTrailingSlash bool
// If enabled, the router tries to fix the current request path, if no
// handle is registered for it.
// First superfluous path elements like ../ or // are removed.
// Afterwards the router does a case-insensitive lookup of the cleaned path.
// If a handle can be found for this route, the router makes a redirection
// to the corrected path with status code 301 for GET requests and 307 for
// all other request methods.
// For example /FOO and /..//Foo could be redirected to /foo.
// RedirectTrailingSlash is independent of this option.
RedirectFixedPath bool
// If enabled, the router checks if another method is allowed for the
// current route, if the current request can not be routed.
// If this is the case, the request is answered with 'Method Not Allowed'
// and HTTP status code 405.
// If no other Method is allowed, the request is delegated to the NotFound
// handler.
HandleMethodNotAllowed bool
ForwardedByClientIP bool
// #726 #755 If enabled, it will thrust some headers starting with
// 'X-AppEngine...' for better integration with that PaaS.
AppEngine bool
// If enabled, the url.RawPath will be used to find parameters.
UseRawPath bool
// If true, the path value will be unescaped.
// If UseRawPath is false (by default), the UnescapePathValues effectively is true,
// as url.Path gonna be used, which is already unescaped.
UnescapePathValues bool
}
2014-06-18 03:42:34 +04:00
var _ IRouter = &Engine{}
2015-06-26 17:01:35 +03:00
// New returns a new blank Engine instance without any middleware attached.
// By default the configuration is:
// - RedirectTrailingSlash: true
// - RedirectFixedPath: false
// - HandleMethodNotAllowed: false
// - ForwardedByClientIP: true
// - UseRawPath: false
// - UnescapePathValues: true
2014-07-06 23:09:23 +04:00
func New() *Engine {
debugPrintWARNINGNew()
2015-03-31 22:39:06 +03:00
engine := &Engine{
2015-04-07 13:22:38 +03:00
RouterGroup: RouterGroup{
Handlers: nil,
basePath: "/",
2015-06-11 02:02:38 +03:00
root: true,
2015-04-07 13:22:38 +03:00
},
FuncMap: template.FuncMap{},
2015-03-31 22:39:06 +03:00
RedirectTrailingSlash: true,
RedirectFixedPath: false,
HandleMethodNotAllowed: false,
2015-06-07 14:51:13 +03:00
ForwardedByClientIP: true,
2016-12-05 13:21:59 +03:00
AppEngine: defaultAppEngine,
UseRawPath: false,
UnescapePathValues: true,
2015-06-07 14:51:13 +03:00
trees: make(methodTrees, 0, 9),
delims: render.Delims{"{{", "}}"},
secureJsonPrefix: "while(1);",
2015-03-31 22:39:06 +03:00
}
2015-04-07 13:22:38 +03:00
engine.RouterGroup.engine = engine
2014-10-08 23:37:26 +04:00
engine.pool.New = func() interface{} {
2015-03-25 21:33:17 +03:00
return engine.allocateContext()
}
2014-06-18 03:42:34 +04:00
return engine
}
// Default returns an Engine instance with the Logger and Recovery middleware already attached.
2014-06-18 03:42:34 +04:00
func Default() *Engine {
engine := New()
engine.Use(Logger(), Recovery())
2014-06-18 03:42:34 +04:00
return engine
}
2015-06-07 14:51:13 +03:00
func (engine *Engine) allocateContext() *Context {
return &Context{engine: engine}
2015-03-25 21:33:17 +03:00
}
func (engine *Engine) Delims(left, right string) *Engine {
engine.delims = render.Delims{left, right}
return engine
}
func (engine *Engine) SecureJsonPrefix(prefix string) *Engine {
engine.secureJsonPrefix = prefix
return engine
}
2014-07-15 19:41:56 +04:00
func (engine *Engine) LoadHTMLGlob(pattern string) {
2014-10-08 23:37:26 +04:00
if IsDebugging() {
debugPrintLoadTemplate(template.Must(template.New("").Delims(engine.delims.Left, engine.delims.Right).Funcs(engine.FuncMap).ParseGlob(pattern)))
engine.HTMLRender = render.HTMLDebug{Glob: pattern, FuncMap: engine.FuncMap, Delims: engine.delims}
return
2014-08-21 03:04:35 +04:00
}
2017-07-19 15:49:18 +03:00
templ := template.Must(template.New("").Delims(engine.delims.Left, engine.delims.Right).Funcs(engine.FuncMap).ParseGlob(pattern))
engine.SetHTMLTemplate(templ)
2014-07-15 19:41:56 +04:00
}
func (engine *Engine) LoadHTMLFiles(files ...string) {
2014-10-08 23:37:26 +04:00
if IsDebugging() {
engine.HTMLRender = render.HTMLDebug{Files: files, FuncMap: engine.FuncMap, Delims: engine.delims}
return
2014-08-21 03:04:35 +04:00
}
2017-07-19 15:49:18 +03:00
templ := template.Must(template.New("").Delims(engine.delims.Left, engine.delims.Right).Funcs(engine.FuncMap).ParseFiles(files...))
engine.SetHTMLTemplate(templ)
2014-08-21 03:04:35 +04:00
}
func (engine *Engine) SetHTMLTemplate(templ *template.Template) {
2015-06-12 19:09:44 +03:00
if len(engine.trees) > 0 {
debugPrintWARNINGSetHTMLTemplate()
2015-06-12 19:09:44 +03:00
}
engine.HTMLRender = render.HTMLProduction{Template: templ.Funcs(engine.FuncMap)}
}
func (engine *Engine) SetFuncMap(funcMap template.FuncMap) {
engine.FuncMap = funcMap
2014-06-18 03:42:34 +04:00
}
2016-04-15 02:16:46 +03:00
// NoRoute adds handlers for NoRoute. It return a 404 code by default.
2014-07-18 01:42:23 +04:00
func (engine *Engine) NoRoute(handlers ...HandlerFunc) {
2014-07-18 02:29:44 +04:00
engine.noRoute = handlers
2014-10-08 23:37:26 +04:00
engine.rebuild404Handlers()
2014-07-18 02:29:44 +04:00
}
2016-04-15 02:16:46 +03:00
// NoMethod sets the handlers called when... TODO
func (engine *Engine) NoMethod(handlers ...HandlerFunc) {
engine.noMethod = handlers
engine.rebuild405Handlers()
}
2016-04-15 02:16:46 +03:00
// Use attachs a global middleware to the router. ie. the middleware attached though Use() will be
2015-05-29 22:03:41 +03:00
// included in the handlers chain for every single request. Even 404, 405, static files...
// For example, this is the right place for a logger or error management middleware.
func (engine *Engine) Use(middleware ...HandlerFunc) IRoutes {
engine.RouterGroup.Use(middleware...)
2014-10-08 23:37:26 +04:00
engine.rebuild404Handlers()
engine.rebuild405Handlers()
2015-06-11 02:02:38 +03:00
return engine
2014-10-08 23:37:26 +04:00
}
func (engine *Engine) rebuild404Handlers() {
2015-03-25 18:53:58 +03:00
engine.allNoRoute = engine.combineHandlers(engine.noRoute)
}
func (engine *Engine) rebuild405Handlers() {
2015-03-25 18:53:58 +03:00
engine.allNoMethod = engine.combineHandlers(engine.noMethod)
2014-06-18 03:42:34 +04:00
}
2015-05-20 00:22:35 +03:00
func (engine *Engine) addRoute(method, path string, handlers HandlersChain) {
2016-01-28 02:35:09 +03:00
assert1(path[0] == '/', "path must begin with '/'")
assert1(len(method) > 0, "HTTP method can not be empty")
assert1(len(handlers) > 0, "there must be at least one handler")
2015-04-09 13:15:02 +03:00
2016-01-28 02:35:09 +03:00
debugPrintRoute(method, path, handlers)
2015-06-04 02:54:36 +03:00
root := engine.trees.get(method)
2015-03-31 22:39:06 +03:00
if root == nil {
root = new(node)
2016-01-28 02:35:09 +03:00
engine.trees = append(engine.trees, methodTree{method: method, root: root})
2015-03-31 22:39:06 +03:00
}
root.addRoute(path, handlers)
}
// Routes returns a slice of registered routes, including some useful information, such as:
// the http method, path and the handler name.
2015-06-18 18:17:22 +03:00
func (engine *Engine) Routes() (routes RoutesInfo) {
2015-06-07 05:20:39 +03:00
for _, tree := range engine.trees {
routes = iterate("", tree.method, routes, tree.root)
2015-06-07 05:20:39 +03:00
}
return routes
}
2015-06-18 18:17:22 +03:00
func iterate(path, method string, routes RoutesInfo, root *node) RoutesInfo {
2015-06-07 05:20:39 +03:00
path += root.path
if len(root.handlers) > 0 {
routes = append(routes, RouteInfo{
Method: method,
Path: path,
Handler: nameOfFunction(root.handlers.Last()),
})
2015-06-07 05:20:39 +03:00
}
2015-07-02 19:42:33 +03:00
for _, child := range root.children {
routes = iterate(path, method, routes, child)
2015-06-07 05:20:39 +03:00
}
return routes
}
// Run attaches the router to a http.Server and starts listening and serving HTTP requests.
2015-05-29 22:03:41 +03:00
// It is a shortcut for http.ListenAndServe(addr, router)
// Note: this method will block the calling goroutine indefinitely unless an error happens.
func (engine *Engine) Run(addr ...string) (err error) {
2015-05-19 01:45:08 +03:00
defer func() { debugPrintError(err) }()
2015-05-09 04:34:43 +03:00
address := resolveAddress(addr)
debugPrint("Listening and serving HTTP on %s\n", address)
err = http.ListenAndServe(address, engine)
2015-05-09 04:34:43 +03:00
return
2015-04-07 13:22:38 +03:00
}
// RunTLS attaches the router to a http.Server and starts listening and serving HTTPS (secure) requests.
2015-05-29 22:03:41 +03:00
// It is a shortcut for http.ListenAndServeTLS(addr, certFile, keyFile, router)
// Note: this method will block the calling goroutine indefinitely unless an error happens.
func (engine *Engine) RunTLS(addr string, certFile string, keyFile string) (err error) {
2015-04-07 13:22:38 +03:00
debugPrint("Listening and serving HTTPS on %s\n", addr)
2015-05-19 01:45:08 +03:00
defer func() { debugPrintError(err) }()
2015-05-09 04:34:43 +03:00
err = http.ListenAndServeTLS(addr, certFile, keyFile, engine)
2015-05-09 04:34:43 +03:00
return
2015-04-07 13:22:38 +03:00
}
// RunUnix attaches the router to a http.Server and starts listening and serving HTTP requests
// through the specified unix socket (ie. a file).
// Note: this method will block the calling goroutine indefinitely unless an error happens.
2015-05-19 01:45:08 +03:00
func (engine *Engine) RunUnix(file string) (err error) {
debugPrint("Listening and serving HTTP on unix:/%s", file)
defer func() { debugPrintError(err) }()
os.Remove(file)
2015-05-19 01:48:19 +03:00
listener, err := net.Listen("unix", file)
2015-05-19 01:45:08 +03:00
if err != nil {
return
}
defer listener.Close()
err = http.Serve(listener, engine)
return
}
2017-07-06 04:28:16 +03:00
// ServeHTTP conforms to the http.Handler interface.
2015-03-31 22:39:06 +03:00
func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
2015-05-18 21:50:46 +03:00
c := engine.pool.Get().(*Context)
c.writermem.reset(w)
c.Request = req
c.reset()
2015-04-07 13:22:38 +03:00
2015-05-28 04:22:34 +03:00
engine.handleHTTPRequest(c)
2015-05-18 21:50:46 +03:00
engine.pool.Put(c)
2015-04-07 13:22:38 +03:00
}
2017-07-06 04:28:16 +03:00
// HandleContext re-enter a context that has been rewritten.
// This can be done by setting c.Request.Path to your new target.
// Disclaimer: You can loop yourself to death with this, use wisely.
func (engine *Engine) HandleContext(c *Context) {
c.reset()
engine.handleHTTPRequest(c)
engine.pool.Put(c)
}
2015-05-18 21:50:46 +03:00
func (engine *Engine) handleHTTPRequest(context *Context) {
2015-04-07 13:22:38 +03:00
httpMethod := context.Request.Method
var path string
var unescape bool
if engine.UseRawPath && len(context.Request.URL.RawPath) > 0 {
path = context.Request.URL.RawPath
unescape = engine.UnescapePathValues
} else {
path = context.Request.URL.Path
unescape = false
}
2015-04-07 13:22:38 +03:00
// Find root of the tree for the given HTTP method
2015-05-29 22:03:28 +03:00
t := engine.trees
for i, tl := 0, len(t); i < tl; i++ {
if t[i].method == httpMethod {
root := t[i].root
2015-05-29 22:03:28 +03:00
// Find route in tree
handlers, params, tsr := root.getValue(path, context.Params, unescape)
2015-05-29 22:03:28 +03:00
if handlers != nil {
context.handlers = handlers
context.Params = params
context.Next()
context.writermem.WriteHeaderNow()
2015-04-07 13:22:38 +03:00
return
2017-06-13 06:36:05 +03:00
}
if httpMethod != "CONNECT" && path != "/" {
if tsr && engine.RedirectTrailingSlash {
redirectTrailingSlash(context)
return
}
if engine.RedirectFixedPath && redirectFixedPath(context, root, engine.RedirectFixedPath) {
2015-05-29 22:03:28 +03:00
return
}
2015-04-07 13:22:38 +03:00
}
2015-06-04 02:54:36 +03:00
break
2015-03-31 22:39:06 +03:00
}
}
2015-04-07 13:22:38 +03:00
if engine.HandleMethodNotAllowed {
2015-05-29 22:03:28 +03:00
for _, tree := range engine.trees {
if tree.method != httpMethod {
if handlers, _, _ := tree.root.getValue(path, nil, unescape); handlers != nil {
2015-04-07 13:22:38 +03:00
context.handlers = engine.allNoMethod
serveError(context, 405, default405Body)
return
}
}
}
}
2015-04-08 15:24:49 +03:00
context.handlers = engine.allNoRoute
2015-04-07 13:22:38 +03:00
serveError(context, 404, default404Body)
2014-06-18 03:42:34 +04:00
}
var mimePlain = []string{MIMEPlain}
func serveError(c *Context, code int, defaultMessage []byte) {
c.writermem.status = code
c.Next()
if !c.writermem.Written() {
if c.writermem.Status() == code {
c.writermem.Header()["Content-Type"] = mimePlain
c.Writer.Write(defaultMessage)
} else {
c.writermem.WriteHeaderNow()
}
}
}
func redirectTrailingSlash(c *Context) {
2015-04-07 13:22:38 +03:00
req := c.Request
path := req.URL.Path
code := 301 // Permanent redirect, request with GET method
if req.Method != "GET" {
code = 307
}
if len(path) > 1 && path[len(path)-1] == '/' {
req.URL.Path = path[:len(path)-1]
} else {
req.URL.Path = path + "/"
}
debugPrint("redirecting request %d: %s --> %s", code, path, req.URL.String())
http.Redirect(c.Writer, req, req.URL.String(), code)
c.writermem.WriteHeaderNow()
}
func redirectFixedPath(c *Context, root *node, trailingSlash bool) bool {
req := c.Request
path := req.URL.Path
fixedPath, found := root.findCaseInsensitivePath(
cleanPath(path),
trailingSlash,
)
if found {
code := 301 // Permanent redirect, request with GET method
if req.Method != "GET" {
code = 307
2015-04-07 13:22:38 +03:00
}
req.URL.Path = string(fixedPath)
debugPrint("redirecting request %d: %s --> %s", code, path, req.URL.String())
2015-04-07 13:22:38 +03:00
http.Redirect(c.Writer, req, req.URL.String(), code)
2015-05-05 17:37:33 +03:00
c.writermem.WriteHeaderNow()
2015-04-07 13:22:38 +03:00
return true
}
return false
2014-06-18 03:42:34 +04:00
}