diff --git a/README.md b/README.md index 37b9abbf..a25a24d9 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ [Language]: http://golang.org [Platform Widget]: https://img.shields.io/badge/platform-Any--OS-gray.svg?style=flat-square +Iris is 3 months baby which has succeeded to be the fastest go web framework that exists, so far, while providing a robust set of features for building web applications. + +- [why v3 has 1 commit ?](https://github.com/kataras/iris/issues/162) + [![Benchmark Wizzard Processing Time Horizontal Graph](https://raw.githubusercontent.com/iris-contrib/website/cf71811e6acb2f9bf1e715e25660392bf090b923/assets/benchmark_horizontal_transparent.png)](#benchmarks) ```sh diff --git a/bindings/form.go b/bindings/form.go index 8e8a6bab..0eddffa2 100644 --- a/bindings/form.go +++ b/bindings/form.go @@ -1,6 +1,4 @@ -/* - File bindings/form.go source code from https://github.com/monoculum/formame. -*/ +// Package bindings source code from https://github.com/monoculum/formame. package bindings import ( diff --git a/config/basicauth.go b/config/basicauth.go index 50f710bc..dc0a7103 100644 --- a/config/basicauth.go +++ b/config/basicauth.go @@ -7,10 +7,14 @@ import ( ) const ( - DefaultBasicAuthRealm = "Authorization Required" + // DefaultBasicAuth is "Authorization Required" + DefaultBasicAuthRealm = "Authorization Required" + // DefaultBasicAuthContextKey is the "auth" + // this key is used to do context.Set("auth", theUsernameFromBasicAuth) DefaultBasicAuthContextKey = "auth" ) +// BasicAuth the configs for the basicauth middleware type BasicAuth struct { // Users a map of login and the value (username/password) Users map[string]string @@ -27,7 +31,7 @@ func DefaultBasicAuth() BasicAuth { return BasicAuth{make(map[string]string), DefaultBasicAuthRealm, DefaultBasicAuthContextKey, 0} } -// Merge MergeSingle the default with the given config and returns the result +// MergeSingle merges the default with the given config and returns the result func (c BasicAuth) MergeSingle(cfg BasicAuth) (config BasicAuth) { config = cfg diff --git a/config/render.go b/config/render.go index bc3698a3..6b45ed63 100644 --- a/config/render.go +++ b/config/render.go @@ -8,16 +8,28 @@ import ( ) const ( - NoEngine EngineType = -1 - HTMLEngine EngineType = 0 - PongoEngine EngineType = 1 + // NoEngine is a Template's config for engine type + // when use this, the templates are disabled + NoEngine EngineType = -1 + // HTMLEngine is a Template's config for engine type + // when use this, the templates are html/template + HTMLEngine EngineType = 0 + // PongoEngine is a Template's config for engine type + // when use this, the templates are flosch/pongo2 + PongoEngine EngineType = 1 + // MarkdownEngine is a Template's config for engine type + // when use this, the templates are .md files MarkdownEngine EngineType = 2 - JadeEngine EngineType = 3 - AmberEngine EngineType = 4 - + // JadeEngine is a Template's config for engine type + // when use this, the templates are joker/jade + JadeEngine EngineType = 3 + // AmberEngine is a Template's config for engine type + // when use this, the templates are eknkc/amber + AmberEngine EngineType = 4 + // DefaultEngine is the HTMLEngine DefaultEngine EngineType = HTMLEngine - // to disable layout for a particular file + // NoLayout to disable layout for a particular template file NoLayout = "@.|.@iris_no_layout@.|.@" ) @@ -51,42 +63,71 @@ type ( MarkdownSanitize bool } + // EngineType is the type of template engine EngineType int8 + // Template the configs for templates (template/view engines) + // contains common configs for all template engines Template struct { - // contains common configs for both HTMLTemplate & Pongo + // Engine the type of template engine + // default is DefaultEngine (HTMLEngine) Engine EngineType - Gzip bool + // Gzip enable gzip compression + // default is false + Gzip bool // Minify minifies the html result, // Note: according to this https://github.com/tdewolff/minify/issues/35, also it removes some when minify on writer, remove this from Iris until fix. // Default is false //Minify bool - IsDevelopment bool - Directory string - Extensions []string - ContentType string - Charset string - Asset func(name string) ([]byte, error) - AssetNames func() []string - Layout string - HTMLTemplate HTMLTemplate // contains specific configs for HTMLTemplate standard html/template - Pongo Pongo // contains specific configs for pongo2 - // Markdown template engine it doesn't supports Layout & binding context - Markdown Markdown // contains specific configs for markdown - Jade Jade // contains specific configs for Jade - Amber Amber // contains specific configs for Amber + // IsDevelopment re-builds the templates on each request + // default is false + IsDevelopment bool + // Directory the system path which the templates live + // default is ./templates + Directory string + // Extensions the allowed file extension + // default is []string{".html"} + Extensions []string + // ContentType is the Content-Type response header + // default is text/html but you can change if if needed + ContentType string + // Charset the charset, default is UTF-8 + Charset string + // Asset is a func which returns bytes, use it to load the templates by binary + Asset func(name string) ([]byte, error) + // AssetNames should returns the template filenames, look Asset + AssetNames func() []string + // Layout the template file ( with its extension) which is the mother of all + // use it to have it as a root file, and include others with {{ yield }}, refer the docs + Layout string + + // HTMLTemplate contains specific configs for HTMLTemplate standard html/template + HTMLTemplate HTMLTemplate + // Pongo contains specific configs for for pongo2 + Pongo Pongo + // Markdown contains specific configs for for markdown + // this doesn't supports Layout & binding context + Markdown Markdown + // Jade contains specific configs for jade + Jade Jade + // Amber contains specific configs for amber + Amber Amber } + // HTMLTemplate the configs for HTMLEngine HTMLTemplate struct { + // RequirePartials default is false RequirePartials bool // Delims - Left string + // Left delimeter, default is {{ + Left string + // Right delimeter, default is }} Right string // Funcs for HTMLTemplate html/template Funcs template.FuncMap } - + // Pongo the configs for PongoEngine Pongo struct { // Filters for pongo2, map[name of the filter] the filter function . The filters are auto register Filters map[string]pongo2.FilterFunction @@ -94,15 +135,18 @@ type ( Globals map[string]interface{} } + // Markdown the configs for MarkdownEngine Markdown struct { Sanitize bool // if true then returns safe html, default is false } + // Jade the configs for JadeEngine // Jade empty for now // stay tuned Jade struct { } + // Amber the configs for AmberEngine Amber struct { // Funcs for the html/template result, amber default funcs are not overrided so use it without worries Funcs template.FuncMap @@ -147,6 +191,7 @@ func (c Rest) MergeSingle(cfg Rest) (config Rest) { return } +// DefaultTemplate returns the default template configs func DefaultTemplate() Template { return Template{ Engine: DefaultEngine, //or HTMLTemplate diff --git a/config/typescript.go b/config/typescript.go index c6d95ff9..4b4717f3 100644 --- a/config/typescript.go +++ b/config/typescript.go @@ -68,12 +68,19 @@ type ( NoImplicitUseStrict bool `json:"noImplicitUseStrict"` } + // Typescript the configs for the Typescript plugin Typescript struct { - Bin string - Dir string - Ignore string + // Bin the path of the tsc binary file + // if empty then the plugin tries to find it + Bin string + // Dir the client side directory, which typescript (.ts) files are live + Dir string + // Ignore ignore folders, default is /node_modules/ + Ignore string + // Tsconfig the typescript build configs, including the compiler's options Tsconfig Tsconfig - Editor Editor + // Editor the Editor plugin + Editor Editor } ) diff --git a/context.go b/context.go index cf323ba0..12f53499 100644 --- a/context.go +++ b/context.go @@ -42,6 +42,7 @@ const ( ) type ( + // Map is just a conversion for a map[string]interface{} Map map[string]interface{} // Context is resetting every time a request is coming to the server // it is not good practice to use this object in goroutines, for these cases use the .Clone() diff --git a/context_request.go b/context_request.go index 38c3d41a..617aad14 100644 --- a/context_request.go +++ b/context_request.go @@ -95,12 +95,12 @@ func (ctx *Context) PostFormValue(name string) string { return string(ctx.RequestCtx.PostArgs().Peek(name)) } -/* Credits to Manish Singh @kryptodev for URLEncode */ // URLEncode returns the path encoded as url // useful when you want to pass something to a database and be valid to retrieve it via context.Param // use it only for special cases, when the default behavior doesn't suits you. // // http://www.blooberry.com/indexdot/html/topics/urlencoding.htm +/* Credits to Manish Singh @kryptodev for URLEncode */ func URLEncode(path string) string { if path == "" { return "" diff --git a/context_storage.go b/context_storage.go index 11902f35..e272f44a 100644 --- a/context_storage.go +++ b/context_storage.go @@ -134,7 +134,7 @@ func (ctx *Context) SetFlashBytes(key string, value []byte) { fasthttp.ReleaseCookie(c) } -// Sessionreturns the current session store, returns nil if provider is "" +// Session returns the current session store, returns nil if provider is "" func (ctx *Context) Session() store.IStore { if ctx.station.sessionManager == nil || ctx.station.config.Sessions.Provider == "" { //the second check can be changed on runtime, users are able to turn off the sessions by setting provider to "" return nil diff --git a/errors.go b/errors.go index 793d6cfc..25d5bccb 100644 --- a/errors.go +++ b/errors.go @@ -9,9 +9,11 @@ var ( // It seems to be a +type Points to: +pointer.' ErrHandler = errors.New("Passed argument is not func(*Context) neither an object which implements the iris.Handler with Serve(ctx *Context)\n It seems to be a %T Points to: %v.") // ErrHandleAnnotated returns an error with message: 'HandleAnnotated parse: +specific error(s)' - ErrHandleAnnotated = errors.New("HandleAnnotated parse: %s") + ErrHandleAnnotated = errors.New("HandleAnnotated parse: %s") + // ErrControllerContextNotFound returns an error with message: 'Context *iris.Context could not be found, the Controller won't be registed.' ErrControllerContextNotFound = errors.New("Context *iris.Context could not be found, the Controller won't be registed.") - ErrDirectoryFileNotFound = errors.New("Directory or file %s couldn't found. Trace: %s") + // ErrDirectoryFileNotFound returns an errir with message: 'Directory or file %s couldn't found. Trace: +error trace' + ErrDirectoryFileNotFound = errors.New("Directory or file %s couldn't found. Trace: %s") // Plugin // ErrPluginAlreadyExists returns an error with message: 'Cannot activate the same plugin again, plugin '+plugin name[+plugin description]' is already exists' diff --git a/iris.go b/iris.go index 9dc1864d..6da1433c 100644 --- a/iris.go +++ b/iris.go @@ -19,7 +19,9 @@ import ( "github.com/kataras/iris/render/template" "github.com/kataras/iris/server" "github.com/kataras/iris/sessions" + // memory loads the memory session provider _ "github.com/kataras/iris/sessions/providers/memory" + // _ redis loads the redis session provider _ "github.com/kataras/iris/sessions/providers/redis" "github.com/kataras/iris/utils" "github.com/kataras/iris/websocket" @@ -27,6 +29,7 @@ import ( ) const ( + // Version of the iris Version = "v3.0.0-beta" banner = ` _____ _ |_ _| (_) @@ -41,14 +44,21 @@ const ( /* for conversion */ var ( - HTMLEngine = config.HTMLEngine - PongoEngine = config.PongoEngine + // HTMLEngine conversion for config.HTMLEngine + HTMLEngine = config.HTMLEngine + // PongoEngine conversion for config.PongoEngine + PongoEngine = config.PongoEngine + // MarkdownEngine conversion for config.MarkdownEngine MarkdownEngine = config.MarkdownEngine - JadeEngine = config.JadeEngine - AmberEngine = config.AmberEngine + // JadeEngine conversion for config.JadeEngine + JadeEngine = config.JadeEngine + // AmberEngine conversion for config.AmberEngine + AmberEngine = config.AmberEngine + // DefaultEngine conversion for config.DefaultEngine DefaultEngine = config.DefaultEngine - NoEngine = config.NoEngine + // NoEngine conversion for config.NoEngine + NoEngine = config.NoEngine // NoLayout = config.NoLayout @@ -104,7 +114,7 @@ func (s *Iris) newContextPool() sync.Pool { } func (s *Iris) initTemplates() { - if s.templates == nil { // because if .Templates() called before server's listen, s.templates != nil + if s.templates == nil { // because if .Templates() called before server's listen, s.templates != nil when PreListen // init the templates s.templates = template.New(s.config.Render.Template) } @@ -295,7 +305,7 @@ func (s *Iris) Logger() *logger.Logger { return s.logger } -// Render returns the rest render +// Rest returns the rest render func (s *Iris) Rest() *rest.Render { return s.rest } diff --git a/iris/main.go b/iris/main.go index d962338c..351af0c4 100644 --- a/iris/main.go +++ b/iris/main.go @@ -14,13 +14,17 @@ import ( ) const ( - PackagesURL = "https://github.com/iris-contrib/iris-command-assets/archive/master.zip" + // PackagesURL the url to download all the packages + PackagesURL = "https://github.com/iris-contrib/iris-command-assets/archive/master.zip" + // PackagesExportedName the folder created after unzip PackagesExportedName = "iris-command-assets-master" ) var ( - app *cli.App - SuccessPrint = color.New(color.FgGreen).Add(color.Bold).PrintfFunc() + app *cli.App + // SuccessPrint prints with a green color + SuccessPrint = color.New(color.FgGreen).Add(color.Bold).PrintfFunc() + // InfoPrint prints with the cyan color InfoPrint = color.New(color.FgHiCyan).Add(color.Bold).PrintfFunc() packagesInstallDir = os.Getenv("GOPATH") + utils.PathSeparator + "src" + utils.PathSeparator + "github.com" + utils.PathSeparator + "kataras" + utils.PathSeparator + "iris" + utils.PathSeparator + "iris" + utils.PathSeparator packagesDir = packagesInstallDir + PackagesExportedName + utils.PathSeparator @@ -63,15 +67,15 @@ func create(flags cli.Flags) (err error) { } func downloadPackages() { - _, err := utils.Install("https://github.com/iris-contrib/iris-command-assets/archive/master.zip", packagesInstallDir) + _, err := utils.Install(PackagesURL, packagesInstallDir) if err != nil { app.Printf("\nProblem while downloading the assets from the internet for the first time. Trace: %s", err.Error()) } } func createPackage(packageName string, targetDir string) error { - basicDir := packagesDir + packageName - err := utils.CopyDir(basicDir, targetDir) + packageDir := packagesDir + packageName + err := utils.CopyDir(packageDir, targetDir) if err != nil { app.Printf("\nProblem while copying the %s package to the %s. Trace: %s", packageName, targetDir, err.Error()) return err @@ -79,7 +83,7 @@ func createPackage(packageName string, targetDir string) error { InfoPrint("\n%s package was installed successfully", packageName) - //run the server + // build & run the server // go build buildCmd := utils.CommandBuilder("go", "build") @@ -94,7 +98,8 @@ func createPackage(packageName string, targetDir string) error { } buildCmd.Wait() println("\n") - // run backend/backend.exe + + // run backend/backend(.exe) executable := "backend" if runtime.GOOS == "windows" { diff --git a/middleware/cors/cors.go b/middleware/cors/cors.go index cfc9678e..91fb5020 100644 --- a/middleware/cors/cors.go +++ b/middleware/cors/cors.go @@ -221,10 +221,12 @@ func DefaultCors() *Cors { return Default() } +// Conflicts used by the router optimizer func (c *Cors) Conflicts() string { return "httpmethod" } +// Serve serves the middleware func (c *Cors) Serve(ctx *iris.Context) { if ctx.MethodString() == "OPTIONS" { c.logf("Serve: Preflight request") diff --git a/middleware/logger/logger.go b/middleware/logger/logger.go index fa6c3bad..be4f43dc 100644 --- a/middleware/logger/logger.go +++ b/middleware/logger/logger.go @@ -1,11 +1,12 @@ package logger import ( + "strconv" + "time" + "github.com/kataras/iris" "github.com/kataras/iris/config" "github.com/kataras/iris/logger" - "strconv" - "time" ) // Options are the options of the logger middlweare @@ -13,11 +14,16 @@ import ( // Latency, Status, IP, Method, Path // if set to true then these will print type Options struct { + // Latency displays latency (bool) Latency bool - Status bool - IP bool - Method bool - Path bool + // Status displays status code (bool) + Status bool + // IP displays request's remote address (bool) + IP bool + // Method displays the http method (bool) + Method bool + // Path displays the request path (bool) + Path bool } // DefaultOptions returns an options which all properties are true @@ -30,7 +36,7 @@ type loggerMiddleware struct { options Options } -// a poor and ugly implementation of a logger but no need to worry about this at the moment +// Serve serves the middleware func (l *loggerMiddleware) Serve(ctx *iris.Context) { //all except latency to string var date, status, ip, method, path string diff --git a/render/template/engine/html/html.go b/render/template/engine/html/html.go index 99e30319..a875bfb9 100644 --- a/render/template/engine/html/html.go +++ b/render/template/engine/html/html.go @@ -49,6 +49,7 @@ func New(c config.Template) *Engine { return &Engine{Config: &c} } +// BuildTemplates builds the templates func (s *Engine) BuildTemplates() error { if s.Config.Asset == nil || s.Config.AssetNames == nil { @@ -218,6 +219,7 @@ func (s *Engine) layoutFuncsFor(name string, binding interface{}) { } } +// ExecuteWriter executes a templates and write its results to the out writer func (s *Engine) ExecuteWriter(out io.Writer, name string, binding interface{}, layout string) error { if layout != "" && layout != config.NoLayout { s.layoutFuncsFor(name, binding) diff --git a/render/template/engine/jade/jade.go b/render/template/engine/jade/jade.go index e8bc3c50..362a7f51 100644 --- a/render/template/engine/jade/jade.go +++ b/render/template/engine/jade/jade.go @@ -6,10 +6,12 @@ import ( "github.com/kataras/iris/render/template/engine/html" ) +// Engine the JadeEngine type Engine struct { *html.Engine } +// new creates and returns a new JadeEngine with its configs func New(cfg config.Template) *Engine { underline := &Engine{Engine: html.New(cfg)} diff --git a/render/template/template.go b/render/template/template.go index ee0e2a5c..719837d8 100644 --- a/render/template/template.go +++ b/render/template/template.go @@ -19,17 +19,37 @@ import ( ) type ( + // Engine the interface that all template engines must inheritance Engine interface { + // BuildTemplates builds the templates for a directory BuildTemplates() error + // ExecuteWriter finds and execute a template and write its result to the out writer ExecuteWriter(out io.Writer, name string, binding interface{}, layout string) error } + // Template the internal configs for the common configs for the template engines Template struct { - Engine Engine - IsDevelopment bool - Gzip bool - ContentType string - Layout string + // Engine the type of the Engine + Engine Engine + // Gzip enable gzip compression + // default is false + Gzip bool + // IsDevelopment re-builds the templates on each request + // default is false + IsDevelopment bool + // Directory the system path which the templates live + // default is ./templates + Directory string + // Extensions the allowed file extension + // default is []string{".html"} + Extensions []string + // ContentType is the Content-Type response header + // default is text/html but you can change if if needed + ContentType string + // Layout the template file ( with its extension) which is the mother of all + // use it to have it as a root file, and include others with {{ yield }}, refer the docs + Layout string + buffer *utils.BufferPool // this is used only for RenderString gzipWriterPool sync.Pool } @@ -77,6 +97,7 @@ func New(c config.Template) *Template { } +// Render renders a template using the context's writer func (t *Template) Render(ctx context.IContext, name string, binding interface{}, layout ...string) (err error) { if t == nil { // No engine was given but .Render was called @@ -120,6 +141,7 @@ func (t *Template) Render(ctx context.IContext, name string, binding interface{} return } +// RenderString executes a template and returns its contents result (string) func (t *Template) RenderString(name string, binding interface{}, layout ...string) (result string, err error) { if t == nil { // No engine was given but .Render was called diff --git a/sessions/providers/memory/register.go b/sessions/providers/memory/register.go index dce2b6a4..ba61e718 100644 --- a/sessions/providers/memory/register.go +++ b/sessions/providers/memory/register.go @@ -12,6 +12,7 @@ func init() { } var ( + // Provider the memory provider Provider = sessions.NewProvider("memory") ) diff --git a/utils/file.go b/utils/file.go index 843f632c..64b85e07 100644 --- a/utils/file.go +++ b/utils/file.go @@ -202,8 +202,7 @@ func CopyFile(source string, destination string) error { return nil } -// CopyDir -// Recursively copies a directory tree, attempting to preserve permissions. +// CopyDir recursively copies a directory tree, attempting to preserve permissions. // Source directory must exist. // // Note: the CopyDir function was not written by me, but its working well