goji

README

Goji

Goji is a minimalistic web framework inspired by Sinatra.

Example

package main

import (
        "fmt"
        "net/http"

        "github.com/zenazn/goji"
        "github.com/zenazn/goji/web"
)

func hello(c web.C, w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Hello, %s!", c.URLParams["name"])
}

func main() {
        goji.Get("/hello/:name", hello)
        goji.Serve()
}

Goji also includes a sample application in the example folder which was artificially constructed to show off all of Goji's features. Check it out!

Features

• Compatible with net/http
• URL patterns (both Sinatra style /foo/:bar patterns and regular expressions)
• Reconfigurable middleware stack
• Context/environment objects threaded through middleware and handlers
• Automatic support for Einhorn, systemd, and more
• Graceful shutdown, and zero-downtime graceful reload when combined with Einhorn.
• Ruby on Rails / jQuery style parameter parsing
• High in antioxidants

Is it any good?

Maybe!

There are plenty of other good Go web frameworks out there. Goji is by no means especially novel, nor is it uniquely good. The primary difference between Goji and other frameworks--and the primary reason I think Goji is any good--is its philosophy:

Goji first of all attempts to be simple. It is of the Sinatra school of web framework design, and not the Rails one. If you want me to tell you what directory you should put your models in, or if you want built-in flash sessions, you won't have a good time with Goji.

Secondly, Goji attempts to be composable. It is fully composable with net/http, and can be used as a http.Handler, or can serve arbitrary http.Handlers. At least a few HTTP frameworks share this property, and is not particularly novel. The more interesting property in my mind is that Goji is fully composable with itself: it defines an interface (web.Handler) which is both fully compatible with http.Handler and allows Goji to perform a "protocol upgrade" of sorts when it detects that it is talking to itself (or another web.Handler compatible component). web.Handler is at the core of Goji's interfaces and is what allows it to share request contexts across unrelated objects.

Third, Goji is not magic. One of my favorite existing frameworks is Martini, but I rejected it in favor of building Goji because I thought it was too magical. Goji's web package does not use reflection at all, which is not in itself a sign of API quality, but to me at least seems to suggest it.

Finally, Goji gives you enough rope to hang yourself with. One of my other favorite libraries, pat, implements Sinatra-like routing in a particularly elegant way, but because of its reliance on net/http's interfaces, doesn't allow programmers to thread their own state through the request handling process. Implementing arbitrary context objects was one of the primary motivations behind abandoning pat to write Goji.

Is it fast?

It's not bad: in very informal tests it performed roughly in the middle of the pack of one set of benchmarks. For almost all applications this means that it's fast enough that it doesn't matter.

I have very little interest in boosting Goji's router's benchmark scores. There is an obvious solution here--radix trees--and maybe if I get bored I'll implement one for Goji, but I think the API guarantees and conceptual simplicity Goji provides are more important (all routes are attempted, one after another, until a matching route is found). Even if I choose to optimize Goji's router, Goji's routing semantics will not change.

Plus, Goji provides users with the ability to create their own radix trees: by using sub-routes you create a tree of routers and match routes in more or less the same way as a radix tree would. But, again, the real win here in my mind isn't the performance, but the separation of concerns you get from having your /admin routes and your /profile routes far, far away from each other.

Goji's performance isn't all about the router though, it's also about allowing net/http to perform its built-in optimizations. Perhaps uniquely in the Go web framework ecosystem, Goji supports net/http's transparent sendfile(2) support.

Contributing

Please do! I love pull requests, and I love pull requests that include tests even more. Goji's core packages have pretty good code coverage (yay code coverage gamification!), and if you have the time to write tests I'd like to keep it that way.

In addition to contributing code, I'd love to know what you think about Goji. Please open an issue or send me an email with your thoughts; it'd mean a lot to me.

Documentation

Overview

Package goji provides an out-of-box web server with reasonable defaults.

Example:

package main

import (
	"fmt"
	"net/http"

	"github.com/zenazn/goji"
	"github.com/zenazn/goji/web"
)

func hello(c web.C, w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello, %s!", c.URLParams["name"])
}

func main() {
	goji.Get("/hello/:name", hello)
	goji.Serve()
}

This package exists purely as a convenience to programmers who want to get started as quickly as possible. It draws almost all of its code from goji's subpackages, the most interesting of which is goji/web, and where most of the documentation for the web framework lives.

A side effect of this package's ease-of-use is the fact that it is opinionated. If you don't like (or have outgrown) its opinions, it should be straightforward to use the APIs of goji's subpackages to reimplement things to your liking. Both methods of using this library are equally well supported.

Goji requires Go 1.2 or newer.

Index

• Variables
• func Abandon(middleware interface{}) error
• func Connect(pattern interface{}, handler interface{})
• func Delete(pattern interface{}, handler interface{})
• func Get(pattern interface{}, handler interface{})
• func Handle(pattern interface{}, handler interface{})
• func Head(pattern interface{}, handler interface{})
• func Insert(middleware, before interface{}) error
• func NotFound(handler interface{})
• func Options(pattern interface{}, handler interface{})
• func Patch(pattern interface{}, handler interface{})
• func Post(pattern interface{}, handler interface{})
• func Put(pattern interface{}, handler interface{})
• func Serve()
• func Trace(pattern interface{}, handler interface{})
• func Use(middleware interface{})

Variables

var DefaultMux *web.Mux

The default web.Mux.

Functions

func Abandon

func Abandon(middleware interface{}) error

Abandon removes the given middleware from the default Mux's middleware stack. See the documentation for web.Mux.Abandon for more information.

func Connect

func Connect(pattern interface{}, handler interface{})

Connect adds a CONNECT route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Delete

func Delete(pattern interface{}, handler interface{})

Delete adds a DELETE route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Get

func Get(pattern interface{}, handler interface{})

Get adds a GET route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Handle

func Handle(pattern interface{}, handler interface{})

Handle adds a route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Head

func Head(pattern interface{}, handler interface{})

Head adds a HEAD route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Insert

func Insert(middleware, before interface{}) error

Insert the given middleware into the default Mux's middleware stack. See the documentation for web.Mux.Insert for more information.

func NotFound

func NotFound(handler interface{})

NotFound sets the NotFound handler for the default Mux. See the documentation for web.Mux.NotFound for more information.

func Options

func Options(pattern interface{}, handler interface{})

Options adds a OPTIONS route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Patch

func Patch(pattern interface{}, handler interface{})

Patch adds a PATCH route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Post

func Post(pattern interface{}, handler interface{})

Post adds a POST route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Put

func Put(pattern interface{}, handler interface{})

Put adds a PUT route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Serve

func Serve()

Serve starts Goji using reasonable defaults.

func Trace

func Trace(pattern interface{}, handler interface{})

Trace adds a TRACE route to the default Mux. See the documentation for web.Mux for more information about what types this function accepts.

func Use

func Use(middleware interface{})

Use appends the given middleware to the default Mux's middleware stack. See the documentation for web.Mux.Use for more information.