The iris from gherkin75

Iris is an efficient and well-designed toolbox with robust set of features.
Write your own perfect high-performance web applications
with unlimited potentials and portability.

If you're coming from Node.js world, this is the expressjs equivalent for the Go Programming Language.

Heroes ♡

Juan Sebastián Suárez Valencia donated 20 EUR at September 11 of 2016

Bob Lee donated 20 EUR at September 16 of 2016

Celso Luiz donated 50 EUR at September 29 of 2016

Ankur Srivastava donated 20 EUR at October 2 of 2016

Damon Zhao donated 20 EUR at October 21 of 2016

exponity - consulting & digital transformation donated 30 EUR at November 4 of 2016

Thomas Fritz donated 25 EUR at Jenuary 8 of 2017

Thanos V. donated 20 EUR at Jenuary 16 of 2017

George Opritescu donated 20 EUR at February 7 of 2017

Lex Tang donated 20 EUR at February 22 of 2017

ANYNOMOUS* donated 336 EUR

Feature Overview

Focus on high performance
Automatically install and serve certificates from https://letsencrypt.org
Robust routing and middleware ecosystem
Build RESTful APIs
Choose your favorite routes' path syntax between httprouter and gorillamux
Request-Scoped Transactions
Group API's and subdomains with wildcard support
Body binding for JSON, XML, Forms, can be extended to use your own custom binders
More than 50 handy functions to send HTTP responses
View system: supporting more than 6+ template engines, with prerenders. You can still use your favorite
Define virtual hosts and (wildcard) subdomains with path level routing
Graceful shutdown
Limit request body
Localization i18N
Serve static files
Cache
Log requests
Customizable format and output for the logger
Customizable HTTP errors
Compression (Gzip)
Authentication
OAuth, OAuth2 supporting 27+ popular websites
JWT
Basic Authentication
HTTP Sessions
Add / Remove trailing slash from the URL with option to redirect
Redirect requests
HTTP to HTTPS
HTTP to HTTPS WWW
HTTP to HTTPS non WWW
Non WWW to WWW
WWW to non WWW
Highly scalable rich content render (Markdown, JSON, JSONP, XML...)
Websocket-only API similar to socket.io
Hot Reload on source code changes
Typescript integration + Web IDE
Checks for updates at startup
Highly customizable
Feels like you used iris forever, thanks to its Fluent API
And many others...

Installation

The only requirement is the Go Programming Language, at least 1.8

$ go get gopkg.in/kataras/iris.v6

For further installation support, navigate here.

Documentation

Godocs ⇒ https://godoc.org/gopkg.in/kataras/iris.v6
Getting Started with Go+Iris ⇒ http://gopherbook.iris-go.com
Navigate through community examples ⇒ https://github.com/iris-contrib/examples
./adaptors and ./middleware contains examples of their usage.
HISTORY.md is your best friend, version migrations are released there.

Overview

package main

import (
	"gopkg.in/kataras/iris.v6"
	"gopkg.in/kataras/iris.v6/adaptors/cors"
	"gopkg.in/kataras/iris.v6/adaptors/httprouter"
	"gopkg.in/kataras/iris.v6/adaptors/view"
)

func main() {
	// Receives optional iris.Configuration{}, see ./configuration.go
	// for more.
	app := iris.New()

	// Order doesn't matter,
	// You can split it to different .Adapt calls.
	// See ./adaptors folder for more.
	app.Adapt(
		// adapt a logger which prints all errors to the os.Stdout
		iris.DevLogger(),
		// adapt the adaptors/httprouter or adaptors/gorillamux
		httprouter.New(),
		// 5 template engines are supported out-of-the-box:
		//
		// - standard html/template
		// - amber
		// - django
		// - handlebars
		// - pug(jade)
		//
		// Use the html standard engine for all files inside "./views" folder with extension ".html"
		view.HTML("./views", ".html"),
		// Cors wrapper to the entire application, allow all origins.
		cors.New(cors.Options{AllowedOrigins: []string{"*"}}))

	// http://localhost:6300
	// Method: "GET"
	// Render ./views/index.html
	app.Get("/", func(ctx *iris.Context) {
		ctx.Render("index.html", iris.Map{"Title": "Page Title"}, iris.RenderOptions{"gzip": true})
	})

	// Group routes, optionally: share middleware, template layout and custom http errors.
	userAPI := app.Party("/users", userAPIMiddleware).
		Layout("layouts/userLayout.html")
	{
		// Fire userNotFoundHandler when Not Found
		// inside http://localhost:6300/users/*anything
		userAPI.OnError(404, userNotFoundHandler)

		// http://localhost:6300/users
		// Method: "GET"
		userAPI.Get("/", getAllHandler)

		// http://localhost:6300/users/42
		// Method: "GET"
		userAPI.Get("/:id", getByIDHandler)

		// http://localhost:6300/users
		// Method: "POST"
		userAPI.Post("/", saveUserHandler)
	}

	// Start the server at 127.0.0.1:6300
	app.Listen(":6300")
}

