siris

README

A fast, cross-platform and efficient web framework with robust set of well-designed features, written entirely in Go.

Build your own web applications and portable APIs with the highest performance and countless potentials.

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

Table of contents

• Installation
• Feature overview
• Documentation
  • Examples
  • Reload on source code changes
• Support
• Third-party middleware list
• Testing
• Philosophy
• People
  • Contact
• Versioning
  • When should I upgrade?
  • Where can I find older versions?

Installation

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

$ go get -u github.com/go-siris/siris

Siris uses the vendor directory feature, so you get truly reproducible builds, as this method guards against upstream renames and deletes. For further installation support, please navigate here.

package main

import (
    "github.com/go-siris/siris"
    "github.com/go-siris/siris/context"
    "github.com/go-siris/siris/view"
)

// 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 := siris.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.AttachView(view.HTML("./views", ".html").Reload(true))
    
    // Regster custom handler for specific http errors.
    app.OnErrorCode(siris.StatusInternalServerError, func(ctx context.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 context.Context) {
    	ctx.Application().Log("Begin request for path: %s", ctx.Path())
    	ctx.Next()
    })
    
    // app.Done(func(ctx context.Context) {})
    
    // Method POST: http://localhost:8080/decode
    app.Post("/decode", func(ctx context.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 context.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)
    
    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(siris.Addr(":8080"), siris.WithCharset("UTF-8"))
}

func logThisMiddleware(ctx context.Context) {
    ctx.Application().Log("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 context.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 context.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 context.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(siris.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")
}

Reload on source code changes

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

Psst: Wanna go to _examples to see more code-snippets?

Feature Overview

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

Documentation

Small but practical examples --they cover each feature.

Wanna create your own fast URL Shortener Service Using Siris? --click here to learn how.

Godocs --for deep understanding.

Performance optimization tips for multi-core systems

enable Reuseport feature:

app.Run(siris.Addr(":8080"), siris.EnableReuseport)
// or before run:
app.Configure(siris.EnableReuseport)

• Enable the Reuseport feature like abdove
• Run a separate server instance per CPU core with GOMAXPROCS=1.
• Pin each server instance to a separate CPU core using taskset.
• Ensure the interrupts of multiqueue network card are evenly distributed between CPU cores. See this article for details.
• Use Go 1.6+ as it provides some considerable performance improvements.

Support

• Post a feature request or report a bug, will help to make the framework even better.
• ⭐ and watch the project, will notify you about updates.
• 🌎 publish an article or share a tweet about siris.
• Donations, will help me to continue.

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

Thanks in advance!

Third Party Middleware

See THIRD-PARTY-MIDDLEWARE.md

Testing

The httptest package is your way for end-to-end HTTP testing, it uses the httpexpect library created by our friend, gavv.

A simple test is located to ./_examples/intermediate/httptest/main_test.go

Philosophy

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

Siris does not force you to use any specific ORM or template engine. With support for the most popular template engines, you can quickly craft your perfect application.

People

The original author of Iris is @kataras. Before we forked to Siris.

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

Contact

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

• Twitter
• Facebook
• Linkedin

Version

Current: 7.3.0

Each new release is pushed to the master. It stays there until the next version. When a next version is released then the previous version goes to its own branch with gopkg.in as its import path (and its own vendor folder), in order to keep it working "for-ever".

Community members can request additional features or report a bug fix for a specific siris version.

Should I upgrade my Siris?

Developers are not forced to use the latest Siris version, they can use any version in production, they can update at any time they want.

Testers should upgrade immediately, if you're willing to use Siris in production you can wait a little more longer, transaction should be as safe as possible.

Where can I find older versions?

Each Siris version is independent. Only bug fixes, Router's API and experience are kept.

Previous versions can be found at releases page.

License

Unless otherwise noted, the source files are distributed under the BSD-3-Clause License found in the LICENSE file.

Note that some third-party packages that you use with Iris may requires different license agreements.

Documentation

Overview

Package siris is a fully-featured HTTP/2 backend web framework written entirely in Google’s Go Language.

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

https://github.com/go-siris/siris

Installation

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

$ go get -u github.com/go-siris/siris

Example code:

package main

import (
    "github.com/go-siris/siris"
    "github.com/go-siris/siris/context"
    "github.com/go-siris/siris/view"
)

