rest

README

rest

This is the template repository for a standard RESTful webservice for ndev.

For a sample of how to use it, see /cmd/demo.

Documentation

Index

• func FatalFunc(builder Builder, reason string) func()
• func LogMW(logger log.FieldLogger, handler http.Handler) http.HandlerFunc
• func StandardSetup(cf *Config, builder Builder) *http.Server
• func WatchSignals(fhup, fint, fterm func())
• type Builder
• type Config
  • func DefaultConfig() *Config
  • func NewConfig() *Config
  • func (cf *Config) AddDuration(name string, def string)
  • func (cf *Config) AddFlag(name string, def bool)
  • func (cf *Config) AddInt(name string, def int)
  • func (cf *Config) AddRequiredFlag(name string)
  • func (cf *Config) AddRequiredInt(name string)
  • func (cf *Config) AddRequiredString(name string)
  • func (cf *Config) AddString(name string, def string)
  • func (cf *Config) AddStringArray(name string, defaults ...string)
  • func (cf *Config) Check()
  • func (cf *Config) Get(name string) (interface{}, bool)
  • func (cf *Config) GetDuration(name string) time.Duration
  • func (cf *Config) GetFlag(name string) bool
  • func (cf *Config) GetInt(name string) int
  • func (cf *Config) GetString(name string) string
  • func (cf *Config) GetStringArray(name string) []string
  • func (cf *Config) Load()
  • func (cf *Config) ParseCmdLine()
  • func (cf *Config) ParseEnv()
  • func (cf *Config) SetDefault(name string, def interface{})
• type ConfigItem
• type LogWriter
  • func (w *LogWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)
  • func (w *LogWriter) Write(b []byte) (int, error)
  • func (w *LogWriter) WriteHeader(status int)

Functions

func FatalFunc

func FatalFunc(builder Builder, reason string) func()

FatalFunc returns a function that logs and shuts down the service

func LogMW

func LogMW(logger log.FieldLogger, handler http.Handler) http.HandlerFunc

LogMW wraps a regular handler and replaces the writer with some logging middleware.

func StandardSetup

func StandardSetup(cf *Config, builder Builder) *http.Server

StandardSetup is what should be called to set up the service before running it. It returns a server, or possibly nil.

func WatchSignals

func WatchSignals(fhup, fint, fterm func())

WatchSignals registers with the operating system to receive specific signals and can call functions on those signals. In the case of SIGTERM, if the function returns, os.Exit is called with a normal exit code of 0.

Types

type Builder

type Builder interface {
	Build(logger *log.Entry, path string) *boneful.Service
	GetLogger() *log.Entry
}

Builder is the interface to which all service builders must conform

type Config

type Config map[string]ConfigItem

Config maintains a map of configuration values. They can be read from the environment and/or the command line (command line overrides environment). The names of configuration items are strings containing letters, numbers, underscores, and hyphens. They can be any of int, string, []string, duration, or bool. Although there are lots of configuration packages out there, there didn't seem to be one that was both simple and would allow the standard service to define part of the configuration, and client packages to define the rest.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig creates a default configuration including the values that are used by the standard server.

func NewConfig

func NewConfig() *Config

NewConfig constructs an empty config

func (*Config) AddDuration

func (cf *Config) AddDuration(name string, def string)

AddDuration adds a config element that is a duration with a default value. The duration is specified as a string and is returned as a time.Duration.

func (*Config) AddFlag

func (cf *Config) AddFlag(name string, def bool)

AddFlag adds a config element that is a boolean flag with a default value.

func (*Config) AddInt

func (cf *Config) AddInt(name string, def int)

AddInt adds a config element that is an integer with its default.

func (*Config) AddRequiredFlag

func (cf *Config) AddRequiredFlag(name string)

AddRequiredFlag adds a config element that is a boolean with no default value (it must be specified or the server will fail to start).

func (*Config) AddRequiredInt

func (cf *Config) AddRequiredInt(name string)

AddRequiredInt adds a config element that is an integer with no default value (it must be specified or the server will fail to start).

func (*Config) AddRequiredString

func (cf *Config) AddRequiredString(name string)

AddRequiredString adds a config element that is a string with no default value (it must be specified or the server will fail to start).

func (*Config) AddString

func (cf *Config) AddString(name string, def string)

AddString adds a config element that is a string with its default.

func (*Config) AddStringArray

func (cf *Config) AddStringArray(name string, defaults ...string)

AddStringArray adds a config element that is an array of strings with an arbitrary list of default values

func (*Config) Check

func (cf *Config) Check()

Check walks the config and looks for required config items that were not specified; if it finds any, it logs it and kills the server.

func (*Config) Get

func (cf *Config) Get(name string) (interface{}, bool)

Get is a generic Get that returns an interface and a flag if it was found to be a valid config variable.

func (*Config) GetDuration

func (cf *Config) GetDuration(name string) time.Duration

GetDuration retrieves a duration (in ParseDuration format) from the config as a time.Duration.

func (*Config) GetFlag

func (cf *Config) GetFlag(name string) bool

GetFlag retrieves a boolean from the config, or false if not found.

func (*Config) GetInt

func (cf *Config) GetInt(name string) int

GetInt retrieves an integer from the config, or 0 if not found.

func (*Config) GetString

func (cf *Config) GetString(name string) string

GetString retrieves a string from the config, or "" if not found.

func (*Config) GetStringArray

func (cf *Config) GetStringArray(name string) []string

GetStringArray retrieves a string array from the config, or []string{} if not found.

func (*Config) Load

func (cf *Config) Load()

Load fetches config values from the environment, and then from the command line, then checks to see if any required variables were missing. Envvars are higher priority than default values, and cmd line is higher priority than envvars.

func (*Config) ParseCmdLine

func (cf *Config) ParseCmdLine()

ParseCmdLine parses the command line and stores the values it finds into the Config. Command line flags are expected to start with either 1 or 2 leading hyphens (no short codes are supported), and are case-insensitive. Hyphens and underscores (after the leading ones) are equivalent. Values *must* be specified with an equals sign and be part of the same argument, so `--foo=bar` is good, `--foo bar` is bad.

func (*Config) ParseEnv

func (cf *Config) ParseEnv()

ParseEnv reads the config and looks for environment variables that match, parsing their values appropriately and overwriting existing configs

func (*Config) SetDefault

func (cf *Config) SetDefault(name string, def interface{})

SetDefault allows setting a default value for a name after it has been created. It does no error checking and if the default type doesn't agree with the config item's type, weird things can happen.

type ConfigItem

type ConfigItem struct {
	Name    string
	Type    string
	Value   interface{}
	Default interface{}
}

ConfigItem is one element of the Config map

type LogWriter

type LogWriter struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

LogWriter proxies http.ResponseWriter and logs.

func (*LogWriter) Hijack

func (w *LogWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)

Hijack implements http.Hijacker for LogWriter

func (*LogWriter) Write

func (w *LogWriter) Write(b []byte) (int, error)

WriteHeader proxies http.ResponseWriter.Write

func (*LogWriter) WriteHeader

func (w *LogWriter) WriteHeader(status int)

WriteHeader proxies http.ResponseWriter.WriteHeader