iris/doc.go

// Copyright (c) 2016-2017 Gerasimos Maropoulos
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.

// Package iris provides efficient and well-designed toolbox with robust set of features to
// create your own perfect high performance web application
// with unlimited portability using the Go Programming Language.
//
// Note: This package is under active development status.
// Each month a new version is releasing
// to adapt the latest web trends and technologies.
//
//
// Basic HTTP API
//
//
// Iris is a very pluggable ecosystem,
// router can be customized by adapting a 'RouterBuilderPolicy && RouterReversionPolicy'.
//
// With the power of Iris' router adaptors, developers are able to use any
// third-party router's path features without any implications to the rest
// of their API.
//
// A Developer is able to select between two out-of-the-box powerful routers:
//
// Httprouter, it's a custom version of https://github.comjulienschmidt/httprouter,
// which is edited to support iris' subdomains, reverse routing, custom http errors and a lot features,
// it should be a bit faster than the original too because of iris' Context.
// It uses `/mypath/:firstParameter/path/:secondParameter` and `/mypath/*wildcardParamName` .
//
// Gorilla Mux, it's the https://github.com/gorilla/mux which supports subdomains,
// custom http errors, reverse routing, pattern matching via regex and the rest of the iris' features.
// It uses `/mypath/{firstParameter:any-regex-valid-here}/path/{secondParameter}` and `/mypath/{wildcardParamName:.*}`
//
//
// Example code:
//
//
//       package main
//
//       import (
//       	"gopkg.in/kataras/iris.v6"
//       	"gopkg.in/kataras/iris.v6/adaptors/httprouter" // <--- or adaptors/gorillamux
//       )
//
//       func main() {
//       	app := iris.New()
//       	app.Adapt(httprouter.New()) // <--- or gorillamux.New()
//
//       	// HTTP Method: GET
//       	// PATH: http://127.0.0.1/
//       	// Handler(s): index
//       	app.Get("/", index)
//
//       	app.Listen(":80")
//       }
//
//       func index(ctx *iris.Context) {
//       	ctx.HTML(iris.StatusOK, "<h1> Welcome to my page!</h1>")
//       }
//
//
//
// All HTTP methods are supported, users can register handlers for same paths on different methods.
// The first parameter is the HTTP Method,
// second parameter is the request path of the route,
// third variadic parameter should contains one or more iris.Handler/HandlerFunc executed
// by the registered order when a user requests for that specific resouce path from the server.
//
// Example code:
//
//
//         app := iris.New()
//
//         app.Handle("GET", "/about", aboutHandler)
//
//         type aboutHandler struct {}
//         func (a aboutHandler) Serve(ctx *iris.Context){
//           ctx.HTML("Hello from /about, executed from an iris.Handler")
//         }
//
//         app.HandleFunc("GET", "/contact", func(ctx *iris.Context){
//           ctx.HTML(iris.StatusOK, "Hello from /contact, executed from an iris.HandlerFunc")
//         })
//
//
// In order to make things easier for the user, Iris provides functions for all HTTP Methods.
// The first parameter is the request path of the route,
// second variadic parameter should contains one or more iris.HandlerFunc executed
// by the registered order when a user requests for that specific resouce path from the server.
//
// Example code:
//
//
//       app := iris.New()
//
//       // Method: "GET"
//       app.Get("/", handler)
//
//       // Method: "POST"
//       app.Post("/", handler)
//
//       // Method: "PUT"
//       app.Put("/", handler)
//
//       // Method: "DELETE"
//       app.Delete("/", handler)
//
//       // Method: "OPTIONS"
//       app.Options("/", handler)
//
//       // Method: "TRACE"
//       app.Trace("/", handler)
//
//       // Method: "CONNECT"
//       app.Connect("/", handler)
//
//       // Method: "HEAD"
//       app.Head("/", handler)
//
//       // Method: "PATCH"
//       app.Patch("/", handler)
//
//       // register the route for all HTTP Methods
//       app.Any("/", handler)
//
//       func handler(ctx *iris.Context){
//         ctx.Writef("Hello from method: %s and path: %s", ctx.Method(), ctx.Path())
//       }
//
//
// Parameterized route's Path, depends on the selected router.
//
// Note: This is the only difference between the routers, the registered path form, the API remains the same for both.
//
// Example `gorillamux` code:
//
//
//       package main
//
//       import (
//       	"gopkg.in/kataras/iris.v6"
//       	"gopkg.in/kataras/iris.v6/adaptors/gorillamux"
//       )
//
//       func main() {
//       	app := iris.New()
//       	app.Adapt(iris.DevLogger())
//       	app.Adapt(gorillamux.New())
//
//       	app.OnError(iris.StatusNotFound, func(ctx *iris.Context) {
//       		ctx.HTML(iris.StatusNotFound, "<h1> custom http error page </h1>")
//       	})
//
//       	app.Get("/healthcheck", h)
//
//       	gamesMiddleware := func(ctx *iris.Context) {
//       		println(ctx.Method() + ": " + ctx.Path())
//       		ctx.Next()
//       	}
//
//       	games := app.Party("/games", gamesMiddleware)
//       	{ // braces are optional of course, it's just a style of code
//       		games.Get("/{gameID:[0-9]+}/clans", h)
//       		games.Get("/{gameID:[0-9]+}/clans/clan/{publicID:[0-9]+}", h)
//       		games.Get("/{gameID:[0-9]+}/clans/search", h)
//
//       		games.Put("/{gameID:[0-9]+}/players/{publicID:[0-9]+}", h)
//       		games.Put("/{gameID:[0-9]+}/clans/clan/{publicID:[0-9]+}", h)
//
//       		games.Post("/{gameID:[0-9]+}/clans", h)
//       		games.Post("/{gameID:[0-9]+}/players", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{publicID:[0-9]+}/leave", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{clanPublicID:[0-9]+}/memberships/application", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{clanPublicID:[0-9]+}/memberships/application/:action", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{clanPublicID:[0-9]+}/memberships/invitation", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{clanPublicID:[0-9]+}/memberships/invitation/:action", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{clanPublicID:[0-9]+}/memberships/delete", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{clanPublicID:[0-9]+}/memberships/promote", h)
//       		games.Post("/{gameID:[0-9]+}/clans/{clanPublicID:[0-9]+}/memberships/demote", h)
//       	}
//
//       	app.Get("/anything/{anythingparameter:.*}", func(ctx *iris.Context) {
//       		s := ctx.Param("anythingparameter")
//       		ctx.Writef("The path after /anything is: %s", s)
//       	})
//
//       	p := app.Party("mysubdomain.")
//       	// http://mysubdomain.myhost.com/
//       	p.Get("/", h)
//
//       	app.Listen("myhost.com:80")
//       }
//
//       func h(ctx *iris.Context) {
//       	ctx.HTML(iris.StatusOK, "<h1>Path<h1/>"+ctx.Path())
//       }
//
//
//
// Example `httprouter` code:
//
//
//       package main
//
//       import (
//         "gopkg.in/kataras/iris.v6"
//         "gopkg.in/kataras/iris.v6/adaptors/httprouter" // <---- NEW
//       )
//
//       func main() {
//         app := iris.New()
//         app.Adapt(iris.DevLogger())
//         app.Adapt(httprouter.New()) // <---- NEW
//
//
//         app.OnError(iris.StatusNotFound, func(ctx *iris.Context){
//           ctx.HTML(iris.StatusNotFound, "<h1> custom http error page </h1>")
//         })
//
//
//         app.Get("/healthcheck", h)
//
//         gamesMiddleware := func(ctx *iris.Context) {
//           println(ctx.Method() + ": " + ctx.Path())
//           ctx.Next()
//         }
//
//         games:= app.Party("/games", gamesMiddleware)
//         { // braces are optional of course, it's just a style of code
//         	 games.Get("/:gameID/clans", h)
//         	 games.Get("/:gameID/clans/clan/:publicID", h)
//         	 games.Get("/:gameID/clans/search", h)
//
//         	 games.Put("/:gameID/players/:publicID", h)
//         	 games.Put("/:gameID/clans/clan/:publicID", h)
//
//         	 games.Post("/:gameID/clans", h)
//         	 games.Post("/:gameID/players", h)
//         	 games.Post("/:gameID/clans/:publicID/leave", h)
//         	 games.Post("/:gameID/clans/:clanPublicID/memberships/application", h)
//         	 games.Post("/:gameID/clans/:clanPublicID/memberships/application/:action", h)
//         	 games.Post("/:gameID/clans/:clanPublicID/memberships/invitation", h)
//         	 games.Post("/:gameID/clans/:clanPublicID/memberships/invitation/:action", h)
//         	 games.Post("/:gameID/clans/:clanPublicID/memberships/delete", h)
//         	 games.Post("/:gameID/clans/:clanPublicID/memberships/promote", h)
//         	 games.Post("/:gameID/clans/:clanPublicID/memberships/demote", h)
//         }
//
//         app.Get("/anything/*anythingparameter", func(ctx *iris.Context){
//           s := ctx.Param("anythingparameter")
//           ctx.Writef("The path after /anything is: %s",s)
//         })
//
//         mysubdomain:= app.Party("mysubdomain.")
//         // http://mysubdomain.myhost.com/
//         mysudomain.Get("/", h)
//
//         app.Listen("myhost.com:80")
//       }
//
//       func h(ctx *iris.Context) {
//       	ctx.HTML(iris.StatusOK, "<h1>Path<h1/>"+ctx.Path())
//       }
//
// Grouping routes that can (optionally) share the same middleware handlers, template layout and path prefix.
//
// Example code:
//
//
//       users:= app.Party("/users", myAuthHandler)
//
//       // http://myhost.com/users/42/profile
//       users.Get("/:userid/profile", userProfileHandler) // httprouter path parameters
//       // http://myhost.com/users/messages/1
//       users.Get("/inbox/:messageid", userMessageHandler)
//
//       app.Listen("myhost.com:80")
//
//
// Custom HTTP Errors page
//
// With iris users are able to register their own handlers for http statuses like 404 not found, 500 internal server error and so on.
//
// Example code:
//
//       // when 404 then render the template $templatedir/errors/404.html
//       // *read below for information about the view engine.*
//       app.OnError(iris.StatusNotFound, func(ctx *iris.Context){
//         ctx.RenderWithstatus(iris.StatusNotFound, "errors/404.html", nil)
//       })
//
//       app.OnError(500, func(ctx *iris.Context){
//         // ...
//       })
//
//
// Custom http errors can be also be registered to a specific group of routes.
//
// Example code:
//
//
//       games:= app.Party("/games", gamesMiddleware)
//       {
//           games.Get("/{gameID:[0-9]+}/clans", h) // gorillamux path parameters
//           games.Get("/{gameID:[0-9]+}/clans/clan/{publicID:[0-9]+}", h)
//           games.Get("/{gameID:[0-9]+}/clans/search", h)
//       }
//
//       games.OnError(iris.StatusNotFound, gamesNotFoundHandler)
//
//
// Middleware ecosystem.
//
// Middleware is just a concept of ordered chain of handlers.
// Middleware can be registered globally, per-party, per-subdomain and per-route.
//
//
// Example code:
//
//       // globally
//       // before any routes, appends the middleware to all routes
//       app.UseFunc(func(ctx *iris.Context){
//          // ... any code here
//
//          ctx.Next() // in order to continue to the next handler,
//          // if that is missing then the next in chain handlers will be not executed,
//          // useful for authentication middleware
//       })
//
//       // globally
//       // after or before any routes, prepends the middleware to all routes
//       app.UseGlobalFunc(handlerFunc1, handlerFunc2, handlerFunc3)
//
//       // per-route
//       app.Post("/login", authenticationHandler, loginPageHandler)
//
//       // per-party(group of routes)
//       users := app.Party("/users", usersMiddleware)
//       users.Get("/", usersIndex)
//
//       // per-subdomain
//       mysubdomain := app.Party("mysubdomain.", firstMiddleware)
//       mysubdomain.UseFunc(secondMiddleware)
//       mysubdomain.Get("/", mysubdomainIndex)
//
//       // per wildcard, dynamic subdomain
//       dynamicSub := app.Party(".*", firstMiddleware, secondMiddleware)
//       dynamicSub.Get("/", func(ctx *iris.Context){
//         ctx.Writef("Hello from subdomain: "+ ctx.Subdomain())
//       })
//
//
// `iris.ToHandler` converts(by wrapping) any `http.Handler/HandlerFunc` or
// `func(w http.ResponseWriter,r *http.Request, next http.HandlerFunc)` to an `iris.HandlerFunc`.
//
// iris.ToHandler(nativeNethttpHandler)
//
// Let's convert the https://github.com/rs/cors net/http external middleware which returns a `next form` handler.
//
//
// Example code:
//
//       package main
//
//       import (
//       	"github.com/rs/cors"
//       	"gopkg.in/kataras/iris.v6"
//       	"gopkg.in/kataras/iris.v6/adaptors/gorillamux"
//       )
//
//       // newCorsMiddleware returns a new cors middleware
//       // with the provided options.
//       func newCorsMiddleware() iris.HandlerFunc {
//       	options := cors.Options{
//       		AllowedOrigins: []string{"*"},
//       	}
//       	handlerWithNext := cors.New(options).ServeHTTP
//
//       	// this is the only func you will have to use if you're going
//       	// to make use of any external net/http middleware.
//       	// iris.ToHandler converts the net/http middleware to an iris-compatible.
//       	return iris.ToHandler(handlerWithNext)
//       }
//
//       func main() {
//       	app := iris.New()
//       	app.Adapt(gorillamux.New())
//
//       	// Any registers a route to all http methods.
//       	app.Any("/user", newCorsMiddleware(), func(ctx *iris.Context) {
//       		// ....
//       	})
//
//       	app.Listen(":8080")
//       }
//
//
// View engine
//
// Iris supports 5 template engines out-of-the-box, developers can still use any external golang template engine,
// as `context.ResponseWriter` is an `io.Writer`.
//
// All of these five template engines have common features with common API,
// like Layout, Template Funcs, Party-specific layout, partial rendering and more.
//
// The standard html, based on github.com/kataras/go-template/tree/master/html
// its template parser is the golang.org/pkg/html/template/.
//
// Django, based ongithub.com/kataras/go-template/tree/master/django
// its template parser is the github.com/flosch/pongo2
//
// Pug(Jade), based on github.com/kataras/go-template/tree/master/pug
// its template parser is the github.com/Joker/jade
//
// Handlebars, based on github.com/kataras/go-template/tree/master/handlebars
// its template parser is the github.com/aymerick/raymond
//
// Amber, based on github.com/kataras/go-template/tree/master/amber
// its template parser is the github.com/eknkc/amber
//
//
// Example code:
//
//       package main
//
//       import (
//       	"gopkg.in/kataras/iris.v6"
//       	"gopkg.in/kataras/iris.v6/adaptors/gorillamux"
//       	"gopkg.in/kataras/iris.v6/adaptors/view" // <--- it contains all the template engines
//       )
//
//       func main() {
//       	app := iris.New(iris.Configuration{Gzip: false, Charset: "UTF-8"}) // defaults to these
//
//       	app.Adapt(iris.DevLogger())
//       	app.Adapt(gorillamux.New())
//
//       	// - standard html  | view.HTML(...)
//       	// - django         | view.Django(...)
//       	// - pug(jade)      | view.Pug(...)
//       	// - handlebars     | view.Handlebars(...)
//       	// - amber          | view.Amber(...)
//       	app.Adapt(view.HTML("./templates", ".html")) // <---- use the standard html
//
//       	// default template funcs:
//       	//
//       	// - {{ url "mynamedroute" "pathParameter_ifneeded"} }
//       	// - {{ urlpath "mynamedroute" "pathParameter_ifneeded" }}
//       	// - {{ render "header.html" }}
//       	// - {{ render_r "header.html" }} // partial relative path to current page
//       	// - {{ yield }}
//       	// - {{ current }}
//       	//
//       	// to adapt custom funcs, use:
//       	app.Adapt(iris.TemplateFuncsPolicy{"myfunc": func(s string) string {
//       		return "hi " + s
//       	}}) // usage inside template: {{ hi "kataras"}}
//
//       	app.Get("/hi", func(ctx *iris.Context) {
//       		ctx.Render(
//       			// the file name of the template relative to the './templates'.
//       			"hi.html",
//       			iris.Map{"Name": "Iris"},
//       			// the .Name inside the ./templates/hi.html,
//       			// you can use any custom struct that you want to bind to the requested template.
//       			iris.Map{"gzip": false}, // set to true to enable gzip compression.
//       		)
//
//       	})
//
//       	// http://127.0.0.1:8080/hi
//       	app.Listen(":8080")
//       }
//
//
// View engine supports bundled(https://github.com/jteeuwen/go-bindata) template files too.
// go-bindata gives you two functions, asset and assetNames,
// these can be setted to each of the template engines using the `.Binary` func.
//
// Example code:
//
//       djangoEngine := view.Django("./templates", ".html")
//       djangoEngine.Binary(asset, assetNames)
//       app.Adapt(djangoEngine)
//
// A real example can be found here: https://github.com/kataras/iris/tree/v6/adaptors/view/_examples/template_binary .
//
// Enable auto-reloading of templates on each request. Useful while users are in dev mode
// because they don't have to restart their app on every edit you make on the template files.
//
// Example code:
//
//
//     pugEngine := view.Pug("./templates", ".jade")
//     pugEngine.Reload(true) // <--- set to true to re-build the templates on each request.
//     app.Adapt(pugEngine)
//
//
// Each one of these template engines has different options located here: https://github.com/kataras/iris/tree/v6/adaptors/view .
//
// That's the basics, we didn't cover a lot, such as static files, websockets, sessions...
//
// But you should have a basic idea of the framework by now, we just scratched the surface.
// If you enjoy what you just saw and want to learn more, please follow the below links:
//
// Examples: https://github.com/iris-contrib/examples
//
// Adaptors: https://github.com/kataras/iris/tree/v6/adaptors
//
// Middleware: https://github.com/kataras/iris/tree/v6/middleware & https://github.com/iris-contrib/middleware
package iris