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
- Support
- Third-party middleware list
- Testing
- Philosophy
- People
- Versioning
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
Feature | More Information |
---|---|
high performance | benchmark |
Authentication | basicauth oauth2 TODO JWT |
Cache | cache-markdown |
Certificates | letsencrypt custom |
Compression | gzip and deflate |
Decode Json, Forms | json form |
Encode Json, JsonP, XML, Forms, Markdown | json cache-markdown |
Error handling | custom [error handler] [panic handler] |
http2 push | TODO add Documentation |
Limits | RequestBody TODO add docu |
Localization | i18n |
Logger Engines | file-logger request-logger |
Routing | routing |
Sessions | sessions |
Static Files | file-server |
Subdomains and Grouping | subdomains |
Template HTML, django, pug(jade), handlebars, amber | views |
Tooling | Typescript integration + Web IDE |
Websockets | websockets |
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.
β and watch the project, will notify you about updates.π publish an article or share a tweet about siris.
Third Party Middleware
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.