diff --git a/config.go b/config.go index 3a03a45c..7dd40d00 100644 --- a/config.go +++ b/config.go @@ -14,54 +14,81 @@ import ( ) var ( + // beego application BeeApp *App + // application configurations AppName string AppPath string AppConfigPath string StaticDir map[string]string + // template caching map TemplateCache map[string]*template.Template - StaticExtensionsToGzip []string //Files which should also be compressed with gzip (.js, .css, etc) + // files with should be compressed with gzip (.js,.css,etc) + StaticExtensionsToGzip []string + // http server configurations HttpAddr string HttpPort int HttpTLS bool HttpCertFile string HttpKeyFile string + // flag of auto recover panic RecoverPanic bool + // flag of render template automatically AutoRender bool ViewsPath string - RunMode string //"dev" or "prod" + // run mode, "dev" or "prod" + RunMode string AppConfig config.ConfigContainer - //related to session - GlobalSessions *session.Manager //GlobalSessions - SessionOn bool // whether auto start session,default is false - SessionProvider string // default session provider memory mysql redis - SessionName string // sessionName cookie's name - SessionGCMaxLifetime int64 // session's gc maxlifetime - SessionSavePath string // session savepath if use mysql/redis/file this set to the connectinfo + // global session mananger + GlobalSessions *session.Manager + // flag of starting session auto. default is false. + SessionOn bool + // default session provider, memory, mysql , redis ,etc. + SessionProvider string + // the cookie name when saving session id into cookie. + SessionName string + // session gc time for auto cleaning expired session. + SessionGCMaxLifetime int64 + // if use mysql/redis/file provider, define save path to connection info. + SessionSavePath string + // session hash generation func. SessionHashFunc string + // session hash salt string. SessionHashKey string + // the life time of session id in cookie. SessionCookieLifeTime int UseFcgi bool MaxMemory int64 - EnableGzip bool // enable gzip - DirectoryIndex bool //enable DirectoryIndex default is false - EnableHotUpdate bool //enable HotUpdate default is false - HttpServerTimeOut int64 //set httpserver timeout - ErrorsShow bool //set weather show errors - XSRFKEY string //set XSRF + // flag of enable gzip + EnableGzip bool + // flag of display directory index. default is false. + DirectoryIndex bool + // flag of hot update checking in app self. default is false. + EnableHotUpdate bool + HttpServerTimeOut int64 + // flag of show errors in page. if true, show error and trace info in page rendered with error template. + ErrorsShow bool + // xsrf hash salt string. + XSRFKEY string + // flag of enable xsrf. EnableXSRF bool + // the expiry of xsrf value. XSRFExpire int - CopyRequestBody bool //When in raw application, You want to the reqeustbody + // flag of copy raw request body in context. + CopyRequestBody bool TemplateLeft string TemplateRight string + // beego server name exported in response header. BeegoServerName string - EnableAdmin bool //enable admin module to log api time - AdminHttpAddr string //admin module http addr + // flag of enable admin module to log every request info. + EnableAdmin bool + // http server configurations for admin module. + AdminHttpAddr string AdminHttpPort int ) func init() { - // create beeapp + // create beego application BeeApp = NewApp() // initialize default configurations @@ -100,7 +127,7 @@ func init() { UseFcgi = false - MaxMemory = 1 << 26 //64MB + MaxMemory = 1<<26 //64MB EnableGzip = false @@ -135,7 +162,8 @@ func init() { } } -//parse config now only support ini, next will support json +// ParseConfig parsed default config file. +// now only support ini, next will support json. func ParseConfig() (err error) { AppConfig, err = config.NewConfig("ini", AppConfigPath) if err != nil { diff --git a/controller.go b/controller.go index f33d38dc..67f7abb8 100644 --- a/controller.go +++ b/controller.go @@ -25,9 +25,12 @@ import ( ) var ( + // custom error when user stop request handler manually. USERSTOPRUN = errors.New("User stop run") ) +// Controller defines some basic http request handler operations, such as +// http context, template and view, session and xsrf. type Controller struct { Ctx *context.Context Data map[interface{}]interface{} @@ -43,6 +46,7 @@ type Controller struct { AppController interface{} } +// ControllerInterface is an interface to uniform all controller handler. type ControllerInterface interface { Init(ct *context.Context, controllerName, actionName string, app interface{}) Prepare() @@ -59,6 +63,7 @@ type ControllerInterface interface { CheckXsrfCookie() bool } +// Init generates default values of controller operations. func (c *Controller) Init(ctx *context.Context, controllerName, actionName string, app interface{}) { c.Data = make(map[interface{}]interface{}) c.Layout = "" @@ -70,42 +75,52 @@ func (c *Controller) Init(ctx *context.Context, controllerName, actionName strin c.AppController = app } +// Prepare runs after Init before request function execution. func (c *Controller) Prepare() { } +// Finish runs after request function execution. func (c *Controller) Finish() { } +// Get adds a request function to handle GET request. func (c *Controller) Get() { http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405) } +// Post adds a request function to handle POST request. func (c *Controller) Post() { http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405) } +// Delete adds a request function to handle DELETE request. func (c *Controller) Delete() { http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405) } +// Put adds a request function to handle PUT request. func (c *Controller) Put() { http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405) } +// Head adds a request function to handle HEAD request. func (c *Controller) Head() { http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405) } +// Patch adds a request function to handle PATCH request. func (c *Controller) Patch() { http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405) } +// Options adds a request function to handle OPTIONS request. func (c *Controller) Options() { http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405) } +// Render sends the response with rendered template bytes as text/html type. func (c *Controller) Render() error { rb, err := c.RenderBytes() @@ -118,24 +133,26 @@ func (c *Controller) Render() error { return nil } +// RenderString returns the rendered template string. Do not send out response. func (c *Controller) RenderString() (string, error) { b, e := c.RenderBytes() return string(b), e } +// RenderBytes returns the bytes of renderd tempate string. Do not send out response. func (c *Controller) RenderBytes() ([]byte, error) { //if the controller has set layout, then first get the tplname's content set the content to the layout if c.Layout != "" { if c.TplNames == "" { - c.TplNames = strings.ToLower(c.controllerName) + "/" + strings.ToLower(c.actionName) + "." + c.TplExt + c.TplNames = strings.ToLower(c.controllerName)+"/"+strings.ToLower(c.actionName)+"." + c.TplExt } if RunMode == "dev" { BuildTemplate(ViewsPath) } newbytes := bytes.NewBufferString("") if _, ok := BeeTemplates[c.TplNames]; !ok { - panic("can't find templatefile in the path:" + c.TplNames) - return []byte{}, errors.New("can't find templatefile in the path:" + c.TplNames) + panic("can't find templatefile in the path:"+c.TplNames) + return []byte{}, errors.New("can't find templatefile in the path:"+c.TplNames) } err := BeeTemplates[c.TplNames].ExecuteTemplate(newbytes, c.TplNames, c.Data) if err != nil { @@ -154,15 +171,15 @@ func (c *Controller) RenderBytes() ([]byte, error) { return icontent, nil } else { if c.TplNames == "" { - c.TplNames = strings.ToLower(c.controllerName) + "/" + strings.ToLower(c.actionName) + "." + c.TplExt + c.TplNames = strings.ToLower(c.controllerName)+"/"+strings.ToLower(c.actionName)+"." + c.TplExt } if RunMode == "dev" { BuildTemplate(ViewsPath) } ibytes := bytes.NewBufferString("") if _, ok := BeeTemplates[c.TplNames]; !ok { - panic("can't find templatefile in the path:" + c.TplNames) - return []byte{}, errors.New("can't find templatefile in the path:" + c.TplNames) + panic("can't find templatefile in the path:"+c.TplNames) + return []byte{}, errors.New("can't find templatefile in the path:"+c.TplNames) } err := BeeTemplates[c.TplNames].ExecuteTemplate(ibytes, c.TplNames, c.Data) if err != nil { @@ -175,10 +192,12 @@ func (c *Controller) RenderBytes() ([]byte, error) { return []byte{}, nil } +// Redirect sends the redirection response to url with status code. func (c *Controller) Redirect(url string, code int) { c.Ctx.Redirect(code, url) } +// Aborts stops controller handler and show the error data if code is defined in ErrorMap or code string. func (c *Controller) Abort(code string) { status, err := strconv.Atoi(code) if err == nil { @@ -188,21 +207,26 @@ func (c *Controller) Abort(code string) { } } +// StopRun makes panic of USERSTOPRUN error and go to recover function if defined. func (c *Controller) StopRun() { panic(USERSTOPRUN) } +// UrlFor does another controller handler in this request function. +// it goes to this controller method if endpoint is not clear. func (c *Controller) UrlFor(endpoint string, values ...string) string { if len(endpoint) <= 0 { return "" } if endpoint[0] == '.' { - return UrlFor(reflect.Indirect(reflect.ValueOf(c.AppController)).Type().Name()+endpoint, values...) + return UrlFor(reflect.Indirect(reflect.ValueOf(c.AppController)).Type().Name() + endpoint, values...) } else { return UrlFor(endpoint, values...) } + return "" } +// ServeJson sends a json response with encoding charset. func (c *Controller) ServeJson(encoding ...bool) { var hasIndent bool var hasencoding bool @@ -217,6 +241,7 @@ func (c *Controller) ServeJson(encoding ...bool) { c.Ctx.Output.Json(c.Data["json"], hasIndent, hasencoding) } +// ServeJson sends a jsonp response. func (c *Controller) ServeJsonp() { var hasIndent bool if RunMode == "prod" { @@ -227,6 +252,7 @@ func (c *Controller) ServeJsonp() { c.Ctx.Output.Jsonp(c.Data["jsonp"], hasIndent) } +// ServeJson sends xml response. func (c *Controller) ServeXml() { var hasIndent bool if RunMode == "prod" { @@ -237,6 +263,7 @@ func (c *Controller) ServeXml() { c.Ctx.Output.Xml(c.Data["xml"], hasIndent) } +// Input returns the input data map from POST or PUT request body and query string. func (c *Controller) Input() url.Values { ct := c.Ctx.Request.Header.Get("Content-Type") if strings.Contains(ct, "multipart/form-data") { @@ -247,14 +274,18 @@ func (c *Controller) Input() url.Values { return c.Ctx.Request.Form } +// ParseForm maps input data map to obj struct. func (c *Controller) ParseForm(obj interface{}) error { return ParseForm(c.Input(), obj) } +// GetString returns the input value by key string. func (c *Controller) GetString(key string) string { return c.Input().Get(key) } +// GetStrings returns the input string slice by key string. +// it's designed for multi-value input field such as checkbox(input[type=checkbox]), multi-selection. func (c *Controller) GetStrings(key string) []string { r := c.Ctx.Request if r.Form == nil { @@ -267,29 +298,36 @@ func (c *Controller) GetStrings(key string) []string { return []string{} } +// GetInt returns input value as int64. func (c *Controller) GetInt(key string) (int64, error) { return strconv.ParseInt(c.Input().Get(key), 10, 64) } +// GetBool returns input value as bool. func (c *Controller) GetBool(key string) (bool, error) { return strconv.ParseBool(c.Input().Get(key)) } +// GetFloat returns input value as float64. func (c *Controller) GetFloat(key string) (float64, error) { return strconv.ParseFloat(c.Input().Get(key), 64) } +// GetFile returns the file data in file upload field named as key. +// it returns the first one of multi-uploaded files. func (c *Controller) GetFile(key string) (multipart.File, *multipart.FileHeader, error) { return c.Ctx.Request.FormFile(key) } +// SaveToFile saves uploaded file to new path. +// it only operates the first one of mutil-upload form file field. func (c *Controller) SaveToFile(fromfile, tofile string) error { file, _, err := c.Ctx.Request.FormFile(fromfile) if err != nil { return err } defer file.Close() - f, err := os.OpenFile(tofile, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0666) + f, err := os.OpenFile(tofile, os.O_WRONLY | os.O_CREATE | os.O_TRUNC, 0666) if err != nil { return err } @@ -298,6 +336,7 @@ func (c *Controller) SaveToFile(fromfile, tofile string) error { return nil } +// StartSession starts session and load old session data info this controller. func (c *Controller) StartSession() session.SessionStore { if c.CruSession == nil { c.CruSession = c.Ctx.Input.CruSession @@ -305,6 +344,7 @@ func (c *Controller) StartSession() session.SessionStore { return c.CruSession } +// SetSession puts value into session. func (c *Controller) SetSession(name interface{}, value interface{}) { if c.CruSession == nil { c.StartSession() @@ -312,6 +352,7 @@ func (c *Controller) SetSession(name interface{}, value interface{}) { c.CruSession.Set(name, value) } +// GetSession gets value from session. func (c *Controller) GetSession(name interface{}) interface{} { if c.CruSession == nil { c.StartSession() @@ -319,6 +360,7 @@ func (c *Controller) GetSession(name interface{}) interface{} { return c.CruSession.Get(name) } +// SetSession removes value from session. func (c *Controller) DelSession(name interface{}) { if c.CruSession == nil { c.StartSession() @@ -326,19 +368,24 @@ func (c *Controller) DelSession(name interface{}) { c.CruSession.Delete(name) } +// SessionRegenerateID regenerates session id for this session. +// the session data have no changes. func (c *Controller) SessionRegenerateID() { c.CruSession = GlobalSessions.SessionRegenerateId(c.Ctx.ResponseWriter, c.Ctx.Request) c.Ctx.Input.CruSession = c.CruSession } +// DestroySession cleans session data and session cookie. func (c *Controller) DestroySession() { GlobalSessions.SessionDestroy(c.Ctx.ResponseWriter, c.Ctx.Request) } +// IsAjax returns this request is ajax or not. func (c *Controller) IsAjax() bool { return c.Ctx.Input.IsAjax() } +// GetSecureCookie returns decoded cookie value from encoded browser cookie values. func (c *Controller) GetSecureCookie(Secret, key string) (string, bool) { val := c.Ctx.GetCookie(key) if val == "" { @@ -365,6 +412,7 @@ func (c *Controller) GetSecureCookie(Secret, key string) (string, bool) { return string(res), true } +// SetSecureCookie puts value into cookie after encoded the value. func (c *Controller) SetSecureCookie(Secret, name, val string, age int64) { vs := base64.URLEncoding.EncodeToString([]byte(val)) timestamp := strconv.FormatInt(time.Now().UnixNano(), 10) @@ -375,6 +423,7 @@ func (c *Controller) SetSecureCookie(Secret, name, val string, age int64) { c.Ctx.SetCookie(name, cookie, age, "/") } +// XsrfToken creates a xsrf token string and returns. func (c *Controller) XsrfToken() string { if c._xsrf_token == "" { token, ok := c.GetSecureCookie(XSRFKEY, "_xsrf") @@ -393,6 +442,9 @@ func (c *Controller) XsrfToken() string { return c._xsrf_token } +// CheckXsrfCookie checks xsrf token in this request is valid or not. +// the token can provided in request header "X-Xsrftoken" and "X-CsrfToken" +// or in form field value named as "_xsrf". func (c *Controller) CheckXsrfCookie() bool { token := c.GetString("_xsrf") if token == "" { @@ -409,16 +461,18 @@ func (c *Controller) CheckXsrfCookie() bool { return true } +// XsrfFormHtml writes an input field contains xsrf token value. func (c *Controller) XsrfFormHtml() string { return "" + c._xsrf_token + "\"/>" } +// GetControllerAndAction gets the executing controller name and action name. func (c *Controller) GetControllerAndAction() (controllerName, actionName string) { return c.controllerName, c.actionName } -//utils func for controller internal +// getRandomString returns random string. func getRandomString(n int) string { const alphanum = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" var bytes = make([]byte, n) diff --git a/filter.go b/filter.go index 05e5fd49..7e0245a6 100644 --- a/filter.go +++ b/filter.go @@ -5,6 +5,8 @@ import ( "strings" ) +// FilterRouter defines filter operation before controller handler execution. +// it can match patterned url and do filter function when action arrives. type FilterRouter struct { pattern string regex *regexp.Regexp @@ -14,6 +16,8 @@ type FilterRouter struct { parseParams map[string]string } +// ValidRouter check current request is valid for this filter. +// if matched, returns parsed params in this request by defined filter router pattern. func (mr *FilterRouter) ValidRouter(router string) (bool, map[string]string) { if mr.pattern == "" { return true, nil diff --git a/flash.go b/flash.go index 5a670176..f435c155 100644 --- a/flash.go +++ b/flash.go @@ -6,18 +6,22 @@ import ( "strings" ) +// the separation string when encoding flash data. const BEEGO_FLASH_SEP = "#BEEGOFLASH#" +// FlashData is a tools to maintain data when using across request. type FlashData struct { Data map[string]string } +// NewFlash return a new empty FlashData struct. func NewFlash() *FlashData { return &FlashData{ Data: make(map[string]string), } } +// Notice writes notice message to flash. func (fd *FlashData) Notice(msg string, args ...interface{}) { if len(args) == 0 { fd.Data["notice"] = msg @@ -26,6 +30,7 @@ func (fd *FlashData) Notice(msg string, args ...interface{}) { } } +// Warning writes warning message to flash. func (fd *FlashData) Warning(msg string, args ...interface{}) { if len(args) == 0 { fd.Data["warning"] = msg @@ -34,6 +39,7 @@ func (fd *FlashData) Warning(msg string, args ...interface{}) { } } +// Error writes error message to flash. func (fd *FlashData) Error(msg string, args ...interface{}) { if len(args) == 0 { fd.Data["error"] = msg @@ -42,6 +48,8 @@ func (fd *FlashData) Error(msg string, args ...interface{}) { } } +// Store does the saving operation of flash data. +// the data are encoded and saved in cookie. func (fd *FlashData) Store(c *Controller) { c.Data["flash"] = fd.Data var flashValue string @@ -51,6 +59,7 @@ func (fd *FlashData) Store(c *Controller) { c.Ctx.SetCookie("BEEGO_FLASH", url.QueryEscape(flashValue), 0, "/") } +// ReadFromRequest parsed flash data from encoded values in cookie. func ReadFromRequest(c *Controller) *FlashData { flash := &FlashData{ Data: make(map[string]string),