iris

package module
v8.5.9+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 22, 2017 License: BSD-3-Clause Imports: 27 Imported by: 0

README

I'm working hard on the dev branch for the next release of Iris.

Do you remember, last Christmas? I did publish the version 6 with net/http and HTTP/2 support, and you've embraced Iris with so much love, ultimately it was a successful move.

I tend to make surprises by giving you the most unique and useful features, especially on Christmas period.

This year, I intend to give you more gifts.

Don't worry, it will not contain any breaking changes, except of some MVC concepts that are re-designed.

The new Iris' MVC Ecosystem is ready on the dev/mvc. It contains features that you've never saw before, in any programming language framework. It is also, by far, the fastest MVC implementation ever created, very close to raw handlers - it's Iris, it's superior, we couldn't expect something different after all :) Treat that with respect as it treats you :)

I'm doing my bests to get it ready before Christmas.

Star or watch the repository to stay up to date and get ready for the most amazing features!

Yours faithfully, Gerasimos Maropoulos.

Iris

build statusreport cardgithub closed issuesreleaseview exampleschatCLA assistant

Iris is a fast, simple and efficient web framework for Go.

Iris provides a beautifully expressive and easy to use foundation for your next website, API, or distributed app.

Learn what others say about Iris and star this github repository to stay up to date.

Benchmarks from third-party source over the rest web frameworks

Comparison with other frameworks

Updated at: Tuesday, 21 November 2017

Built with ♥️

We have no doubt you will able to find other web frameworks written in Go and even put up a real fight to learn and use them for quite some time but make no mistake, sooner or later you will be using Iris, not because of the ergonomic, high-performant solution that it provides but its well-documented unique features, as these will transform you to a real rockstar geek.

No matter what you're trying to build, Iris covers every type of application, from micro services to large monolithic web applications. It's actually the best piece of software for back-end web developers you can find online.

Iris may have reached version 8, but we're not stopping there. We have many feature ideas on our board that we're anxious to add and other innovative web development solutions that we're planning to build into Iris.

Accelerated by KeyCDN, a simple, fast and reliable CDN.

We are developing this project using the best code editor for Golang; Visual Studio Code supported by Microsoft.

If you're coming from nodejs world, Iris is the expressjs equivalent for Gophers.

Table Of Content

Installation

The only requirement is the Go Programming Language

Iris takes advantage of the vendor directory feature. You get truly reproducible builds, as this method guards against upstream renames and deletes.

A simple copy-paste and go get ./... to resolve two dependencies: kataras/golog and the iris-contrib/httpexpect will work for ever even for older versions, the newest version can be retrieved by go get but this branch contains an older version of Iris.

Follow the instructions below:

  1. install the Go Programming Language: https://golang.org/dl
  2. clear yours previously $GOPATH/src/github.com/kataras/iris folder or create new
  3. download the Iris v8.5.9 (final): https://github.com/kataras/iris/archive/v8.zip
  4. extract the contents of the iris-v8 folder that's inside the downloaded zip file to your $GOPATH/src/github.com/kataras/iris
  5. navigate to your $GOPATH/src/github.com/kataras/iris folder if you're not already there and open a terminal/command prompt, execute the command: go get ./... and you're ready to GO:)

Getting Started

package main

import "github.com/kataras/iris"

func main() {
    app := iris.New()
    // Load all templates from the "./views" folder
    // where extension is ".html" and parse them
    // using the standard `html/template` package.
    app.RegisterView(iris.HTML("./views", ".html"))

    // Method:    GET
    // Resource:  http://localhost:8080
    app.Get("/", func(ctx iris.Context) {
        // Bind: {{.message}} with "Hello world!"
        ctx.ViewData("message", "Hello world!")
        // Render template file: ./views/hello.html
        ctx.View("hello.html")
    })

    // Method:    GET
    // Resource:  http://localhost:8080/user/42
    //
    // Need to use a custom regexp instead?
    // Easy;
    // Just mark the parameter's type to 'string'
    // which accepts anything and make use of
    // its `regexp` macro function, i.e:
    // app.Get("/user/{id:string regexp(^[0-9]+$)}")
    app.Get("/user/{id:long}", func(ctx iris.Context) {
        userID, _ := ctx.Params().GetInt64("id")
        ctx.Writef("User ID: %d", userID)
    })

    // Start the server using a network address.
    app.Run(iris.Addr(":8080"))
}

Learn more about path parameter's types by clicking here.

<!-- file: ./views/hello.html -->
<html>
<head>
    <title>Hello Page</title>
</head>
<body>
    <h1>{{.message}}</h1>
</body>
</html>

overview screen

Wanna re-start your app automatically when source code changes happens? Install the rizla tool and run rizla main.go instead of go run main.go.

Guidelines for bootstrapping applications can be found at the _examples/structuring.

Quick MVC Tutorial

package main

import (
    "github.com/kataras/iris"
    "github.com/kataras/iris/mvc"
)

func main() {
    app := iris.New()

    app.Controller("/helloworld", new(HelloWorldController))

    app.Run(iris.Addr("localhost:8080"))
}

type HelloWorldController struct {
    mvc.C

    // [ Your fields here ]
    // Request lifecycle data
    // Models
    // Database
    // Global properties
}

//
// GET: /helloworld

func (c *HelloWorldController) Get() string {
    return "This is my default action..."
}

//
// GET: /helloworld/{name:string}

func (c *HelloWorldController) GetBy(name string) string {
    return "Hello " + name
}

//
// GET: /helloworld/welcome

func (c *HelloWorldController) GetWelcome() (string, int) {
    return "This is the GetWelcome action func...", iris.StatusOK
}

//
// GET: /helloworld/welcome/{name:string}/{numTimes:int}

func (c *HelloWorldController) GetWelcomeBy(name string, numTimes int) {
    // Access to the low-level Context,
    // output arguments are optional of course so we don't have to use them here.
    c.Ctx.Writef("Hello %s, NumTimes is: %d", name, numTimes)
}

The _examples/mvc and mvc/controller_test.go files explain each feature with simple paradigms, they show how you can take advandage of the Iris MVC Binder, Iris MVC Models and many more...

Every exported func prefixed with an HTTP Method(Get, Post, Put, Delete...) in a controller is callable as an HTTP endpoint. In the sample above, all funcs writes a string to the response. Note the comments preceding each method.

An HTTP endpoint is a targetable URL in the web application, such as http://localhost:8080/helloworld, and combines the protocol used: HTTP, the network location of the web server (including the TCP port): localhost:8080 and the target URI /helloworld.

The first comment states this is an HTTP GET method that is invoked by appending "/helloworld" to the base URL. The third comment specifies an HTTP GET method that is invoked by appending "/helloworld/welcome" to the URL.

Controller knows how to handle the "name" on GetBy or the "name" and "numTimes" at GetWelcomeBy, because of the By keyword, and builds the dynamic route without boilerplate; the third comment specifies an HTTP GET dynamic method that is invoked by any URL that starts with "/helloworld/welcome" and followed by two more path parts, the first one can accept any value and the second can accept only numbers, i,e: "http://localhost:8080/helloworld/welcome/golang/32719", otherwise a 404 Not Found HTTP Error will be sent to the client instead.

Quick MVC Tutorial #2

Iris has a very powerful and blazing fast MVC support, you can return any value of any type from a method function and it will be sent to the client as expected.

  • if string then it's the body.
  • if string is the second output argument then it's the content type.
  • if int then it's the status code.
  • if error and not nil then (any type) response will be omitted and error's text with a 400 bad request will be rendered instead.
  • if (int, error) and error is not nil then the response result will be the error's text with the status code as int.
  • if bool is false then it throws 404 not found http error by skipping everything else.
  • if custom struct or interface{} or slice or map then it will be rendered as json, unless a string content type is following.
  • if mvc.Result then it executes its Dispatch function, so good design patters can be used to split the model's logic where needed.

The example below is not intended to be used in production but it's a good showcase of some of the return types we saw before;

package main

import (
    "github.com/kataras/iris"
    "github.com/kataras/iris/middleware/basicauth"
    "github.com/kataras/iris/mvc"
)

// Movie is our sample data structure.
type Movie struct {
    Name   string `json:"name"`
    Year   int    `json:"year"`
    Genre  string `json:"genre"`
    Poster string `json:"poster"`
}

// movies contains our imaginary data source.
var movies = []Movie{
    {
        Name:   "Casablanca",
        Year:   1942,
        Genre:  "Romance",
        Poster: "https://iris-go.com/images/examples/mvc-movies/1.jpg",
    },
    {
        Name:   "Gone with the Wind",
        Year:   1939,
        Genre:  "Romance",
        Poster: "https://iris-go.com/images/examples/mvc-movies/2.jpg",
    },
    {
        Name:   "Citizen Kane",
        Year:   1941,
        Genre:  "Mystery",
        Poster: "https://iris-go.com/images/examples/mvc-movies/3.jpg",
    },
    {
        Name:   "The Wizard of Oz",
        Year:   1939,
        Genre:  "Fantasy",
        Poster: "https://iris-go.com/images/examples/mvc-movies/4.jpg",
    },
}


var basicAuth = basicauth.New(basicauth.Config{
    Users: map[string]string{
        "admin": "password",
    },
})


func main() {
    app := iris.New()

    app.Use(basicAuth)

    app.Controller("/movies", new(MoviesController))

    app.Run(iris.Addr(":8080"))
}

// MoviesController is our /movies controller.
type MoviesController struct {
    mvc.C
}

// Get returns list of the movies
// Demo:
// curl -i http://localhost:8080/movies
func (c *MoviesController) Get() []Movie {
    return movies
}

// GetBy returns a movie
// Demo:
// curl -i http://localhost:8080/movies/1
func (c *MoviesController) GetBy(id int) Movie {
    return movies[id]
}

// PutBy updates a movie
// Demo:
// curl -i -X PUT -F "genre=Thriller" -F "poster=@/Users/kataras/Downloads/out.gif" http://localhost:8080/movies/1
func (c *MoviesController) PutBy(id int) Movie {
    // get the movie
    m := movies[id]

    // get the request data for poster and genre
    file, info, err := c.Ctx.FormFile("poster")
    if err != nil {
        c.Ctx.StatusCode(iris.StatusInternalServerError)
        return Movie{}
    }
    file.Close()            // we don't need the file
    poster := info.Filename // imagine that as the url of the uploaded file...
    genre := c.Ctx.FormValue("genre")

    // update the poster
    m.Poster = poster
    m.Genre = genre
    movies[id] = m

    return m
}

// DeleteBy deletes a movie
// Demo:
// curl -i -X DELETE -u admin:password http://localhost:8080/movies/1
func (c *MoviesController) DeleteBy(id int) iris.Map {
    // delete the entry from the movies slice
    deleted := movies[id].Name
    movies = append(movies[:id], movies[id+1:]...)
    // and return the deleted movie's name
    return iris.Map{"deleted": deleted}
}

Quick MVC Tutorial #3

Nothing stops you from using your favorite folder structure. Iris is a low level web framework, it has got MVC first-class support but it doesn't limit your folder structure, this is your choice.

Structuring depends on your own needs. We can't tell you how to design your own application for sure but you're free to take a closer look to one typical example below;

folder structure example

Shhh, let's spread the code itself.

Data Model Layer
// file: datamodels/movie.go

package datamodels

// Movie is our sample data structure.
// Keep note that the tags for public-use (for our web app)
// should be kept in other file like "web/viewmodels/movie.go"
// which could wrap by embedding the datamodels.Movie or
// declare new fields instead butwe will use this datamodel
// as the only one Movie model in our application,
// for the shake of simplicty.
type Movie struct {
    ID     int64  `json:"id"`
    Name   string `json:"name"`
    Year   int    `json:"year"`
    Genre  string `json:"genre"`
    Poster string `json:"poster"`
}
Data Source / Data Store Layer
// file: datasource/movies.go

package datasource

import "github.com/kataras/iris/_examples/mvc/overview/datamodels"

// Movies is our imaginary data source.
var Movies = map[int64]datamodels.Movie{
    1: {
        ID:     1,
        Name:   "Casablanca",
        Year:   1942,
        Genre:  "Romance",
        Poster: "https://iris-go.com/images/examples/mvc-movies/1.jpg",
    },
    2: {
        ID:     2,
        Name:   "Gone with the Wind",
        Year:   1939,
        Genre:  "Romance",
        Poster: "https://iris-go.com/images/examples/mvc-movies/2.jpg",
    },
    3: {
        ID:     3,
        Name:   "Citizen Kane",
        Year:   1941,
        Genre:  "Mystery",
        Poster: "https://iris-go.com/images/examples/mvc-movies/3.jpg",
    },
    4: {
        ID:     4,
        Name:   "The Wizard of Oz",
        Year:   1939,
        Genre:  "Fantasy",
        Poster: "https://iris-go.com/images/examples/mvc-movies/4.jpg",
    },
    5: {
        ID:     5,
        Name:   "North by Northwest",
        Year:   1959,
        Genre:  "Thriller",
        Poster: "https://iris-go.com/images/examples/mvc-movies/5.jpg",
    },
}
Repositories

The layer which has direct access to the "datasource" and can manipulate data directly.

// file: repositories/movie_repository.go

package repositories

import (
    "errors"
    "sync"

    "github.com/kataras/iris/_examples/mvc/overview/datamodels"
)

// Query represents the visitor and action queries.
type Query func(datamodels.Movie) bool

// MovieRepository handles the basic operations of a movie entity/model.
// It's an interface in order to be testable, i.e a memory movie repository or
// a connected to an sql database.
type MovieRepository interface {
    Exec(query Query, action Query, limit int, mode int) (ok bool)

    Select(query Query) (movie datamodels.Movie, found bool)
    SelectMany(query Query, limit int) (results []datamodels.Movie)

    InsertOrUpdate(movie datamodels.Movie) (updatedMovie datamodels.Movie, err error)
    Delete(query Query, limit int) (deleted bool)
}

// NewMovieRepository returns a new movie memory-based repository,
// the one and only repository type in our example.
func NewMovieRepository(source map[int64]datamodels.Movie) MovieRepository {
    return &movieMemoryRepository{source: source}
}

// movieMemoryRepository is a "MovieRepository"
// which manages the movies using the memory data source (map).
type movieMemoryRepository struct {
    source map[int64]datamodels.Movie
    mu     sync.RWMutex
}

const (
    // ReadOnlyMode will RLock(read) the data .
    ReadOnlyMode = iota
    // ReadWriteMode will Lock(read/write) the data.
    ReadWriteMode
)

func (r *movieMemoryRepository) Exec(query Query, action Query, actionLimit int, mode int) (ok bool) {
    loops := 0

    if mode == ReadOnlyMode {
        r.mu.RLock()
        defer r.mu.RUnlock()
    } else {
        r.mu.Lock()
        defer r.mu.Unlock()
    }

    for _, movie := range r.source {
        ok = query(movie)
        if ok {
            if action(movie) {
                loops++
                if actionLimit >= loops {
                    break // break
                }
            }
        }
    }

    return
}

// Select receives a query function
// which is fired for every single movie model inside
// our imaginary data source.
// When that function returns true then it stops the iteration.
//
// It returns the query's return last known "found" value
// and the last known movie model
// to help callers to reduce the LOC.
//
// It's actually a simple but very clever prototype function
// I'm using everywhere since I firstly think of it,
// hope you'll find it very useful as well.
func (r *movieMemoryRepository) Select(query Query) (movie datamodels.Movie, found bool) {
    found = r.Exec(query, func(m datamodels.Movie) bool {
        movie = m
        return true
    }, 1, ReadOnlyMode)

    // set an empty datamodels.Movie if not found at all.
    if !found {
        movie = datamodels.Movie{}
    }

    return
}

// SelectMany same as Select but returns one or more datamodels.Movie as a slice.
// If limit <=0 then it returns everything.
func (r *movieMemoryRepository) SelectMany(query Query, limit int) (results []datamodels.Movie) {
    r.Exec(query, func(m datamodels.Movie) bool {
        results = append(results, m)
        return true
    }, limit, ReadOnlyMode)

    return
}

