goserv

README

go-serv

go-serv attempts to take care of common requirements for web applications while not dictating any specific Go web framework.

Repo: https://github.com/ashcrow/go-serv/

Warning: Currently in development with no official release yet.

Features

• Built on Go's net/http library
• Framework agnostic
• Logging via logrus (https://github.com/Sirupsen/logrus/)
• Configuration file parsing via TOML (https://github.com/toml-lang/toml/)
• Flags through pflag (https://github.com/ogier/pflag)
• Command line flags which can overrule configuration file
• Simple status/health system for exposing structs
• Run HTTP and HTTPS servers with the same binary.

Installation

$ go get gopkg.in/ashcrow/go-serv.v0

Unittesting

$ go test -v -cover

or

$ make test

Configuration File Example

# Note that the names are the same across the BaseConfiguration
# struct, this config file, and command line flags.
BindAddress = "127.0.0.1"
BindPort    = 8000
LogLevel    = "info"
LogFile     = "/tmp/out.log"

Default Command Line Flags

Application Defaults

$ ./status-example -help
Usage of ./status-example:
  --BindAddress="0.0.0.0": Bind address.
  --BindHttpsPort=443: HTTPS bind port.
  --BindPort=80: HTTP bind port.
  --CertFile="": Cert file.
  --KeyFile="": Key file.
  --LogFile="": Log file.
  --LogLevel="info": Log level.
  --MaxHeaderBytes=1048576: Max header bytes.
  --ReadTimeout=10s: Read timeout.
  --WriteTimeout=10s: Write timeout.

Configuration File Defaults

$ ./status-example -help /path/to/conf.toml
Usage of ./status-example:
  --BindAddress="127.0.0.1": Bind address.
  --BindHttpsPort=8181: HTTPS bind port.
  --BindPort=8000: HTTP bind port.
  --CertFile="./cert.pem": Cert file.
  --KeyFile="./key.pem": Key file.
  --LogFile="/tmp/out.log": Log file.
  --LogLevel="info": Log level.
  --MaxHeaderBytes=1048576: Max header bytes.
  --ReadTimeout=10s: Read timeout.
  --WriteTimeout=10s: Write timeout.

Examples

Examples can be found in the examples folder

Building Examples

There is a Makefile provided to build the code in the examples folder.

$ make build-examples-all

Documentation

Overview

Package goserv is a simple web application server bootstrap. It provides a common base for those wishing to focus on their application rather than on setting up flags, configuration files or logging. go-serv also comes with a simple status system for those who wish to expose structures via HTTP(s) for monitoring.

Index

• Constants
• Variables
• func BackgroundRunHttp(server *http.Server, conf *BaseConfiguration) chan error
• func BackgroundRunHttps(server *http.Server, conf *BaseConfiguration) chan error
• func FuncHandler(callable Callable, pretty bool) http.HandlerFunc
• func LogAccess(handler http.Handler) http.Handler
• func NewServer(conf *BaseConfiguration) http.Server
• func RestrictByIP(handler http.HandlerFunc, allowedIps []string) http.HandlerFunc
• func RunHttpAndHttps(server *http.Server, conf *BaseConfiguration) error
• func StructHandler(item interface{}, pretty bool) http.HandlerFunc
• type BaseConfiguration
• type Callable
• type Status
• Bugs

Constants

const VERSION = "0.0.0"

Version of the library

Variables

var (
	// Package level logger
	Logger logrus.Logger

	// Logger used with http.Server. This is an instance of Logger.Writer()
	ServerErrorLogger log.Logger
)

Functions

func BackgroundRunHttp

func BackgroundRunHttp(server *http.Server, conf *BaseConfiguration) chan error

BackgroundRunHttp runs an http server in a goroutine. Returns a send-only channel to watch for errors.

func BackgroundRunHttps

func BackgroundRunHttps(server *http.Server, conf *BaseConfiguration) chan error

BackgroundRunHttps runs an https server in a goroutine. Returns a send-only channel to watch for errors.

func FuncHandler

func FuncHandler(callable Callable, pretty bool) http.HandlerFunc

FuncHandler takes a Callable and bool to note if the results should be pretty and passes the resulting interface go StatusHandler.StructHandler

func LogAccess

func LogAccess(handler http.Handler) http.Handler

LogAccess logs Access requests that come in to the server

func NewServer

func NewServer(conf *BaseConfiguration) http.Server

NewServer creates a new http.Server instance based off the BaseConfiguration. NewServer also handles reading the TOML configuration file and providing/reading the command line flags. Because of this NewServer should always be called after all flags have been defined.

func RestrictByIP

func RestrictByIP(handler http.HandlerFunc, allowedIps []string) http.HandlerFunc

RestrictByIP restricts access to a handler by IP

func RunHttpAndHttps

func RunHttpAndHttps(server *http.Server, conf *BaseConfiguration) error

Runs both Http and Https servers in their own goroutines. If one server exists the channels are closed and execution returns to the main goroutine.

func StructHandler

func StructHandler(item interface{}, pretty bool) http.HandlerFunc

StructHandler takes an interface and bool to note if the results should be pretty and turns it into Status output in JSON

Types

type BaseConfiguration

type BaseConfiguration struct {
	BindAddress    string
	BindPort       int
	ReadTimeout    time.Duration
	WriteTimeout   time.Duration
	MaxHeaderBytes int
	LogLevel       string
	LogFile        string
	BindHttpsPort  int
	CertFile       string
	KeyFile        string
}

BaseConfiguration structure which can be filled out via defaults passed via flags, a configuration file or via the defaults set by the programmer (in that order of precedence)

type Callable

type Callable func() interface{}

Callable is a function that takes no input and returns on item

type Status

type Status struct {
	Time time.Time
	Data interface{}
}

Status is used for the output of all status items

Notes

Bugs

• This needs work!!!