webserver

README

Webserver Infrastructure

This package has been open sourced in hopes some other gopher finds it helpful. This package was not open sourced in hopes of becoming a really popular framework.

What is this package all about? The Webserver provides infrastructure by supporting common webserver behavior so gophers can focus on value.

This Webserver does not support the standard GO http interface but you can easily work with handlers that do if you'd like. What this Webserver does do is make it easier for gophers to build the experiences we need by providing the following:

• Several convenience methods for working with input and output
• Means of passing information between handlers without requiring locking
• The ability to execute pre-handlers, post-handlers, and wrap handlers for custom behavior.
• Building blocks to help you auto-document handler/endpoint behavior.

Known Bugs

A version has not yet shipped.

Developing the Webserver Infrastructure

Before You Start

• Verify you have the required software installed on your system.
• The Webserver Infrastructure is intended to run on Linux, Mac, and Windows and may be run on either x86 (32/64bit) or ARM architecture. Download the correct Go distribution for your environment.
• Ensure you have access to the source repository and database environments.

Required Software

1. Go Distribution v1.4 distribution for your system.
2. A working git installation and a registered ssh-key for the repository.

Download the Source

Step 1: Use GO's get command to download the source code. The go get command will use your git installation to download the source code and download any dependent GO packages from their repositories. The source code will be downloaded into your $GO_PATH directory. See the GO documentation if you run into trouble.

Compiling

This is a support library and will not compile on it's own.

Writing Automated Tests

This paragraph still needs to be written.

Go BDD Testing using github.com/onsi/ginkgo

Please familiarize yourself with the Golang Ginkgo BDD Testing Framework.

Questions?

Please contact Aaron Greenlee!

Change Log

A version has not yet shipped.

Documentation

Overview

Package webserver is responsible for web server operations including creating new web servers, registering handlers, and rendering and caching templates. One might think of this package as our own web framework that uses conventions to consistently work across products and projects.

Index

• Constants
• Variables
• type Conventions
• type HandlerDef
• type HandlerFunc
• type RouteNamespace
  • func (rns *RouteNamespace) FILES(url string, path string)
  • func (rns *RouteNamespace) GET(path string, handlers ...HandlerFunc)
  • func (rns *RouteNamespace) Handle(method string, path string, handlers []HandlerFunc)
  • func (rns *RouteNamespace) POST(path string, handlers ...HandlerFunc)
  • func (rns *RouteNamespace) PUT(path string, handlers ...HandlerFunc)
• type Server
  • func New(debugLogger *log.Logger, infoLogger *log.Logger, warningLogger *log.Logger, ...) *Server
  • func (s *Server) RegisterHandlerDef(h HandlerDef)
  • func (s *Server) RegisterHandlerDefs(h []HandlerDef)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (s *Server) Start(address string)

Constants

const (
	// MIMEJSON represents the standard classification for data encoded as JSON.
	MIMEJSON = "application/json"
	// MIMEHTML represents the standard classification for HTML web pages.
	MIMEHTML = "text/html"
	// MIMEXML represents the standard classification for data encoded as XML.
	MIMEXML = "application/xml"
	// MIMEXMLTEXT represents the standard classification for a XML text document.
	MIMEXMLTEXT = "text/xml"
	// MIMEPLAIN represents the standard classification for plain text data without
	// any encoded format and is generally human readable text data.
	MIMEPLAIN = "text/plain"
	// MIMEFORM represents form data encoded by a Web browser posted to a server.
	MIMEFORM = "application/x-www-form-urlencoded"
	// MIMECSS represents the standard classificaton for Cascading Style Sheets.
	MIMECSS = "text/css"
	// MIMEJS represents the standard classification for JavaScript.
	MIMEJS = "application/javascript"
	// MIMEPNG represents the standard classificaton for PNG images.
	MIMEPNG = "image/png"
	// MIMEJPEG represents the standard classificaton for JPEG/JPG images.
	MIMEJPEG = "image/jpeg"
	// MIMEGIF represents the standard classificaton for GIF images.
	MIMEGIF = "image/gif"
	// MIMEXICON represents the proposed classification for icons such as favicon images
	MIMEXICON = "image/x-icon"
)

Variables

var (
	// Settings allows a developer to override the conventional settings of the
	// webserver.
	Settings = Conventions{
		Render:                 &render.Settings,
		EnableStaticFileServer: false,
		SystemTemplates: map[string]string{
			"onMissingHandler": "errors/onMissingHandler",
		},

		RequestDurationWarning: time.Second / 4,
		// contains filtered or unexported fields
	}
)