// 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 := siris.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.AttachView(view.HTML("./views", ".html").Reload(true))

    // Regster custom handler for specific http errors.
    app.OnErrorCode(siris.StatusInternalServerError, func(ctx context.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 context.Context) {
        ctx.Application().Log("Begin request for path: %s", ctx.Path())
        ctx.Next()
    })

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

    // Method POST: http://localhost:8080/decode
    app.Post("/decode", func(ctx context.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 context.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)

    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(siris.Addr(":8080"), siris.WithCharset("UTF-8"))
}

func logThisMiddleware(ctx context.Context) {
    ctx.Application().Log("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 context.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 context.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 context.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(siris.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")
}

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 context.Handler executed by the registered order when a user requests for that specific resouce path from the server.

Example code:

app := siris.New()

app.Handle("GET", "/contact", func(ctx context.Context){
    ctx.HTML("<h1> Hello from /contact </h1>")
})

In order to make things easier for the user, Siris provides functions for all HTTP Methods. The first parameter is the request path of the route, second variadic parameter should contains one or more context.Handler executed by the registered order when a user requests for that specific resouce path from the server.

Example code:

app := siris.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 context.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", myAuthHandler)

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

app.Run(siris.Addr("myhost.com:80"))

Custom HTTP Errors

Siris 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(siris.StatusNotFound, func(ctx context.Context){
    ctx.View("errors/404.html")
})

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

Basic HTTP API

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

Example code:

package main

import (
    "github.com/go-siris/siris"
    "github.com/go-siris/siris/context"
)

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

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

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

    app.Get("/home", func(ctx context.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 context.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(siris.StatusBadRequest)
            return
        }

        ctx.JSON(map[string]interface{}{
            // you can pass any custom structured go value of course.
            "user_id": userID,
        })
    })
    // app.Post("/", func(ctx context.Context){}) -> for POST http method.
    // app.Put("/", func(ctx context.Context){})-> for "PUT" http method.
    // app.Delete("/", func(ctx context.Context){})-> for "DELETE" http method.
    // app.Options("/", func(ctx context.Context){})-> for "OPTIONS" http method.
    // app.Trace("/", func(ctx context.Context){})-> for "TRACE" http method.
    // app.Head("/", func(ctx context.Context){})-> for "HEAD" http method.
    // app.Connect("/", func(ctx context.Context){})-> for "CONNECT" http method.
    // app.Patch("/", func(ctx context.Context){})-> for "PATCH" http method.
    // app.Any("/", func(ctx context.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 context.Context) { // executes always last if ctx.Next()
        ctx.Application().Log("response sent to " + ctx.Path())
    })
    // adminRoutes.Layout("/views/layouts/admin.html") // set a view layout for these routes, see more at intermediate/view examples.

    // GET: http://localhost:8080/admin
    adminRoutes.Get("/", func(ctx context.Context) {
        // [...]
        ctx.StatusCode(siris.StatusOK) // default is 200 == siris.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 context.Context) {
        // [...]
    })
    // POST: http://localhost:8080/admin/login
    adminRoutes.Post("/login", func(ctx context.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 context.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 context.Context) {
                ctx.Writef("All users")
            })
            // http://v1.localhost:8080/api/users/42
            usersAPI.Get("/{userid:int}", func(ctx context.Context) {
                ctx.Writef("user with id: %s", ctx.Params().Get("userid"))
            })
        }
    }

    // wildcard subdomains.
    wildcardSubdomain := app.Party("*.")
    {
        wildcardSubdomain.Get("/", func(ctx context.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(siris.Addr(":8080"))
}

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

func donateHandler(ctx context.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/go-siris/siris#buy-me-a-cup-of-coffee")
    ctx.Next() // in order to execute the next handler in the chain, look donate route.
}

func donateFinishHandler(ctx context.Context) {
    // values can be any type of object so we could cast the value to a string
    // but Siris 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().Log("donate_url value was: " + donateURL)
    ctx.Writef("\n\nDonate sent(?).")
}

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

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 paramete and custom http errors, now it's time to see wildcard parameters and macros.

Siris, like net/http std package registers route's handlers by a Handler, the Siris' type of handler is just a func(ctx context.Context) where context comes from github.com/go-siris/siris/context. Until go 1.9 you will have to import that package too, after go 1.9 this will be not be necessary.

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

At the same time, Siris has its own interpeter(yes like a programming language) for route's path syntax and their dynamic path parameters parsing and evaluation, I am calling 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: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().GetString("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 Siris 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(siris)} , "siris" 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 context.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 context.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 context.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 context.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/kataras
	app.Get("/lowercase/{name:string regexp(^[a-z]+)}", func(ctx context.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 context.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 context.Context) {
		ctx.Writef("path type accepts any number of path segments, path after /myfiles/ is: %s", ctx.Params().Get("directory"))
	})

    // for wildcard path (any number of path segments) without validation you can use:
	// /myfiles/*directory
	// "{param}"'s performance is exactly the same of ":param"'s.

	// alternatives -> ":param" for single path parameter and "*paramPath" for wildcard path parameter
	// acquire them by ctx.Params().Get as always.

	if err := app.Run(siris.Addr(":8080")); err != nil {
		panic(err)
	}
}

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/go-siris/siris/tree/master/_examples/intermediate/serve-embedded-files
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/go-siris/siris"
    "github.com/go-siris/siris/context"
)

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

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

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

    app.Get("/", func(ctx context.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 Siris 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(siris.Addr(":8080"))
}

More examples can be found here: https://github.com/go-siris/siris/tree/master/_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 context.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 context.Context){
  ctx.Writef("Hello from subdomain: "+ ctx.Subdomain())
})