func userAPIMiddleware(ctx *iris.Context) {
	// your code here...
	println("Request: " + ctx.Path())
	ctx.Next() // go to the next handler(s)
}

func userNotFoundHandler(ctx *iris.Context) {
	// your code here...
	ctx.HTML(iris.StatusNotFound, "<h1> User page not found </h1>")
}

func getAllHandler(ctx *iris.Context) {
	// your code here...
}

func getByIDHandler(ctx *iris.Context) {
	// take the :id from the path, parse to integer
	// and set it to the new userID local variable.
	userID, _ := ctx.ParamInt("id")

	// userRepo, imaginary database service <- your only job.
	user := userRepo.GetByID(userID)

	// send back a response to the client,
	// .JSON: content type as application/json; charset="utf-8"
	// iris.StatusOK: with 200 http status code.
	//
	// send user as it is or make use of any json valid golang type,
	// like the iris.Map{"username" : user.Username}.
	ctx.JSON(iris.StatusOK, user)
}

func saveUserHandler(ctx *iris.Context) {
	// your code here...
}

Reload on source code changes

$ go get -u github.com/kataras/rizla
$ cd $GOPATH/src/mywebapp
$ rizla main.go

Reload templates on each incoming request

app.Adapt(view.HTML("./views", ".html").Reload(true))

Third Party Middleware

Iris has its own middleware form of func(ctx *iris.Context) but it's also compatible with all net/http middleware forms using iris.ToHandler, i.e Negroni's middleware form of func(w http.ResponseWriter, r *http.Request, next http.HandlerFunc).

Here is a small list of Iris compatible middleware, I'm sure you can find more! Feel free to put up a PR your middleware if you have built one :

Middleware	Author	Description
binding	Matt Holt	Data binding from HTTP requests into structs
cloudwatch	Colin Steele	AWS cloudwatch metrics middleware
csp	Awake Networks	Content Security Policy (CSP) support
delay	Jeff Martinez	Add delays/latency to endpoints. Useful when testing effects of high latency
New Relic Go Agent	Yadvendar Champawat	Official New Relic Go Agent (currently in beta)
gorelic	Jingwen Owen Ou	New Relic agent for Go runtime
JWT Middleware	Auth0	Middleware checks for a JWT on the `Authorization` header on incoming requests and decodes it
logrus	Dan Buch	Logrus-based logger
onthefly	Alexander Rødseth	Generate TinySVG, HTML and CSS on the fly
permissions2	Alexander Rødseth	Cookies, users and permissions
prometheus	Rene Zbinden	Easily create metrics endpoint for the prometheus instrumentation tool
render	Cory Jacobsen	Render JSON, XML and HTML templates
RestGate	Prasanga Siripala	Secure authentication for REST API endpoints
secure	Cory Jacobsen	Middleware that implements a few quick security wins
stats	Florent Messa	Store information about your web application (response time, etc.)
VanGoH	Taylor Wrobel	Configurable AWS-Style HMAC authentication middleware
xrequestid	Andrea Franz	Middleware that assigns a random X-Request-Id header to each request
digits	Bilal Amarni	Middleware that handles Twitter Digits authentication

FAQ

Q: OK Iris is really fast, but my current website does not need that performance at the moment, are there other reasons to move into Iris?

Iris is fully vendored. That means it is independent of any API changes in the used libraries and will work seamlessly in the future!

The size of the executable file is a critical part of the Application Deployment Process.

Two very simple identical applications, the first was written with iris and the second with a simple golang router.

iris had 8.505 KB overall file size
gin had 9.029 KB overall file size
net/http had produced an executable file with 5.380 KB size.

Iris has built'n support for the most of the features that you will use to craft your perfect web application, while the golang router(gin & httprouter alone) doesn't. Imagine what would happened if the simple app we created would use sessions, websockets, view engine... I tested that too, gin and net/http had produced the x3 of their original size, while iris application' overall executable filesize remained stable!

