go-siris / siris

DEPRECATED: The community driven fork of Iris. The fastest web framework for Golang!
Other
142 stars 16 forks source link
cross-platform crossplatform easy-to-use framework go golang high-performance http2 http2-server https iris party-middleware quic quic-server siris tls web-framework

Logo

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

Build status Report card Support forum Examples Godocs Chat

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

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

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.