helm

README

helm

helm is a simple, fast and minimalist router for writing web applications in Go. It builds on top of net/http and aims to be an elegant addition by removing some of the cumbersome work involved with using the default net/http mux.

Features

• Simple API.
• Middleware support built right in.
• Great for building API servers.
• Minimalist codebase at just a few hundred LOC. Great way to learn how to write your own router.
• Inspired by Express.js.

Installation

go get github.com/acmacalister/helm

Example

package main

import (
  "fmt"
  "net/http"
  "os"

  "github.com/acmacalister/helm"
)

func main() {
  r := helm.New(fallThrough)                                         // Our fallthrough route.
  r.Use(helm.NewLogger(os.Stdout, "[helm]"), auth, helm.NewStatic()) // add global/router level middleware to run on every route.
  r.Handle("GET", "/", root, blah)
  r.Run(":8080")
}

func log(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
  fmt.Println("Before")
  next(w, r)
  fmt.Println("After")
}

func auth(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
  fmt.Println("Do sweet auth stuff")
  next(w, r)
}

func blah(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
  fmt.Println("blah...")
  next(w, r)
}

func fallThrough(w http.ResponseWriter, r *http.Request) {
  http.Error(w, "You done messed up A-aron", http.StatusNotFound)
}

func root(w http.ResponseWriter, r *http.Request) {
  fmt.Println("root!")
  w.WriteHeader(200)
  w.Write([]byte("Root!"))
}

Docs

godoc

Example Project

Check out the example directory for a simple example.

Why?

There are already a number of great routers and middleware out there for Go, but since most of them are either middlware or a router, getting them to work together felt clumsy to me. Helm's goal is to provide a minimalist set of tools to make building web services a breeze.

TODOs

• Add Unit Tests
• Add support for something like the express.js all method.

Contributing

If you are interested on helping out or have a feature suggestion, feel free to open an issue or do a PR.

Additional middleware

helm's middleware is quite simple as it is standard net/http functions that provides pre-parsed params. If you would like would to include a middleware that is compatibility with helm, open an issue and we will get it added.

License

MIT

Contact

Austin Cherry

• http://twitter.com/acmacalister
• http://austincherry.me

Documentation

Overview

Package helm is a simple, fast and minimalist router for writing web applications in Go. It builds on top of `net/http` and aims to be an elegant addition, by removing some of the cumbersome work involved with using the default `net/http` mux.

For more information, see https://github.com/acmacalister/helm

package main

import (

"fmt"
"net/http"

"github.com/acmacalister/helm"

)

type user struct {
	name string
}

type server struct {
	db string
}

func main() {
	//s := server{db: "austin you are awesome!"}
	// helm.NewStatic()

	r := helm.New(fallThrough) // Our fallthrough route.
	r.Use(log, auth)           // add global/router level middleware to run on every route.
	r.Handle("GET", "/", root, blah)
	r.Run(":8080")
}

func log(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
	fmt.Println("Before")
	next(w, r)
	fmt.Println("After")
}

func auth(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
	fmt.Println("Do sweet auth stuff")
	next(w, r)
}

func blah(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
	fmt.Println("blah...")
	next(w, r)
}

func fallThrough(w http.ResponseWriter, r *http.Request) {
	http.Error(w, "You done messed up A-aron", http.StatusNotFound)
}

func root(w http.ResponseWriter, r *http.Request) {
	fmt.Println("root!")
	w.WriteHeader(200)
	w.Write([]byte("Root!"))
}

Index

• func ContextGet(r *http.Request, key interface{}) interface{}
• func ContextSet(r *http.Request, key, val interface{}) *http.Request
• func DecodeFormData(r *http.Request, v interface{}) error
• func GetParams(r *http.Request) url.Values
• func RespondWithJSON(w http.ResponseWriter, v interface{}, status int)
• func RespondWithXML(w http.ResponseWriter, v interface{}, status int)
• type Handler
• type HandlerFunc
  • func NewLogger(w io.Writer, format string) HandlerFunc
  • func NewStatic(directories ...string) HandlerFunc
  • func (h HandlerFunc) ServeHTTP(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc)
