possum

README

Possum

Possum is a micro web library for Go.

It has following modules:

• Routers
• Views
• Session
• Helpers

Install

Install the package:

go get github.com/mikespook/possum

Usage

Importing the package and sub-packages:

import (
	"github.com/mikespook/possum"
	"github.com/mikespook/possum/router"
	"github.com/mikespook/possum/view"
)

Possum uses Context for passing data, handling request and rendering response.

This is how to create a new server mux for Possum:

mux := possum.NewServerMux()

And assign a customized error handler:

mux.ErrorHandle = func(err error) {
	fmt.Println(err)
}

PreRequest and PostResponse are useful for pre-checking or customizing logs:

mux.PreRequest = func(ctx *possum.Context) error {
	host, port, err := net.SplitHostPort(ctx.Request.RemoteAddr)
	if err != nil {
		return err
	}
	if host != "127.0.0.1" {
		return possum.NewError(http.StatusForbidden, "Localhost only")
	}
	return nil
}

mux.PostResponse = func(ctx *possum.Context) error {
	fmt.Printf("[%d] %s:%s \"%s\"", ctx.Response.Status,
		ctx.Request.RemoteAddr,	ctx.Request.Method,
		ctx.Request.URL.String())		
}

A specific path can bind to a different combination of routers, handlers and views:

f := session.NewFactory(session.CookieStorage('session-id', nil))

func helloword(ctx *Context) error {
	ctx.StartSession(f)
	return nil
}

mux.HandlerFunc(router.Simple("/json"), helloword, view.Json(view.CharSetUTF8))

if err := view.InitHtmlTemplates("*.html"); err != nil {
	return
}
mux.HandleFunc(router.Wildcard("/html/*/*"),
	helloworld, view.Html("base.html", "utf-8"))

if err := view.InitWatcher("*.html", view.InitTextTemplates, nil);
	err != nil {
	return
}
mux.HandleFunc(router.RegEx("/html/(.*)/[a-z]"),
	helloworld, view.Text("base.html", "utf-8"))

mux.HandleFunc(router.Colon("/:img/:id"), 
	nil, view.File("img.jpg", "image/jpeg"))

Also, a PProf methods can be initialized by mux.InitPProf:

mux.InitPProf("/_pprof")

It will serve profiles and debug informations through http://ip:port/_pprof.

E.g.:

And finally, it is a standard way for listening and serving:

http.ListenAndServe(":8080", mux)

For more details, please see the demo.

Contributors

(Alphabetic order)

• Xing Xing mikespook@gmail.com @Twitter

Open Source - MIT Software License

See LICENSE.

Documentation

Index

• Variables
• func InitPProf(psm *Possum, prefix string)
• func Session(w http.ResponseWriter, req *http.Request) (sn *session.Session, deferFunc func(), err error)
• type Error
  • func (err Error) Error() string
• type HandlerFunc
  • func Chain(h ...HandlerFunc) HandlerFunc
  • func Method(m map[string]HandlerFunc) HandlerFunc
  • func Rand(h ...HandlerFunc) HandlerFunc
• type Possum
  • func New() *Possum
  • func (psm *Possum) Add(rtr router.Router, f HandlerFunc, view view.View)
  • func (psm *Possum) ServeHTTP(w http.ResponseWriter, req *http.Request)

Variables

var SessionFacotryFunc = session.NewFactory(session.CookieStorage(sessionCookieName, nil))

SessionFacotryFunc is the default factory function of session.

Functions

func InitPProf

func InitPProf(psm *Possum, prefix string)

InitPProf registers pprof handlers to the ServeMux. The pprof handlers can be specified a customized prefix.

func Session

func Session(w http.ResponseWriter, req *http.Request) (sn *session.Session, deferFunc func(), err error)

Session extracts data from the request and returns session instance. It uses SessionFacotryFunc to initialise session if no session has been set yet.

Types

type Error

type Error struct {
	Status  int
	Message string
}

Error implements error interface

func (Error) Error

func (err Error) Error() string

type HandlerFunc

type HandlerFunc func(w http.ResponseWriter, req *http.Request) (interface{}, int)

func Chain

func Chain(h ...HandlerFunc) HandlerFunc

Chain combins a slide of HandlerFunc(s) in to one request. TODO

func Method

func Method(m map[string]HandlerFunc) HandlerFunc

Method takes one map as a paramater. Keys of this map are HTTP method mapping to HandlerFunc(s).

func Rand

func Rand(h ...HandlerFunc) HandlerFunc

Rand picks one HandlerFunc(s) in the slide.

type Possum

type Possum struct {
	sync.RWMutex

	// PreRequest is called after initialised the request and session, before user-defined handler
	PreRequest http.HandlerFunc
	// PreResponse is called before sending response to client.
	PreResponse http.HandlerFunc
	// ErrorHandler gets a chance to write user-defined error handler
	ErrorHandle func(error)
	// contains filtered or unexported fields
}

Possum implements `http.Handler`.

func New

func New() *Possum

New initailizes Possum instance.

func (*Possum) Add

func (psm *Possum) Add(rtr router.Router, f HandlerFunc, view view.View)

Add a router to list

func (*Possum) ServeHTTP

func (psm *Possum) ServeHTTP(w http.ResponseWriter, req *http.Request)