Types

type Conventions

type Conventions struct {
	// Reference to the conventions of the webserver's rendering engine
	Render *render.Conventions
	// EnableStaticFileServer if true, enables the serving of static assets such as CSS, JS, or other files.
	EnableStaticFileServer bool
	// StaticFilePath defines the releative root directory static files can be served from. Example "public" or "web-src/cdn/"
	StaticFilePath string
	// SystemTemplates is a map of keys to template paths. Default templates
	// such as `onMissingHandler` (404) are configurable here allowing developers
	// to customize exception pages for each implementation.
	SystemTemplates map[string]string

	// Flag requests that take longer than N miliseconds. Default is 250ms (1/4th a second)
	RequestDurationWarning time.Duration
	// contains filtered or unexported fields
}

Conventions defines our configuration.

type HandlerDef

type HandlerDef struct {
	// A string to name the handler
	Alias string
	// The method to interact with the handler (i.e. GET or POST)
	Method string
	// The URL Path to access the handler
	Path string
	// The location of a HTML file describing the HandlerDef behavior in detail.
	Documentation string
	// The maximum time this HandlerFunc should take to process. This information is useful for performance testing.
	DurationExpectation string
	// An optional reference to a structure containing input paramaters for the HandlerFunc.
	Params interface{}
	// An optional reference to a structure containing output for successful HandlerFunc calls.
	Response interface{}
	// An optional reference to a map describing extra headers for the HandlerFunc (input or output)
	Headers map[string]string
	// The handler to register
	Handler HandlerFunc
	// A chain of handlers to process before executing the primary HandlerFunc
	PreHandlers []HandlerDef
	// A chain of handlers to process after executing the primary HandlerFunc
	PostHandlers []HandlerDef
}

HandlerDef provides for a system to organize HandlerFunc metadata. Use of a HandlerDef to describe a HandlerFunc is not required but provides a way to eaisly configure advanced behavior and document that behavior.

This abstraction binds documentation to implementation. This tight coupeling between the two helps reduce documentaton buridens and ensures documentation is kept current.

type HandlerFunc

type HandlerFunc func(*context.Context)

HandlerFunc is a request event handler and accepts a RequestContext

type RouteNamespace

type RouteNamespace struct {
	DebugLogger   *log.Logger
	InfoLogger    *log.Logger
	WarningLogger *log.Logger
	ErrorLogger   *log.Logger
	// contains filtered or unexported fields
}

RouteNamespace groups routes according to a specific URL entry point or prefix.

func (*RouteNamespace) FILES

func (rns *RouteNamespace) FILES(url string, path string)

FILES registers a url and directory path to serve static files. The webserver will serve all static files in any directories under these paths. Executing this method enables the static file server flag.

func (*RouteNamespace) GET

func (rns *RouteNamespace) GET(path string, handlers ...HandlerFunc)

GET is a conveinence method for registering handlers

func (*RouteNamespace) Handle

func (rns *RouteNamespace) Handle(method string, path string, handlers []HandlerFunc)

Handle registers handlers!

func (*RouteNamespace) POST

func (rns *RouteNamespace) POST(path string, handlers ...HandlerFunc)

POST is a conveinence method for registering handlers

func (*RouteNamespace) PUT

func (rns *RouteNamespace) PUT(path string, handlers ...HandlerFunc)

PUT is a conveinence method for registering handlers

type Server

type Server struct {
	*RouteNamespace

	MissingHandler []HandlerFunc

	// HandlerDef maintains a map of all registered handler definitions
	HandlerDef map[string]HandlerDef

	DebugLogger   *log.Logger
	InfoLogger    *log.Logger
	WarningLogger *log.Logger
	ErrorLogger   *log.Logger
	// contains filtered or unexported fields
}

Server represents an instance of the webserver.

func New

func New(
	debugLogger *log.Logger,
	infoLogger *log.Logger,
	warningLogger *log.Logger,
	errorLogger *log.Logger) *Server

New returns a new WebServer.

func (*Server) RegisterHandlerDef

func (s *Server) RegisterHandlerDef(h HandlerDef)

RegisterHandlerDef accepts a HandlerDef and registers it's behavior with the webserver.

func (*Server) RegisterHandlerDefs

func (s *Server) RegisterHandlerDefs(h []HandlerDef)

RegisterHandlerDefs accepts a slice of HandlerDefs and registers each

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP handles all requests of our web server

func (*Server) Start

func (s *Server) Start(address string)

Start launches the webserver so that it begins listening and serving requests on the desired address.