// InsertOrUpdate adds or updates a movie to the (memory) storage.
//
// Returns the new movie and an error if any.
func (r *movieMemoryRepository) InsertOrUpdate(movie datamodels.Movie) (datamodels.Movie, error) {
    id := movie.ID

    if id == 0 { // Create new action
        var lastID int64
        // find the biggest ID in order to not have duplications
        // in productions apps you can use a third-party
        // library to generate a UUID as string.
        r.mu.RLock()
        for _, item := range r.source {
            if item.ID > lastID {
                lastID = item.ID
            }
        }
        r.mu.RUnlock()

        id = lastID + 1
        movie.ID = id

        // map-specific thing
        r.mu.Lock()
        r.source[id] = movie
        r.mu.Unlock()

        return movie, nil
    }

    // Update action based on the movie.ID,
    // here we will allow updating the poster and genre if not empty.
    // Alternatively we could do pure replace instead:
    // r.source[id] = movie
    // and comment the code below;
    current, exists := r.Select(func(m datamodels.Movie) bool {
        return m.ID == id
    })

    if !exists { // ID is not a real one, return an error.
        return datamodels.Movie{}, errors.New("failed to update a nonexistent movie")
    }

    // or comment these and r.source[id] = m for pure replace
    if movie.Poster != "" {
        current.Poster = movie.Poster
    }

    if movie.Genre != "" {
        current.Genre = movie.Genre
    }

    // map-specific thing
    r.mu.Lock()
    r.source[id] = current
    r.mu.Unlock()

    return movie, nil
}

func (r *movieMemoryRepository) Delete(query Query, limit int) bool {
    return r.Exec(query, func(m datamodels.Movie) bool {
        delete(r.source, m.ID)
        return true
    }, limit, ReadWriteMode)
}
Services

The layer which has access to call functions from the "repositories" and "models" (or even "datamodels" if simple application). It should contain the most of the domain logic.

// file: services/movie_service.go

package services

import (
    "github.com/kataras/iris/_examples/mvc/overview/datamodels"
    "github.com/kataras/iris/_examples/mvc/overview/repositories"
)

// MovieService handles some of the CRUID operations of the movie datamodel.
// It depends on a movie repository for its actions.
// It's here to decouple the data source from the higher level compoments.
// As a result a different repository type can be used with the same logic without any aditional changes.
// It's an interface and it's used as interface everywhere
// because we may need to change or try an experimental different domain logic at the future.
type MovieService interface {
    GetAll() []datamodels.Movie
    GetByID(id int64) (datamodels.Movie, bool)
    DeleteByID(id int64) bool
    UpdatePosterAndGenreByID(id int64, poster string, genre string) (datamodels.Movie, error)
}

// NewMovieService returns the default movie service.
func NewMovieService(repo repositories.MovieRepository) MovieService {
    return &movieService{
        repo: repo,
    }
}

type movieService struct {
    repo repositories.MovieRepository
}

// GetAll returns all movies.
func (s *movieService) GetAll() []datamodels.Movie {
    return s.repo.SelectMany(func(_ datamodels.Movie) bool {
        return true
    }, -1)
}

// GetByID returns a movie based on its id.
func (s *movieService) GetByID(id int64) (datamodels.Movie, bool) {
    return s.repo.Select(func(m datamodels.Movie) bool {
        return m.ID == id
    })
}

// UpdatePosterAndGenreByID updates a movie's poster and genre.
func (s *movieService) UpdatePosterAndGenreByID(id int64, poster string, genre string) (datamodels.Movie, error) {
    // update the movie and return it.
    return s.repo.InsertOrUpdate(datamodels.Movie{
        ID:     id,
        Poster: poster,
        Genre:  genre,
    })
}

// DeleteByID deletes a movie by its id.
//
// Returns true if deleted otherwise false.
func (s *movieService) DeleteByID(id int64) bool {
    return s.repo.Delete(func(m datamodels.Movie) bool {
        return m.ID == id
    }, 1)
}
View Models

There should be the view models, the structure that the client will be able to see.

Example:

import (
    "github.com/kataras/iris/_examples/mvc/overview/datamodels"

    "github.com/kataras/iris/context"
)

type Movie struct {
    datamodels.Movie
}

func (m Movie) IsValid() bool {
    /* do some checks and return true if it's valid... */
    return m.ID > 0
}

Iris is able to convert any custom data Structure into an HTTP Response Dispatcher, so theoretically, something like the following is permitted if it's really necessary;

// Dispatch completes the `kataras/iris/mvc#Result` interface.
// Sends a `Movie` as a controlled http response.
// If its ID is zero or less then it returns a 404 not found error
// else it returns its json representation,
// (just like the controller's functions do for custom types by default).
//
// Don't overdo it, the application's logic should not be here.
// It's just one more step of validation before the response,
// simple checks can be added here.
//
// It's just a showcase,
// imagine the potentials this feature gives when designing a bigger application.
//
// This is called where the return value from a controller's method functions
// is type of `Movie`.
// For example the `controllers/movie_controller.go#GetBy`.
func (m Movie) Dispatch(ctx context.Context) {
    if !m.IsValid() {
        ctx.NotFound()
        return
    }
    ctx.JSON(m, context.JSON{Indent: " "})
}

However, we will use the "datamodels" as the only one models package because Movie structure doesn't contain any sensitive data, clients are able to see all of its fields and we don't need any extra functionality or validation inside it.

Controllers

Handles web requests, bridge between the services and the client.

// file: web/controllers/movie_controller.go

package controllers

import (
    "errors"

    "github.com/kataras/iris/_examples/mvc/overview/datamodels"
    "github.com/kataras/iris/_examples/mvc/overview/services"

    "github.com/kataras/iris"
    "github.com/kataras/iris/mvc"
)

// MovieController is our /movies controller.
type MovieController struct {
    mvc.C

    // Our MovieService, it's an interface which
    // is binded from the main application.
    Service services.MovieService
}

// Get returns list of the movies.
// Demo:
// curl -i http://localhost:8080/movies
//
// The correct way if you have sensitive data:
// func (c *MovieController) Get() (results []viewmodels.Movie) {
//  data := c.Service.GetAll()
//
//  for _, movie := range data {
// 	  results = append(results, viewmodels.Movie{movie})
//  }
//  return
// }
// otherwise just return the datamodels.
func (c *MovieController) Get() (results []datamodels.Movie) {
    return c.Service.GetAll()
}

// GetBy returns a movie.
// Demo:
// curl -i http://localhost:8080/movies/1
func (c *MovieController) GetBy(id int64) (movie datamodels.Movie, found bool) {
    return c.Service.GetByID(id) // it will throw 404 if not found.
}

// PutBy updates a movie.
// Demo:
// curl -i -X PUT -F "genre=Thriller" -F "poster=@/Users/kataras/Downloads/out.gif" http://localhost:8080/movies/1
func (c *MovieController) PutBy(id int64) (datamodels.Movie, error) {
    // get the request data for poster and genre
    file, info, err := c.Ctx.FormFile("poster")
    if err != nil {
        return datamodels.Movie{}, errors.New("failed due form file 'poster' missing")
    }
    // we don't need the file so close it now.
    file.Close()

    // imagine that is the url of the uploaded file...
    poster := info.Filename
    genre := c.Ctx.FormValue("genre")

    return c.Service.UpdatePosterAndGenreByID(id, poster, genre)
}

// DeleteBy deletes a movie.
// Demo:
// curl -i -X DELETE -u admin:password http://localhost:8080/movies/1
func (c *MovieController) DeleteBy(id int64) interface{} {
    wasDel := c.Service.DeleteByID(id)
    if wasDel {
        // return the deleted movie's ID
        return iris.Map{"deleted": id}
    }
    // right here we can see that a method function can return any of those two types(map or int),
    // we don't have to specify the return type to a specific type.
    return iris.StatusBadRequest
}

// file: web/controllers/hello_controller.go

package controllers

import (
    "errors"

    "github.com/kataras/iris/mvc"
)

// HelloController is our sample controller
// it handles GET: /hello and GET: /hello/{name}
type HelloController struct {
    mvc.C
}

var helloView = mvc.View{
    Name: "hello/index.html",
    Data: map[string]interface{}{
        "Title":     "Hello Page",
        "MyMessage": "Welcome to my awesome website",
    },
}

// Get will return a predefined view with bind data.
//
// `mvc.Result` is just an interface with a `Dispatch` function.
// `mvc.Response` and `mvc.View` are the built'n result type dispatchers
// you can even create custom response dispatchers by
// implementing the `github.com/kataras/iris/mvc#Result` interface.
func (c *HelloController) Get() mvc.Result {
    return helloView
}

// you can define a standard error in order to be re-usable anywhere in your app.
var errBadName = errors.New("bad name")

// you can just return it as error or even better
// wrap this error with an mvc.Response to make it an mvc.Result compatible type.
var badName = mvc.Response{Err: errBadName, Code: 400}

// GetBy returns a "Hello {name}" response.
// Demos:
// curl -i http://localhost:8080/hello/iris
// curl -i http://localhost:8080/hello/anything
func (c *HelloController) GetBy(name string) mvc.Result {
    if name != "iris" {
        return badName
        // or
        // GetBy(name string) (mvc.Result, error) {
        //  return nil, errBadName
        // }
    }

    // return mvc.Response{Text: "Hello " + name} OR:
    return mvc.View{
        Name: "hello/name.html",
        Data: name,
    }
}

// file: web/middleware/basicauth.go

package middleware

import "github.com/kataras/iris/middleware/basicauth"

// BasicAuth middleware sample.
var BasicAuth = basicauth.New(basicauth.Config{
    Users: map[string]string{
        "admin": "password",
    },
})

<!-- file: web/views/hello/index.html -->
<html>

<head>
    <title>{{.Title}} - My App</title>
</head>

<body>
    <p>{{.MyMessage}}</p>
</body>

</html>

<!-- file: web/views/hello/name.html -->
<html>

<head>
    <title>{{.}}' Portfolio - My App</title>
</head>

<body>
    <h1>Hello {{.}}</h1>
</body>

</html>

Navigate to the _examples/view for more examples like shared layouts, tmpl funcs, reverse routing and more!

Main

This file creates any necessary component and links them together.

// file: main.go

package main

import (
    "github.com/kataras/iris/_examples/mvc/overview/datasource"
    "github.com/kataras/iris/_examples/mvc/overview/repositories"
    "github.com/kataras/iris/_examples/mvc/overview/services"
    "github.com/kataras/iris/_examples/mvc/overview/web/controllers"
    "github.com/kataras/iris/_examples/mvc/overview/web/middleware"

    "github.com/kataras/iris"
)

func main() {
    app := iris.New()

    // Load the template files.
    app.RegisterView(iris.HTML("./web/views", ".html"))

    // Register our controllers.
    app.Controller("/hello", new(controllers.HelloController))

    // Create our movie repository with some (memory) data from the datasource.
    repo := repositories.NewMovieRepository(datasource.Movies)
    // Create our movie service, we will bind it to the movie controller.
    movieService := services.NewMovieService(repo)

    app.Controller("/movies", new(controllers.MovieController),
        // Bind the "movieService" to the MovieController's Service (interface) field.
        movieService,
        // Add the basic authentication(admin:password) middleware
        // for the /movies based requests.
        middleware.BasicAuth)

    // Start the web server at localhost:8080
    // http://localhost:8080/hello
    // http://localhost:8080/hello/iris
    // http://localhost:8080/movies
    // http://localhost:8080/movies/1
    app.Run(
        iris.Addr("localhost:8080"),
        iris.WithoutVersionChecker,
        iris.WithoutServerError(iris.ErrServerClosed),
        iris.WithOptimizations, // enables faster json serialization and more
    )
}

More folder structure guidelines can be found at the _examples/#structuring section.

Now you are ready to move to the next step and get closer to becoming a pro gopher

Congratulations, since you've made it so far, we've crafted just for you some next level content to turn you into a real pro gopher 😃

Don't forget to prepare yourself a cup of coffee, or tea, whatever enjoys you the most!

People

The author of Iris is @kataras, you can reach him via;

List of all Authors

List of all Contributors

Help this project to continue deliver awesome and unique features with the higher code quality as possible by donating any amount via PayPal or BTC.

For more information about contributing to the Iris project please check the CONTRIBUTING.md file.

We need your help with translations into your native language

Iris needs your help, please think about contributing to the translation of the README and https://iris-go.com, you will be rewarded.

Instructions can be found at: https://github.com/kataras/iris/issues/796

03, October 2017 | Iris User Experience Report

Be part of the first Iris User Experience Report by submitting a simple form, it won't take more than 2 minutes.

The form contains some questions that you may need to answer in order to learn more about you; learning more about you helps us to serve you with the best possible way!

https://docs.google.com/forms/d/e/1FAIpQLSdCxZXPANg_xHWil4kVAdhmh7EBBHQZ_4_xSZVDL-oCC_z5pA/viewform?usp=sf_link

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Become a sponsor

License

Iris is licensed under the 3-Clause BSD License. Iris is 100% open-source software.

For any questions regarding the license please contact us.

Documentation

Overview

Package iris provides a beautifully expressive and easy to use foundation for your next website, API, or distributed app.

Source code and other details for the project are available at GitHub: 

https://github.com/kataras/iris

Current Version

8.5.9 Final

Installation

The only requirement is the Go Programming Language, at least version 1.8 but 1.9 is highly recommended.

Iris takes advantage of the vendor directory feature wisely: https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo. You get truly reproducible builds, as this method guards against upstream renames and deletes.

A simple copy-paste and `go get ./...` to resolve two dependencies: https://github.com/kataras/golog and the https://github.com/iris-contrib/httpexpect will work for ever even for older versions, the newest version can be retrieved by `go get` but this file contains documentation for an older version of Iris.

Follow the instructions below:

1. install the Go Programming Language: https://golang.org/dl 2. clear yours previously `$GOPATH/src/github.com/kataras/iris` folder or create new 3. download the Iris v8.5.9 (final): https://github.com/kataras/iris/archive/v8.zip 4. extract the contents of the `iris-v8` folder that's inside the downloaded zip file to your `$GOPATH/src/github.com/kataras/iris` 5. navigate to your `$GOPATH/src/github.com/kataras/iris` folder if you're not already there and open a terminal/command prompt, execute the command: `go get ./...` and you're ready to GO:)

Example code: 

package main

import "github.com/kataras/iris"

// User is just a bindable object structure.
type User struct {
    Username  string `json:"username"`
    Firstname string `json:"firstname"`
    Lastname  string `json:"lastname"`
    City      string `json:"city"`
    Age       int    `json:"age"`
}

func main() {
    app := iris.New()

    // Define templates using the std html/template engine.
    // Parse and load all files inside "./views" folder with ".html" file extension.
    // Reload the templates on each request (development mode).
    app.RegisterView(iris.HTML("./views", ".html").Reload(true))

    // Register custom handler for specific http errors.
    app.OnErrorCode(iris.StatusInternalServerError, func(ctx iris.Context) {
        // .Values are used to communicate between handlers, middleware.
        errMessage := ctx.Values().GetString("error")
        if errMessage != "" {
            ctx.Writef("Internal server error: %s", errMessage)
            return
        }

        ctx.Writef("(Unexpected) internal server error")
    })

    app.Use(func(ctx iris.Context) {
        ctx.Application().Logger().Infof("Begin request for path: %s", ctx.Path())
        ctx.Next()
    })

    // app.Done(func(ctx iris.Context) {})

    // Method POST: http://localhost:8080/decode
    app.Post("/decode", func(ctx iris.Context) {
        var user User
        ctx.ReadJSON(&user)
        ctx.Writef("%s %s is %d years old and comes from %s", user.Firstname, user.Lastname, user.Age, user.City)
    })

    // Method GET: http://localhost:8080/encode
    app.Get("/encode", func(ctx iris.Context) {
        doe := User{
            Username:  "Johndoe",
            Firstname: "John",
            Lastname:  "Doe",
            City:      "Neither FBI knows!!!",
            Age:       25,
        }

        ctx.JSON(doe)
    })

    // Method GET: http://localhost:8080/profile/anytypeofstring
    app.Get("/profile/{username:string}", profileByUsername)

    // Want to use a custom regex expression instead?
    // Easy: app.Get("/profile/{username:string regexp(^[a-zA-Z ]+$)}")
    //
    // If parameter type is missing then it's string which accepts anything,
    // i.e: /{paramname} it's exactly the same as /{paramname:string}.

    usersRoutes := app.Party("/users", logThisMiddleware)
    {
        // Method GET: http://localhost:8080/users/42
        usersRoutes.Get("/{id:int min(1)}", getUserByID)
        // Method POST: http://localhost:8080/users/create
        usersRoutes.Post("/create", createUser)
    }

    // Listen for incoming HTTP/1.x & HTTP/2 clients on localhost port 8080.
    app.Run(iris.Addr(":8080"), iris.WithCharset("UTF-8"))
}