Siris 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/go-siris/siris"
    "github.com/go-siris/siris/context"
)

func main() {

    app := siris.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(siris.Addr(":8080"))
}

func h(ctx context.Context) {
    ctx.Application().Log(ctx.Path())
    ctx.Writef("Hello from %s", ctx.Path())
}

View Engine

Siris supports 5 template engines out-of-the-box, developers can still use any external golang template engine, as `context.ResponseWriter()` is an `io.Writer`.

All of these five template engines have common features with common API, like Layout, Template Funcs, Party-specific layout, partial rendering and more.

The standard html,
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/go-siris/siris"
    "github.com/go-siris/siris/context"
    "github.com/go-siris/siris/view"
)

func main() {
    app := siris.New() // defaults to these

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

    tmpl := view.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 }}
    tmpl.AddFunc("greet", func(s string) string {
        return "Greetings " + s + "!"
    })
    app.AttachView(tmpl)

    app.Get("/", hi)

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

func hi(ctx context.Context) {
    ctx.ViewData("Title", "Hi Page")
    ctx.ViewData("Name", "Siris") // {{.Name}} will render: Siris
    // 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/go-siris/siris"
    "github.com/go-siris/siris/context"
    "github.com/go-siris/siris/view"
)

func main() {
    app := siris.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.AttachView(view.HTML("./templates", ".html").Binary(Asset, AssetNames))
    app.Get("/", hi)

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

type page struct {
    Title, Name string
}

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

A real example can be found here: https://github.com/go-siris/siris/tree/master/_examples/intermediate/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 := view.Pug("./templates", ".jade")
pugEngine.Reload(true) // <--- set to true to re-build the templates on each request.
app.AttachView(pugEngine)

Each one of these template engines has different options located here: https://github.com/go-siris/siris/tree/master/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:

// sessions.go
package main

import (
    "github.com/go-siris/siris"
    "github.com/go-siris/siris/context"
    "github.com/go-siris/siris/sessions"
)

var (
    key = "my_sessionid"
)

func secret(ctx context.Context) {

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

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

func login(ctx context.Context) {
    session := ctx.Session()

    // Authentication goes here
    // ...

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

func logout(ctx context.Context) {
    session := ctx.Session()

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

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

    sess := sessions.New(sessions.Config{Cookie: key})
    app.AttachSessionManager(sess)

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

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

Running the example:

$ go run sessions.go

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

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

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

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/go-siris/siris/tree/master/_examples

Built'n Middleware:

https://github.com/go-siris/siris/tree/master/middleware

Community Middleware:

https://github.com/iris-contrib/middleware

Home Page:

http://go-siris.com

Index

• Constants
• Variables
• func ToHandler(handler interface{}) context.Handler
• type Application
  • func Default() *Application
  • func New() *Application
  • func (app *Application) AttachLogger(logWriter io.Writer)
  • func (app *Application) AttachSessionManager(manager sessions.Sessions)
  • func (app *Application) AttachView(viewEngine view.Engine) error
  • func (app *Application) Build() (err error)
  • func (app *Application) ConfigurationReadOnly() context.ConfigurationReadOnly
  • func (app *Application) Configure(configurators ...Configurator) *Application
  • func (app *Application) Listen(addr string)
  • func (app *Application) ListenLETSENCRYPT(addr string, cacheDirOptional ...string)
  • func (app *Application) ListenTLS(addr string, certFile, keyFile string)
  • func (app *Application) ListenUNIX(socketFile string, mode os.FileMode)
  • func (app *Application) Log(format string, a ...interface{})
  • func (app *Application) NewHost(srv *http.Server) *host.Supervisor
  • func (app *Application) OnStatusCode(statusCode int, handler context.Handler)
  • func (app *Application) Run(serve Runner, withOrWithout ...Configurator) error
  • func (app *Application) SPA(assetHandler context.Handler)
  • func (app *Application) Serve(l net.Listener) error
  • func (app *Application) SessionManager() (sessions.Sessions, error)
  • func (app *Application) View(writer io.Writer, filename string, layout string, bindingData interface{}) error
• type Configuration
  • func DefaultConfiguration() Configuration
  • func TOML(filename string) Configuration
  • func YAML(filename string) Configuration
  • func (c Configuration) GetCharset() string
  • func (c Configuration) GetDisableAutoFireStatusCode() bool
  • func (c Configuration) GetDisableBodyConsumptionOnUnmarshal() bool
  • func (c Configuration) GetDisablePathCorrection() bool
  • func (c Configuration) GetEnablePathEscape() bool
  • func (c Configuration) GetEnableReuseport() bool
  • func (c Configuration) GetFireMethodNotAllowed() bool
  • func (c Configuration) GetOther() map[string]interface{}
  • func (c Configuration) GetTimeFormat() string
  • func (c Configuration) GetTranslateFunctionContextKey() string
  • func (c Configuration) GetTranslateLanguageContextKey() string
  • func (c Configuration) GetVHost() string
  • func (c Configuration) GetViewDataContextKey() string
  • func (c Configuration) GetViewLayoutContextKey() string
• type Configurator
  • func WithCharset(charset string) Configurator
  • func WithConfiguration(c Configuration) Configurator
  • func WithOtherValue(key string, val interface{}) Configurator
  • func WithTimeFormat(timeformat string) Configurator
• type Runner
  • func Addr(addr string) Runner
  • func AutoTLS(addr string) Runner
  • func Listener(l net.Listener) Runner
  • func Raw(f func() error) Runner
  • func Server(srv *http.Server) Runner
  • func TLS(addr string, certFile, keyFile string) Runner

Constants

const (
	// MethodNone is a Virtual method
	// to store the "offline" routes.
	//
	// Conversion for router.MethodNone.
	MethodNone = router.MethodNone
	// NoLayout to disable layout for a particular template file
	// Conversion for view.NoLayout.
	NoLayout = view.NoLayout
)

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.

These may or may not stay.

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

These may or may not stay, you can use net/http's constants too.

const (

	// Version is the current version number of the Siris Web framework.
	//
	// Look https://github.com/go-siris/siris#where-can-i-find-older-versions for older versions.
	Version = "7.3.0"
)

Variables

var Cache = cache.Handler

Cache provides cache capabilities to a route's handler. Usage:

Get("/", siris.Cache(time.Duration(10*time.Second)), func(ctx context.Context){
   ctx.Writef("Hello, world!") // or a template or anything else
})

Deprecated. Use "github.com/go-siris/siris/cache" sub-package which contains the full features instead.

var CheckErr = func(err error) {
	if err != nil {
		panic(err)
	}
}

CheckErr is the old `Must`. It panics on errors as expected with the old listen functions, change of this method will affect only ListenXXX functions.

Its only callers are the following, deprecated, listen functions.

var EnableReuseport = func(app *Application) {
	app.config.EnableReuseport = true
}

EnableReuseport turns on the Reuseport feature.

var WithFireMethodNotAllowed = func(app *Application) {
	app.config.FireMethodNotAllowed = true
}

WithFireMethodNotAllowed enanbles the FireMethodNotAllowed setting.

See` Configuration`.

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

WithPathEscape enanbles the PathEscape setting.

See` Configuration`.

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

WithoutAutoFireStatusCode disables the AutoFireStatusCode setting.

See` Configuration`.

var WithoutBanner = func(app *Application) {
	app.config.DisableBanner = true
}

WithoutBanner turns off the write banner on server startup.

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

WithoutBodyConsumptionOnUnmarshal disables BodyConsumptionOnUnmarshal setting.

See` Configuration`.

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

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

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

WithoutPathCorrection disables the PathCorrection setting.

See` Configuration`.

Functions

func ToHandler

func ToHandler(handler interface{}) context.Handler

ToHandler converts native http.Handler & http.HandlerFunc to context.Handler.

Supported form types:

.ToHandler(h http.Handler)
.ToHandler(func(w http.ResponseWriter, r *http.Request))
.ToHandler(func(w http.ResponseWriter, r *http.Request, next http.HandlerFunc))

Deprecated. Use the "core/handlerconv" package instead, equivalent to `ToHandler` is its `FromStd` function.

Types

type Application

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

	Shutdown func(stdContext.Context) error
	// 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. Unlike `New` this method prepares some things for you. std html templates from the "./templates" directory, session manager is attached with a default expiration of 7 days, recovery and (request) logger handlers(middleware) are being registered.

func New

func New() *Application

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

func (*Application) AttachLogger

func (app *Application) AttachLogger(logWriter io.Writer)

AttachLogger attachs a new logger to the framework.

func (*Application) AttachSessionManager

func (app *Application) AttachSessionManager(manager sessions.Sessions)

AttachSessionManager registers a session manager to the framework which is used for flash messages too.

See context.Session too.

func (*Application) AttachView

func (app *Application) AttachView(viewEngine view.Engine) error

AttachView should be used to register view engines mapping to a root directory and the template file(s) extension. Returns an error on failure, otherwise nil.

func (*Application) Build

func (app *Application) Build() (err 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 siris.

func (*Application) ConfigurationReadOnly

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

ConfigurationReadOnly returns a structure which doesn't allow 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) Listen

func (app *Application) Listen(addr string)

Listen starts the standalone http server which listens to the addr parameter which as the form of host:port

Deprecated. Use `Run` instead.

func (*Application) ListenLETSENCRYPT

func (app *Application) ListenLETSENCRYPT(addr string, cacheDirOptional ...string)

ListenLETSENCRYPT starts the server listening at the specific nat address using key & certification taken from the letsencrypt.org 's servers it's also starts a second 'http' server to redirect all 'http://$ADDR/$PATH' to the' https://$ADDR/$PATH' it creates a cache file to store the certifications, for performance reasons, this file by-default is "./certcache" if you skip the second parameter then the cache file is "./letsencrypt.cache" if you want to disable cache then simple pass as second argument an empty empty string ""

Deprecated. Use `Run` instead.

func (*Application) ListenTLS

func (app *Application) ListenTLS(addr string, certFile, keyFile string)

ListenTLS starts the secure server with provided certificates, if you use this method the requests of the form of 'http://' will fail only https:// connections are allowed which listens to the addr parameter which as the form of host:port

Deprecated. Use `Run` instead.

func (*Application) ListenUNIX

func (app *Application) ListenUNIX(socketFile string, mode os.FileMode)

ListenUNIX starts the server listening to the new requests using a 'socket file'. Note: this works only on unix.

Deprecated. Use `Run` instead.

func (*Application) Log

func (app *Application) Log(format string, a ...interface{})

Log sends a message to the defined io.Writer logger, it's just a help function for internal use but it can be used to a cusotom middleware too.

See AttachLogger too.

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

func (app *Application) OnStatusCode(statusCode int, handler context.Handler)

OnStatusCode registers an error http status code based on the "statusCode" >= 400. The handler is being wrapepd by a generic handler which will try to reset the body if recorder was enabled and/or disable the gzip if gzip response recorder was active.

Deprecated. Use `OnErrorCode` instead.

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 siris 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), WithoutBanner, WithCharset("UTF-8"))

The Application can go online with any type of server or siris'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)

SPA accepts an "assetHandler" which can be the result of an app.StaticHandler or app.StaticEmbeddedHandler. It wraps the router and checks: if it;s an asset, if the request contains "." (this behavior can be changed via /core/router.NewSPABuilder), if the request is index, redirects back to the "/" in order to let the root handler to be executed, if it's not an asset then it executes the router, so the rest of registered routes can be executed without conflicts with the file server ("assetHandler").

Use that instead of `StaticWeb` for root "/" file server.

Example: https://github.com/go-siris/siris/tree/master/_examples/beginner/file-server/single-page-application

func (*Application) Serve

func (app *Application) Serve(l net.Listener) error

Serve serves incoming connections from the given listener.

Serve blocks until the given listener returns permanent error.

Deprecated. Use `Run` instead.

func (*Application) SessionManager

func (app *Application) SessionManager() (sessions.Sessions, error)

SessionManager returns the session manager which contain a Start and Destroy methods used inside the context.Session().

It's ready to use after the RegisterSessions.

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 Configuration

type Configuration struct {

	// EnableReuseport if setted to true then it turns on the Reuseport feature.
	//
	// Defaults to false.
	EnableReuseport bool `yaml:"EnableReuseport" toml:"EnableReuseport"`

	// DisableBanner if setted to true then it turns off the write banner on server startup.
	//
	// Defaults to false.
	DisableBanner bool `yaml:"DisableBanner" toml:"DisableBanner"`

	// 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 `yaml:"DisableInterruptHandler" toml:"DisableInterruptHandler"`

	// 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 `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/go-siris/siris/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 `yaml:"EnablePathEscape" toml:"EnablePathEscape"`

	// FireMethodNotAllowed if it's true router checks for StatusMethodNotAllowed(405) and
	//  fires the 405 error instead of 404
	// Defaults to false.
	FireMethodNotAllowed bool `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 `yaml:"DisableBodyConsumptionOnUnmarshal" toml:"DisableBodyConsumptionOnUnmarshal"`

	// 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 "framework.OnStatusCode(code, handler)".
	//
	// Defaults to false.
	DisableAutoFireStatusCode bool `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 `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 `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/go-siris/siris/tree/master/middleware/i18n.
	//
	// Defaults to "siris.translate" and "siris.language"
	TranslateFunctionContextKey string `yaml:"TranslateFunctionContextKey" toml:"TranslateFunctionContextKey"`

	// TranslateLanguageContextKey used for i18n.
	//
	// Defaults to "siris.language"
	TranslateLanguageContextKey string `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 "siris.ViewLayout"
	ViewLayoutContextKey string `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 "siris.viewData"
	ViewDataContextKey string `yaml:"ViewDataContextKey" toml:"ViewDataContextKey"`

	// 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{} `yaml:"Other" toml:"Other"`
	// contains filtered or unexported fields
}

Configuration the whole configuration for an Siris 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 Siris 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.

Usage: app := siris.Run(siris.Addr(":8080"), siris.WithConfiguration(siris.YAML("myconfig.tml")))

func YAML

func YAML(filename string) Configuration

YAML reads Configuration from a configuration.yml file.

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

Usage: app := siris.Run(siris.Addr(":8080"), siris.WithConfiguration(siris.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) 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) GetEnableReuseport

func (c Configuration) GetEnableReuseport() bool

GetEnableReuseport is the configuration.EnableReuseport, returns true when its use the feature of the Reusepost listener.

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) 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(siris.Addr(":8080"), siris.WithConfiguration(siris.Configuration{/* fields here */ })) or siris.WithConfiguration(siris.YAML("./cfg/iris.yml")) or siris.WithConfiguration(siris.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 WithTimeFormat

func WithTimeFormat(timeformat string) Configurator

WithTimeFormat sets the TimeFormat setting.

See` Configuration`.

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

See `Run` for more.

func AutoTLS

func AutoTLS(addr string) 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.

See `Run` for more.

func Listener

func Listener(l net.Listener) 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`.

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 Siris can run by-default.

See `Run` for more.

func Server

func Server(srv *http.Server) Runner

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

See `Run` for more.

func TLS

func TLS(addr string, certFile, keyFile string) 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.

See `Run` for more.