Documentation
¶
Overview ¶
Package gorilla/sessions provides cookie and filesystem sessions and infrastructure for custom session backends.
The key features are:
- Simple API: use it as an easy way to set signed (and optionally encrypted) cookies.
- Built-in backends to store sessions in cookies or the filesystem.
- Flash messages: session values that last until read.
- Convenient way to switch session persistency (aka "remember me") and set other attributes.
- Mechanism to rotate authentication and encryption keys.
- Multiple sessions per request, even using different backends.
- Interfaces and infrastructure for custom session backends: sessions from different stores can be retrieved and batch-saved using a common API.
Let's start with an example that shows the sessions API in a nutshell:
import (
"net/http"
"code.google.com/p/gorilla/sessions"
)
var store = sessions.NewCookieStore([]byte("something-very-secret"))
func MyHandler(w http.ResponseWriter, r *http.Request) {
// Get a session. We're ignoring the error resulted from decoding an
// existing session: Get() always returns a session, even if empty.
session, _ := store.Get(r, "session-name")
// Set some session values.
session.Values["foo"] = "bar"
session.Values[42] = 43
// Save it.
session.Save(r, w)
}
First we initialize a session store calling NewCookieStore() and passing a secret key used to authenticate the session. Inside the handler, we call store.Get() to retrieve an existing session or a new one. Then we set some session values in session.Values, which is a map[interface{}]interface{}. And finally we call session.Save() to save the session in the response.
That's all you need to know for the basic usage. Let's take a look at other options, starting with flash messages.
Flash messages are session values that last until read. The term appeared with Ruby On Rails a few years back. When we request a flash message, it is removed from the session. To add a flash, call session.AddFlash(), and to get all flashes, call session.Flashes(). Here is an example:
func MyHandler(w http.ResponseWriter, r *http.Request) {
// Get a session.
session, _ := store.Get(r, "session-name")
// Get the previously flashes, if any.
if flashes := session.Flashes(); len(flashes) > 0 {
// Just print the flash values.
fmt.Fprint(w, "%v", flashes)
} else {
// Set a new flash.
session.AddFlash("Hello, flash messages world!")
fmt.Fprint(w, "No flashes found.")
}
session.Save(r, w)
}
Flash messages are useful to set information to be read after a redirection, like after form submissions.
By default, session cookies last for a month. This is probably too long for some cases, but it is easy to change this and other attributes during runtime. Sessions can be configured individually or the store can be configured and then all sessions saved using it will use that configuration. We access session.Options or store.Options to set a new configuration. The fields are basically a subset of http.Cookie fields. Let's change the maximum age of a session to one week:
session.Options = &sessions.Options{
Path: "/",
MaxAge: 86400 * 7,
}
Sometimes we may want to change authentication and/or encryption keys without breaking existing sessions. The CookieStore supports key rotation, and to use it you just need to set multiple authentication and encryption keys, in pairs, to be tested in order:
var store = sessions.NewCookieStore(
[]byte("new-authentication-key"),
[]byte("new-encryption-key"),
[]byte("old-authentication-key"),
[]byte("old-encryption-key"),
)
New sessions will be saved using the first pair. Old sessions can still be read because the first pair will fail, and the second will be tested. This makes it easy to "rotate" secret keys and still be able to validate existing sessions. Note: for all pairs the encryption key is optional; set it to nil or omit it and and encryption won't be used.
Multiple sessions can be used in the same request, even with different session backends. When this happens, calling Save() on each session individually would be cumbersome, so we have a way to save all sessions at once: it's sessions.Save(). Here's an example:
var store = sessions.NewCookieStore([]byte("something-very-secret"))
func MyHandler(w http.ResponseWriter, r *http.Request) {
// Get a session and set a value.
session1, _ := store.Get(r, "session-one")
session1.Values["foo"] = "bar"
// Get another session and set another value.
session2, _ := store.Get(r, "session-two")
session2.Values[42] = 43
// Save all sessions.
sessions.Save(r, w)
}
This is possible because when we call Get() from a session store, it adds the session to a common registry. Save() uses it to save all registered sessions.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CookieStore ¶
type CookieStore struct {
Codecs []securecookie.Codec
Options *Options // default configuration
}
CookieStore stores sessions using secure cookies.
func NewCookieStore ¶
func NewCookieStore(keyPairs ...[]byte) *CookieStore
NewCookieStore returns a new CookieStore.
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.
Use the convenience function securecookie.GenerateRandomKey() to create strong keys.
func (*CookieStore) Get ¶
Get returns a session for the given name after adding it to the registry.
It returns a new session if the sessions doesn't exist. Access IsNew on the session to check if it is an existing session or a new one.
It returns a new session and an error if the session exists but could not be decoded.
func (*CookieStore) New ¶
New returns a session for the given name without adding it to the registry.
The difference between New() and Get() is that calling New() twice will decode the session data twice, while Get() registers and reuses the same decoded session after the first call.
func (*CookieStore) Save ¶
func (s *CookieStore) Save(r *http.Request, w http.ResponseWriter, session *Session) error
Save adds a single session to the response.
type FilesystemStore ¶
type FilesystemStore struct {
Codecs []securecookie.Codec
Options *Options // default configuration
// contains filtered or unexported fields
}
FilesystemStore stores sessions in the filesystem.
It also serves as a referece for custom stores.
This store is still experimental and not well tested. Feedback is welcome.
func NewFilesystemStore ¶
func NewFilesystemStore(path string, keyPairs ...[]byte) *FilesystemStore
NewFilesystemStore returns a new FilesystemStore.
The path argument is the directory where sessions will be saved. If empty it will use os.TempDir().
See NewCookieStore() for a description of the other parameters.
func (*FilesystemStore) Get ¶
Get returns a session for the given name after adding it to the registry.
See CookieStore.Get().
func (*FilesystemStore) New ¶
New returns a session for the given name without adding it to the registry.
See CookieStore.New().
func (*FilesystemStore) Save ¶
func (s *FilesystemStore) Save(r *http.Request, w http.ResponseWriter, session *Session) error
Save adds a single session to the response.
type MultiError ¶
type MultiError []error
MultiError stores multiple errors.
Borrowed from the App Engine SDK.
func (MultiError) Error ¶
func (m MultiError) Error() string
type Options ¶
type Options struct {
Path string
Domain string
// MaxAge=0 means no 'Max-Age' attribute specified.
// MaxAge<0 means delete cookie now, equivalently 'Max-Age: 0'.
// MaxAge>0 means Max-Age attribute present and given in seconds.
MaxAge int
Secure bool
HttpOnly bool
}
Options stores configuration for a session or session store.
Fields are a subset of http.Cookie fields.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores sessions used during a request.
func GetRegistry ¶
GetRegistry returns a registry instance for the current request.
type Session ¶
type Session struct {
ID string
Values map[interface{}]interface{}
Options *Options
IsNew bool
// contains filtered or unexported fields
}
Session stores the values and optional configuration for a session.
func NewSession ¶
NewSession is called by session stores to create a new session instance.
func (*Session) AddFlash ¶
AddFlash adds a flash message to the session.
A single variadic argument is accepted, and it is optional: it defines the flash key. If not defined "_flash" is used by default.
func (*Session) Flashes ¶
Flashes returns a slice of flash messages from the session.
A single variadic argument is accepted, and it is optional: it defines the flash key. If not defined "_flash" is used by default.
Source Files