sessions

README

sessions

Package sessions provides minimalist Go sessions, backed by securecookie or database stores.

Features

• Store provides a predicatable interface for dealing with individual sessions.
  • New returns a new named Session.
  • Get returns the named Session from the http.Request iff it was correctly verified and decoded. Otherwise the error is non-nil.
  • Save encodes and signs Session.Value data.
  • Destroy removes (expires) the session cookie of a given name.
• Each Session provides Save and Destroy convenience methods.
• Provides CookieStore for managing client-side secure cookies.
• Extensible for custom session database backends.

Install

go get github.com/dghubble/sessions

Documentation

Read GoDoc

Differences from gorilla/sessions

• Gorilla stores a context map of Requests to Sessions to abstract multiple sessions. dghubble/sessions provides individual sessions, leaving multiple sessions to a multisessions package. No Registry is needed.
• Gorilla has a depedency on gorilla/context, a non-standard context.
• Gorilla requires all handlers be wrapped in context.ClearHandler to avoid memory leaks.
• Gorilla's Store interface is surprising. New and Get can both possibly return a new session, a field check is needed. Some use cases expect developers to ignore an error. Destroy isn't provided.

License

MIT License

Documentation

Overview

Package sessions provides minimalist Go sessions, backed by a securecookie Store.

Index

• type Config
• type CookieStore
  • func NewCookieStore(keyPairs ...[]byte) *CookieStore
  • func (s *CookieStore) Destroy(w http.ResponseWriter, name string)
  • func (s *CookieStore) Get(req *http.Request, name string) (session *Session, err error)
  • func (s *CookieStore) New(name string) *Session
  • func (s *CookieStore) Save(w http.ResponseWriter, session *Session) error
• type Session
  • func NewSession(store Store, name string) *Session
  • func (s *Session) Destroy(w http.ResponseWriter)
  • func (s *Session) Name() string
  • func (s *Session) Save(w http.ResponseWriter) error
• type Store

Types

type Config

type Config struct {
	// cookie domain/path scope (leave zeroed for requested resource scope)
	Domain string
	Path   string
	// MaxAge=0 means no 'Max-Age' attribute specified.
	// MaxAge<0 means delete cookie now, equivalently 'Max-Age: 0'.
	// MaxAge>0 means Max-Age attribute present and given in seconds.
	MaxAge int
	// browser should prohibit non-HTTP (i.e. javascript) cookie access
	HTTPOnly bool
	// cookie may only be transferred over HTTPS
	Secure bool
	// prohibit sending in cross-site requests with SameSiteLaxMode or SameSiteLaxMode
	SameSite http.SameSite
}

Config is the set of cookie properties.

type CookieStore

type CookieStore struct {
	// encodes and decodes signed and optionally encrypted cookie values
	Codecs []securecookie.Codec
	// configures session cookie properties of new Sessions
	Config *Config
}

CookieStore stores Sessions in secure cookies (i.e. client-side)

func NewCookieStore

func NewCookieStore(keyPairs ...[]byte) *CookieStore

NewCookieStore returns a new CookieStore which signs and optionally encrypts session cookies.

func (*CookieStore) Destroy

func (s *CookieStore) Destroy(w http.ResponseWriter, name string)

Destroy deletes the Session with the given name by issuing an expired session cookie with the same name.

func (*CookieStore) Get

func (s *CookieStore) Get(req *http.Request, name string) (session *Session, err error)

Get returns the named Session from the Request. Returns an error if the session cookie cannot be found, the cookie verification fails, or an error occurs decoding the cookie value.

func (*CookieStore) New

func (s *CookieStore) New(name string) *Session

New returns a new Session with the requested name and the store's config value.

func (*CookieStore) Save

func (s *CookieStore) Save(w http.ResponseWriter, session *Session) error

Save adds or updates the Session on the response via a signed and optionally encrypted session cookie. Session Values are encoded into the cookie value and the session Config sets cookie properties.

type Session

type Session struct {
	Config *Config // session cookie config

	Values map[string]interface{}
	// contains filtered or unexported fields
}

Session represents Values state which a named bundle of maintained web state stores web session state

func NewSession

func NewSession(store Store, name string) *Session

NewSession returns a new Session.

func (*Session) Destroy

func (s *Session) Destroy(w http.ResponseWriter)

Destroy destroys the session. Identical to calling store.Destroy(w, session.name).

func (*Session) Name

func (s *Session) Name() string

Name returns the name of the session.

func (*Session) Save

func (s *Session) Save(w http.ResponseWriter) error

Save adds or updates the session. Identical to calling store.Save(w, session).

type Store

type Store interface {
	New(name string) *Session
	Get(req *http.Request, name string) (*Session, error)
	Save(w http.ResponseWriter, session *Session) error
	Destroy(w http.ResponseWriter, name string)
}

Store is the interface for creating, reading, updating and destroying named Sessions.