1// Copyright 2012 The Gorilla Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5/* 6Package sessions provides cookie and filesystem sessions and 7infrastructure for custom session backends. 8 9The key features are: 10 11 * Simple API: use it as an easy way to set signed (and optionally 12 encrypted) cookies. 13 * Built-in backends to store sessions in cookies or the filesystem. 14 * Flash messages: session values that last until read. 15 * Convenient way to switch session persistency (aka "remember me") and set 16 other attributes. 17 * Mechanism to rotate authentication and encryption keys. 18 * Multiple sessions per request, even using different backends. 19 * Interfaces and infrastructure for custom session backends: sessions from 20 different stores can be retrieved and batch-saved using a common API. 21 22Let's start with an example that shows the sessions API in a nutshell: 23 24 import ( 25 "net/http" 26 "github.com/gorilla/sessions" 27 ) 28 29 // Note: Don't store your key in your source code. Pass it via an 30 // environmental variable, or flag (or both), and don't accidentally commit it 31 // alongside your code. Ensure your key is sufficiently random - i.e. use Go's 32 // crypto/rand or securecookie.GenerateRandomKey(32) and persist the result. 33 var store = sessions.NewCookieStore(os.Getenv("SESSION_KEY")) 34 35 func MyHandler(w http.ResponseWriter, r *http.Request) { 36 // Get a session. Get() always returns a session, even if empty. 37 session, err := store.Get(r, "session-name") 38 if err != nil { 39 http.Error(w, err.Error(), http.StatusInternalServerError) 40 return 41 } 42 43 // Set some session values. 44 session.Values["foo"] = "bar" 45 session.Values[42] = 43 46 // Save it before we write to the response/return from the handler. 47 session.Save(r, w) 48 } 49 50First we initialize a session store calling NewCookieStore() and passing a 51secret key used to authenticate the session. Inside the handler, we call 52store.Get() to retrieve an existing session or a new one. Then we set some 53session values in session.Values, which is a map[interface{}]interface{}. 54And finally we call session.Save() to save the session in the response. 55 56Note that in production code, we should check for errors when calling 57session.Save(r, w), and either display an error message or otherwise handle it. 58 59Save must be called before writing to the response, otherwise the session 60cookie will not be sent to the client. 61 62Important Note: If you aren't using gorilla/mux, you need to wrap your handlers 63with context.ClearHandler as or else you will leak memory! An easy way to do this 64is to wrap the top-level mux when calling http.ListenAndServe: 65 66 http.ListenAndServe(":8080", context.ClearHandler(http.DefaultServeMux)) 67 68The ClearHandler function is provided by the gorilla/context package. 69 70That's all you need to know for the basic usage. Let's take a look at other 71options, starting with flash messages. 72 73Flash messages are session values that last until read. The term appeared with 74Ruby On Rails a few years back. When we request a flash message, it is removed 75from the session. To add a flash, call session.AddFlash(), and to get all 76flashes, call session.Flashes(). Here is an example: 77 78 func MyHandler(w http.ResponseWriter, r *http.Request) { 79 // Get a session. 80 session, err := store.Get(r, "session-name") 81 if err != nil { 82 http.Error(w, err.Error(), http.StatusInternalServerError) 83 return 84 } 85 86 // Get the previous flashes, if any. 87 if flashes := session.Flashes(); len(flashes) > 0 { 88 // Use the flash values. 89 } else { 90 // Set a new flash. 91 session.AddFlash("Hello, flash messages world!") 92 } 93 session.Save(r, w) 94 } 95 96Flash messages are useful to set information to be read after a redirection, 97like after form submissions. 98 99There may also be cases where you want to store a complex datatype within a 100session, such as a struct. Sessions are serialised using the encoding/gob package, 101so it is easy to register new datatypes for storage in sessions: 102 103 import( 104 "encoding/gob" 105 "github.com/gorilla/sessions" 106 ) 107 108 type Person struct { 109 FirstName string 110 LastName string 111 Email string 112 Age int 113 } 114 115 type M map[string]interface{} 116 117 func init() { 118 119 gob.Register(&Person{}) 120 gob.Register(&M{}) 121 } 122 123As it's not possible to pass a raw type as a parameter to a function, gob.Register() 124relies on us passing it a value of the desired type. In the example above we've passed 125it a pointer to a struct and a pointer to a custom type representing a 126map[string]interface. (We could have passed non-pointer values if we wished.) This will 127then allow us to serialise/deserialise values of those types to and from our sessions. 128 129Note that because session values are stored in a map[string]interface{}, there's 130a need to type-assert data when retrieving it. We'll use the Person struct we registered above: 131 132 func MyHandler(w http.ResponseWriter, r *http.Request) { 133 session, err := store.Get(r, "session-name") 134 if err != nil { 135 http.Error(w, err.Error(), http.StatusInternalServerError) 136 return 137 } 138 139 // Retrieve our struct and type-assert it 140 val := session.Values["person"] 141 var person = &Person{} 142 if person, ok := val.(*Person); !ok { 143 // Handle the case that it's not an expected type 144 } 145 146 // Now we can use our person object 147 } 148 149By default, session cookies last for a month. This is probably too long for 150some cases, but it is easy to change this and other attributes during 151runtime. Sessions can be configured individually or the store can be 152configured and then all sessions saved using it will use that configuration. 153We access session.Options or store.Options to set a new configuration. The 154fields are basically a subset of http.Cookie fields. Let's change the 155maximum age of a session to one week: 156 157 session.Options = &sessions.Options{ 158 Path: "/", 159 MaxAge: 86400 * 7, 160 HttpOnly: true, 161 } 162 163Sometimes we may want to change authentication and/or encryption keys without 164breaking existing sessions. The CookieStore supports key rotation, and to use 165it you just need to set multiple authentication and encryption keys, in pairs, 166to be tested in order: 167 168 var store = sessions.NewCookieStore( 169 []byte("new-authentication-key"), 170 []byte("new-encryption-key"), 171 []byte("old-authentication-key"), 172 []byte("old-encryption-key"), 173 ) 174 175New sessions will be saved using the first pair. Old sessions can still be 176read because the first pair will fail, and the second will be tested. This 177makes it easy to "rotate" secret keys and still be able to validate existing 178sessions. Note: for all pairs the encryption key is optional; set it to nil 179or omit it and and encryption won't be used. 180 181Multiple sessions can be used in the same request, even with different 182session backends. When this happens, calling Save() on each session 183individually would be cumbersome, so we have a way to save all sessions 184at once: it's sessions.Save(). Here's an example: 185 186 var store = sessions.NewCookieStore([]byte("something-very-secret")) 187 188 func MyHandler(w http.ResponseWriter, r *http.Request) { 189 // Get a session and set a value. 190 session1, _ := store.Get(r, "session-one") 191 session1.Values["foo"] = "bar" 192 // Get another session and set another value. 193 session2, _ := store.Get(r, "session-two") 194 session2.Values[42] = 43 195 // Save all sessions. 196 sessions.Save(r, w) 197 } 198 199This is possible because when we call Get() from a session store, it adds the 200session to a common registry. Save() uses it to save all registered sessions. 201*/ 202package sessions 203