/iris

Fast, cross-platform HTTP/2 Web Framework for Go. Written by a nerd, for nerds.

Primary LanguageGoMIT LicenseMIT

Navigate to http://support.iris-go.com

Build Status http://goreportcard.com/report/kataras/iris Iris support forum Examples for new Gophers Docs Chat Buy me a cup of coffee
Iris is an efficient and well-designed, cross-platform, web framework with robust set of features.
Build your own high-performance web applications and APIs powered by unlimited potentials and portability.

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

News

Upcoming release - Calliope

Hello people, I'm designing the new Iris version with the codename of "Calliope".

Based on the Greek goddesses of ancient mythology, Calliope was one of the Muses, the muse of epic poetry, daughter of Zeus and Mnemosyne and the wisest of the Muses.

The next, tactical, month release *should be published at the 1 May of 2017 *.

I am making my bests to catch up this deadline, so I'm very busy these days. Sorry for being late to answer to your questions!

UPDATE: 6 May 2017

The release could be published at the first may of 2017 but it was postponed.

The below tasks should be completed before publishing the new release:

  • The review, of the new release's specifications that I wrote, should be ready at the next couple of days.
  • The results from our beta testers may take a little more but it worths the waiting.

What you say about Iris ✌



What people say What people say

Legends ♡

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

Conrad Steenberg donated 25 EUR at March 23 of 2017

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...

Table of Contents

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.

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))

FAQ & Documentation

  1. Getting Started with Go+Iris

  2. Official small but practical examples

  3. Navigate through community examples too

  4. Creating A URL Shortener Service Using Go, Iris, and Bolt

  5. Godocs for deep documentation

  6. HISTORY.md is your best friend, version migrations are released there

I'll be glad to talk with you about your awesome feature requests, open a new discussion, you will be heard!

Support

  • ⭐ the project, will help you to follow the upcoming features
  • Donate, will help me to continue
  • Post a feature request or report a bug, will help all of us to build a better web, together
  • 🌎 post an article or tweet and share it with your neighbor

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.

I spend all my time in the construction of Iris, therefore I have no income value.

Feel free to send any amount through paypal

Please check your e-mail after your donation.

Thanks for your gratitude and finance help ♡

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:

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

Feel free to put up a PR your middleware!

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 ./_examples/advanced/httptest/main_test.go

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.

Contact

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:

Codename: "√Νεxτ"

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.