sessionmw

README

About sessionmw

A Goji v2 middleware package providing session management and storage via context.Context.

Installation

Install the package via the following:

go get -u github.com/knq/sessionmw

Usage

Please see the GoDoc API page for a full API listing. Currently there is a simple in-memory store for sessions, as well as a simple redis store. Please see the examples directory.

The sessionmw package can be used similarly to the following:

// examples/simple/simple.go
package main

import (
    "fmt"
    "html"
    "net/http"

    "github.com/knq/sessionmw"
    "goji.io"
    "goji.io/pat"
    "golang.org/x/net/context"
)

func main() {
    // create session middleware
    sessConfig := &sessionmw.Config{
        Secret:      []byte("LymWKG0UvJFCiXLHdeYJTR1xaAcRvrf7"),
        BlockSecret: []byte("NxyECgzxiYdMhMbsBrUcAAbyBuqKDrpp"),

        Store: sessionmw.NewMemStore(),
    }

    // create goji mux and add sessionmw
    mux := goji.NewMux()
    mux.UseC(sessConfig.Handler)

    // add handlers
    mux.HandleFuncC(pat.Get("/set/:name"), func(ctxt context.Context, res http.ResponseWriter, req *http.Request) {
        val := pat.Param(ctxt, "name")
        sessionmw.Set(ctxt, "name", val)
        http.Error(res, fmt.Sprintf("name saved as '%s'.", html.EscapeString(val)), http.StatusOK)
    })
    mux.HandleFuncC(pat.Get("/"), func(ctxt context.Context, res http.ResponseWriter, req *http.Request) {
        var name = "[no name]"
        val, _ := sessionmw.Get(ctxt, "name")
        if n, ok := val.(string); ok {
            name = n
        }
        http.Error(res, fmt.Sprintf("hello '%s'", html.EscapeString(name)), http.StatusOK)
    })

    // serve
    http.ListenAndServe(":3000", mux)
}

TODO

• Finish writing unit tests.
• Finish json store and example.
• Finish groupcache store and example.
• Finish simple database store and example.

Documentation

Overview

Package sessionmw provides a Goji v2 context aware session middleware.

Index

• Constants
• Variables
• func CookieName(ctxt context.Context) string
• func Delete(ctxt context.Context, key string)
• func Destroy(ctxt context.Context, res ...http.ResponseWriter) error
• func Get(ctxt context.Context, key string) (interface{}, bool)
• func ID(ctxt context.Context) string
• func Set(ctxt context.Context, key string, val interface{})
• type Config
  • func (c Config) Handler(h goji.Handler) goji.Handler
• type IDFn
• type Store
  • func GetStore(ctxt context.Context) Store

Constants

const (
	// DefaultCookieName is the default cookie name.
	DefaultCookieName = "SESSID"
)

Variables

var ErrSessionNotFound = errors.New("session not found")

ErrSessionNotFound is the error returned by sessionmw.Store providers when a session cannot be found.

Functions

func CookieName

func CookieName(ctxt context.Context) string

CookieName retrieves the cookie name from the context.

func Delete

func Delete(ctxt context.Context, key string)

Delete deletes a stored session value from the context.

func Destroy

func Destroy(ctxt context.Context, res ...http.ResponseWriter) error

Destroy destroys a session in the underlying session store.

Note that any existing values will continue to remain in the context after destruction. The context should be closed (or destroyed).

If the optional http.ResponseWriter is provided, then an expired cookie will be added to the response headers.

func Get

func Get(ctxt context.Context, key string) (interface{}, bool)

Get retrieves a previously stored session value from the context.

func ID

func ID(ctxt context.Context) string

ID retrieves the id for this session from the context.

func Set

func Set(ctxt context.Context, key string, val interface{})

Set stores a session value into the context.

Session values will be saved to the underlying store after Handler has finished.

Types

type Config

type Config struct {
	// Secret is
	Secret      []byte
	BlockSecret []byte

	// Store is the underlying session store.
	Store Store

	// IDFn is the id generation func.
	IDFn IDFn

	// Name is the cookie name.
	Name string

	// Path is the cookie path.
	Path string

	// Domain is the cookie domain.
	Domain string

	// Expires is the cookie expiration time.
	Expires time.Time

	// MaxAge is the cookie max age.
	MaxAge time.Duration

	// Secure is the cookie secure flag.
	Secure bool

	// HttpOnly is the cookie http only flag.
	HttpOnly bool
}

Config contains the configuration parameters for the session middleware.

func (Config) Handler

func (c Config) Handler(h goji.Handler) goji.Handler

Handler provides the goji.Handler for the session middleware.

type IDFn

type IDFn func() string

IDFn is the ID generation func type.

type Store

type Store interface {
	// Write retrieves the session for the provided id.
	Write(key string, obj interface{}) error

	// Read saves the session for the provided id.
	//
	// If the provided id already exists in storage, then it will be
	// overwritten.
	Read(key string) (interface{}, error)

	// Destroy permanently destroys the session with the provided id.
	Erase(key string) error
}

Store is the common interface for session storage.

Please see github.com/knq/kv.Store for a compatible store.

func GetStore

func GetStore(ctxt context.Context) Store

GetStore retrieves the session store from the context.