nirvana

README

nirvana

Introduction

nirvana is a golang http framework designed with productivity and usability in mind. It aims to be the building block for all golang services in Caicloud. The high-level goals are:

• Reduce api level errors and inconsistency
• Improve engineering productivity via removing repeated work, adding code generation, etc
• Adding new resource type should only require defining struct definition
• Adding validation should only require declaring validation method as part of struct definition
• Consistent behavior, structure and layout across all golang server projects

Features

Following is a list of requirements we've seen from writing golang services. Some of these features are general ones while some are specific to Caicloud. Note this is not an exhaustive list.

Routing, Request & Response

• Routes mapping from request to function
• Routes grouping
• Request/Response API object marshal/unmarshal
• General middleware support with sane default (logging, recovery, tracing)
• Contextual process chain and parameter injection
• Enforcing API error convention

Instrumentation

• Provide default metrics at well-known endpoints for prometheus to scrape
• Tracing is provided by default to allow better troubleshooting
• Profiling can be enabled in debug mode for troubleshootting

Validation

• Provide default validation on api types with struct tags
• Support custom validations defined by developers on api types
• Support validation on all parameters (path, query, etc)

Usability

• A working project should be brought up with few lines using the framework
• Framework must automatically follow engineering conventions to help developers focus on business logic
• OpenAPI (swagger 2.0) specification can be generated automatically with no extra work
• Provides a well-established layout conforming to golang project layout
• Easy and standard configuration management
• A reasonable support for websocket

Documentation

Index

• func RegisterConfigInstaller(ci ConfigInstaller)
• type Config
  • func NewConfig() *Config
  • func NewDefaultConfig(ip string, port uint16) *Config
  • func (c *Config) Config(name string) interface{}
  • func (c *Config) Configure(configurers ...Configurer) *Config
  • func (c *Config) Set(name string, config interface{})
• type ConfigInstaller
  • func ConfigInstallerFor(name string) ConfigInstaller
• type Configurer
  • func Descriptor(descriptors ...definition.Descriptor) Configurer
  • func Filter(filters ...service.Filter) Configurer
  • func IP(ip string) Configurer
  • func Logger(logger log.Logger) Configurer
  • func Modifier(modifiers ...service.DefinitionModifier) Configurer
  • func Port(port uint16) Configurer
• type Server
  • func NewServer(c *Config) Server

Functions

func RegisterConfigInstaller

func RegisterConfigInstaller(ci ConfigInstaller)

RegisterConfigInstaller registers a config installer.

Types

type Config

type Config struct {
	// IP is the ip to listen. Empty means `0.0.0.0`.
	IP string
	// Port is the port to listen.
	Port uint16
	// Logger is used to output info inside framework.
	Logger log.Logger
	// Descriptors contains all APIs.
	Descriptors []definition.Descriptor
	// Filters is http filters.
	Filters []service.Filter
	// Modifiers is definition modifiers
	Modifiers service.DefinitionModifiers
	// contains filtered or unexported fields
}

Config describes configuration of server.

func NewConfig

func NewConfig() *Config

NewConfig creates a pure config.

func NewDefaultConfig

func NewDefaultConfig(ip string, port uint16) *Config

NewDefaultConfig creates default config. Default config contains:

Filters: RedirectTrailingSlash, FillLeadingSlash, ParseRequestForm.
Modifiers: FirstContextParameter, EmptyConsumeForHTTPGet,
           ConsumeAllIfComsumesIsEmpty, ProduceAllIfProducesIsEmpty,
           ConsumeNoneForHTTPGet, ConsumeNoneForHTTPDelete,
           ProduceNoneForHTTPDelete.

func (*Config) Config

func (c *Config) Config(name string) interface{}

Config gets external config by name.

func (*Config) Configure

func (c *Config) Configure(configurers ...Configurer) *Config

Configure configs by configurers. It panics if an error occurs.

func (*Config) Set

func (c *Config) Set(name string, config interface{})

Set sets external config by name. Set a nil config will delete it.

type ConfigInstaller

type ConfigInstaller interface {
	// Name is the external config name.
	Name() string
	// Install installs stuffs before server starting.
	Install(builder service.Builder, config *Config) error
	// Uninstall uninstalls stuffs after server terminating.
	Uninstall(builder service.Builder, config *Config) error
}

ConfigInstaller is used to install config to service builder.

func ConfigInstallerFor

func ConfigInstallerFor(name string) ConfigInstaller

ConfigInstallerFor gets installer by name.

type Configurer

type Configurer func(c *Config) error

Configurer is used to configure server config.

func Descriptor

func Descriptor(descriptors ...definition.Descriptor) Configurer

Descriptor returns a configurer to add descriptors into config.

func Filter

func Filter(filters ...service.Filter) Configurer

Filter returns a configurer to add filters into config.

func IP

func IP(ip string) Configurer

IP returns a configurer to set ip into config.

func Logger

func Logger(logger log.Logger) Configurer

Logger returns a configurer to set logger into config.

func Modifier

func Modifier(modifiers ...service.DefinitionModifier) Configurer

Modifier returns a configurer to add definition modifiers into config.

func Port

func Port(port uint16) Configurer

Port returns a configurer to set port into config.

type Server

type Server interface {
	// Serve starts to listen and serve requests.
	// The method won't return except an error occurs.
	Serve() error
}

Server is a complete API server. The server contains a router to handle all requests form clients.

func NewServer

func NewServer(c *Config) Server

NewServer creates a nirvana server.