Applications that are written using Iris produce smaller file size even if they use more features than a simple router library!

Iris always follows the latest trends and best practices. Iris is the Secret To Staying One Step Ahead of Your Competition.

Iris is a high-performance tool, but it doesn't stops there. Performance depends on your application too, Iris helps you to make the right choices on every step.

Familiar and easy API. Sinatra-like REST API.

Contains examples and documentation for all its features.

Iris is a low-level access web framework, you always know what you're doing.

You'll never miss a thing from net/http, but if you do on some point, no problem because Iris is fully compatible with stdlib, you still have access to http.ResponseWriter and http.Request, you can adapt any third-party middleware of form func(http.ResponseWriter, *http.Request, next http.HandlerFunc) as well.

Iris is a community-driven project, you suggest and I code.

Unlike other repositories, this one is very active. When you post an issue, you get an answer at the next couple of minutes(hours at the worst). If you find a bug, I am obliged to fix that on the same day.

Click the below animation to see by your self what people, like you, say about Iris.

Q: Why no serverless?

New web developers are so enthusiastic about the idea of serverless and AWS. Most of the experienced developers we already know that we shouldn't use these things for our critical parts of our application.

Serverless and AWS Are Wonderful—Until They Go Wrong. There was a flash-point (at 28 February of 2017) where the 'internet was offline' and most of the sites, including isitdownrightnow.com, were down or operated very slow! Why? Because of serverless and AmazonS3. Please think twice before moving your code into serverless, instead, use web frameworks that are created for servers that you control, i.e Iris.

Proof of concept:

Explore these questions and join to our community chat!

Testing

The httptest package is a simple Iris helper for the httpexpect, a new library for End-to-end HTTP and REST API testing for Go.

You can find tests by navigating to the source code, i.e:

A simple test is located to ./httptest/_example/main_test.go

httpexpect's repository has some Iris examples too:

https://github.com/gavv/httpexpect/blob/master/_examples/iris.go (without httptest package)
https://github.com/gavv/httpexpect/blob/master/_examples/iris_test.go (without httptest package)

Philosophy

The Iris philosophy is to provide robust tooling for HTTP, making it a great solution for single page applications, web sites, hybrids, or public HTTP APIs. Keep note that, today, iris is faster than nginx itself.

Iris does not force you to use any specific ORM or template engine. Iris is routerless which means you can adapt any router you like, httprouter is the fastest, gorillamux has more features. With support for the most used template engines (5), you can quickly craft the perfect application.

People

The author of Iris is @kataras.

However the real Success of Iris belongs to you with your bug reports and feature requests that made this Framework so Unique.

Support

The main purpose of donations to open source is to say "thank you" to the developer rather than actually advancing the project.

Open source projects don’t need the money like those charities do—and so it’s usually phrased like: Buy the developer a cup of coffee.

Buy me a cup of coffee?

Iris is free and open source but developing it has taken thousands of hours of my time and a large part of my sanity. If you feel this web framework useful to you, it would go a great way to ensuring that I can afford to take the time to continue to develop it.

Thanks for your gratitude and finance help ♡

Some of the benefits are listed here:

Your github username, after your approval, is visible at the top of the README page.
Access to the 'donors' private chat room gives you real-time assistance by Iris' Author.

ANONYMOUS: People who donate but don't want to be shown here. ANONYMOUS are listed as one group instead of an individual entry, in order to protect their exact date of their donation.

The names, shown at the supporters list, are sorted by date and NOT by the amount of the donation.

More options!

Star the project, will help you to follow the upcoming features.
Write an article about Iris or even post a Tweet.
If you are interested in contributing to the Iris project, please see the document CONTRIBUTING.

Become An Iris Sponsor

Want to add your company's logo to our website?

Please contact me via email: [email protected]

Thank you!

Socialize

Besides the fact that we have a community chat for questions or reports and ideas, stackoverflow section for generic go+iris questions and the iris support for bug reports and feature requests, you can also contact with me, as a person who is always open to help you:

Versioning

Current: v6, code-named as "√Νεxτ"

v5: https://github.com/kataras/iris/tree/5.0.0

License

Unless otherwise noted, the source files are distributed under the MIT License found in the LICENSE file.

Note that some optional components that you may use with Iris requires different license agreements.

TODO

Refactor the Examples to be align with the latest version
Upgrade GitBook for the latest release

Iris is a Community-Driven project waiting for your feature requests!

gherkin75 / iris Goto Github PK

iris's Introduction