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.

Session values can be deleted from the database by saving the session with a MaxAge of <= 0.

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.

The session store does not delete expired sessions from the database. The gorilla/sessions API does not allow the session ID to be retrieved from a session cookie once the session has expired, so there is no way for the session store to know what IDs needs to be deleted from the database. The database layer must track when the session was created and manually delete expired sessions.

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.

sessionMaxAge should be given in seconds. The session store prevents session values from being returned once a session expires.

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.