func logThisMiddleware(ctx iris.Context) {
    ctx.Application().Logger().Infof("Path: %s | IP: %s", ctx.Path(), ctx.RemoteAddr())

    // .Next is required to move forward to the chain of handlers,
    // if missing then it stops the execution at this handler.
    ctx.Next()
}

func profileByUsername(ctx iris.Context) {
    // .Params are used to get dynamic path parameters.
    username := ctx.Params().Get("username")
    ctx.ViewData("Username", username)
    // renders "./views/users/profile.html"
    // with {{ .Username }} equals to the username dynamic path parameter.
    ctx.View("users/profile.html")
}

func getUserByID(ctx iris.Context) {
    userID := ctx.Params().Get("id") // Or convert directly using: .Values().GetInt/GetInt64 etc...
    // your own db fetch here instead of user :=...
    user := User{Username: "username" + userID}

    ctx.XML(user)
}

func createUser(ctx iris.Context) {
    var user User
    err := ctx.ReadForm(&user)
    if err != nil {
        ctx.Values().Set("error", "creating user, read and parse form failed. "+err.Error())
        ctx.StatusCode(iris.StatusInternalServerError)
        return
    }
    // renders "./views/users/create_verification.html"
    // with {{ . }} equals to the User object, i.e {{ .Username }} , {{ .Firstname}} etc...
    ctx.ViewData("", user)
    ctx.View("users/create_verification.html")
}

Listening and gracefully shutdown

You can start the server(s) listening to any type of `net.Listener` or even `http.Server` instance. The method for initialization of the server should be passed at the end, via `Run` function.

Below you'll see some useful examples: 

// Listening on tcp with network address 0.0.0.0:8080
app.Run(iris.Addr(":8080"))

// Same as before but using a custom http.Server which may be in use somewhere else too
app.Run(iris.Server(&http.Server{Addr:":8080"}))

// Using a custom net.Listener
l, err := net.Listen("tcp4", ":8080")
if err != nil {
    panic(err)
}
app.Run(iris.Listener(l))

// TLS using files
app.Run(iris.TLS("127.0.0.1:443", "mycert.cert", "mykey.key"))

// Automatic TLS
app.Run(iris.AutoTLS(":443", "example.com", "admin@example.com"))

// UNIX socket
if errOs := os.Remove(socketFile); errOs != nil && !os.IsNotExist(errOs) {
    app.Logger().Fatal(errOs)
}

l, err := net.Listen("unix", socketFile)

if err != nil {
    app.Logger().Fatal(err)
}

if err = os.Chmod(socketFile, mode); err != nil {
    app.Logger().Fatal(err)
}

app.Run(iris.Listener(l))

// Using any func() error,
// the responsibility of starting up a listener is up to you with this way,
// for the sake of simplicity we will use the
// ListenAndServe function of the `net/http` package.
app.Run(iris.Raw(&http.Server{Addr:":8080"}).ListenAndServe)

UNIX and BSD hosts can take advandage of the reuse port feature.

Example code: 

package main

import (
    // Package tcplisten provides customizable TCP net.Listener with various
    // performance-related options:
    //
    //   - SO_REUSEPORT. This option allows linear scaling server performance
    //     on multi-CPU servers.
    //     See https://www.nginx.com/blog/socket-sharding-nginx-release-1-9-1/ for details.
    //
    //   - TCP_DEFER_ACCEPT. This option expects the server reads from the accepted
    //     connection before writing to them.
    //
    //   - TCP_FASTOPEN. See https://lwn.net/Articles/508865/ for details.
    "github.com/valyala/tcplisten"

    "github.com/kataras/iris"
)

// $ go get github.com/valyala/tcplisten
// $ go run main.go

func main() {
    app := iris.New()

    app.Get("/", func(ctx iris.Context) {
        ctx.HTML("<b>Hello World!</b>")
    })

    listenerCfg := tcplisten.Config{
        ReusePort:   true,
        DeferAccept: true,
        FastOpen:    true,
    }

    l, err := listenerCfg.NewListener("tcp", ":8080")
    if err != nil {
        panic(err)
    }

    app.Run(iris.Listener(l))
}

That's all with listening, you have the full control when you need it.

Let's continue by learning how to catch CONTROL+C/COMMAND+C or unix kill command and shutdown the server gracefully. 

Gracefully Shutdown on CONTROL+C/COMMAND+C or when kill command sent is ENABLED BY-DEFAULT.

In order to manually manage what to do when app is interrupted, we have to disable the default behavior with the option `WithoutInterruptHandler` and register a new interrupt handler (globally, across all possible hosts).

Example code: 

package main

import (
    stdContext "context"
    "time"

    "github.com/kataras/iris"
)

func main() {
    app := iris.New()

    iris.RegisterOnInterrupt(func() {
        timeout := 5 * time.Second
        ctx, cancel := stdContext.WithTimeout(stdContext.Background(), timeout)
        defer cancel()
        // close all hosts
        app.Shutdown(ctx)
    })

    app.Get("/", func(ctx iris.Context) {
        ctx.HTML(" <h1>hi, I just exist in order to see if the server is closed</h1>")
    })

    // http://localhost:8080
    app.Run(iris.Addr(":8080"), iris.WithoutInterruptHandler)
}

Hosts

Access to all hosts that serve your application can be provided by the `Application#Hosts` field, after the `Run` method.

But the most common scenario is that you may need access to the host before the `Run` method, there are two ways of gain access to the host supervisor, read below.

First way is to use the `app.NewHost` to create a new host and use one of its `Serve` or `Listen` functions to start the application via the `iris#Raw` Runner. Note that this way needs an extra import of the `net/http` package.

Example Code: 

h := app.NewHost(&http.Server{Addr:":8080"})
h.RegisterOnShutdown(func(){
    println("terminate")
})

app.Run(iris.Raw(h.ListenAndServe))

Second, and probably easier way is to use the `host.Configurator`.

Note that this method requires an extra import statement of "github.com/kataras/iris/core/host" when using go < 1.9, if you're targeting on go1.9 then you can use the `iris#Supervisor` and omit the extra host import.

All common `Runners` we saw earlier (`iris#Addr, iris#Listener, iris#Server, iris#TLS, iris#AutoTLS`) accept a variadic argument of `host.Configurator`, there are just `func(*host.Supervisor)`. Therefore the `Application` gives you the rights to modify the auto-created host supervisor through these.

Example Code: 

package main

import (
    stdContext "context"
    "time"

    "github.com/kataras/iris"
    "github.com/kataras/iris/core/host"
)

func main() {
    app := iris.New()

    app.Get("/", func(ctx iris.Context) {
        ctx.HTML("<h1>Hello, try to refresh the page after ~10 secs</h1>")
    })

    app.Logger().Info("Wait 10 seconds and check your terminal again")
    // simulate a shutdown action here...
    go func() {
        <-time.After(10 * time.Second)
        timeout := 5 * time.Second
        ctx, cancel := stdContext.WithTimeout(stdContext.Background(), timeout)
        defer cancel()
        // close all hosts, this will notify the callback we had register
        // inside the `configureHost` func.
        app.Shutdown(ctx)
    }()

    // start the server as usual, the only difference is that
    // we're adding a second (optional) function
    // to configure the just-created host supervisor.
    //
    // http://localhost:8080
    // wait 10 seconds and check your terminal.
    app.Run(iris.Addr(":8080", configureHost), iris.WithoutServerError(iris.ErrServerClosed))

}

func configureHost(su *host.Supervisor) {
    // here we have full access to the host that will be created
    // inside the `Run` function.
    //
    // we register a shutdown "event" callback
    su.RegisterOnShutdown(func() {
        println("terminate")
    })
    // su.RegisterOnError
    // su.RegisterOnServe
}

Read more about listening and gracefully shutdown by navigating to: 

https://github.com/kataras/iris/tree/v8/_examples/#http-listening

Routing

All HTTP methods are supported, developers can also register handlers for same paths for 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 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", "/contact", func(ctx iris.Context) {
    ctx.HTML("<h1> Hello from /contact </h1>")
})

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.Handler 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())
}

Grouping Routes

A set of routes that are being groupped by path prefix can (optionally) share the same middleware handlers and template layout. A group can have a nested group too.

`.Party` is being used to group routes, developers can declare an unlimited number of (nested) groups.

Example code: 

users := app.Party("/users", myAuthMiddlewareHandler)

// http://myhost.com/users/42/profile
users.Get("/{id:int}/profile", userProfileHandler)
// http://myhost.com/users/messages/1
users.Get("/inbox/{id:int}", userMessageHandler)

Custom HTTP Errors

iris developers 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
app.OnErrorCode(iris.StatusNotFound, func(ctx iris.Context){
    ctx.View("errors/404.html")
})

app.OnErrorCode(500, func(ctx iris.Context){
    // ...
})

Basic HTTP API

With the help of iris's expressionist router you can build any form of API you desire, with safety.

Example code: 

package main

import "github.com/kataras/iris"

func main() {
    app := iris.New()

    // registers a custom handler for 404 not found http (error) status code,
    // fires when route not found or manually by ctx.StatusCode(iris.StatusNotFound).
    app.OnErrorCode(iris.StatusNotFound, notFoundHandler)

    // GET -> HTTP Method
    // / -> Path
    // func(ctx iris.Context) -> The route's handler.
    //
    // Third receiver should contains the route's handler(s), they are executed by order.
    app.Handle("GET", "/", func(ctx iris.Context) {
        // navigate to the middle of $GOPATH/src/github.com/kataras/iris/context/context.go
        // to overview all context's method (there a lot of them, read that and you will learn how iris works too)
        ctx.HTML("Hello from " + ctx.Path()) // Hello from /
    })

    app.Get("/home", func(ctx iris.Context) {
        ctx.Writef(`Same as app.Handle("GET", "/", [...])`)
    })

    app.Get("/donate", donateHandler, donateFinishHandler)

    // Pssst, don't forget dynamic-path example for more "magic"!
    app.Get("/api/users/{userid:int min(1)}", func(ctx iris.Context) {
        userID, err := ctx.Params().GetInt("userid")

        if err != nil {
            ctx.Writef("error while trying to parse userid parameter," +
                "this will never happen if :int is being used because if it's not integer it will fire Not Found automatically.")
            ctx.StatusCode(iris.StatusBadRequest)
            return
        }

        ctx.JSON(map[string]interface{}{
            // you can pass any custom structured go value of course.
            "user_id": userID,
        })
    })
    // app.Post("/", func(ctx iris.Context){}) -> for POST http method.
    // app.Put("/", func(ctx iris.Context){})-> for "PUT" http method.
    // app.Delete("/", func(ctx iris.Context){})-> for "DELETE" http method.
    // app.Options("/", func(ctx iris.Context){})-> for "OPTIONS" http method.
    // app.Trace("/", func(ctx iris.Context){})-> for "TRACE" http method.
    // app.Head("/", func(ctx iris.Context){})-> for "HEAD" http method.
    // app.Connect("/", func(ctx iris.Context){})-> for "CONNECT" http method.
    // app.Patch("/", func(ctx iris.Context){})-> for "PATCH" http method.
    // app.Any("/", func(ctx iris.Context){}) for all http methods.

    // More than one route can contain the same path with a different http mapped method.
    // You can catch any route creation errors with:
    // route, err := app.Get(...)
    // set a name to a route: route.Name = "myroute"

    // You can also group routes by path prefix, sharing middleware(s) and done handlers.

    adminRoutes := app.Party("/admin", adminMiddleware)

    adminRoutes.Done(func(ctx iris.Context) { // executes always last if ctx.Next()
        ctx.Application().Logger().Infof("response sent to " + ctx.Path())
    })
    // adminRoutes.Layout("/views/layouts/admin.html") // set a view layout for these routes, see more at view examples.

    // GET: http://localhost:8080/admin
    adminRoutes.Get("/", func(ctx iris.Context) {
        // [...]
        ctx.StatusCode(iris.StatusOK) // default is 200 == iris.StatusOK
        ctx.HTML("<h1>Hello from admin/</h1>")

        ctx.Next() // in order to execute the party's "Done" Handler(s)
    })

    // GET: http://localhost:8080/admin/login
    adminRoutes.Get("/login", func(ctx iris.Context) {
        // [...]
    })
    // POST: http://localhost:8080/admin/login
    adminRoutes.Post("/login", func(ctx iris.Context) {
        // [...]
    })

    // subdomains, easier than ever, should add localhost or 127.0.0.1 into your hosts file,
    // etc/hosts on unix or C:/windows/system32/drivers/etc/hosts on windows.
    v1 := app.Party("v1.")
    { // braces are optional, it's just type of style, to group the routes visually.

        // http://v1.localhost:8080
        v1.Get("/", func(ctx iris.Context) {
            ctx.HTML("Version 1 API. go to <a href='" + ctx.Path() + "/api" + "'>/api/users</a>")
        })

        usersAPI := v1.Party("/api/users")
        {
            // http://v1.localhost:8080/api/users
            usersAPI.Get("/", func(ctx iris.Context) {
                ctx.Writef("All users")
            })
            // http://v1.localhost:8080/api/users/42
            usersAPI.Get("/{userid:int}", func(ctx iris.Context) {
                ctx.Writef("user with id: %s", ctx.Params().Get("userid"))
            })
        }
    }

    // wildcard subdomains.
    wildcardSubdomain := app.Party("*.")
    {
        wildcardSubdomain.Get("/", func(ctx iris.Context) {
            ctx.Writef("Subdomain can be anything, now you're here from: %s", ctx.Subdomain())
        })
    }

    // http://localhost:8080
    // http://localhost:8080/home
    // http://localhost:8080/donate
    // http://localhost:8080/api/users/42
    // http://localhost:8080/admin
    // http://localhost:8080/admin/login
    //
    // http://localhost:8080/api/users/0
    // http://localhost:8080/api/users/blabla
    // http://localhost:8080/wontfound
    //
    // if hosts edited:
    //  http://v1.localhost:8080
    //  http://v1.localhost:8080/api/users
    //  http://v1.localhost:8080/api/users/42
    //  http://anything.localhost:8080
    app.Run(iris.Addr(":8080"))
}

func adminMiddleware(ctx iris.Context) {
    // [...]
    ctx.Next() // to move to the next handler, or don't that if you have any auth logic.
}

func donateHandler(ctx iris.Context) {
    ctx.Writef("Just like an inline handler, but it can be " +
        "used by other package, anywhere in your project.")

    // let's pass a value to the next handler
    // Values is the way handlers(or middleware) are communicating between each other.
    ctx.Values().Set("donate_url", "https://github.com/kataras/iris#-people")
    ctx.Next() // in order to execute the next handler in the chain, look donate route.
}

func donateFinishHandler(ctx iris.Context) {
    // values can be any type of object so we could cast the value to a string
    // but iris provides an easy to do that, if donate_url is not defined, then it returns an empty string instead.
    donateURL := ctx.Values().GetString("donate_url")
    ctx.Application().Logger().Infof("donate_url value was: " + donateURL)
    ctx.Writef("\n\nDonate sent(?).")
}

func notFoundHandler(ctx iris.Context) {
    ctx.HTML("Custom route for 404 not found http code, here you can render a view, html, json <b>any valid response</b>.")
}

MVC - Model View Controller

Iris has first-class support for the MVC pattern, you'll not find these stuff anywhere else in the Go world.

