sesh

Sesh

A minimal, type-safe, pluggable session manager for Go. A viable alternative to gorilla/sessions.

Features

• Type-safe, minimal API using Go 1.18+ Generics
• Easy-to-use middleware design
• Pluggable session storage
• Doesn't break websockets and server-sent events (SSE)

Install

go get github.com/matthewmueller/sesh

Example

type User struct {
  ID   int    `json:"id"`
  Name string `json:"name"`
}
type Data struct {
  User *User
}

// Initialize the session manager
sessions := sesh.New[Data]()

// Setup the router
router := http.NewServeMux()

// Login a user
router.HandleFunc("POST /sessions", func(w http.ResponseWriter, r *http.Request) {
  // Get the session from context
  session := sessions.FromRequest(r)

  // Assumes we've loaded and authenticated the user
  session.User = &User{
    ID:   1,
    Name: "Alice",
  }

  http.Redirect(w, r, "/", http.StatusFound)
})

// Show the user if they're logged in
router.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
  // Get the session from context
  session := sessions.FromRequest(r)

  // Logged in state
  if session.User != nil {
    w.Write([]byte("Welcome " + session.User.Name))
    return
  }

  // Logged out state
  w.Write([]byte("Welcome!"))
})

// Automatically find and update the session on each request
handler := sessions.Middleware(router)

// Listen on :8080
http.ListenAndServe(":8080", handler)

Making authenticated requests outside of the Browser

For HTTP calls to an app using sesh.Middleware, create a client with the session data the request should have. This is useful for calling authenticated webhook handlers, internal endpoints and impersonating users:

client, err := sessions.Client(Data{
  User: &User{
    ID: 1,
    Name: "Alice",
  },
})
if err != nil {
  return err
}

resp, err := client.Post(webhookURL, "application/json", strings.NewReader(`{"event":"updated"}`))
if err != nil {
  return err
}
defer resp.Body.Close()

For a custom http.Client, you can use sessions.Transport(data) to get the underlying http.RoundTripper.

Flash messages

Use sessions.Flash inside session middleware to queue string values for the next request:

sessions.Flash.Set(r, "notice", "Board created")
sessions.Flash.Add(r, "error", "Name is required")
http.Redirect(w, r, "/boards", http.StatusSeeOther)

On the next request, sessions.Flash.Get(r, "notice") returns the first value. sessions.Flash.All(r) returns a deep copy of all current flashes; use flashes.Values("error") to read multiple values. Reads do not consume flashes. Current flashes expire when the request completes, even if they were never read.

Set and Add queue values for the next request. Del(r, key) and Clear(r) remove pending values without changing the current request's flashes. Application session data needs no flash fields, and middleware handles persistence.

Sessions are stored as JSON, wrapping application data and flashes. Sessions that cannot be decoded are reset. Custom codecs must encode the same value to the same bytes, since sessions are only saved when their encoding changes.

Streaming responses

Responses aren't buffered, so handlers can stream. The session is saved right before the headers are written, so make changes that need a cookie, such as logging in, before writing the body:

session := sessions.FromRequest(r)
session.User = user // change the session first, so the cookie is sent
w.Write([]byte("Welcome " + user.Name))

Changes after the first write are still saved for existing sessions, once the handler returns. A new session can't set its cookie after the headers are sent, so late changes to it are reported to ErrorHandler instead.

Session Storage Plugins

• memory: Default in-memory store. These sessions will last until your server is restart.
• pgxstore: PostgreSQL store using pgx.
• sqstore: SQLite store. Bring your own *sql.DB.
• mockstore: Mockable store. Primarily used for testing.

Missing a Store? Open a PR!

FAQ

How does this compare to gorilla/sessions?

This library is newer, so it has a more modern API. It's also much less battle-tested. Gorilla has many more session stores.

In gorilla, you'll typically get and set sessions like this:

func Handler(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.
  err := session.Save(r, w)
  if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
  }
}

Here's what that looks like in sesh. You'll notice a bit less verbosity, along with not needing to save the session at the end:

type Data struct {
  Foo string
  FortyTwo int
}

var sessions = sesh.New[Data]()

func Handler(w http.ResponseWriter, r *http.Request) {
  session := sessions.Session(r)
  // Set some session values.
  session.Foo = "bar"
  session.FortyTwo = 42

How does this library compare to alexedwards/scs?

Sesh was a successful experiment in trying get a type-safe session store. I also wanted a smaller API surface. As with gorilla/sessions, scs is much more battle-tested and has a larger set of session stores.

The libraries share a similar API:

func main() {
	// Initialize a new session manager
	sessionManager = scs.New()

	mux := http.NewServeMux()
	mux.HandleFunc("/put", putHandler)
	mux.HandleFunc("/get", getHandler)

	// Setup the session middleware
	http.ListenAndServe(":4000", sessionManager.LoadAndSave(mux))
}

func putHandler(w http.ResponseWriter, r *http.Request) {
	// Store a new key and value in the session data.
	sessionManager.Put(r.Context(), "message", "Hello from a session!")
}

func getHandler(w http.ResponseWriter, r *http.Request) {
	// Use the GetString helper to retrieve the string value associated with a
	// key. The zero value is returned if the key does not exist.
	msg := sessionManager.GetString(r.Context(), "message")
	io.WriteString(w, msg)
}

While sesh would look like:

type Data struct {
  Message string
}

func main() {
	// Initialize a new session manager
	sessionManager = sesh[Data].New()

	mux := http.NewServeMux()
	mux.HandleFunc("/put", putHandler)
	mux.HandleFunc("/get", getHandler)

  // Setup the session middleware
	http.ListenAndServe(":4000", sessionManager.Middleware(mux))
}

func putHandler(w http.ResponseWriter, r *http.Request) {
	// Store a new key and value in the session data.
  session := sessionManager.Session(r)
  session.Message = "Hello from a session!"
}

func getHandler(w http.ResponseWriter, r *http.Request) {
  session := sessionManager.Session(r)
	msg := session.Message
	io.WriteString(w, msg)
}

Does it support a stateless cookie store?

Similar to scs, there is no store for saving the session within a cookie. A stateless session needs a different Store interface because it's tied to HTTP and needs to live within the request-response lifecycle.

I thought I'd miss this capability, but it turns out you get a lot of nice features if you store your sessions externally. You get the ability to:

• Tie much more data to a session
• Clear all sessions (e.g. log everyone out)
• Manipulate sessions outside of HTTP (e.g. workers)

Thanks

• Alex Edwards (@alexedwards) for creating scs, which was a big inspiration for this project.

Contributions

We welcome all contributions! Pull requests, bug reports and features requests are all appreciated.

If you have an idea or are unsure how to contribute, open an issue!

Contributors

• Matt Mueller (@mattmueller)

License

MIT