Awesome

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
• Support
• Third-party middleware list
• Testing
• Philosophy
• People
• Versioning
  • When should I upgrade?
  • Where can I find older versions?

Installation

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

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

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().Logger().Info("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().Logger().Info("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")
}

Feature Overview

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.

Hints --some performance hints and tooling.

Support

• Chat Ask the Community for help
• Post a feature request or report a bug, will help to make the framework even better.
• :star: and watch the project, will notify you about updates.
• :earth_americas: publish an article or share a tweet about siris.

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

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.

Version

Current: 7.4.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.

Previous Iris versions are archived at iris archive

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 Siris may requires different license agreements.