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"
  "net/url"

  "github.com/acmacalister/helm"
)

func main() {
  r := helm.New(fallThrough)                         // Our fallthrough route.
  r.Use(fooMiddleware, barMiddleware, helm.Static()) // add global/router level middleware to run on every route.
  r.Handle("GET", "/", root)
  r.Handle("GET", "/users", users, authMiddleware) // local/route specific middleware that only runs on this route.
  r.GET("/users/edit", root)
  r.Handle("GET", "/users/:name", userShow, authMiddleware) // same as above, but with a named param.
  r.Handle("GET", "/users/:name/blog/new", userBlogShow, authMiddleware)
  r.GET("/blogs", blogs) // convenience method for HTTP verb. Beside GET, there is the whole RESTful gang (POST, PUT, PATCH, DELETE, etc)
  r.GET("/blogs/:id", blogShow)
  r.Run(":8080")
}

// Notice the Middleware has a return type. True means go to the next middleware. False
// means to stop right here. If you return false to end the request-response cycle you MUST
// write something back to the client, otherwise it will be left hanging.
func fooMiddleware(w http.ResponseWriter, r *http.Request, params url.Values) bool {
  fmt.Println("Foo!")
  return true
}

func barMiddleware(w http.ResponseWriter, r *http.Request, params url.Values) bool {
  fmt.Println("Bar!")
  return true
}

func authMiddleware(w http.ResponseWriter, r *http.Request, params url.Values) bool {
  fmt.Println("Doing Auth here")
  return true
}

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

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

func users(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprint(w, "Users!\n")
}

func userShow(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprintf(w, "Hi %s", params["name"]) // Notice we are able to get the username from the url resource. Quite handy!
}

func userBlogShow(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprintf(w, "This is %s Blog", params["name"])
}

func blogs(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprint(w, "Blogs!\n")
}

func blogShow(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprintf(w, "Blog number: %s", params["id"])
}

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

• https://github.com/acmacalister
• 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"
  "net/url"

  "github.com/acmacalister/helm"
)

func main() {
  r := helm.New(fallThrough)                         // Our fallthrough route.
  r.Use(fooMiddleware, barMiddleware, helm.Static()) // add global/router level middleware to run on every route.
  r.Handle("GET", "/", root)
  r.Handle("GET", "/users", users, authMiddleware) // local/route specific middleware that only runs on this route.
  r.GET("/users/edit", root)
  r.Handle("GET", "/users/:name", userShow, authMiddleware) // same as above, but with a named param.
  r.Handle("GET", "/users/:name/blog/new", userBlogShow, authMiddleware)
  r.GET("/blogs", blogs) // convenience method for HTTP verb. Beside GET, there is the whole RESTful gang (POST, PUT, PATCH, DELETE, etc)
  r.GET("/blogs/:id", blogShow)
  r.Run(":8080")
}

// Notice the Middleware has a return type. True means go to the next middleware. False
// means to stop right here. If you return false to end the request-response cycle you MUST
// write something back to the client, otherwise it will be left hanging.
func fooMiddleware(w http.ResponseWriter, r *http.Request, params url.Values) bool {
  fmt.Println("Foo!")
  return true
}

func barMiddleware(w http.ResponseWriter, r *http.Request, params url.Values) bool {
  fmt.Println("Bar!")
  return true
}

func authMiddleware(w http.ResponseWriter, r *http.Request, params url.Values) bool {
  fmt.Println("Doing Auth here")
  return true
}

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

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

func users(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprint(w, "Users!\n")
}

func userShow(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprintf(w, "Hi %s", params["name"]) // Notice we are able to get the username from the url resource. Quite handy!
}

func userBlogShow(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprintf(w, "This is %s Blog", params["name"])
}

func blogs(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprint(w, "Blogs!\n")
}

func blogShow(w http.ResponseWriter, r *http.Request, params url.Values) {
  fmt.Fprintf(w, "Blog number: %s", params["id"])
}

Index

• func Get(r *http.Request, key interface{}) interface{}
• func RespondWithJSON(w http.ResponseWriter, v interface{}, status int)
• func RespondWithXML(w http.ResponseWriter, v interface{}, status int)
• func Set(r *http.Request, key, val interface{})
• func ValidateParams(params url.Values, desiredParams []Param) (map[string]string, error)
• type Handle
• type Middleware
  • func Static(directories ...string) Middleware
• type Param
• type Router
  • func New(rootHandler Handle) *Router
  • func (r *Router) DELETE(path string, handler Handle, middleware ...Middleware)
  • func (r *Router) EnableLogging(w io.Writer)
  • func (r *Router) GET(path string, handler Handle, middleware ...Middleware)
  • func (r *Router) HEAD(path string, handler Handle, middleware ...Middleware)
  • func (r *Router) Handle(method, path string, handler Handle, middleware ...Middleware)
  • func (r *Router) PATCH(path string, handler Handle, middleware ...Middleware)
  • func (r *Router) POST(path string, handler Handle, middleware ...Middleware)
  • func (r *Router) PUT(path string, handler Handle, middleware ...Middleware)
  • func (r *Router) Run(address string)
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) Use(middleware ...Middleware)

Functions

func Get

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

func RespondWithJSON

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

func RespondWithXML

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

func Set

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

func ValidateParams

func ValidateParams(params url.Values, desiredParams []Param) (map[string]string, error)

ValidateParams is used for validating and sanizating params. Since HTTP params can have same name for multiple params, if this happens it will just use the first one.

Types

type Handle

type Handle func(http.ResponseWriter, *http.Request, url.Values)

Handle is just like "net/http" Handlers, only takes params.

type Middleware

type Middleware func(http.ResponseWriter, *http.Request, url.Values) bool

Middleware is just like the Handle type, but has a boolean return. True means to keep processing the rest of the middleware chain, false means end. If you return false to end the request-response cycle you MUST write something back to the client, otherwise it will be left hanging.

func Static

func Static(directories ...string) Middleware

Static 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.

type Param

type Param struct {
	Name     string
	Required bool
}

type Router

type Router struct {
	LoggingEnabled bool
	// contains filtered or unexported fields
}

Router name says it all.

func New

func New(rootHandler Handle) *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 Handle, middleware ...Middleware)

DELETE same as Handle only the method is already implied.

func (*Router) EnableLogging

func (r *Router) EnableLogging(w io.Writer)

EnableLogging sets logging to supplied writer.

func (*Router) GET

func (r *Router) GET(path string, handler Handle, middleware ...Middleware)

GET same as Handle only the method is already implied.

func (*Router) HEAD

func (r *Router) HEAD(path string, handler Handle, middleware ...Middleware)

HEAD same as Handle only the method is already implied.

func (*Router) Handle

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

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

func (*Router) PATCH

func (r *Router) PATCH(path string, handler Handle, middleware ...Middleware)

PATCH same as Handle only the method is already implied.

func (*Router) POST

func (r *Router) POST(path string, handler Handle, middleware ...Middleware)

POST same as Handle only the method is already implied.

func (*Router) PUT

func (r *Router) PUT(path string, handler Handle, middleware ...Middleware)

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 ...Middleware)

Use adds middleware to all of the routes.