Example Code: 

package main

import (
    "github.com/kataras/iris"

    "github.com/kataras/iris/middleware/logger"
    "github.com/kataras/iris/middleware/recover"
)

// This example is equivalent to the
// https://github.com/kataras/iris/blob/v8/_examples/hello-world/main.go
//
// It seems that additional code you
// have to write doesn't worth it
// but remember that, this example
// does not make use of iris mvc features like
// the Model, Persistence or the View engine neither the Session,
// it's very simple for learning purposes,
// probably you'll never use such
// as simple controller anywhere in your app.

func main() {
    app := iris.New()
    // Optionally, add two built'n handlers
    // that can recover from any http-relative panics
    // and log the requests to the terminal.
    app.Use(recover.New())
    app.Use(logger.New())

    app.Controller("/", new(IndexController))
    app.Controller("/ping", new(PingController))
    app.Controller("/hello", new(HelloController))

    // http://localhost:8080
    // http://localhost:8080/ping
    // http://localhost:8080/hello
    app.Run(iris.Addr(":8080"))
}

// IndexController serves the "/".
type IndexController struct {
    // if you build with go1.8 you have to use the mvc package, `mvc.Controller` instead.
    iris.Controller
}

// Get serves
// Method:   GET
// Resource: http://localhost:8080/
func (c *IndexController) Get() {
    c.Ctx.HTML("<b>Welcome!</b>")
}

// PingController serves the "/ping".
type PingController struct {
    iris.Controller
}

// Get serves
// Method:   GET
// Resource: http://localhost:8080/ping
func (c *PingController) Get() {
    c.Ctx.WriteString("pong")
}

// HelloController serves the "/hello".
type HelloController struct {
    iris.Controller
}

// Get serves
// Method:   GET
// Resource: http://localhost:8080/hello
func (c *HelloController) Get() {
    c.Ctx.JSON(iris.Map{"message": "Hello iris web framework."})
}

// Can use more than one, the factory will make sure
// that the correct http methods are being registered for each route
// for this controller, uncomment these if you want:

// func (c *HelloController) Post() {}
// func (c *HelloController) Put() {}
// func (c *HelloController) Delete() {}
// func (c *HelloController) Connect() {}
// func (c *HelloController) Head() {}
// func (c *HelloController) Patch() {}
// func (c *HelloController) Options() {}
// func (c *HelloController) Trace() {}
// or All() or Any() to catch all http methods.

Iris web framework supports Request data, Models, Persistence Data and Binding with the fastest possible execution.

Characteristics:

All HTTP Methods are supported, for example if want to serve `GET` then the controller should have a function named `Get()`, you can define more than one method function to serve in the same Controller struct.

Persistence data inside your Controller struct (share data between requests) via `iris:"persistence"` tag right to the field or Bind using `app.Controller("/" , new(myController), theBindValue)`.

Models inside your Controller struct (set-ed at the Method function and rendered by the View) via `iris:"model"` tag right to the field, i.e User UserModel `iris:"model" name:"user"` view will recognise it as `{{.user}}`. If `name` tag is missing then it takes the field's name, in this case the `"User"`.

Access to the request path and its parameters via the `Path and Params` fields.

Access to the template file that should be rendered via the `Tmpl` field.

Access to the template data that should be rendered inside the template file via `Data` field.

Access to the template layout via the `Layout` field.

Access to the low-level `iris.Context` via the `Ctx` field.

Get the relative request path by using the controller's name via `RelPath()`.

Get the relative template path directory by using the controller's name via `RelTmpl()`.

Flow as you used to, `Controllers` can be registered to any `Party`, including Subdomains, the Party's begin and done handlers work as expected.

Optional `BeginRequest(ctx)` function to perform any initialization before the method execution, useful to call middlewares or when many methods use the same collection of data.

Optional `EndRequest(ctx)` function to perform any finalization after any method executed.

Inheritance, recursively, see for example our `mvc.SessionController/iris.SessionController`, it has the `mvc.Controller/iris.Controller` as an embedded field and it adds its logic to its `BeginRequest`. Source file: https://github.com/kataras/iris/blob/v8/mvc/session_controller.go.

Read access to the current route via the `Route` field.

Support for more than one input arguments (map to dynamic request path parameters).

Register one or more relative paths and able to get path parameters, i.e 

If `app.Controller("/user", new(user.Controller))`

- `func(*Controller) Get()` - `GET:/user` , as usual.
- `func(*Controller) Post()` - `POST:/user`, as usual.
- `func(*Controller) GetLogin()` - `GET:/user/login`
- `func(*Controller) PostLogin()` - `POST:/user/login`
- `func(*Controller) GetProfileFollowers()` - `GET:/user/profile/followers`
- `func(*Controller) PostProfileFollowers()` - `POST:/user/profile/followers`
- `func(*Controller) GetBy(id int64)` - `GET:/user/{param:long}`
- `func(*Controller) PostBy(id int64)` - `POST:/user/{param:long}`
If `app.Controller("/profile", new(profile.Controller))`

- `func(*Controller) GetBy(username string)` - `GET:/profile/{param:string}`

If `app.Controller("/assets", new(file.Controller))`

- `func(*Controller) GetByWildard(path string)` - `GET:/assets/{param:path}`

If `app.Controller("/equality", new(profile.Equality))`

- `func(*Controller) GetBy(is bool)` - `GET:/equality/{param:boolean}`
- `func(*Controller) GetByOtherBy(is bool, otherID int64)` - `GET:/equality/{paramfirst:boolean}/other/{paramsecond:long}`

Supported types for method functions receivers: int, int64, bool and string.

Response via output arguments, optionally, i.e 

func(c *ExampleController) Get() string |
(string, string) |
(string, int) |
(string, error) |
int |
(int, string) |
(any, int) |
error |
(int, error) |
(customStruct, error) |
(any, error) |
bool |
(any, bool)
customStruct |
(customStruct, int) |
(customStruct, string) |
`Result` or (`Result`, error)

Where `any` means everything, from custom structs to standard language's types-. `Result` is an interface which contains only that function: Dispatch(ctx iris.Context) and Get where HTTP Method function(Post, Put, Delete...).

Iris MVC Method Result

Iris has a very powerful and blazing fast MVC support, you can return any value of any type from a method function and it will be sent to the client as expected.

* if `string` then it's the body. * if `string` is the second output argument then it's the content type. * if `int` then it's the status code. * if `bool` is false then it throws 404 not found http error by skipping everything else. * if `error` and not nil then (any type) response will be omitted and error's text with a 400 bad request will be rendered instead. * if `(int, error)` and error is not nil then the response result will be the error's text with the status code as `int`. * if `custom struct` or `interface{}` or `slice` or `map` then it will be rendered as json, unless a `string` content type is following. * if `mvc.Result` then it executes its `Dispatch` function, so good design patters can be used to split the model's logic where needed.

The example below is not intended to be used in production but it's a good showcase of some of the return types we saw before; 

package main

import (
    "github.com/kataras/iris"
    "github.com/kataras/iris/middleware/basicauth"
    "github.com/kataras/iris/mvc"
)

// Movie is our sample data structure.
type Movie struct {
    Name   string `json:"name"`
    Year   int    `json:"year"`
    Genre  string `json:"genre"`
    Poster string `json:"poster"`
}

// movies contains our imaginary data source.
var movies = []Movie{
    {
        Name:   "Casablanca",
        Year:   1942,
        Genre:  "Romance",
        Poster: "https://iris-go.com/images/examples/mvc-movies/1.jpg",
    },
    {
        Name:   "Gone with the Wind",
        Year:   1939,
        Genre:  "Romance",
        Poster: "https://iris-go.com/images/examples/mvc-movies/2.jpg",
    },
    {
        Name:   "Citizen Kane",
        Year:   1941,
        Genre:  "Mystery",
        Poster: "https://iris-go.com/images/examples/mvc-movies/3.jpg",
    },
    {
        Name:   "The Wizard of Oz",
        Year:   1939,
        Genre:  "Fantasy",
        Poster: "https://iris-go.com/images/examples/mvc-movies/4.jpg",
    },
}

var basicAuth = basicauth.New(basicauth.Config{
    Users: map[string]string{
        "admin": "password",
    },
})

func main() {
    app := iris.New()

    app.Use(basicAuth)

    app.Controller("/movies", new(MoviesController))

    app.Run(iris.Addr(":8080"))
}

// MoviesController is our /movies controller.
type MoviesController struct {
    // if you build with go1.8 you have to use the mvc package always,
    // otherwise
    // you can, optionally
    // use the type alias `iris.C`,
    // same for
    // context.Context -> iris.Context,
    // mvc.Result -> iris.Result,
    // mvc.Response -> iris.Response,
    // mvc.View -> iris.View
    mvc.C
}

// Get returns list of the movies
// Demo:
// curl -i http://localhost:8080/movies
func (c *MoviesController) Get() []Movie {
    return movies
}

// GetBy returns a movie
// Demo:
// curl -i http://localhost:8080/movies/1
func (c *MoviesController) GetBy(id int) Movie {
    return movies[id]
}

// PutBy updates a movie
// Demo:
// curl -i -X PUT -F "genre=Thriller" -F "poster=@/Users/kataras/Downloads/out.gif" http://localhost:8080/movies/1
func (c *MoviesController) PutBy(id int) Movie {
    // get the movie
    m := movies[id]

    // get the request data for poster and genre
    file, info, err := c.Ctx.FormFile("poster")
    if err != nil {
        c.Ctx.StatusCode(iris.StatusInternalServerError)
        return Movie{}
    }
    file.Close()            // we don't need the file
    poster := info.Filename // imagine that as the url of the uploaded file...
    genre := c.Ctx.FormValue("genre")

    // update the poster
    m.Poster = poster
    m.Genre = genre
    movies[id] = m

    return m
}

// DeleteBy deletes a movie
// Demo:
// curl -i -X DELETE -u admin:password http://localhost:8080/movies/1
func (c *MoviesController) DeleteBy(id int) iris.Map {
    // delete the entry from the movies slice
    deleted := movies[id].Name
    movies = append(movies[:id], movies[id+1:]...)
    // and return the deleted movie's name
    return iris.Map{"deleted": deleted}
}

Another good example with a typical folder structure, that many developers are used to work, can be found at: https://github.com/kataras/iris/tree/v8/_examples/mvc/overview.

Using Iris MVC for code reuse

By creating components that are independent of one another, developers are able to reuse components quickly and easily in other applications. The same (or similar) view for one application can be refactored for another application with different data because the view is simply handling how the data is being displayed to the user.

If you're new to back-end web development read about the MVC architectural pattern first, a good start is that wikipedia article: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller.

Follow the examples at: https://github.com/kataras/iris/tree/v8/_examples/#mvc

Parameterized Path

At the previous example, we've seen static routes, group of routes, subdomains, wildcard subdomains, a small example of parameterized path with a single known parameter and custom http errors, now it's time to see wildcard parameters and macros.

iris, like net/http std package registers route's handlers by a Handler, the iris' type of handler is just a func(ctx iris.Context) where context comes from github.com/kataras/iris/context.

Iris has the easiest and the most powerful routing process you have ever meet.

At the same time, iris has its own interpeter(yes like a programming language) for route's path syntax and their dynamic path parameters parsing and evaluation, We call them "macros" for shortcut. How? It calculates its needs and if not any special regexp needed then it just registers the route with the low-level path syntax, otherwise it pre-compiles the regexp and adds the necessary middleware(s).

Standard macro types for parameters: 

+------------------------+
| {param:string}         |
+------------------------+
string type
anything

+------------------------+
| {param:int}            |
+------------------------+
int type
only numbers (0-9)

+------------------------+
| {param:long}           |
+------------------------+
int64 type
only numbers (0-9)

+------------------------+
| {param:boolean}        |
+------------------------+
bool type
only "1" or "t" or "T" or "TRUE" or "true" or "True"
or "0" or "f" or "F" or "FALSE" or "false" or "False"

+------------------------+
| {param:alphabetical}   |
+------------------------+
alphabetical/letter type
letters only (upper or lowercase)

+------------------------+
| {param:file}           |
+------------------------+
file type
letters (upper or lowercase)
numbers (0-9)
underscore (_)
dash (-)
point (.)
no spaces ! or other character

+------------------------+
| {param:path}           |
+------------------------+
path type
anything, should be the last part, more than one path segment,
i.e: /path1/path2/path3 , ctx.Params().Get("param") == "/path1/path2/path3"

if type is missing then parameter's type is defaulted to string, so {param} == {param:string}.

If a function not found on that type then the "string"'s types functions are being used. i.e: 

{param:int min(3)}

Besides the fact that iris provides the basic types and some default "macro funcs" you are able to register your own too!.

Register a named path parameter function: 

app.Macros().Int.RegisterFunc("min", func(argument int) func(paramValue string) bool {
    [...]
    return true/false -> true means valid.
})

at the func(argument ...) you can have any standard type, it will be validated before the server starts so don't care about performance here, the only thing it runs at serve time is the returning func(paramValue string) bool. 

{param:string equal(iris)} , "iris" will be the argument here:
app.Macros().String.RegisterFunc("equal", func(argument string) func(paramValue string) bool {
    return func(paramValue string){ return argument == paramValue }
})

Example Code: 

	// you can use the "string" type which is valid for a single path parameter that can be anything.
	app.Get("/username/{name}", func(ctx iris.Context) {
		ctx.Writef("Hello %s", ctx.Params().Get("name"))
	}) // type is missing = {name:string}

	// Let's register our first macro attached to int macro type.
	// "min" = the function
	// "minValue" = the argument of the function
	// func(string) bool = the macro's path parameter evaluator, this executes in serve time when
	// a user requests a path which contains the :int macro type with the min(...) macro parameter function.
	app.Macros().Int.RegisterFunc("min", func(minValue int) func(string) bool {
		// do anything before serve here [...]
		// at this case we don't need to do anything
		return func(paramValue string) bool {
			n, err := strconv.Atoi(paramValue)
			if err != nil {
				return false
			}
			return n >= minValue
		}
	})

	// http://localhost:8080/profile/id>=1
	// this will throw 404 even if it's found as route on : /profile/0, /profile/blabla, /profile/-1
	// macro parameter functions are optional of course.
	app.Get("/profile/{id:int min(1)}", func(ctx iris.Context) {
		// second parameter is the error but it will always nil because we use macros,
		// the validaton already happened.
		id, _ := ctx.Params().GetInt("id")
		ctx.Writef("Hello id: %d", id)
	})

	// to change the error code per route's macro evaluator:
	app.Get("/profile/{id:int min(1)}/friends/{friendid:int min(1) else 504}", func(ctx iris.Context) {
		id, _ := ctx.Params().GetInt("id")
		friendid, _ := ctx.Params().GetInt("friendid")
		ctx.Writef("Hello id: %d looking for friend id: ", id, friendid)
	}) // this will throw e 504 error code instead of 404 if all route's macros not passed.

	// http://localhost:8080/game/a-zA-Z/level/0-9
	// remember, alphabetical is lowercase or uppercase letters only.
	app.Get("/game/{name:alphabetical}/level/{level:int}", func(ctx iris.Context) {
		ctx.Writef("name: %s | level: %s", ctx.Params().Get("name"), ctx.Params().Get("level"))
	})

	// let's use a trivial custom regexp that validates a single path parameter
	// which its value is only lowercase letters.

	// http://localhost:8080/lowercase/anylowercase
	app.Get("/lowercase/{name:string regexp(^[a-z]+)}", func(ctx iris.Context) {
		ctx.Writef("name should be only lowercase, otherwise this handler will never executed: %s", ctx.Params().Get("name"))
	})

	// http://localhost:8080/single_file/app.js
	app.Get("/single_file/{myfile:file}", func(ctx iris.Context) {
		ctx.Writef("file type validates if the parameter value has a form of a file name, got: %s", ctx.Params().Get("myfile"))
	})

	// http://localhost:8080/myfiles/any/directory/here/
	// this is the only macro type that accepts any number of path segments.
	app.Get("/myfiles/{directory:path}", func(ctx iris.Context) {
		ctx.Writef("path type accepts any number of path segments, path after /myfiles/ is: %s", ctx.Params().Get("directory"))
    })

	app.Run(iris.Addr(":8080"))
}

