ses

Documentation

Overview

Package ses provides an abstraction over varying, http session authentication systems. The basic idea is that we receive some kind of token in an http request either way. The token contains at least a session identifier that we can use to lookup session data.

Index

• Constants
• func Decorate(r *http.Request, s *Session) *http.Request
• func Provide(m *Manager) func(http.Handler) http.Handler
• type Config
• type Cookie
  • func DefaultCookie(name string, secure bool) *Cookie
  • func (cc *Cookie) ReadToken(r *http.Request) string
  • func (cc *Cookie) WriteToken(w http.ResponseWriter, tok string)
• type Data
• type HeaderReader
  • func (tr HeaderReader) ReadToken(r *http.Request) string
• type Manager
  • func NewManager(store Store, conf ...Config) *Manager
  • func (m *Manager) Clear(w http.ResponseWriter, r *http.Request)
  • func (m *Manager) EncodeAndWrite(w http.ResponseWriter, s *Session) (err error)
  • func (m *Manager) Read(w http.ResponseWriter, r *http.Request) (_ *Session, err error)
  • func (m *Manager) ReadOrCreate(w http.ResponseWriter, r *http.Request, cookie bool) *http.Request
  • func (m *Manager) Save(w http.ResponseWriter, s *Session) error
• type Provider
  • func (m Provider) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Requirer
  • func (c Requirer) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Session
  • func Get(r *http.Request) *Session
• type Store
• type TokenCodec
• type TokenReader
• type TokenWriter

Constants

const ContextKey sesKey = "ses"

ContextKey is the http request context key for a session pointer.

Functions

func Decorate

func Decorate(r *http.Request, s *Session) *http.Request

Decorate is the default request context decorator used by manager.

func Provide

func Provide(m *Manager) func(http.Handler) http.Handler

Provide returns a http middleware that injects a session provider.

Types

type Config

type Config struct {
	// TokenReader reads tokens from requests. Some readers do also implement token write.
	TokenReader
	// Codec is codec list that is tried from first to last both for decoding and encoding.
	// This allows seamless key rotations for session encodings. We try older codecs to fail
	// gracefully if a newly introduced codec cannot encode the token data.
	Codec []TokenCodec
}

Config represent a session token configuration with multiple codecs and helpers.

type Cookie

type Cookie http.Cookie

Cookie is a wrapped http cookie that implements token reader and writer.

func DefaultCookie

func DefaultCookie(name string, secure bool) *Cookie

DefaultCookie returns a cookie using name and secure and other default parameters. The defaults are http only, root path and same site lax mode.

func (*Cookie) ReadToken

func (cc *Cookie) ReadToken(r *http.Request) string

func (*Cookie) WriteToken

func (cc *Cookie) WriteToken(w http.ResponseWriter, tok string)

type Data

type Data interface {

	// ID returns the session id.
	ID() string

	// Tok returns the data to be encoded in the token.
	// This is usually just the session id but can be any string encoded value.
	Tok() string

	// User returns the user or account id if authenticated.
	User() string
}

Data is the user defined session data that is often coupled to a specific application and store.

type HeaderReader

type HeaderReader string

HeaderReader is a token reader that reads a named http request header

func (HeaderReader) ReadToken

func (tr HeaderReader) ReadToken(r *http.Request) string

type Manager

type Manager struct {
	Config   []Config
	Store    Store
	Log      log.Logger
	Decorate func(*http.Request, *Session) *http.Request
}

func NewManager

func NewManager(store Store, conf ...Config) *Manager

func (*Manager) Clear

func (m *Manager) Clear(w http.ResponseWriter, r *http.Request)

func (*Manager) EncodeAndWrite

func (m *Manager) EncodeAndWrite(w http.ResponseWriter, s *Session) (err error)

func (*Manager) Read

func (m *Manager) Read(w http.ResponseWriter, r *http.Request) (_ *Session, err error)

func (*Manager) ReadOrCreate

func (m *Manager) ReadOrCreate(w http.ResponseWriter, r *http.Request, cookie bool) *http.Request

func (*Manager) Save

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

type Provider

type Provider struct {
	*Manager
	Next http.Handler
}

Provider is a http handler that provides sessions to all handled http requests.

func (Provider) ServeHTTP

func (m Provider) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Requirer

type Requirer struct {
	// Allow returns whether the request is allowed to proceed. On failure Allow should write an
	// error or redirect to the response writer. There are usually two error classes:
	// unauthenticated and unauthorized requests. Unauthenticated request should be redirected
	// to a login page, unauthorized requests should see a simple error page with a back link.
	Allow func(http.ResponseWriter, *http.Request, *Session) bool
	Next  http.Handler
}

Requirer is a http handler that checks sessions before proceeding with the next handler.

func (Requirer) ServeHTTP

func (c Requirer) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Session

type Session struct {
	Data
	IsNew    bool
	IsCookie bool
}

Session decorates the user session data with additional fields.

func Get

func Get(r *http.Request) *Session

Ger returns the session from a http request context or nil.

type Store

type Store interface {

	// New creates and returns session data that must at least have a unique id or an error.
	New() (Data, error)

	// Get returns session data for the given token data or an error.
	Get(td string) (Data, error)

	// Save persist the given session data or returns an error.
	Save(d Data, isnew bool) error

	// Delete deletes the session data for the given token data or returns an error.
	Delete(td string) error
}

Store provides access to often persisted session data.

type TokenCodec

type TokenCodec interface {
	DecodeToken(tok string) (td string, err error)
	EncodeToken(td string) (tok string, err error)
}

TokenCodec and decode and encode a token to the underlying token data. Data is used as string in this context, but anything can be encode as string. You can wrap github.com/gorilla/securecookie as a simple an proven token codec. Or you can check your claims from any kind of bearer token you want to use.

type TokenReader

type TokenReader interface {
	ReadToken(*http.Request) string
}

TokenReader can read a token from a http request.

type TokenWriter

type TokenWriter interface {
	WriteToken(http.ResponseWriter, string)
}

TokenWriter can write a token to a http response, usually cookies. The token should be cleared when called with an empty token string.