seshcookie: github.com/bpowers/seshcookie Index | Files | Directories

package seshcookie

import "github.com/bpowers/seshcookie"

Package seshcookie enables you to associate session-state with HTTP requests while keeping your server stateless. Because session-state is transferred as part of the HTTP request (in a cookie), state can be seamlessly maintained between server restarts or load balancing. It's inspired by Beaker (http://pypi.python.org/pypi/Beaker), which provides a similar service for Python webapps. The cookies are authenticated and encrypted (using AES-GCM) with a key derived from a string provided to the NewHandler function. This makes seshcookie reliable and secure: session contents are opaque to users and not able to be manipulated or forged by third parties.

Storing session-state in a cookie makes building some apps trivial, like this example that tells a user how many times they have visited the site:

package main

import (
	"net/http"
	"log"
	"fmt"

	"github.com/bpowers/seshcookie"
)

type VisitedHandler struct{}

func (h *VisitedHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
	if req.URL.Path != "/" {
		return
	}

	session := seshcookie.GetSession(req.Context())

	count, _ := session["count"].(int)
	count++
	session["count"] = count

	rw.Header().Set("Content-Type", "text/plain")
	rw.WriteHeader(200)
	if count == 1 {
		rw.Write([]byte("this is your first visit, welcome!"))
	} else {
		rw.Write([]byte(fmt.Sprintf("page view #%d", count)))
	}
}

func main() {
	key := "session key, preferably a sequence of data from /dev/urandom"
	http.Handle("/", seshcookie.NewHandler(
		&VisitedHandler{},
		key,
		&seshcookie.Config{HTTPOnly: true, Secure: false}))

	if err := http.ListenAndServe(":8080", nil); err != nil {
		log.Fatalf("ListenAndServe: %s", err)
	}
}

Index

Package Files

doc.go seshcookie.go

Variables

var (
    // DefaultConfig is used as the configuration if a nil config
    // is passed to NewHandler
    DefaultConfig = &Config{
        CookieName: defaultCookieName,
        CookiePath: "/",
        HTTPOnly:   true,
        Secure:     true,
    }
)

type Config Uses

type Config struct {
    CookieName string // name of the cookie to store our session in
    CookiePath string // resource path the cookie is valid for
    HTTPOnly   bool   // don't allow JavaScript to access cookie
    Secure     bool   // only send session over HTTPS
}

Config provides directives to a seshcookie instance on cookie attributes, like if they are accessible from JavaScript and/or only set on HTTPS connections.

type Handler Uses

type Handler struct {
    http.Handler
    Config Config
    // contains filtered or unexported fields
}

Handler is the seshcookie HTTP handler that provides a Session object to child handlers.

func NewHandler Uses

func NewHandler(handler http.Handler, key string, config *Config) *Handler

NewHandler creates a new seshcookie Handler with a given encryption key and configuration.

func (*Handler) ServeHTTP Uses

func (h *Handler) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type Session Uses

type Session map[string]interface{}

Session is simply a map of keys to arbitrary values, with the restriction that the value must be GOB-encodable.

func GetSession Uses

func GetSession(ctx context.Context) Session

GetSession is a wrapper to grab the seshcookie Session out of a Context.

By only providing a 'Get' API, we ensure that clients can't mistakenly set something unexpected on the given context in place of the session.

Directories

PathSynopsis
example

Package seshcookie imports 16 packages (graph) and is imported by 7 packages. Updated 2018-08-06. Refresh now. Tools for package owners.