A path parameter name should contain only alphabetical letters, symbols, containing '_' and numbers are NOT allowed. If route failed to be registered, the app will panic without any warnings if you didn't catch the second return value(error) on .Handle/.Get....

Last, do not confuse ctx.Values() with ctx.Params(). Path parameter's values goes to ctx.Params() and context's local storage that can be used to communicate between handlers and middleware(s) goes to ctx.Values(), path parameters and the rest of any custom values are separated for your own good.

Run 

$ go run main.go

Static Files 

// StaticServe serves a directory as web resource
// it's the simpliest form of the Static* functions
// Almost same usage as StaticWeb
// accepts only one required parameter which is the systemPath,
// the same path will be used to register the GET and HEAD method routes.
// If second parameter is empty, otherwise the requestPath is the second parameter
// it uses gzip compression (compression on each request, no file cache).
//
// Returns the GET *Route.
StaticServe(systemPath string, requestPath ...string) (*Route, error)

// StaticContent registers a GET and HEAD method routes to the requestPath
// that are ready to serve raw static bytes, memory cached.
//
// Returns the GET *Route.
StaticContent(reqPath string, cType string, content []byte) (*Route, error)

// StaticEmbedded  used when files are distributed inside the app executable, using go-bindata mostly
// First parameter is the request path, the path which the files in the vdir will be served to, for example "/static"
// Second parameter is the (virtual) directory path, for example "./assets"
// Third parameter is the Asset function
// Forth parameter is the AssetNames function.
//
// Returns the GET *Route.
//
// Example: https://github.com/kataras/iris/tree/v8/_examples/file-server/embedding-files-into-app
StaticEmbedded(requestPath string, vdir string, assetFn func(name string) ([]byte, error), namesFn func() []string) (*Route, error)

// Favicon serves static favicon
// accepts 2 parameters, second is optional
// favPath (string), declare the system directory path of the __.ico
// requestPath (string), it's the route's path, by default this is the "/favicon.ico" because some browsers tries to get this by default first,
// you can declare your own path if you have more than one favicon (desktop, mobile and so on)
//
// this func will add a route for you which will static serve the /yuorpath/yourfile.ico to the /yourfile.ico
// (nothing special that you can't handle by yourself).
// Note that you have to call it on every favicon you have to serve automatically (desktop, mobile and so on).
//
// Returns the GET *Route.
Favicon(favPath string, requestPath ...string) (*Route, error)

// StaticWeb returns a handler that serves HTTP requests
// with the contents of the file system rooted at directory.
//
// first parameter: the route path
// second parameter: the system directory
// third OPTIONAL parameter: the exception routes
//      (= give priority to these routes instead of the static handler)
// for more options look app.StaticHandler.
//
//     app.StaticWeb("/static", "./static")
//
// As a special case, the returned file server redirects any request
// ending in "/index.html" to the same path, without the final
// "index.html".
//
// StaticWeb calls the StaticHandler(systemPath, listingDirectories: false, gzip: false ).
//
// Returns the GET *Route.
StaticWeb(requestPath string, systemPath string, exceptRoutes ...*Route) (*Route, error)

Example code: 

package main

import "github.com/kataras/iris"

func main() {
    app := iris.New()

    // This will serve the ./static/favicons/ion_32_32.ico to: localhost:8080/favicon.ico
    app.Favicon("./static/favicons/ion_32_32.ico")

    // app.Favicon("./static/favicons/ion_32_32.ico", "/favicon_48_48.ico")
    // This will serve the ./static/favicons/ion_32_32.ico to: localhost:8080/favicon_48_48.ico

    app.Get("/", func(ctx iris.Context) {
        ctx.HTML(`<a href="/favicon.ico"> press here to see the favicon.ico</a>.
        At some browsers like chrome, it should be visible at the top-left side of the browser's window,
        because some browsers make requests to the /favicon.ico automatically,
        so iris serves your favicon in that path too (you can change it).`)
    }) // if favicon doesn't show to you, try to clear your browser's cache.

    app.Run(iris.Addr(":8080"))
}

More examples can be found here: https://github.com/kataras/iris/tree/v8/_examples/beginner/file-server

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.Use(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.UseGlobal(handler1, handler2, handler3)

// 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.Use(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 is able to wrap and convert any external, third-party Handler you used to use to your web application. 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"

    "github.com/kataras/iris"
)

func main() {

    app := iris.New()
    corsOptions := cors.Options{
        AllowedOrigins:   []string{"*"},
        AllowCredentials: true,
    }

    corsWrapper := cors.New(corsOptions).ServeHTTP

    app.WrapRouter(corsWrapper)

    v1 := app.Party("/api/v1")
    {
        v1.Get("/", h)
        v1.Put("/put", h)
        v1.Post("/post", h)
    }

    app.Run(iris.Addr(":8080"))
}

func h(ctx iris.Context) {
    ctx.Application().Logger().Infof(ctx.Path())
    ctx.Writef("Hello from %s", ctx.Path())
}

View Engine

Iris supports 5 template engines out-of-the-box, developers can still use any external golang template engine, as `context/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,
its template parser is the golang.org/pkg/html/template/

Django,
its template parser is the github.com/flosch/pongo2

Pug(Jade),
its template parser is the github.com/Joker/jade

Handlebars,
its template parser is the github.com/aymerick/raymond

Amber,
its template parser is the github.com/eknkc/amber

Example code: 

package main

import "github.com/kataras/iris"

func main() {
    app := iris.New()

    // - standard html  | iris.HTML(...)
    // - django         | iris.Django(...)
    // - pug(jade)      | iris.Pug(...)
    // - handlebars     | iris.Handlebars(...)
    // - amber          | iris.Amber(...)

    tmpl := iris.HTML("./templates", ".html")
    tmpl.Reload(true) // reload templates on each request (development mode)
    // default template funcs are:
    //
    // - {{ urlpath "mynamedroute" "pathParameter_ifneeded" }}
    // - {{ render "header.html" }}
    // - {{ render_r "header.html" }} // partial relative path to current page
    // - {{ yield }}
    // - {{ current }}

    // register a custom template func.
    tmpl.AddFunc("greet", func(s string) string {
        return "Greetings " + s + "!"
    })

    // register the view engine to the views, this will load the templates.
    app.RegisterView(tmpl)

    app.Get("/", hi)

    // http://localhost:8080
    app.Run(iris.Addr(":8080"), iris.WithCharset("UTF-8")) // defaults to that but you can change it.
}

func hi(ctx iris.Context) {
    ctx.ViewData("Title", "Hi Page")
    ctx.ViewData("Name", "iris") // {{.Name}} will render: iris
    // ctx.ViewData("", myCcustomStruct{})
    ctx.View("hi.html")
}

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: 

package main

import "github.com/kataras/iris"

func main() {
    app := iris.New()
    // $ go get -u github.com/jteeuwen/go-bindata/...
    // $ go-bindata ./templates/...
    // $ go build
    // $ ./embedding-templates-into-app
    // html files are not used, you can delete the folder and run the example
    app.RegisterView(iris.HTML("./templates", ".html").Binary(Asset, AssetNames))
    app.Get("/", hi)

    // http://localhost:8080
    app.Run(iris.Addr(":8080"))
}

type page struct {
    Title, Name string
}

func hi(ctx iris.Context) {
    ctx.ViewData("", page{Title: "Hi Page", Name: "iris"})
    ctx.View("hi.html")
}

A real example can be found here: https://github.com/kataras/iris/tree/v8/_examples/view/embedding-templates-into-app.

Enable auto-reloading of templates on each request. Useful while developers are in dev mode as they no neeed to restart their app on every template edit.

Example code: 

pugEngine := iris.Pug("./templates", ".jade")
pugEngine.Reload(true) // <--- set to true to re-build the templates on each request.
app.RegisterView(pugEngine)

Note:

In case you're wondering, the code behind the view engines derives from the "github.com/kataras/iris/view" package, access to the engines' variables can be granded by "github.com/kataras/iris" package too. 

iris.HTML(...) is a shortcut of view.HTML(...)
iris.Django(...)     >> >>      view.Django(...)
iris.Pug(...)        >> >>      view.Pug(...)
iris.Handlebars(...) >> >>      view.Handlebars(...)
iris.Amber(...)      >> >>      view.Amber(...)

Each one of these template engines has different options located here: https://github.com/kataras/iris/tree/v8/view .

Sessions

This example will show how to store and access data from a session.

You don’t need any third-party library, but If you want you can use any session manager compatible or not.

In this example we will only allow authenticated users to view our secret message on the /secret page. To get access to it, the will first have to visit /login to get a valid session cookie, which logs him in. Additionally he can visit /logout to revoke his access to our secret message.

Example code: 

// main.go
package main

import (
    "github.com/kataras/iris"

    "github.com/kataras/iris/sessions"
)

var (
    cookieNameForSessionID = "mycookiesessionnameid"
    sess                   = sessions.New(sessions.Config{Cookie: cookieNameForSessionID})
)

func secret(ctx iris.Context) {

    // Check if user is authenticated
    if auth, _ := sess.Start(ctx).GetBoolean("authenticated"); !auth {
        ctx.StatusCode(iris.StatusForbidden)
        return
    }

    // Print secret message
    ctx.WriteString("The cake is a lie!")
}

func login(ctx iris.Context) {
    session := sess.Start(ctx)

    // Authentication goes here
    // ...

    // Set user as authenticated
    session.Set("authenticated", true)
}

func logout(ctx iris.Context) {
    session := sess.Start(ctx)

    // Revoke users authentication
    session.Set("authenticated", false)
}

func main() {
    app := iris.New()

    app.Get("/secret", secret)
    app.Get("/login", login)
    app.Get("/logout", logout)

    app.Run(iris.Addr(":8080"))
}

Running the example: 

$ go get github.com/kataras/iris/sessions
$ go run main.go

$ curl -s http://localhost:8080/secret
Forbidden

$ curl -s -I http://localhost:8080/login
Set-Cookie: mycookiesessionnameid=MTQ4NzE5Mz...

$ curl -s --cookie "mycookiesessionnameid=MTQ4NzE5Mz..." http://localhost:8080/secret
The cake is a lie!

Sessions persistence can be achieved using one (or more) `sessiondb`.

Example Code: 

package main

import (
    "time"

    "github.com/kataras/iris"

    "github.com/kataras/iris/sessions"
    "github.com/kataras/iris/sessions/sessiondb/boltdb" // <- IMPORTANT
)

func main() {
    db, _ := boltdb.New("./sessions/sessions.db", 0666, "users")
    // use different go routines to sync the database
    db.Async(true)

    // close and unlock the database when control+C/cmd+C pressed
    iris.RegisterOnInterrupt(func() {
        db.Close()
    })

    sess := sessions.New(sessions.Config{
        Cookie:  "sessionscookieid",
        Expires: 45 * time.Minute, // <=0 means unlimited life
    })

    //
    // IMPORTANT:
    //
    sess.UseDatabase(db)

    // the rest of the code stays the same.
    app := iris.New()

    app.Get("/", func(ctx iris.Context) {
        ctx.Writef("You should navigate to the /set, /get, /delete, /clear,/destroy instead")
    })
    app.Get("/set", func(ctx iris.Context) {
        s := sess.Start(ctx)
        //set session values
        s.Set("name", "iris")

        //test if setted here
        ctx.Writef("All ok session setted to: %s", s.GetString("name"))
    })

    app.Get("/set/{key}/{value}", func(ctx iris.Context) {
        key, value := ctx.Params().Get("key"), ctx.Params().Get("value")
        s := sess.Start(ctx)
        // set session values
        s.Set(key, value)

        // test if setted here
        ctx.Writef("All ok session setted to: %s", s.GetString(key))
    })

    app.Get("/get", func(ctx iris.Context) {
        // get a specific key, as string, if no found returns just an empty string
        name := sess.Start(ctx).GetString("name")

        ctx.Writef("The name on the /set was: %s", name)
    })

    app.Get("/get/{key}", func(ctx iris.Context) {
        // get a specific key, as string, if no found returns just an empty string
        name := sess.Start(ctx).GetString(ctx.Params().Get("key"))

        ctx.Writef("The name on the /set was: %s", name)
    })

    app.Get("/delete", func(ctx iris.Context) {
        // delete a specific key
        sess.Start(ctx).Delete("name")
    })

    app.Get("/clear", func(ctx iris.Context) {
        // removes all entries
        sess.Start(ctx).Clear()
    })

    app.Get("/destroy", func(ctx iris.Context) {
        //destroy, removes the entire session data and cookie
        sess.Destroy(ctx)
    })

    app.Get("/update", func(ctx iris.Context) {
        // updates expire date with a new date
        sess.ShiftExpiration(ctx)
    })

    app.Run(iris.Addr(":8080"))
}

More examples: 

https://github.com/kataras/iris/tree/v8/sessions

Websockets

In this example we will create a small chat between web sockets via browser.

Example Server Code: 

// main.go
package main

import (
    "fmt"

    "github.com/kataras/iris"

    "github.com/kataras/iris/websocket"
)

func main() {
    app := iris.New()

    app.Get("/", func(ctx iris.Context) {
        ctx.ServeFile("websockets.html", false) // second parameter: enable gzip?
    })

    setupWebsocket(app)

    // x2
    // http://localhost:8080
    // http://localhost:8080
    // write something, press submit, see the result.
    app.Run(iris.Addr(":8080"))
}

func setupWebsocket(app *iris.Application) {
    // create our echo websocket server
    ws := websocket.New(websocket.Config{
        ReadBufferSize:  1024,
        WriteBufferSize: 1024,
    })
    ws.OnConnection(handleConnection)

    // register the server on an endpoint.
    // see the inline javascript code i the websockets.html, this endpoint is used to connect to the server.
    app.Get("/echo", ws.Handler())

    // serve the javascript built'n client-side library,
    // see weboskcets.html script tags, this path is used.
    app.Any("/iris-ws.js", func(ctx iris.Context) {
        ctx.Write(websocket.ClientSource)
    })
}

func handleConnection(c websocket.Connection) {
    // Read events from browser
    c.On("chat", func(msg string) {
        // Print the message to the console, c.Context() is the iris's http context.
        fmt.Printf("%s sent: %s\n", c.Context().RemoteAddr(), msg)
        // Write message back to the client message owner:
        // c.Emit("chat", msg)
        c.To(websocket.Broadcast).Emit("chat", msg)
    })
}

Example Client(javascript) Code: 

<!-- websockets.html -->
<input id="input" type="text" />
<button onclick="send()">Send</button>
<pre id="output"></pre>
<script src="/iris-ws.js"></script>
<script>
    var input = document.getElementById("input");
    var output = document.getElementById("output");

    // Ws comes from the auto-served '/iris-ws.js'
    var socket = new Ws("ws://localhost:8080/echo");
    socket.OnConnect(function () {
        output.innerHTML += "Status: Connected\n";
    });

    socket.OnDisconnect(function () {
        output.innerHTML += "Status: Disconnected\n";
    });

    // read events from the server
    socket.On("chat", function (msg) {
        addMessage(msg)
    });

    function send() {
        addMessage("Me: "+input.value) // write ourselves
        socket.Emit("chat", input.value);// send chat event data to the websocket server
        input.value = ""; // clear the input
    }

    function addMessage(msg) {
        output.innerHTML += msg + "\n";
    }
</script>

Running the example: 

$ go get github.com/kataras/iris/websocket
$ go run main.go
$ start http://localhost:8080

That's the basics

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/kataras/iris/tree/v8/_examples

Middleware: 

https://github.com/kataras/iris/tree/v8/middleware
https://github.com/iris-contrib/middleware/tree/v8

Home Page: 

https://iris-go.com

Index

Constants

View Source 
const (
	StatusContinue           = 100 // RFC 7231, 6.2.1
	StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2
	StatusProcessing         = 102 // RFC 2518, 10.1

	StatusOK                   = 200 // RFC 7231, 6.3.1
	StatusCreated              = 201 // RFC 7231, 6.3.2
	StatusAccepted             = 202 // RFC 7231, 6.3.3
	StatusNonAuthoritativeInfo = 203 // RFC 7231, 6.3.4
	StatusNoContent            = 204 // RFC 7231, 6.3.5
	StatusResetContent         = 205 // RFC 7231, 6.3.6
	StatusPartialContent       = 206 // RFC 7233, 4.1
	StatusMultiStatus          = 207 // RFC 4918, 11.1
	StatusAlreadyReported      = 208 // RFC 5842, 7.1
	StatusIMUsed               = 226 // RFC 3229, 10.4.1

	StatusMultipleChoices  = 300 // RFC 7231, 6.4.1
	StatusMovedPermanently = 301 // RFC 7231, 6.4.2
	StatusFound            = 302 // RFC 7231, 6.4.3
	StatusSeeOther         = 303 // RFC 7231, 6.4.4
	StatusNotModified      = 304 // RFC 7232, 4.1
	StatusUseProxy         = 305 // RFC 7231, 6.4.5

	StatusTemporaryRedirect = 307 // RFC 7231, 6.4.7
	StatusPermanentRedirect = 308 // RFC 7538, 3

	StatusBadRequest                   = 400 // RFC 7231, 6.5.1
	StatusUnauthorized                 = 401 // RFC 7235, 3.1
	StatusPaymentRequired              = 402 // RFC 7231, 6.5.2
	StatusForbidden                    = 403 // RFC 7231, 6.5.3
	StatusNotFound                     = 404 // RFC 7231, 6.5.4
	StatusMethodNotAllowed             = 405 // RFC 7231, 6.5.5
	StatusNotAcceptable                = 406 // RFC 7231, 6.5.6
	StatusProxyAuthRequired            = 407 // RFC 7235, 3.2
	StatusRequestTimeout               = 408 // RFC 7231, 6.5.7
	StatusConflict                     = 409 // RFC 7231, 6.5.8
	StatusGone                         = 410 // RFC 7231, 6.5.9
	StatusLengthRequired               = 411 // RFC 7231, 6.5.10
	StatusPreconditionFailed           = 412 // RFC 7232, 4.2
	StatusRequestEntityTooLarge        = 413 // RFC 7231, 6.5.11
	StatusRequestURITooLong            = 414 // RFC 7231, 6.5.12
	StatusUnsupportedMediaType         = 415 // RFC 7231, 6.5.13
	StatusRequestedRangeNotSatisfiable = 416 // RFC 7233, 4.4
	StatusExpectationFailed            = 417 // RFC 7231, 6.5.14
	StatusTeapot                       = 418 // RFC 7168, 2.3.3
	StatusUnprocessableEntity          = 422 // RFC 4918, 11.2
	StatusLocked                       = 423 // RFC 4918, 11.3
	StatusFailedDependency             = 424 // RFC 4918, 11.4
	StatusUpgradeRequired              = 426 // RFC 7231, 6.5.15
	StatusPreconditionRequired         = 428 // RFC 6585, 3
	StatusTooManyRequests              = 429 // RFC 6585, 4
	StatusRequestHeaderFieldsTooLarge  = 431 // RFC 6585, 5
	StatusUnavailableForLegalReasons   = 451 // RFC 7725, 3

	StatusInternalServerError           = 500 // RFC 7231, 6.6.1
	StatusNotImplemented                = 501 // RFC 7231, 6.6.2
	StatusBadGateway                    = 502 // RFC 7231, 6.6.3
	StatusServiceUnavailable            = 503 // RFC 7231, 6.6.4
	StatusGatewayTimeout                = 504 // RFC 7231, 6.6.5
	StatusHTTPVersionNotSupported       = 505 // RFC 7231, 6.6.6
	StatusVariantAlsoNegotiates         = 506 // RFC 2295, 8.1
	StatusInsufficientStorage           = 507 // RFC 4918, 11.5
	StatusLoopDetected                  = 508 // RFC 5842, 7.2
	StatusNotExtended                   = 510 // RFC 2774, 7
	StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6
)

HTTP status codes as registered with IANA. See: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml Raw Copy from the net/http std package in order to recude the import path of "net/http" for the users.

Copied from `net/http` package.

View Source 
const (
	MethodGet     = "GET"
	MethodPost    = "POST"
	MethodPut     = "PUT"
	MethodDelete  = "DELETE"
	MethodConnect = "CONNECT"
	MethodHead    = "HEAD"
	MethodPatch   = "PATCH"
	MethodOptions = "OPTIONS"
	MethodTrace   = "TRACE"
)

HTTP Methods copied from `net/http`.

View Source 
const MethodNone = "NONE"

MethodNone is an iris-specific "virtual" method to store the "offline" routes.

View Source 
const NoLayout = view.NoLayout

NoLayout to disable layout for a particular template file A shortcut for the `view#NoLayout`.