• type Param
• type Router
  • func New(rootHandler http.HandlerFunc) *Router
  • func (r *Router) DELETE(path string, handler http.HandlerFunc, middleware ...HandlerFunc)
  • func (r *Router) GET(path string, handler http.HandlerFunc, middleware ...HandlerFunc)
  • func (r *Router) HEAD(path string, handler http.HandlerFunc, middleware ...HandlerFunc)
  • func (r *Router) Handle(method, path string, handler http.HandlerFunc, middleware ...HandlerFunc)
  • func (r *Router) PATCH(path string, handler http.HandlerFunc, middleware ...HandlerFunc)
  • func (r *Router) POST(path string, handler http.HandlerFunc, middleware ...HandlerFunc)
  • func (r *Router) PUT(path string, handler http.HandlerFunc, middleware ...HandlerFunc)
  • func (r *Router) Run(address string)
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) Use(middleware ...HandlerFunc)

Functions

func ContextGet

func ContextGet(r *http.Request, key interface{}) interface{}

func ContextSet

func ContextSet(r *http.Request, key, val interface{}) *http.Request

func DecodeFormData

func DecodeFormData(r *http.Request, v interface{}) error

func GetParams

func GetParams(r *http.Request) url.Values

func RespondWithJSON

func RespondWithJSON(w http.ResponseWriter, v interface{}, status int)

func RespondWithXML

func RespondWithXML(w http.ResponseWriter, v interface{}, status int)

Types

type Handler

type Handler interface {
	ServeHTTP(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc)
}

type HandlerFunc

type HandlerFunc func(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc)

func NewLogger

func NewLogger(w io.Writer, format string) HandlerFunc

func NewStatic

func NewStatic(directories ...string) HandlerFunc

NewStatic is a builtin middleware for serving static assets. If no directories are added, public is used. If directories contain the same file paths, the first one is used.

func (HandlerFunc) ServeHTTP

func (h HandlerFunc) ServeHTTP(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc)

type Param

type Param struct {
	Name     string
	Required bool
}

type Router

type Router struct {
	URIVersion string
	// contains filtered or unexported fields
}

Router name says it all.

func New

func New(rootHandler http.HandlerFunc) *Router

New creates a new router. Take the root/fall through route like how the default mux works. Only difference is in this case, you have to specific one.

func (*Router) DELETE

func (r *Router) DELETE(path string, handler http.HandlerFunc, middleware ...HandlerFunc)

DELETE same as Handle only the method is already implied.

func (*Router) GET

func (r *Router) GET(path string, handler http.HandlerFunc, middleware ...HandlerFunc)

GET same as Handle only the method is already implied.

func (*Router) HEAD

func (r *Router) HEAD(path string, handler http.HandlerFunc, middleware ...HandlerFunc)

HEAD same as Handle only the method is already implied.

func (*Router) Handle

func (r *Router) Handle(method, path string, handler http.HandlerFunc, middleware ...HandlerFunc)

Handle takes an http handler, method and pattern for a route.

func (*Router) PATCH

func (r *Router) PATCH(path string, handler http.HandlerFunc, middleware ...HandlerFunc)

PATCH same as Handle only the method is already implied.

func (*Router) POST

func (r *Router) POST(path string, handler http.HandlerFunc, middleware ...HandlerFunc)

POST same as Handle only the method is already implied.

func (*Router) PUT

func (r *Router) PUT(path string, handler http.HandlerFunc, middleware ...HandlerFunc)

PUT same as Handle only the method is already implied.

func (*Router) Run

func (r *Router) Run(address string)

Run is a simple wrapper around http.ListenAndServe.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

Needed by "net/http" to handle http requests and be a mux to http.ListenAndServe.

func (*Router) Use

func (r *Router) Use(middleware ...HandlerFunc)

Use adds middleware to all of the routes.