diff options
| -rw-r--r-- | README.md | 59 | ||||
| -rw-r--r-- | doc.go | 36 | ||||
| -rw-r--r-- | sessions.go | 3 | ||||
| -rw-r--r-- | store.go | 38 |
4 files changed, 100 insertions, 36 deletions
@@ -1,10 +1,59 @@ sessions ======== +[](https://godoc.org/github.com/gorilla/sessions) [](https://travis-ci.org/gorilla/sessions) + +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: + +```go + import ( + "net/http" + "github.com/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 before we write to the response/return from the handler. + 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. + +More examples are available [on the Gorilla +website](http://www.gorillatoolkit.org/pkg/sessions). + +## Store Implementations -Store Implementations ---------------------- Other implementations of the sessions.Store interface: + * [github.com/starJammer/gorilla-sessions-arangodb](https://github.com/starJammer/gorilla-sessions-arangodb) - ArangoDB * [github.com/yosssi/boltstore](https://github.com/yosssi/boltstore) - Bolt * [github.com/srinathgs/couchbasestore](https://github.com/srinathgs/couchbasestore) - Couchbase * [github.com/denizeren/dynamostore](https://github.com/denizeren/dynamostore) - Dynamodb on AWS @@ -14,4 +63,10 @@ Other implementations of the sessions.Store interface: * [github.com/srinathgs/mysqlstore](https://github.com/srinathgs/mysqlstore) - MySQL * [github.com/antonlindstrom/pgstore](https://github.com/antonlindstrom/pgstore) - PostgreSQL * [github.com/boj/redistore](https://github.com/boj/redistore) - Redis + * [github.com/boj/rethinkstore](https://github.com/boj/rethinkstore) - RethinkDB * [github.com/boj/riakstore](https://github.com/boj/riakstore) - Riak + * [github.com/michaeljs1990/sqlitestore](https://github.com/michaeljs1990/sqlitestore) - SQLite + + ## License + + BSD licensed. See the LICENSE file for details. @@ -31,11 +31,16 @@ Let's start with an example that shows the sessions API in a nutshell: 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") + session, err := store.Get(r, "session-name") + if err != nil { + http.Error(w, err.Error(), 500) + return + } + // Set some session values. session.Values["foo"] = "bar" session.Values[42] = 43 - // Save it. + // Save it before we write to the response/return from the handler. session.Save(r, w) } @@ -69,7 +74,12 @@ 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") + session, err := store.Get(r, "session-name") + if err != nil { + http.Error(w, err.Error(), 500) + return + } + // Get the previously flashes, if any. if flashes := session.Flashes(); len(flashes) > 0 { // Use the flash values. @@ -113,6 +123,26 @@ above we've passed it a pointer to a struct and a pointer to a custom type representing a map[string]interface. This will then allow us to serialise/deserialise values of those types to and from our sessions. +Note that because session values are stored in a map[string]interface{}, there's +a need to type-assert data when retrieving it. We'll use the Person struct we registered above: + + func MyHandler(w http.ResponseWriter, r *http.Request) { + session, err := store.Get(r, "session-name") + if err != nil { + http.Error(w, err.Error(), 500) + return + } + + // Retrieve our struct and type-assert it + val := session.Values["person"] + var person &Person{} + if person, ok := val.(*Person); !ok { + // Handle the case that it's not an expected type + } + + // Now we can use our person object + } + 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 diff --git a/sessions.go b/sessions.go index 53111b3..d6bfb6e 100644 --- a/sessions.go +++ b/sessions.go @@ -88,7 +88,8 @@ func (s *Session) AddFlash(value interface{}, vars ...string) { } // Save is a convenience method to save this session. It is the same as calling -// store.Save(request, response, session) +// store.Save(request, response, session). You should call Save before writing to +// the response or returning from the handler. func (s *Session) Save(r *http.Request, w http.ResponseWriter) error { return s.store.Save(r, w, s) } @@ -6,9 +6,10 @@ package sessions import ( "encoding/base32" - "io" + "io/ioutil" "net/http" "os" + "path/filepath" "strings" "sync" @@ -123,9 +124,6 @@ func NewFilesystemStore(path string, keyPairs ...[]byte) *FilesystemStore { if path == "" { path = os.TempDir() } - if path[len(path)-1] != '/' { - path += "/" - } return &FilesystemStore{ Codecs: securecookie.CodecsFromPairs(keyPairs...), Options: &Options{ @@ -215,41 +213,21 @@ func (s *FilesystemStore) save(session *Session) error { if err != nil { return err } - filename := s.path + "session_" + session.ID + filename := filepath.Join(s.path, "session_"+session.ID) fileMutex.Lock() defer fileMutex.Unlock() - fp, err := os.OpenFile(filename, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600) - if err != nil { - return err - } - if _, err = fp.Write([]byte(encoded)); err != nil { - return err - } - fp.Close() - return nil + return ioutil.WriteFile(filename, []byte(encoded), 0600) } // load reads a file and decodes its content into session.Values. func (s *FilesystemStore) load(session *Session) error { - filename := s.path + "session_" + session.ID - fp, err := os.OpenFile(filename, os.O_RDONLY, 0400) + filename := filepath.Join(s.path, "session_"+session.ID) + fileMutex.RLock() + defer fileMutex.RUnlock() + fdata, err := ioutil.ReadFile(filename) if err != nil { return err } - defer fp.Close() - var fdata []byte - buf := make([]byte, 128) - for { - var n int - n, err = fp.Read(buf[0:]) - fdata = append(fdata, buf[0:n]...) - if err != nil { - if err == io.EOF { - break - } - return err - } - } if err = securecookie.DecodeMulti(session.Name(), string(fdata), &session.Values, s.Codecs...); err != nil { return err |