Variables

View Source 
var (
	// HTML view engine.
	// Conversion for the view.HTML.
	HTML = view.HTML
	// Django view engine.
	// Conversion for the view.Django.
	Django = view.Django
	// Handlebars view engine.
	// Conversion for the view.Handlebars.
	Handlebars = view.Handlebars
	// Pug view engine.
	// Conversion for the view.Pug.
	Pug = view.Pug
	// Amber view engine.
	// Conversion for the view.Amber.
	Amber = view.Amber
)
View Source 
var (
	// LimitRequestBodySize is a middleware which sets a request body size limit
	// for all next handlers in the chain.
	//
	// A shortcut for the `context#LimitRequestBodySize`.
	LimitRequestBodySize = context.LimitRequestBodySize
	// StaticEmbeddedHandler returns a Handler which can serve
	// embedded into executable files.
	//
	//
	// Examples: https://github.com/kataras/iris/tree/v8/_examples/file-server
	StaticEmbeddedHandler = router.StaticEmbeddedHandler
	// Gzip is a middleware which enables writing
	// using gzip compression, if client supports.
	//
	// A shortcut for the `context#Gzip`.
	Gzip = context.Gzip
	// FromStd converts native http.Handler, http.HandlerFunc & func(w, r, next) to context.Handler.
	//
	// Supported form types:
	// 		 .FromStd(h http.Handler)
	// 		 .FromStd(func(w http.ResponseWriter, r *http.Request))
	// 		 .FromStd(func(w http.ResponseWriter, r *http.Request, next http.HandlerFunc))
	//
	// A shortcut for the `handlerconv#FromStd`.
	FromStd = handlerconv.FromStd
	// Cache is a middleware providing cache functionalities
	// to the next handlers, can be used as: `app.Get("/", iris.Cache, aboutHandler)`.
	//
	// Examples can be found at: https://github.com/kataras/iris/tree/v8/_examples/#caching
	Cache = cache.Handler
)
View Source 
var ErrServerClosed = http.ErrServerClosed

ErrServerClosed is returned by the Server's Serve, ServeTLS, ListenAndServe, and ListenAndServeTLS methods after a call to Shutdown or Close.

A shortcut for the `http#ErrServerClosed`.

View Source 
var RegisterOnInterrupt = host.RegisterOnInterrupt

RegisterOnInterrupt registers a global function to call when CTRL+C/CMD+C pressed or a unix kill command received.

A shortcut for the `host#RegisterOnInterrupt`.

View Source 
var Try = mvc.Try

Try is a shortcut for the function `mvc.Try` result. See more at `mvc#Try` documentation.

View Source 
var (
	// Version is the current version number of the Iris Web Framework.
	Version = maintenance.Version
)
View Source 
var WithFireMethodNotAllowed = func(app *Application) {
	app.config.FireMethodNotAllowed = true
}

WithFireMethodNotAllowed enanbles the FireMethodNotAllowed setting.

See `Configuration`.

View Source 
var WithGlobalConfiguration = func(app *Application) {
	app.Configure(WithConfiguration(YAML(globalConfigurationKeyword)))
}

WithGlobalConfiguration will load the global yaml configuration file from the home directory and it will set/override the whole app's configuration to that file's contents. The global configuration file can be modified by user and be used by multiple iris instances.

This is useful when we run multiple iris servers that share the same configuration, even with custom values at its "Other" field.

Usage: `app.Configure(iris.WithGlobalConfiguration)` or `app.Run(iris.Runner, iris.WithGlobalConfiguration)`.

View Source 
var WithOptimizations = func(app *Application) {
	app.config.EnableOptimizations = true
}

WithOptimizations can force the application to optimize for the best performance where is possible.

See `Configuration`.

View Source 
var WithPathEscape = func(app *Application) {
	app.config.EnablePathEscape = true
}

WithPathEscape enanbles the PathEscape setting.

See `Configuration`.

View Source 
var WithoutAutoFireStatusCode = func(app *Application) {
	app.config.DisableAutoFireStatusCode = true
}

WithoutAutoFireStatusCode disables the AutoFireStatusCode setting.

See `Configuration`.

View Source 
var WithoutBanner = WithoutStartupLog

WithoutBanner is a conversion for the `WithoutStartupLog` option.

Turns off the information send, once, to the terminal when the main server is open.

View Source 
var WithoutBodyConsumptionOnUnmarshal = func(app *Application) {
	app.config.DisableBodyConsumptionOnUnmarshal = true
}

WithoutBodyConsumptionOnUnmarshal disables BodyConsumptionOnUnmarshal setting.

See `Configuration`.

View Source 
var WithoutInterruptHandler = func(app *Application) {
	app.config.DisableInterruptHandler = true
}

WithoutInterruptHandler disables the automatic graceful server shutdown when control/cmd+C pressed.

View Source 
var WithoutPathCorrection = func(app *Application) {
	app.config.DisablePathCorrection = true
}

WithoutPathCorrection disables the PathCorrection setting.

See `Configuration`.

View Source 
var WithoutStartupLog = func(app *Application) {
	app.config.DisableStartupLog = true
}

WithoutStartupLog turns off the information send, once, to the terminal when the main server is open.

View Source 
var WithoutVersionChecker = func(app *Application) {
	app.config.DisableVersionChecker = true
}

WithoutVersionChecker will disable the version checker and updater. The Iris server will be not receive automatic updates if you pass this to the `Run` function. Use it only while you're ready for Production environment.

Functions

This section is empty.

Types

type Application 

type Application struct {
	// routing embedded | exposing APIBuilder's and Router's public API.
	*router.APIBuilder
	*router.Router
	ContextPool *context.Pool

	// Hosts contains a list of all servers (Host Supervisors) that this app is running on.
	//
	// Hosts may be empty only if application ran(`app.Run`) with `iris.Raw` option runner,
	// otherwise it contains a single host (`app.Hosts[0]`).
	//
	// Additional Host Supervisors can be added to that list by calling the `app.NewHost` manually.
	//
	// Hosts field is available after `Run` or `NewHost`.
	Hosts []*host.Supervisor
	// contains filtered or unexported fields
}

Application is responsible to manage the state of the application. It contains and handles all the necessary parts to create a fast web server.

func Default 

func Default() *Application

Default returns a new Application instance which, unlike `New`, recovers on panics and logs the incoming http requests.

func New 

func New() *Application

New creates and returns a fresh empty iris *Application instance.

func (*Application) Build 

func (app *Application) Build() error

Build sets up, once, the framework. It builds the default router with its default macros and the template functions that are very-closed to iris.

func (*Application) ConfigurationReadOnly 

func (app *Application) ConfigurationReadOnly() context.ConfigurationReadOnly

ConfigurationReadOnly returns an object which doesn't allow field writing.

func (*Application) Configure 

func (app *Application) Configure(configurators ...Configurator) *Application

Configure can called when modifications to the framework instance needed. It accepts the framework instance and returns an error which if it's not nil it's printed to the logger. See configuration.go for more.

Returns itself in order to be used like `app:= New().Configure(...)`

func (*Application) ConfigureHost 

func (app *Application) ConfigureHost(configurators ...host.Configurator) *Application

ConfigureHost accepts one or more `host#Configuration`, these configurators functions can access the host created by `app.Run`, they're being executed when application is ready to being served to the public.

It's an alternative way to interact with a host that is automatically created by `app.Run`.

These "configurators" can work side-by-side with the `iris#Addr, iris#Server, iris#TLS, iris#AutoTLS, iris#Listener` final arguments("hostConfigs") too.

Note that these application's host "configurators" will be shared with the rest of the hosts that this app will may create (using `app.NewHost`), meaning that `app.NewHost` will execute these "configurators" everytime that is being called as well.

These "configurators" should be registered before the `app.Run` or `host.Serve/Listen` functions.

func (*Application) Logger 

func (app *Application) Logger() *golog.Logger

Logger returns the golog logger instance(pointer) that is being used inside the "app".

Available levels: - "disable" - "fatal" - "error" - "warn" - "info" - "debug" Usage: app.Logger().SetLevel("error") Defaults to "info" level.

Callers can use the application's logger which is the same `golog.Default` logger, to print custom logs too. Usage: app.Logger().Error/Errorf("...") app.Logger().Warn/Warnf("...") app.Logger().Info/Infof("...") app.Logger().Debug/Debugf("...")

Setting one or more outputs: app.Logger().SetOutput(io.Writer...) Adding one or more outputs : app.Logger().AddOutput(io.Writer...)

Adding custom levels requires import of the `github.com/kataras/golog` package: 

First we create our level to a golog.Level
in order to be used in the Log functions.
var SuccessLevel golog.Level = 6
Register our level, just three fields.
golog.Levels[SuccessLevel] = &golog.LevelMetadata{
	Name:    "success",
	RawText: "[SUCC]",
	// ColorfulText (Green Color[SUCC])
	ColorfulText: "\x1b[32m[SUCC]\x1b[0m",
}

Usage: app.Logger().SetLevel("success") app.Logger().Logf(SuccessLevel, "a custom leveled log message")

func (*Application) NewHost 

func (app *Application) NewHost(srv *http.Server) *host.Supervisor

NewHost accepts a standar *http.Server object, completes the necessary missing parts of that "srv" and returns a new, ready-to-use, host (supervisor).

func (*Application) RegisterView 

func (app *Application) RegisterView(viewEngine view.Engine)

RegisterView should be used to register view engines mapping to a root directory and the template file(s) extension.

func (*Application) Run 

func (app *Application) Run(serve Runner, withOrWithout ...Configurator) error

Run builds the framework and starts the desired `Runner` with or without configuration edits.

Run should be called only once per Application instance, it blocks like http.Server.

If more than one server needed to run on the same iris instance then create a new host and run it manually by `go NewHost(*http.Server).Serve/ListenAndServe` etc... or use an already created host: h := NewHost(*http.Server) Run(Raw(h.ListenAndServe), WithCharset("UTF-8"), WithRemoteAddrHeader("CF-Connecting-IP"))

The Application can go online with any type of server or iris's host with the help of the following runners: `Listener`, `Server`, `Addr`, `TLS`, `AutoTLS` and `Raw`.

func (*Application) SPA 

func (app *Application) SPA(assetHandler context.Handler) *router.SPABuilder

SPA accepts an "assetHandler" which can be the result of an app.StaticHandler or app.StaticEmbeddedHandler. Use that when you want to navigate from /index.html to / automatically it's a helper function which just makes some checks based on the `IndexNames` and `AssetValidators` before the assetHandler call.

Example: https://github.com/kataras/iris/tree/v8/_examples/file-server/single-page-application

func (*Application) Shutdown 

func (app *Application) Shutdown(ctx stdContext.Context) error

Shutdown gracefully terminates all the application's server hosts. Returns an error on the first failure, otherwise nil.

func (*Application) View 

func (app *Application) View(writer io.Writer, filename string, layout string, bindingData interface{}) error

View executes and writes the result of a template file to the writer.

First parameter is the writer to write the parsed template. Second parameter is the relative, to templates directory, template filename, including extension. Third parameter is the layout, can be empty string. Forth parameter is the bindable data to the template, can be nil.

Use context.View to render templates to the client instead. Returns an error on failure, otherwise nil.

type C 

type C = mvc.C

