ale

README

Ale is a minimalistic web framework written in Go.

Why?

Why does the world need another web framework?

It doesn't.

I'm a strong believer in the Go philosophy of not using extraneous frameworks, and building everything yourself from scratch.

On the other hand, I write multiple web applications, and I don't want to duplicate all the boilerplate code in every one. So this package is simply my web framework scaffolding. I make no attempt to make this useful for anyone else. I publish it on GitHub for my own personal convenience, and on the off chance that someone else might also find it useful. But I make no guarantees, or necessarily even any effort, to make this product meaningful or useful for anyone other than me, in my own situation.

Why the name?

There's a trend toward naming Go web frameworks after cocktails. I hate cocktails. But I like beer. And "Ale" is shorter than "Belgian Tripel", which is my favorite style, and seems catchier than either "Red" or "IPA", which tie it for length.

What does it do?

Ale is designed to make writing 12-factor apps easier, and this informs many assumptions.

Ale simplifies a few tedious tasks I was tired of repeating in my web apps:

• Reading configuration from the environment
• Logging to stdout
• Debugging to stdout when the 'debug' build flag is used
• Port binding
• Graceful shutdown

TODO:

• Simple handling of html/template

What does it not do?

Anything not on the list above, Ale does not attempt to do.

What license?

Ale is released under the MIT license. See the LICENSE.txt file for details.

Documentation

Index

• Constants
• Variables
• func ExtractClientIP(req *http.Request) (net.IP, error)
• func GetClientIP(r *http.Request) net.IP
• func GetParams(r *http.Request) map[string]string
• func GetStash(r *http.Request) map[string]interface{}
• type Context
• type ResponseWriter
• type Server
  • func New() *Server
  • func (s *Server) EnvPrefix() string
  • func (s *Server) FastCGI() error
  • func (s *Server) GetConf(key string) (val string)
  • func (s *Server) Render(w ResponseWriter, r *http.Request)
  • func (s *Server) Run() error
  • func (s *Server) ServeFiles(path string, root http.FileSystem)
  • func (s *Server) ServeHTTP(rw http.ResponseWriter, req *http.Request)
  • func (s *Server) SetEnvPrefix(prefix string)
• type View
  • func GetView(r *http.Request) *View
  • func (v *View) Copy() *View
  • func (v *View) GetFuncMap() template.FuncMap

Constants

const (
	// ConfHTTPBind is the config key for the HTTP bind address
	ConfHTTPBind = "HTTP_BIND"
	// ConfHTTPSBind is the config key for the HTTPS bind address
	ConfHTTPSBind = "HTTPS_BIND"
	// ConfSSLCert is the config key for the SSL Certificate location
	ConfSSLCert = "SSL_CERT"
	// ConfSSLKey is the config key for the SSL Key location
	ConfSSLKey = "SSL_KEY"
	// ConfFCGIBind will enable FastCGI mode if set to a bind address
	ConfFCGIBind = "FASTCGI_BIND"
	// ConfNoLog will disable logging to stdout
	ConfNoLog = "NOLOG"
	// ConfNoCompress will disable opportunistic compression. Useful if you're
	// behind a reverse proxy that does compression for you.
	ConfNoCompress = "NOCOMPRESS"
)

const ClientIPContextKey = "🍺.userip"

ClientIPContextKey is the key used to fetch the client IP from r.Context()

const ParamsContextKey = 0 // copied from https://github.com/dimfeld/httptreemux/blob/master/context.go#L123

ParamsContextKey is the key used to fetch URL paramaters from r.Context()

const StashContextKey = "🍺.stash"

StashContextKey is the key used to fetch the stash from r.Context()

const Timeout = 10 * time.Second

Timeout defines the default time to wait before killing active connections on shutdown or restart.

const ViewContextKey = "🍺.view"

ViewContextKey is the key used to fetch the view from r.Context()

Variables

var BufPoolAlloc = 10 * 1024

BufPoolAlloc is the maximum size of each buffer.

var BufPoolSize = 32

BufPoolSize is the size of the BufferPool.

Functions

func ExtractClientIP

func ExtractClientIP(req *http.Request) (net.IP, error)

ExtractClientIP parses the request and returns the clients IP

func GetClientIP

func GetClientIP(r *http.Request) net.IP

GetClientIP fetches the parsed client IP from an http.Request

func GetParams

func GetParams(r *http.Request) map[string]string

GetParams fetches the URL params from an http.Request

func GetStash

func GetStash(r *http.Request) map[string]interface{}

GetStash fetches the stash from an http.Request

Types

type Context

type Context interface {
	Deadline() (time.Time, bool)
	Done() <-chan struct{}
	Err() error
	Value(interface{}) interface{}
}

Context is a clone of the context.Context interface, for convenience

type ResponseWriter

type ResponseWriter interface {
	Header() http.Header
	Write([]byte) (int, error)
	WriteHeader(int)
	Written() bool
}

ResponseWriter is Ale's custom version of http.ResponseWriter

type Server

type Server struct {
	// Timeout is the duration to wait before killing active requests when stopping the server
	Timeout time.Duration
	// Context is the master context for this server instance
	Context Context
	// TemplateDir is the name of the path which contains the HTML templates.
	// If this path contains a subdir 'lib/', any files contianed within lib
	// are also loaded into each template. This is where shared components
	// should generally go.
	TemplateDir string
	// View is the default View configuration
	View *View

	Router *httptreemux.ContextGroup
	// contains filtered or unexported fields
}

Server represents an Ale server instance.

func New

func New() *Server

New returns a new Ale server instance.

func (*Server) EnvPrefix

func (s *Server) EnvPrefix() string

EnvPrefix returns the currently configured ENV prefix

func (*Server) FastCGI

func (s *Server) FastCGI() error

FastCGI binds to the FastCGI port

func (*Server) GetConf

func (s *Server) GetConf(key string) (val string)

GetConf retrieves the requested configuration variable

func (*Server) Render

func (s *Server) Render(w ResponseWriter, r *http.Request)

Render renders the page

func (*Server) Run

func (s *Server) Run() error

Run initializes the web server instance

func (*Server) ServeFiles

func (s *Server) ServeFiles(path string, root http.FileSystem)

ServeFiles is a wrapper around httprouter.ServeFiles

func (*Server) ServeHTTP

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

func (*Server) SetEnvPrefix

func (s *Server) SetEnvPrefix(prefix string)

SetEnvPrefix sets the environment prefix for configuration

type View

type View struct {
	View     string
	Template string
	FuncMap  map[string]interface{}
}

View provides view configuration options

func GetView

func GetView(r *http.Request) *View

GetView fetches the view configuratoin from an http.Request

func (*View) Copy

func (v *View) Copy() *View

Copy makes a deep copy of a View

func (*View) GetFuncMap

func (v *View) GetFuncMap() template.FuncMap

GetFuncMap returns a compiled FuncMap