Iris is a very minimal but flexible go web framework providing arobust set of features for building shiny web applications.
This project is under extremely development
- Install
- Benchmarks
- Principles
- Features
- Introduction
- API
- Declaration & Options
- Party
- Named Parameters
- Match anything and the Static serve handler
- Declaring routes
- Context
- Examples
- Third Party Middleware
- Contributors
- Community
- Todo
$ go get github.com/kataras/irisIris is still in development status, in order to have the latest version update the package every 2-3 days
$ go get -u github.com/kataras/irisWith Intel(R) Core(TM) i7-4710HQ CPU @ 2.50GHz 2.50 HGz and 8GB Ram:
-
Easy to use
-
Robust
-
Simplicity Equals Productivity. The best way to make something seem simple is to have it actually be simple. iris's main functionality has clean, classically beautiful APIs
Parameters in your routing pattern: give meaming to your routes, give them a path segment a name and the iris' will provide the dynamic value to you.
Party of routes: Combine routes where have same prefix, provide a middleware to this Party, a Party can have other Party too.
Compatible: At the end the Iris is just a middleware which acts like router and a small simply web framework, this means that you can you use it side-by-side with your favorite big and well-tested web framework. Iris is fully compatible with the net/http package.
Multi server instances: Besides the fact that iris has a default main server. You can declare a new iris using the iris.New() func. example: server1:= iris.New(); server1.Get(....); server1.Listen(":9999")
The name of this framework came from Greek mythology, Iris was the name of the Greek goddess of the rainbow. Iris is a very minimal but flexible golang http middleware & standalone web application framework, providing a robust set of features for building single & multi-page, web applications.
package main
import "github.com/kataras/iris"
func main() {
iris.Get("/hello", func(c *iris.Context) {
c.HTML("<b> Hello </b>")
})
iris.Listen(":8080")
//or for https and http2
//iris.ListenTLS(":8080","localhost.cert","localhost.key")
//the cert and key must be in the same path of the executable main server file
}Note: for macOS, If you are having problems on .Listen then pass only the port "8080" without ':'
Use of GET, POST, PUT, DELETE, HEAD, PATCH & OPTIONS
package main
import (
"github.com/kataras/iris"
"net/http"
)
func main() {
iris.Get("/home", iris.ToHandlerFunc(testGet))
iris.Post("/login",testPost)
iris.Put("/add",testPut)
iris.Delete("/remove",testDelete)
iris.Head("/testHead",testHead)
iris.Patch("/testPatch",testPatch)
iris.Options("/testOptions",testOptions)
iris.Listen(":8080")
}
func testGet(res http.ResponseWriter, req *http.Request) {
//...
}
//iris.Context gives more information and control of the route, named parameters, redirect, error handling and render.
func testPost(c *iris.Context) {
//...
}
//and so on....Iris is compatible with net/http package over iris.ToHandlerFunc(...) or iris.ToHandler(...) if you wanna use a whole iris.Handler interface. You can use any method you like but, believe me it's easier to pass just a func(c *Context).
Let's make a pause,
- Q: Why you use iris package declaration? other frameworks needs more lines to start a server
- A: Iris gives you the freedom to choose between three methods/ways to use Iris
- global iris.
- set a new iris with variable = iris**.New()**
- set a new iris with custom options with variable = iris**.Custom(options)**
import "github.com/kataras/iris"
// 1.
func methodFirst() {
iris.Get("/home",func(c *iris.Context){})
iris.Listen(":8080")
//iris.ListenTLS(":8080","yourcertfile.cert","yourkeyfile.key"
}
// 2.
func methodSecond() {
api := iris.New()
api.Get("/home",func(c *iris.Context){})
api.Listen(":8080")
}
// 3.
func methodThree() {
//these are the default options' values
options := iris.StationOptions{
Profile: false,
ProfilePath: iris.DefaultProfilePath,
Cache: true,
CacheMaxItems: 0,
CacheResetDuration: 5 * time.Minute,
PathCorrection: true, //explanation at the end of this chapter
}//these are the default values that you can change
//DefaultProfilePath = "/debug/pprof"
api := iris.Custom(options)
api.Get("/home",func(c *iris.Context){})
api.Listen(":8080")
}Note that with 2. & 3. you can define and use more than one Iris container in the same app, when it's necessary.
As you can see there are some options that you can chage at your iris declaration, you cannot change them after. If an option value not passed then it considers to be false if bool or the default if string.
For example if we do that...
import "github.com/kataras/iris"
func main() {
options := iris.StationOptions{
Cache: true,
Profile: true,
ProfilePath: "/mypath/debug",
}
api := iris.Custom(options)
api.Listen(":8080")
}run it, then you can open your browser, type 'localhost:8080/mypath/debug/profile' at the location input field and you should see a webpage shows you informations about CPU.
For profiling & debug there are seven (7) generated pages ('/debug/pprof/' is the default profile path, which on previous example we changed it to '/mypath/debug'):
- /debug/pprof/cmdline
- /debug/pprof/profile
- /debug/pprof/symbol
- /debug/pprof/goroutine
- /debug/pprof/heap
- /debug/pprof/threadcreate
- /debug/pprof/pprof/block
PathCorrection corrects and redirects the requested path to the registed path for example, if /home/ path is requested but no handler for this Route found, then the Router checks if /home handler exists, if yes, redirects the client to the correct path /home and VICE - VERSA if /home/ is registed but /home is requested then it redirects to /home/ (Default is true)
Let's party with Iris web framework!
func main() {
//log everything middleware
iris.UseFunc(func(c *iris.Context) {
println("[Global log] the requested url path is: ", c.Request.URL.Path)
c.Next()
})
// manage all /users
users := iris.Party("/users")
{
// provide a middleware
users.UseFunc(func(c *iris.Context) {
println("LOG [/users...] This is the middleware for: ", c.Request.URL.Path)
c.Next()
})
users.Post("/login", loginHandler)
users.Get("/:userId", singleUserHandler)
users.Delete("/:userId", userAccountRemoveUserHandler)
}
// Party inside an existing Party example:
beta:= iris.Party("/beta")
admin := beta.Party("/admin")
{
/// GET: /beta/admin/
admin.Get("/", func(c *iris.Context){})
/// POST: /beta/admin/signin
admin.Post("/signin", func(c *iris.Context){})
/// GET: /beta/admin/dashboard
admin.Get("/dashboard", func(c *iris.Context){})
/// PUT: /beta/admin/users/add
admin.Put("/users/add", func(c *iris.Context){})
}
iris.Listen(":8080")
}Named parameters are just custom paths to your routes, you can access them for each request using context's c.Param("nameoftheparameter"). Get all, as array ({Key,Value}) using c.Params property.
No limit on how long a path can be.
Usage:
package main
import "github.com/kataras/iris"
func main() {
// MATCH to /hello/anywordhere (if PathCorrection:true match also /hello/anywordhere/)
// NOT match to /hello or /hello/ or /hello/anywordhere/something
iris.Get("/hello/:name", func(c *iris.Context) {
name := c.Param("name")
c.Write("Hello %s", name)
})
// MATCH to /profile/iris/friends/42 (if PathCorrection:true matches also /profile/iris/friends/42/ ,otherwise not match)
// NOT match to /profile/ , /profile/something ,
// NOT match to /profile/something/friends, /profile/something/friends ,
// NOT match to /profile/anything/friends/42/something
iris.Get("/profile/:fullname/friends/:friendId",
func(c *iris.Context){
name:= c.Param("fullname")
//friendId := c.ParamInt("friendId")
c.HTML("<b> Hello </b>"+name)
})
iris.Listen(":8080")
//or log.Fatal(http.ListenAndServe(":8080", iris))
}Match everything/anything (symbol *withAKeyLikeParameters)
// Will match any request which url's preffix is "/anything/" and has content after that
iris.Get("/anything/*randomName", func(c *iris.Context) { } )
// Match: /anything/whateverhere/whateveragain , /anything/blablabla
// c.Params("randomName") will be /whateverhere/whateveragain, blablabla
// Not Match: /anything , /anything/ , /somethingPure http static file server as handler using iris.Static("./path/to/the/resources/directory/","path_to_strip_or_nothing")
// Will match any request which url's preffix is "/public/"
/* and continues with a file whith it's extension which exists inside the os.Gwd()(dot means working directory)+ /static/resources/
*/
iris.Get("/public/*assets", iris.Static("./static/resources/","/public/"))
//Note: strip of the /public/ is handled by passing the last argument to "/public/"
//you can pass only the first two arguments for no strip path.Iris framework has three (3) different forms of functions in order to declare a route's handler and one(1) annotated struct to declare a complete route.
- Typical classic handler function, compatible with net/http and other frameworks using iris.ToHandlerFunc
- *func(res http.ResponseWriter, req http.Request)
iris.Get("/user/add", iris.ToHandlerFunc(func(res http.ResponseWriter, req *http.Request)) {
})- Context parameter in function-declaration
- *func(c iris.Context)
iris.Get("/user/:userId", func(c *iris.Context) {
})- http.Handler again it can be converted by ToHandlerFunc
- http.Handler
iris.Get("/about", iris.ToHandlerFunc(http.HandlerFunc(func(res http.Response, req *req.Request)) {
}))Note that all .Get,.Post takes a func(c *Context) as parameter, to pass an iris.Handler use the iris.Handle("/path",handler,"GET")
- 'External' annotated struct which directly implements the Iris Handler interface
///file: userhandler.go
import "github.com/kataras/iris"
type UserRoute struct {
iris.Handler `get:"/profile/user/:userId"`
}
func (u *UserRoute) Serve(c *iris.Context) {
defer c.Close()
userId := c.Param("userId")
c.RenderFile("user.html", struct{ Message string }{Message: "Hello User with ID: " + userId})
}
///file: main.go
//...cache the html files
iris.Templates("src/iristests/templates/**/*.html")
//...register the handler
iris.HandleAnnotated(&UserRoute{})
//...continue writing your wonderful APIPersonally I use the external struct and the *func(c iris.Context) form . At the next chapter you will learn what are the benefits of having the Context as parameter to the handler.
Variables
- ResponseWriter
- The ResponseWriter is the exactly the same as you used to use with the standar http library.
- Request
- The Request is the pointer of the *Request, is the exactly the same as you used to use with the standar http library.
- Params
- Contains the Named path Parameters, imagine it as a map[string]string which contains all parameters of a request.
Functions
-
Clone()
- Returns a clone of the Context, useful when you want to use the context outscoped for example in goroutines.
-
Write(contents string)
- Writes a pure string to the ResponseWriter and sends to the client.
-
Param(key string) returns string
- Returns the string representation of the key's named parameter's value. Registed path= /profile/:name) Requested url is /profile/something where the key argument is the named parameter's key, returns the value which is 'something' here.
-
ParamInt(key string) returns integer, error
- Returns the int representation of the key's named parameter's value, if something goes wrong the second return value, the error is not nil.
-
URLParam(key string) returns string
- Returns the string representation of a requested url parameter (?key=something) where the key argument is the name of, something is the returned value.
-
URLParamInt(key string) returns integer, error
- Returns the int representation of a requested url parameter
-
SetCookie(name string, value string)
- Adds a cookie to the request.
-
GetCookie(name string) returns string
- Get the cookie value, as string, of a cookie.
-
ServeFile(path string)
- This just calls the http.ServeFile, which serves a file given by the path argument to the client.
-
NotFound()
- Sends a http.StatusNotFound with a custom template you defined (if any otherwise the default template is there) to the client. --- Note: We will learn all about Custom Error Handlers later.
-
Close()
- Calls the Request.Body.Close().
-
WriteHTML(status int, contents string) & HTML(contents string)
- WriteHTML: Writes html string with a given http status to the client, it sets the Header with the correct content-type.
- HTML: Same as WriteHTML but you don't have to pass a status, it's defaulted to http.StatusOK (200).
-
WriteData(status int, binaryData []byte) & Data(binaryData []byte)
- WriteData: Writes binary data with a given http status to the client, it sets the Header with the correct content-type.
- Data : Same as WriteData but you don't have to pass a status, it's defaulted to http.StatusOK (200).
-
WriteText(status int, contents string) & Text(contents string)
- WriteText: Writes plain text with a given http status to the client, it sets the Header with the correct content-type.
- Text: Same as WriteTextbut you don't have to pass a status, it's defaulted to http.StatusOK (200).
-
WriteJSON(status int, jsonObject interface{}) & JSON(jsonObject interface{}) returns error
- WriteJSON: Writes json which is converted from structed object(s) with a given http status to the client, it sets the Header with the correct content-type. If something goes wrong then it's returned value which is an error type is not nil. No indent.
-
RenderJSON(jsonObjects ...interface{}) returns error - RenderJSON: Same as WriteJSON & JSON but with Indent (formated json) - JSON: Same as WriteJSON but you don't have to pass a status, it's defaulted to http.StatusOK (200).
-
WriteXML(status int, xmlStructs ...interface{}) & XML(xmlStructs ...interface{}) returns error
- WriteXML: Writes writes xml which is converted from struct(s) with a given http status to the client, it sets the Header with the correct content-type. If something goes wrong then it's returned value which is an error type is not nil.
- XML: Same as WriteXML but you don't have to pass a status, it's defaulted to http.StatusOK (200).
-
RenderFile(file string, pageContext interface{}) returns error
- RenderFile: Renders a file by its name (which a file is saved to the template cache) and a page context passed to the function, default http status is http.StatusOK(200) if the template was found, otherwise http.StatusNotFound(404). If something goes wrong then it's returned value which is an error type is not nil.
-
Render(pageContext interface{}) returns error
- Render: Renders the root file template and a context passed to the function, default http status is http.StatusOK(200) if the template was found, otherwise http.StatusNotFound(404). If something goes wrong then it's returned value which is an error type is not nil. --- Note: We will learn how to add templates at the next chapters.
-
Next()
- Next: calls all the next handler from the middleware stack, it used inside a middleware
-
SendStatus(statusCode int, message string)
- SendStatus: writes a http statusCode with a text/plain message
[[TODO chapt 5DA8 ers: Register custom error handlers, cache templates , create & use middleware]]
Inside the _examples folder you will find practical examples
.
*The iris tries to supports a lot of middleware out there, you can use them by parsing their handlers, for example: *
iris.UseFunc(func(c *iris.Context) {
//run the middleware here
c.Next()
})Note: Some of these, may not be work, a lot of them are especially for Negroni and nothing more.
Iris has a middleware system to create it's own middleware and is at a state which tries to find person who are be willing to convert them to Iris middleware or create new. Contact or open an issue if you are interesting.
| Middleware | Author | Description | Tested |
|---|---|---|---|
| sessions | Ported to Iris | Session Management | Yes |
| Graceful | Tyler Bunnell | Graceful HTTP Shutdown | Yes |
| gzip | Iris | GZIP response compression | Yes |
| RestGate | Prasanga Siripala | Secure authentication for REST API endpoints | No |
| secure | Cory Jacobsen | Middleware that implements a few quick security wins | Yes |
| JWT Middleware | Auth0 | Middleware checks for a JWT on the Authorization header on incoming requests and decodes it |
No |
| binding | Matt Holt | Data binding from HTTP requests into structs | No |
| logrus | Dan Buch | Logrus-based logger | No |
| render | Cory Jacobsen | Render JSON, XML and HTML templates | No |
| gorelic | Jingwen Owen Ou | New Relic agent for Go runtime | No |
| oauth2 | David Bochenski | oAuth2 middleware | No |
| permissions2 | Alexander Rødseth | Cookies, users and permissions | No |
| onthefly | Alexander Rødseth | Generate TinySVG, HTML and CSS on the fly | No |
| cors | Olivier Poitrey | Cross Origin Resource Sharing (CORS) support | No |
| xrequestid | Andrea Franz | Middleware that assigns a random X-Request-Id header to each request | No |
| VanGoH | Taylor Wrobel | Configurable AWS-Style HMAC authentication middleware | No |
| stats | Florent Messa | Store information about your web application (response time, etc.) | No |
Thanks goes to the people who have contributed code to this package, see the GitHub Contributors page.
If you'd like to discuss this package, or ask questions about it, feel free to
- Never stop writing the docs.
- Provide full README for _examples and thirdparty middleware examples.
- Before any commit run -count 50 -benchtime 30s , if performance stays on top then commit else find other way to do the same thing.
- Notice the author of any thirdparty package before I try to port into iris myself, maybe they can do it better.
- Notice author's of middleware, which I'm writing examples for,to take a look, if they don't want to exists in the Iris community, I have to respect them.
- Provide a lighter, with less using bytes, to save middleware for a route.
- Create examples in this repository.
- Subdomains supports with the same syntax as iris.Get, iris.Post ...
- Convert useful middlewares out there into Iris middlewares, or contact with their authors to do so.
- Create an easy websocket api.
- Create a mechanism that scan for Typescript files, compile them on server startup and serve them.
This project is licensed under the BSD 3-Clause License. License can be found here.