C is the lightweight BaseController type as an alternative of the `Controller` struct type. It contains only the Name of the controller and the Context, it's the best option to balance the performance cost reflection uses if your controller uses the new func output values dispatcher feature; func(c *ExampleController) Get() string | (string, string) | (string, int) | int | (int, string | (string, error) | error | (int, error) | (customStruct, error) | customStruct | (customStruct, int) | (customStruct, string) | Result or (Result, error) where Get is an HTTP Method func.

Look `core/router#APIBuilder#Controller` method too.

A shortcut for the `mvc#C`, useful when `app.Controller` method is being used.

A C controller can be declared by importing the "github.com/kataras/iris/mvc" as well.

type Configuration 

type Configuration struct {

	// IgnoreServerErrors will cause to ignore the matched "errors"
	// from the main application's `Run` function.
	// This is a slice of string, not a slice of error
	// users can register these errors using yaml or toml configuration file
	// like the rest of the configuration fields.
	//
	// See `WithoutServerError(...)` function too.
	//
	// Example: https://github.com/kataras/iris/tree/v8/_examples/http-listening/listen-addr/omit-server-errors
	//
	// Defaults to an empty slice.
	IgnoreServerErrors []string `json:"ignoreServerErrors,omitempty" yaml:"IgnoreServerErrors" toml:"IgnoreServerErrors"`

	// DisableStartupLog if setted to true then it turns off the write banner on server startup.
	//
	// Defaults to false.
	DisableStartupLog bool `json:"disableStartupLog,omitempty" yaml:"DisableStartupLog" toml:"DisableStartupLog"`
	// DisableInterruptHandler if setted to true then it disables the automatic graceful server shutdown
	// when control/cmd+C pressed.
	// Turn this to true if you're planning to handle this by your own via a custom host.Task.
	//
	// Defaults to false.
	DisableInterruptHandler bool `json:"disableInterruptHandler,omitempty" yaml:"DisableInterruptHandler" toml:"DisableInterruptHandler"`

	// DisableVersionChecker if true then process will be not be notified for any available updates.
	//
	// Defaults to false.
	DisableVersionChecker bool `json:"disableVersionChecker,omitempty" yaml:"DisableVersionChecker" toml:"DisableVersionChecker"`

	// DisablePathCorrection corrects and redirects the requested path to the registered 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,
	// (permant)redirects the client to the correct path /home
	//
	// Defaults to false.
	DisablePathCorrection bool `json:"disablePathCorrection,omitempty" yaml:"DisablePathCorrection" toml:"DisablePathCorrection"`

	// EnablePathEscape when is true then its escapes the path, the named parameters (if any).
	// Change to false it if you want something like this https://github.com/kataras/iris/issues/135 to work
	//
	// When do you need to Disable(false) it:
	// accepts parameters with slash '/'
	// Request: http://localhost:8080/details/Project%2FDelta
	// ctx.Param("project") returns the raw named parameter: Project%2FDelta
	// which you can escape it manually with net/url:
	// projectName, _ := url.QueryUnescape(c.Param("project").
	//
	// Defaults to false.
	EnablePathEscape bool `json:"enablePathEscape,omitempty" yaml:"EnablePathEscape" toml:"EnablePathEscape"`

	// EnableOptimization when this field is true
	// then the application tries to optimize for the best performance where is possible.
	//
	// Defaults to false.
	EnableOptimizations bool `json:"enableOptimizations,omitempty" yaml:"EnableOptimizations" toml:"EnableOptimizations"`
	// FireMethodNotAllowed if it's true router checks for StatusMethodNotAllowed(405) and
	//  fires the 405 error instead of 404
	// Defaults to false.
	FireMethodNotAllowed bool `json:"fireMethodNotAllowed,omitempty" yaml:"FireMethodNotAllowed" toml:"FireMethodNotAllowed"`

	// DisableBodyConsumptionOnUnmarshal manages the reading behavior of the context's body readers/binders.
	// If setted to true then it
	// disables the body consumption by the `context.UnmarshalBody/ReadJSON/ReadXML`.
	//
	// By-default io.ReadAll` is used to read the body from the `context.Request.Body which is an `io.ReadCloser`,
	// if this field setted to true then a new buffer will be created to read from and the request body.
	// The body will not be changed and existing data before the
	// context.UnmarshalBody/ReadJSON/ReadXML will be not consumed.
	DisableBodyConsumptionOnUnmarshal bool `` /* 132-byte string literal not displayed */

	// DisableAutoFireStatusCode if true then it turns off the http error status code handler automatic execution
	// from "context.StatusCode(>=400)" and instead app should manually call the "context.FireStatusCode(>=400)".
	//
	// By-default a custom http error handler will be fired when "context.StatusCode(code)" called,
	// code should be >=400 in order to be received as an "http error handler".
	//
	// Developer may want this option to setted as true in order to manually call the
	// error handlers when needed via "context.FireStatusCode(>=400)".
	// HTTP Custom error handlers are being registered via app.OnErrorCode(code, handler)".
	//
	// Defaults to false.
	DisableAutoFireStatusCode bool `json:"disableAutoFireStatusCode,omitempty" yaml:"DisableAutoFireStatusCode" toml:"DisableAutoFireStatusCode"`

	// TimeFormat time format for any kind of datetime parsing
	// Defaults to  "Mon, 02 Jan 2006 15:04:05 GMT".
	TimeFormat string `json:"timeFormat,omitempty" yaml:"TimeFormat" toml:"TimeFormat"`

	// Charset character encoding for various rendering
	// used for templates and the rest of the responses
	// Defaults to "UTF-8".
	Charset string `json:"charset,omitempty" yaml:"Charset" toml:"Charset"`

	// Context values' keys for various features.
	//
	// TranslateLanguageContextKey & TranslateFunctionContextKey are used by i18n handlers/middleware
	// currently we have only one: https://github.com/kataras/iris/tree/v8/middleware/i18n.
	//
	// Defaults to "iris.translate" and "iris.language"
	TranslateFunctionContextKey string `json:"translateFunctionContextKey,omitempty" yaml:"TranslateFunctionContextKey" toml:"TranslateFunctionContextKey"`
	// TranslateLanguageContextKey used for i18n.
	//
	// Defaults to "iris.language"
	TranslateLanguageContextKey string `json:"translateLanguageContextKey,omitempty" yaml:"TranslateLanguageContextKey" toml:"TranslateLanguageContextKey"`

	// GetViewLayoutContextKey is the key of the context's user values' key
	// which is being used to set the template
	// layout from a middleware or the main handler.
	// Overrides the parent's or the configuration's.
	//
	// Defaults to "iris.ViewLayout"
	ViewLayoutContextKey string `json:"viewLayoutContextKey,omitempty" yaml:"ViewLayoutContextKey" toml:"ViewLayoutContextKey"`
	// GetViewDataContextKey is the key of the context's user values' key
	// which is being used to set the template
	// binding data from a middleware or the main handler.
	//
	// Defaults to "iris.viewData"
	ViewDataContextKey string `json:"viewDataContextKey,omitempty" yaml:"ViewDataContextKey" toml:"ViewDataContextKey"`
	// RemoteAddrHeaders returns the allowed request headers names
	// that can be valid to parse the client's IP based on.
	//
	// Defaults to:
	// "X-Real-Ip":             false,
	// "X-Forwarded-For":       false,
	// "CF-Connecting-IP": false
	//
	// Look `context.RemoteAddr()` for more.
	RemoteAddrHeaders map[string]bool `json:"remoteAddrHeaders,omitempty" yaml:"RemoteAddrHeaders" toml:"RemoteAddrHeaders"`

	// Other are the custom, dynamic options, can be empty.
	// This field used only by you to set any app's options you want
	// or by custom adaptors, it's a way to simple communicate between your adaptors (if any)
	// Defaults to a non-nil empty map.
	Other map[string]interface{} `json:"other,omitempty" yaml:"Other" toml:"Other"`
	// contains filtered or unexported fields
}

Configuration the whole configuration for an iris instance these can be passed via options also, look at the top of this file(configuration.go). Configuration is a valid OptionSetter.

func DefaultConfiguration 

func DefaultConfiguration() Configuration

DefaultConfiguration returns the default configuration for an iris station, fills the main Configuration

func TOML 

func TOML(filename string) Configuration

TOML reads Configuration from a toml-compatible document file. Read more about toml's implementation at: https://github.com/toml-lang/toml

Accepts the absolute path of the configuration file. An error will be shown to the user via panic with the error message. Error may occur when the file doesn't exists or is not formatted correctly.

Note: if the char '~' passed as "filename" then it tries to load and return the configuration from the $home_directory + iris.tml, see `WithGlobalConfiguration` for more information.

Usage: app.Configure(iris.WithConfiguration(iris.YAML("myconfig.tml"))) or app.Run(iris.Runner, iris.WithConfiguration(iris.YAML("myconfig.tml"))).

func YAML 

func YAML(filename string) Configuration

YAML reads Configuration from a configuration.yml file.

Accepts the absolute path of the cfg.yml. An error will be shown to the user via panic with the error message. Error may occur when the cfg.yml doesn't exists or is not formatted correctly.

Note: if the char '~' passed as "filename" then it tries to load and return the configuration from the $home_directory + iris.yml, see `WithGlobalConfiguration` for more information.

Usage: app.Configure(iris.WithConfiguration(iris.YAML("myconfig.yml"))) or app.Run(iris.Runner, iris.WithConfiguration(iris.YAML("myconfig.yml"))).

func (Configuration) GetCharset 

func (c Configuration) GetCharset() string

GetCharset returns the Configuration#Charset, the character encoding for various rendering used for templates and the rest of the responses.

func (Configuration) GetDisableAutoFireStatusCode 

func (c Configuration) GetDisableAutoFireStatusCode() bool

GetDisableAutoFireStatusCode returns the Configuration#DisableAutoFireStatusCode. Returns true when the http error status code handler automatic execution turned off.

func (Configuration) GetDisableBodyConsumptionOnUnmarshal 

func (c Configuration) GetDisableBodyConsumptionOnUnmarshal() bool

GetDisableBodyConsumptionOnUnmarshal returns the Configuration#GetDisableBodyConsumptionOnUnmarshal, manages the reading behavior of the context's body readers/binders. If returns true then the body consumption by the `context.UnmarshalBody/ReadJSON/ReadXML` is disabled.

By-default io.ReadAll` is used to read the body from the `context.Request.Body which is an `io.ReadCloser`, if this field setted to true then a new buffer will be created to read from and the request body. The body will not be changed and existing data before the context.UnmarshalBody/ReadJSON/ReadXML will be not consumed.

func (Configuration) GetDisablePathCorrection 

func (c Configuration) GetDisablePathCorrection() bool

GetDisablePathCorrection returns the Configuration#DisablePathCorrection, DisablePathCorrection corrects and redirects the requested path to the registered 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, (permant)redirects the client to the correct path /home.

func (Configuration) GetEnableOptimizations 

func (c Configuration) GetEnableOptimizations() bool

GetEnableOptimizations returns whether the application has performance optimizations enabled.

func (Configuration) GetEnablePathEscape 

func (c Configuration) GetEnablePathEscape() bool

GetEnablePathEscape is the Configuration#EnablePathEscape, returns true when its escapes the path, the named parameters (if any).

func (Configuration) GetFireMethodNotAllowed 

func (c Configuration) GetFireMethodNotAllowed() bool

GetFireMethodNotAllowed returns the Configuration#FireMethodNotAllowed.

func (Configuration) GetOther 

func (c Configuration) GetOther() map[string]interface{}

GetOther returns the Configuration#Other map.

func (Configuration) GetRemoteAddrHeaders 

func (c Configuration) GetRemoteAddrHeaders() map[string]bool

GetRemoteAddrHeaders returns the allowed request headers names that can be valid to parse the client's IP based on.

Defaults to: "X-Real-Ip": false, "X-Forwarded-For": false, "CF-Connecting-IP": false

Look `context.RemoteAddr()` for more.

func (Configuration) GetTimeFormat 

func (c Configuration) GetTimeFormat() string

GetTimeFormat returns the Configuration#TimeFormat, format for any kind of datetime parsing.

func (Configuration) GetTranslateFunctionContextKey 

func (c Configuration) GetTranslateFunctionContextKey() string

GetTranslateFunctionContextKey returns the configuration's TranslateFunctionContextKey value, used for i18n.

func (Configuration) GetTranslateLanguageContextKey 

func (c Configuration) GetTranslateLanguageContextKey() string

GetTranslateLanguageContextKey returns the configuration's TranslateLanguageContextKey value, used for i18n.

func (Configuration) GetVHost 

func (c Configuration) GetVHost() string

GetVHost returns the non-exported vhost config field.

If original addr ended with :443 or :80, it will return the host without the port. If original addr was :https or :http, it will return localhost. If original addr was 0.0.0.0, it will return localhost.

func (Configuration) GetViewDataContextKey 

func (c Configuration) GetViewDataContextKey() string

GetViewDataContextKey returns the key of the context's user values' key which is being used to set the template binding data from a middleware or the main handler.

func (Configuration) GetViewLayoutContextKey 

func (c Configuration) GetViewLayoutContextKey() string

GetViewLayoutContextKey returns the key of the context's user values' key which is being used to set the template layout from a middleware or the main handler. Overrides the parent's or the configuration's.

type Configurator 

type Configurator func(*Application)

Configurator is just an interface which accepts the framework instance.

It can be used to register a custom configuration with `Configure` in order to modify the framework instance.

Currently Configurator is being used to describe the configuration's fields values.

func WithCharset 

func WithCharset(charset string) Configurator

WithCharset sets the Charset setting.

See `Configuration`.

func WithConfiguration 

func WithConfiguration(c Configuration) Configurator

WithConfiguration sets the "c" values to the framework's configurations.

Usage: app.Run(iris.Addr(":8080"), iris.WithConfiguration(iris.Configuration{/* fields here */ })) or iris.WithConfiguration(iris.YAML("./cfg/iris.yml")) or iris.WithConfiguration(iris.TOML("./cfg/iris.tml"))

func WithOtherValue 

func WithOtherValue(key string, val interface{}) Configurator

WithOtherValue adds a value based on a key to the Other setting.

See `Configuration`.

func WithRemoteAddrHeader 

func WithRemoteAddrHeader(headerName string) Configurator

WithRemoteAddrHeader enables or adds a new or existing request header name that can be used to validate the client's real IP.

Existing values are: "X-Real-Ip": false, "X-Forwarded-For": false, "CF-Connecting-IP": false

Look `context.RemoteAddr()` for more.

func WithTimeFormat 

func WithTimeFormat(timeformat string) Configurator

WithTimeFormat sets the TimeFormat setting.

See `Configuration`.

func WithoutRemoteAddrHeader 

func WithoutRemoteAddrHeader(headerName string) Configurator

WithoutRemoteAddrHeader disables an existing request header name that can be used to validate the client's real IP.

Existing values are: "X-Real-Ip": false, "X-Forwarded-For": false, "CF-Connecting-IP": false

Look `context.RemoteAddr()` for more.

func WithoutServerError 

func WithoutServerError(errors ...error) Configurator

WithoutServerError will cause to ignore the matched "errors" from the main application's `Run` function.

Usage: err := app.Run(iris.Addr(":8080"), iris.WithoutServerError(iris.ErrServerClosed)) will return `nil` if the server's error was `http/iris#ErrServerClosed`.

See `Configuration#IgnoreServerErrors []string` too.

Example: https://github.com/kataras/iris/tree/v8/_examples/http-listening/listen-addr/omit-server-errors

type Context 

type Context = context.Context

Context is the midle-man server's "object" for the clients.

A New context is being acquired from a sync.Pool on each connection. The Context is the most important thing on the iris's http flow.

Developers send responses to the client's request through a Context. Developers get request information from the client's request by a Context.

type Controller 

type Controller = mvc.Controller

Controller is the base controller for the high level controllers instances.

This base controller is used as an alternative way of building APIs, the controller can register all type of http methods.

Keep note that controllers are bit slow because of the reflection use however it's as fast as possible because it does preparation before the serve-time handler but still remains slower than the low-level handlers such as `Handle, Get, Post, Put, Delete, Connect, Head, Trace, Patch`.

