storage

Documentation

Overview

Session storage, for use with session-pinning webservers only.

This session system has no locking and is suitable only for use on a single replica, or behind a load balancer which performs session pinning.

Index

• Variables
• type Cookie
  • func DecodeCookie(s string, secretKey []byte) (Cookie, error)
  • func (sc *Cookie) Bump()
  • func (sc *Cookie) Encode(secretKey []byte) string
• type ID
• type Store

Variables

var ErrNotFound = fmt.Errorf("session not found")

Error returned if the session with the given ID is not found.

Types

type Cookie

type Cookie struct {
	ID    ID     // Session ID as assigned by storage backend.
	Epoch uint32 // Session Epoch, starts at zero.
}

Represents a session reference to be encoded into a cookie. Such a cookie is a 2-tuple (ID, Epoch) which is HMAC-signed.

The purpose of the epoch is to change the session cookie without changing the session ID used for backend storage purposes. This may be done, for example, on login or logout. The epoch is stored in the session storage backend, so a session cookie can be considered invalid if the epoch does not match. The epoch is a monotonously increasing counter, and the sole operation which should be performed on it is to increment it.

func DecodeCookie

func DecodeCookie(s string, secretKey []byte) (Cookie, error)

Decodes a session cookie value. The HMAC signature is verified using the secret key given, and the cookie is returned.

func (*Cookie) Bump

func (sc *Cookie) Bump()

Increment the epoch.

func (*Cookie) Encode

func (sc *Cookie) Encode(secretKey []byte) string

Encodes the cookie into a form suitable for use as a cookie value (i.e. text). The cookie is MAC'd against tampering. The secret key to use for the HMAC signature must be passed.

type ID

type ID string

A session ID. Should be treated as an opaque identifying string.

Must be guaranteed to be unique (e.g. a UUID or monotonically incrementing integer).

type Store

type Store interface {
	// Create a session. Returns a unique session ID.
	//
	// In order to make this interface idiotproof in relation to session
	// fixation, sessions can only be created via this method, not via Set.
	Create() (ID, error)

	// Get a session by ID. Returns error if the session does not exist.
	//
	// The consuming code may mutate the returned map, but must do so only if it
	// guarantees that it will later call Set with the same ID and that same map.
	// Such changes may manifest in future calls to Get even before the call to
	// Set or even if Set is not called; i.e., for memory-based session stores,
	// this may be the map used internally, not a copy.
	//
	// The session must have been created via a call to Create.
	Get(ID) (map[string]interface{}, error)

	// Set a session. Returns error if the session does not exist.
	//
	// The session must have been created via a call to Create.
	Set(ID, map[string]interface{}) error

	// Delete a session. Returns error if the session does not exist.
	Delete(ID) error
}

Represents a session store.