Nirvana

English version of this docs is expired. We will rewrite it in the future. If you have any idea or you want to contribute to this docs, PLEASE let us know it.

Nirvana is a Golang web framework with a focus on developer efficiency and performance. It handles request routing, input validation, logging, error handling, etc. with sensible defaults and options for complete control. Built for developers with ❤️ by developers in Caicloud.

Status

Currently the framework is 🚧 WIP 🚧, any comments or contributions are welcome!

Getting Started

In Nirvana, APIs are defined via definition.Descriptor. We will not introduce details of the concept Descriptor, instead, let's take a look at a contrived example:

// API descriptor.
var echo = definition.Descriptor{
    Path:        "/echo",
    Description: "Echo API",
    Definitions: []definition.Definition{
        {
            Method: definition.Get,
            Function: Echo,
            Consumes: []string{definition.MIMEAll},
            Produces: []string{definition.MIMEText},
            Parameters: []definition.Parameter{
                {
                    Source: definition.Query,
                    Name: "msg",
                    Description: "Corresponding to the second parameter",
                },
            },
            Results: []definition.Result{
                {
                    Destination: definition.Data,
                    Description: "Corresponding to the first result",
                },
                {
                    Destination: definition.Error,
                    Description: "Corresponding to the second result",
                },
            },
        },
    },
}

This is an echo server API descriptor. The descriptor is a bit complex at first glance, but is actually quite simple. Below is a partially translated HTTP language:

HTTP Path: /echo[?msg=]
HTTP Method: Get
HTTP Headers:
    Content-Type: Any Type
    Accept: text/plain or */*

The request handler Echo receives two parameters and returns two results, as defined in our descriptor. Note the first parameter is always context.Context - it is injected by default config.

// API function.
func Echo(ctx context.Context, msg string) (string, error) {
    return msg, nil
}

Nirvana will parse incoming request and generate function parameters for Echo function as defined via Definition.Parameters - parameters will be converted into the exact type defined in Echo. Once done, Nirvana collects the results and sends back response.

With our API descriptors ready, we can now create a server to serve requests:

package main

import (
    "context"

    "github.com/caicloud/nirvana"
    "github.com/caicloud/nirvana/definition"
    "github.com/caicloud/nirvana/log"
)

func main() {
    config := nirvana.NewDefaultConfig("", 8080)
    config.Configure(nirvana.Descriptor(echo))
    log.Infof("Listening on %s:%d", config.IP, config.Port)
    if err := nirvana.NewServer(config).Serve(); err != nil {
        log.Fatal(err)
    }
}

Now run the server and test it:

go run ./examples/getting-started/basics/echo.go
INFO  0202-16:34:38.663+08 echo.go:65 | Listening on :8080
INFO  0202-16:34:38.663+08 builder.go:163 | Definitions: 1 Middlewares: 0 Path: /echo
INFO  0202-16:34:38.663+08 builder.go:178 |   Method: Get Consumes: [*/*] Produces: [text/plain]

In another terminal:

$ curl "http://localhost:8080/echo?msg=test"
test

For full example code, see basics.

results matching ""

    No results matching ""