All fields that are tagged with iris:"persistence"` are being persistence and kept between the different requests, meaning that these data will not be reset-ed on each new request, they will be the same for all requests.

An Example Controller can be: 

type IndexController struct {
	iris.Controller
}

func (c *IndexController) Get() {
	c.Tmpl = "index.html"
	c.Data["title"] = "Index page"
	c.Data["message"] = "Hello world!"
}

Usage: app.Controller("/", new(IndexController))

Another example with persistence data: 

type UserController struct {
	iris.Controller

	CreatedAt time.Time `iris:"persistence"`
	Title     string    `iris:"persistence"`
	DB        *DB       `iris:"persistence"`
}

// Get serves using the User controller when HTTP Method is "GET". 

func (c *UserController) Get() {
	c.Tmpl = "user/index.html"
	c.Data["title"] = c.Title
	c.Data["username"] = "kataras " + c.Params.Get("userid")
	c.Data["connstring"] = c.DB.Connstring
	c.Data["uptime"] = time.Now().Sub(c.CreatedAt).Seconds()
}

Usage: app.Controller("/user/{id:int}", &UserController{
	CreatedAt: time.Now(),
	Title: "User page",
	DB: yourDB,
})

Look `core/router#APIBuilder#Controller` method too.

A shortcut for the `mvc#Controller`, useful when `app.Controller` method is being used.

A Controller can be declared by importing the "github.com/kataras/iris/mvc" package for machines that have not installed go1.9 yet.

type Handler 

type Handler = context.Handler

A Handler responds to an HTTP request. It writes reply headers and data to the Context.ResponseWriter() and then return. Returning signals that the request is finished; it is not valid to use the Context after or concurrently with the completion of the Handler call.

Depending on the HTTP client software, HTTP protocol version, and any intermediaries between the client and the iris server, it may not be possible to read from the Context.Request().Body after writing to the context.ResponseWriter(). Cautious handlers should read the Context.Request().Body first, and then reply.

Except for reading the body, handlers should not modify the provided Context.

If Handler panics, the server (the caller of Handler) assumes that the effect of the panic was isolated to the active request. It recovers the panic, logs a stack trace to the server error log, and hangs up the connection.

type Map 

type Map = context.Map

A Map is a shortcut of the map[string]interface{}.

type Party 

type Party = router.Party

Party is just a group joiner of routes which have the same prefix and share same middleware(s) also. Party could also be named as 'Join' or 'Node' or 'Group' , Party chosen because it is fun.

Look the `core/router#APIBuilder` for its implementation.

A shortcut for the `core/router#Party`, useful when `PartyFunc` is being used.

type Response 

type Response = mvc.Response

Response completes the `mvc/activator/methodfunc.Result` interface. It's being used as an alternative return value which wraps the status code, the content type, a content as bytes or as string and an error, it's smart enough to complete the request and send the correct response to the client.

A shortcut for the `mvc#Response`, useful when return values from method functions, i.e GetHelloworld() iris.Response { iris.Response{ Text:"Hello World!", Code: 200 }}

type Result 

type Result = mvc.Result

Result is a response dispatcher. All types that complete this interface can be returned as values from the method functions. A shortcut for the `mvc#Result` which is a shortcut for `mvc/activator/methodfunc#Result`, useful when return values from method functions, i.e GetUser() iris.Result { iris.Response{} or a custom iris.Result } Can be also used for the TryResult function.

type Runner 

type Runner func(*Application) error

Runner is just an interface which accepts the framework instance and returns an error.

It can be used to register a custom runner with `Run` in order to set the framework's server listen action.

Currently Runner is being used to declare the built'n server listeners.

See `Run` for more.

func Addr 

func Addr(addr string, hostConfigs ...host.Configurator) Runner

Addr can be used as an argument for the `Run` method. It accepts a host address which is used to build a server and a listener which listens on that host and port.

Addr should have the form of host:port, i.e localhost:8080 or :8080.

Second argument is optional, it accepts one or more `func(*host.Configurator)` that are being executed on that specific host that this function will create to start the server. Via host configurators you can configure the back-end host supervisor, i.e to add events for shutdown, serve or error. An example of this use case can be found at: https://github.com/kataras/iris/blob/v8/_examples/http-listening/notify-on-shutdown/main.go Look at the `ConfigureHost` too.

See `Run` for more.

func AutoTLS 

func AutoTLS(
	addr string,
	domain string, email string,
	hostConfigs ...host.Configurator) Runner

AutoTLS can be used as an argument for the `Run` method. It will start the Application's secure server using certifications created on the fly by the "autocert" golang/x package, so localhost may not be working, use it at "production" machine.

Addr should have the form of host:port, i.e mydomain.com:443 or :443.

The whitelisted domains are separated by whitespace in "domain" argument, i.e "iris-go.com", can be different than "addr". If empty, all hosts are currently allowed. This is not recommended, as it opens a potential attack where clients connect to a server by IP address and pretend to be asking for an incorrect host name. Manager will attempt to obtain a certificate for that host, incorrectly, eventually reaching the CA's rate limit for certificate requests and making it impossible to obtain actual certificates.

For an "e-mail" use a non-public one, letsencrypt needs that for your own security.

Note: If domain is not empty and the server's port was "443" then it will start a new server, automatically for you, which will redirect all http versions to their https as well.

Last argument is optional, it accepts one or more `func(*host.Configurator)` that are being executed on that specific host that this function will create to start the server. Via host configurators you can configure the back-end host supervisor, i.e to add events for shutdown, serve or error. An example of this use case can be found at: https://github.com/kataras/iris/blob/v8/_examples/http-listening/notify-on-shutdown/main.go Look at the `ConfigureHost` too.

Usage: app.Run(iris.AutoTLS(":443", "example.com", "mail@example.com"))

See `Run` and `core/host/Supervisor#ListenAndServeAutoTLS` for more.

func Listener 

func Listener(l net.Listener, hostConfigs ...host.Configurator) Runner

Listener can be used as an argument for the `Run` method. It can start a server with a custom net.Listener via server's `Serve`.

Second argument is optional, it accepts one or more `func(*host.Configurator)` that are being executed on that specific host that this function will create to start the server. Via host configurators you can configure the back-end host supervisor, i.e to add events for shutdown, serve or error. An example of this use case can be found at: https://github.com/kataras/iris/blob/v8/_examples/http-listening/notify-on-shutdown/main.go Look at the `ConfigureHost` too.

See `Run` for more.

func Raw 

func Raw(f func() error) Runner

Raw can be used as an argument for the `Run` method. It accepts any (listen) function that returns an error, this function should be block and return an error only when the server exited or a fatal error caused.

With this option you're not limited to the servers that iris can run by-default.

See `Run` for more.

func Server 

func Server(srv *http.Server, hostConfigs ...host.Configurator) Runner

Server can be used as an argument for the `Run` method. It can start a server with a *http.Server.

Second argument is optional, it accepts one or more `func(*host.Configurator)` that are being executed on that specific host that this function will create to start the server. Via host configurators you can configure the back-end host supervisor, i.e to add events for shutdown, serve or error. An example of this use case can be found at: https://github.com/kataras/iris/blob/v8/_examples/http-listening/notify-on-shutdown/main.go Look at the `ConfigureHost` too.

See `Run` for more.

func TLS 

func TLS(addr string, certFile, keyFile string, hostConfigs ...host.Configurator) Runner

TLS can be used as an argument for the `Run` method. It will start the Application's secure server.

Use it like you used to use the http.ListenAndServeTLS function.

Addr should have the form of host:port, i.e localhost:443 or :443. CertFile & KeyFile should be filenames with their extensions.

Second argument is optional, it accepts one or more `func(*host.Configurator)` that are being executed on that specific host that this function will create to start the server. Via host configurators you can configure the back-end host supervisor, i.e to add events for shutdown, serve or error. An example of this use case can be found at: https://github.com/kataras/iris/blob/v8/_examples/http-listening/notify-on-shutdown/main.go Look at the `ConfigureHost` too.

See `Run` for more.

type SessionController 

type SessionController = mvc.SessionController

SessionController is a simple `Controller` implementation which requires a binded session manager in order to give direct access to the current client's session via its `Session` field.

type Supervisor 

type Supervisor = host.Supervisor

Supervisor is a shortcut of the `host#Supervisor`. Used to add supervisor configurators on common Runners without the need of importing the `core/host` package.

type View 

type View = mvc.View

View completes the `mvc/activator/methodfunc.Result` interface. It's being used as an alternative return value which wraps the template file name, layout, (any) view data, status code and error. It's smart enough to complete the request and send the correct response to the client.

A shortcut for the `mvc#View`, useful when return values from method functions, i.e GetUser() iris.View { iris.View{ Name:"user.html", Data: currentUser } }

Source Files

View all Source files

Directories

Path Synopsis
_benchmarks
iris
iris-mvc
iris-mvc-templates
iris-mvc-templates/controllers
iris-mvc-templates/models
iris-mvc/controllers
iris-sessions
_examples
apidoc/yaag
authentication/basicauth
authentication/oauth2
cache/simple
configuration/from-configuration-structure
configuration/from-toml-file
configuration/from-yaml-file
configuration/from-yaml-file/shared-configuration
configuration/functional
convert-handlers/negroni-like
convert-handlers/nethttp
convert-handlers/real-usecase-raven/wrapping-the-router
convert-handlers/real-usecase-raven/writing-middleware
experimental-handlers/casbin/middleware
experimental-handlers/casbin/wrapper
experimental-handlers/cloudwatch/simple
experimental-handlers/cors/simple
experimental-handlers/csrf
This middleware provides Cross-Site Request Forgery protection.
 This middleware provides Cross-Site Request Forgery protection.
experimental-handlers/jwt
iris provides some basic middleware, most for your learning courve.
 iris provides some basic middleware, most for your learning courve.
experimental-handlers/newrelic/simple
experimental-handlers/prometheus/simple
experimental-handlers/secure/simple
experimental-handlers/tollboothic/limit-handler
file-server/basic
file-server/embedding-files-into-app
file-server/favicon
file-server/send-files
file-server/single-page-application/basic
file-server/single-page-application/embedded-single-page-application
file-server/single-page-application/embedded-single-page-application-with-other-routes
hello-world
http-listening/custom-httpserver/easy-way
http-listening/custom-httpserver/multi
http-listening/custom-httpserver/std-way
http-listening/custom-listener
http-listening/custom-listener/unix-reuseport
http-listening/graceful-shutdown/custom-notifier
http-listening/graceful-shutdown/default-notifier
http-listening/iris-configurator-and-host-configurator
http-listening/iris-configurator-and-host-configurator/counter
http-listening/listen-addr
http-listening/listen-addr/omit-server-errors
http-listening/listen-letsencrypt
Package main provide one-line integration with letsencrypt.org
 Package main provide one-line integration with letsencrypt.org
http-listening/listen-tls
http-listening/listen-unix
http-listening/notify-on-shutdown
http_request/read-form
package main contains an example on how to use the ReadForm, but with the same way you can do the ReadJSON & ReadJSON
 package main contains an example on how to use the ReadForm, but with the same way you can do the ReadJSON & ReadJSON
http_request/read-json
http_request/request-logger
http_request/request-logger/request-logger-file
http_request/upload-files
http_responsewriter/hero
http_responsewriter/hero/template
Code generated by hero.
 Code generated by hero.
http_responsewriter/quicktemplate
http_responsewriter/quicktemplate/controllers
http_responsewriter/quicktemplate/templates
http_responsewriter/stream-writer
http_responsewriter/transactions
http_responsewriter/write-gzip
http_responsewriter/write-rest
miscellaneous/file-logger
miscellaneous/i18n
miscellaneous/pprof
miscellaneous/recaptcha
miscellaneous/recaptcha/custom_form
miscellaneous/recover
mvc/hello-world
mvc/login
mvc/login/datamodels
mvc/login/datasource
mvc/login/repositories
mvc/login/services
mvc/login/web/controllers
mvc/login/web/middleware
mvc/overview
mvc/overview/datamodels
mvc/overview/datasource
mvc/overview/repositories
mvc/overview/services
mvc/overview/web/controllers
mvc/overview/web/middleware
mvc/session-controller
orm/xorm
Package main shows how an orm can be used within your web app it just inserts a column and select the first.
 Package main shows how an orm can be used within your web app it just inserts a column and select the first.
overview
routing
routing/basic
routing/custom-context/method-overriding
routing/custom-context/new-implementation
routing/custom-wrapper
routing/dynamic-path
routing/dynamic-path/root-wildcard
routing/http-errors
routing/overview
routing/reverse
routing/route-state
routing/writing-a-middleware/globally
routing/writing-a-middleware/per-route
sessions/database/badger
sessions/database/boltdb
sessions/database/file
sessions/database/leveldb
sessions/database/redis
sessions/flash-messages
sessions/overview
sessions/securecookie
sessions/standalone
structuring/bootstrap
structuring/bootstrap/bootstrap
structuring/bootstrap/middleware/identity
structuring/bootstrap/routes
structuring/login-mvc-single-responsibility-package
structuring/login-mvc-single-responsibility-package/user
subdomains/multi
subdomains/single
Package main register static subdomains, simple as parties, check ./hosts if you use windows
 Package main register static subdomains, simple as parties, check ./hosts if you use windows
subdomains/wildcard
Package main an example on how to catch dynamic subdomains - wildcard.
 Package main an example on how to catch dynamic subdomains - wildcard.
subdomains/www
testing/httptest
tutorial/caddy/server1
tutorial/caddy/server2
tutorial/dropzonejs/src
tutorial/online-visitors
tutorial/url-shortener
Package main shows how you can create a simple URL Shortener.
 Package main shows how you can create a simple URL Shortener.
view/context-view-data
view/embedding-templates-into-app
view/overview
view/template_html_0
view/template_html_1
view/template_html_2
view/template_html_3
Package main an example on how to naming your routes & use the custom 'url path' HTML Template Engine, same for other template engines.
 Package main an example on how to naming your routes & use the custom 'url path' HTML Template Engine, same for other template engines.
view/template_html_4
Package main an example on how to naming your routes & use the custom 'url' HTML Template Engine, same for other template engines.
 Package main an example on how to naming your routes & use the custom 'url' HTML Template Engine, same for other template engines.
websocket/chat
websocket/connectionlist
websocket/custom-go-client
websocket/native-messages
websocket/secure
websocket/third-party-socketio
cfg
client
client/rule
entry
ruleset
Package ruleset provides the basics rules which are being extended by rules.
 Package ruleset provides the basics rules which are being extended by rules.
uri
core
errors
handlerconv
host
maintenance
maintenance/client
maintenance/encoding
maintenance/version
memstore
Package memstore contains a store which is just a collection of key-value entries with immutability capabilities.
 Package memstore contains a store which is just a collection of key-value entries with immutability capabilities.
netutil
router
router/macro
router/macro/interpreter/ast
router/macro/interpreter/lexer
router/macro/interpreter/parser
router/macro/interpreter/token
router/node
middleware
basicauth
Package basicauth provides http basic authentication via middleware.
 Package basicauth provides http basic authentication via middleware.
i18n
Package i18n provides internalization and localization via middleware.
 Package i18n provides internalization and localization via middleware.
logger
Package logger provides request logging via middleware.
 Package logger provides request logging via middleware.
pprof
Package pprof provides native pprof support via middleware.
 Package pprof provides native pprof support via middleware.
recaptcha
recover
Package recover provides recovery for specific routes or for the whole app via middleware.
 Package recover provides recovery for specific routes or for the whole app via middleware.
mvc
activator
activator/field
activator/methodfunc
activator/model
activator/persistence
sessiondb/badger
sessiondb/boltdb
sessiondb/file
sessiondb/leveldb
sessiondb/redis
sessiondb/redis/service
Package typescript provides a typescript compiler with hot-reloader and optionally a cloud-based editor, called 'alm-tools'.
 Package typescript provides a typescript compiler with hot-reloader and optionally a cloud-based editor, called 'alm-tools'.
_examples/editor
_examples/typescript
editor
npm
Package websocket provides rich websocket support for the iris web framework.
 Package websocket provides rich websocket support for the iris web framework.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.