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 ¶
Constants ¶
This section is empty.
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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.
Types ¶
type DB ¶ added in v1.3.0
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 ¶ added in v1.3.0
type EncodedSession struct {
Values string
}
EncodedSession contains a session's encoded values.