SCS is a fast and lightweight HTTP session manager for Go. It features:
- Built-in PostgreSQL, MySQL, Redis, Memcached, encrypted cookie and in-memory storage engines. Custom storage engines are also supported.
- Supports OWASP good-practices, including absolute and idle session timeouts and easy regeneration of session tokens.
- Fast and very memory-efficient performance.
- Type-safe and sensible API for managing session data. Safe for concurrent use.
- Automatic saving of session data.
Recent changes: Release v1.0.0 made breaking changes to the package layout and API. If you need the old version please vendor release v0.1.1.
Install with go get:
$ go get github.com/alexedwards/scspackage main
import (
"io"
"net/http"
"github.com/alexedwards/scs"
)
// Initialize a new encrypted-cookie based session manager and store it in a global
// variable. In a real application, you might inject the session manager as a
// dependency to your handlers instead. The parameter to the NewCookieManager()
// function is a 32 character long random key, which is used to encrypt and
// authenticate the session cookies.
var sessionManager = scs.NewCookieManager("u46IpCV9y5Vlur8YvODJEhgOY8m9JVE4")
func main() {
// Set up your HTTP handlers in the normal way.
mux := http.NewServeMux()
mux.HandleFunc("/put", putHandler)
mux.HandleFunc("/get", getHandler)
// Wrap your handlers with the session manager middleware.
http.ListenAndServe(":4000", sessionManager.Use(mux))
}
func putHandler(w http.ResponseWriter, r *http.Request) {
// Load the session data for the current request. Any errors are deferred
// until you actually use the session data.
session := sessionManager.Load(r)
// Use the PutString() method to add a new key and associated string value
// to the session data. Methods for many other common data types are also
// provided. The session data is automatically saved.
err := session.PutString(w, "message", "Hello world!")
if err != nil {
http.Error(w, err.Error(), 500)
}
}
func getHandler(w http.ResponseWriter, r *http.Request) {
// Load the session data for the current request.
session := sessionManager.Load(r)
// Use the GetString() helper to retrieve the string value for the "message"
// key from the session data. The zero value for a string is returned if the
// key does not exist.
message, err := session.GetString("message")
if err != nil {
http.Error(w, err.Error(), 500)
}
io.WriteString(w, message)
}SCS provides a wide range of functions for working with session data.
Put…andGet…methods for storing and retrieving a variety of common data types and custom objects.Pop…methods for one-time retrieval of common data types (and custom objects) from the session data.Keysreturns an alphabetically-sorted slice of all keys in the session data.Existsreturns whether a specific key exists in the session data.Removeremoves an individual key and value from the session data.Clearremoves all data for the current session.RenewTokencreates a new session token. This should be used before privilege changes to help avoid session fixation.Destroydeletes the current session and instructs the browser to delete the session cookie.
A full list of available functions can be found in the GoDoc.
The session manager can be configured to customize its behavior. For example:
sessionManager = scs.NewCookieManager("u46IpCV9y5Vlur8YvODJEhgOY8m9JVE4")
sessionManager.Lifetime(time.Hour) // Set the maximum session lifetime to 1 hour.
sessionManager.Persist(true) // Persist the session after a user has closed their browser.
sessionManager.Secure(true) // Set the Secure flag on the session cookie.A full list of available settings can be found in the GoDoc.
The above examples use encrypted cookies to store session data, but SCS also supports a range of server-side stores.
| Package | |
|---|---|
| stores/boltstore | BoltDB-based session store |
| stores/buntstore | BuntDB based session store |
| stores/cookiestore | Encrypted-cookie session store |
| stores/dynamostore | DynamoDB-based session store |
| stores/memstore | In-memory session store |
| stores/mysqlstore | MySQL-based session store |
| stores/pgstore | PostgreSQL-based storage eninge |
| stores/qlstore | QL-based session store |
| stores/redisstore | Redis-based session store |
| stores/memcached | Memcached-based session store |
SCS is designed to be compatible with Go's net/http package and the http.Handler interface.
If you're using the Echo framework, the official session middleware for Echo is likely to be a better fit for your application.