sessions

Documentation

Overview

Package sessions implements a custom session store that uses the gorilla/sessions and gorilla/securecookie libraries.

The only session store methods that the caller needs to use are Get() and Save().

The caller uses Get() to initialize a new session.

The caller can save application specific key-value data to the session by saving it to the Values field. This data is never sent to the client. It's saved to the databse as an encoded string and can be retrieved using the session ID.

The caller uses Save() to save the encoded session values to the database and to save the encoded session ID to the http response cookies.

On future requests, the encoded session ID is provided by the client in the request cookie. The caller uses Get() to decode the session ID and to lookup the session values from the database.

The key used to encode/decode the session ID and the session values is provided to the session store on initialization. Keys can be rotated by providing multiple keys on initialization.

Index

• Variables
• func DisableLog()
• func NewOptions(sessionMaxAge int) *sessions.Options
• func NewStore(db DB, opts *sessions.Options, keyPairs ...[]byte) *sessionStore
• func UseLogger(logger slog.Logger)
• type DB
• type EncodedSession

Variables

var (
	// ErrNotFound is returned when an entry is not found in the database.
	ErrNotFound = errors.New("session not found")
)

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func NewOptions

func NewOptions(sessionMaxAge int) *sessions.Options

NewOptions returns a Options for the session store that is configured conservatively. Only deviate from this configuration if you know what you're doing.

func NewStore

func NewStore(db DB, opts *sessions.Options, keyPairs ...[]byte) *sessionStore

NewStore returns a new sessionStore.

Keys are defined in pairs to allow key rotation, but the common case is to set a single authentication key and optionally an encryption key.

The first key in a pair is used for authentication and the second for encryption. The encryption key can be set to nil or omitted in the last pair, but the authentication key is required in all pairs.

It is recommended to use an authentication key with 32 or 64 bytes. The encryption key, if set, must be either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 modes.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using slog.

Types

type DB

type DB interface {
	// Save saves a session to the database.
	Save(sessionID string, s EncodedSession) error

	// Del deletes a session from the database.
	//
	// An error is not returned if the session does not exist.
	Del(sessionID string) error

	// Get gets a session from the database.
	//
	// An ErrNotFound error MUST be returned if a session is not found
	// for the session ID.
	Get(sessionID string) (*EncodedSession, error)
}

DB represents the database for encoded session data.

type EncodedSession

type EncodedSession struct {
	Values string
}

EncodedSession contains a session's encoded values.