session

README

Session Handler

Session management for Go web apps

• Uses Go's standard library as much as possible.
• Automatically saves session data at the end of each request-response lifecycle.
• Only makes calls to backing store if session data has actually changed.
• Secured by default through HTTP and secured only cookies, that are also encrypted and authenticated using XSalsa20 and Poly1305.
• Cookie Store built-in and use as default.
• Extensible through the implementation of new Stores.

Documentation

Overview

Package session offers a HTTP handler to manage web sessions using encrypted and authenticated cookies as well as pluggable backing stores.

Index

• func Handler(h http.Handler, opts ...option) http.Handler
• func Register(id int8, value interface{})
• func WithDomain(d string) option
• func WithMaxAge(d time.Duration) option
• func WithName(n string) option
• func WithSecretKey(k ...string) option
• func WithStore(store Store) option
• type Session
  • func FromContext(ctx context.Context) (s *Session, ok bool)
  • func New(name string, keys []string) *Session
  • func (s *Session) Decode(data []byte) error
  • func (s *Session) Delete(key string) error
  • func (s *Session) Destroy()
  • func (s *Session) Encode() ([]byte, error)
  • func (s *Session) Get(key string) interface{}
  • func (s *Session) Set(key string, value interface{}) error
• type Store

Functions

func Handler

func Handler(h http.Handler, opts ...option) http.Handler

Handler verifies and creates new sessions. If a session is found and valid, it is attached to the Request's context for further modification or retrieval by other handlers. Sessions are automatically saved before sending the response.

func Register

func Register(id int8, value interface{})

Register registers custom struct types that are going to be stored in the sessions. It allows to retrive struct types from the session and do type assertions on them as opposed to map values.

func WithDomain

func WithDomain(d string) option

WithDomain allows setting the cookie name for storing the session.

func WithMaxAge

func WithMaxAge(d time.Duration) option

WithMaxAge allows to set the duration of the session.

func WithName

func WithName(n string) option

WithName allows setting the cookie name for storing the session.

func WithSecretKey

func WithSecretKey(k ...string) option

WithSecretKey allows to configure the secret key to encrypt and authenticate the session data. Key rotation is supported, the left-most key is always the current key.

func WithStore

func WithStore(store Store) option

WithStore sets a specific backing store for session data. By default, the built-in Cookie Store is used.

Types

type Session

type Session struct {
	*http.Cookie
	// contains filtered or unexported fields
}

Session represents a secure session cookie. By default, it stores session data in the session cookie. If a Store is provided, only the session ID is stored in the session cookie.

func FromContext

func FromContext(ctx context.Context) (s *Session, ok bool)

FromContext extracts the session from the given context.

func New

func New(name string, keys []string) *Session

New returns a new Session

func (*Session) Decode

func (s *Session) Decode(data []byte) error

Decode decrypts, authenticates and deserializes cookie's session data.

func (*Session) Delete

func (s *Session) Delete(key string) error

Delete removes the given key's value from the session store.

func (*Session) Destroy

func (s *Session) Destroy()

Destroy signals the user's browser to remove the session cookie.

func (*Session) Encode

func (s *Session) Encode() ([]byte, error)

Encode encrypts and serializes the session cookie's data.

func (*Session) Get

func (s *Session) Get(key string) interface{}

Get retrieves the given key's value from the session store.

func (*Session) Set

func (s *Session) Set(key string, value interface{}) error

Set assigns a value to a specific key.

type Store

type Store interface {
	// Load retrieves opaque session data from backing store
	Load(id string) ([]byte, error)
	// Saves persists opaque session data to backing store
	Save(id string, data []byte) error
	// Destroy removes the session altogether from backing store
	Destroy(id string) error
}

Store defines the contract for implementing different session data stores.