sessions

README

Sessions

Package sessions provides HTTP session cookie management for Go. It allows you to set both data that persists between requests (session data), and data that persists until the next request (flash data).

Unlike typical session libraries for Go, sessions uses the request's context for storage within the same request liftime, allowing you to access the session between multiple handlers or HTTP middleware, as well as within test cases that do not use an HTTP server.

Usage

Install the package with go get:

$ go get github.com/bentranter/sessions

Then you can set session and flash data:

// Create a new session manager.
session := New(GenerateRandomKey(32), Options{
    // Set a custom session name (default is "_session").
    Name: "_example_session_name",
})

// Get and set session data.
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    if r.Method == http.MethodGet {
        name := session.Get(r, "name")
        fmt.Fprintf(w, "Your name is: %s\n", name)
        return
    }
    session.Set(w, r, "name", "Ben")
    http.Redirect(w, r, "/", http.StatusSeeOther)
})

// List and display all session data as JSON.
http.HandleFunc("/list", func(w http.ResponseWriter, r *http.Request) {
    values := session.List(r)

    data, err := json.MarshalIndent(values, "", "  ")
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    w.Write(data)
})

// Delete a flash message.
http.HandleFunc("/delete", func(w http.ResponseWriter, r *http.Request) {
    session.Delete(w, r, "name")
    http.Redirect(w, r, "/", http.StatusFound)
})

// List and set flash messages.
http.HandleFunc("/flash", func(w http.ResponseWriter, r *http.Request) {
    if r.Method == http.MethodGet {
        flashes := session.Flashes(w, r)

        data, err := json.MarshalIndent(flashes, "", "  ")
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }

        w.Write(data)
        return
    }

    if r.URL.Query().Has("flash") {
        session.Flash(w, r, "notice", "This is a flash message")
    }
    http.Redirect(w, r, "/flash", http.StatusSeeOther)
})

// Clear all session data.
http.HandleFunc("/reset", func(w http.ResponseWriter, r *http.Request) {
    session.Reset(w, r)
    http.Redirect(w, r, "/", http.StatusFound)
})

Using with templ

templ FlashComponent() {
	for key, val := range session.FlashesCtx(ctx) {
		<div>{ key }: { fmt.Sprintf("%v", val) }</div>
	}
}

Documentation

Overview

Package sessions implements HTTP sessions.

(Description TODO)

Index

• Constants
• func FlashesCtx(ctx context.Context) map[string]interface{}
• func GenerateRandomKey(length int) []byte
• type Options
• type Session
  • func New(secret []byte, opts ...Options) *Session
  • func (s *Session) Delete(w http.ResponseWriter, r *http.Request, key string) interface{}
  • func (s *Session) Flash(w http.ResponseWriter, r *http.Request, key string, value interface{})
  • func (s *Session) Flashes(w http.ResponseWriter, r *http.Request) map[string]interface{}
  • func (s *Session) FlashesCtx(ctx context.Context) map[string]interface{}
  • func (s *Session) Get(r *http.Request, key string) interface{}
  • func (s *Session) List(r *http.Request) map[string]interface{}
  • func (s *Session) Reset(w http.ResponseWriter, r *http.Request)
  • func (s *Session) Set(w http.ResponseWriter, r *http.Request, key string, value interface{})
  • func (s *Session) TemplMiddleware(next http.Handler, skipPaths ...string) http.Handler

Examples

• Session

Constants

const Version = "1.3.0"

Version is the released version of the library.

Functions

func FlashesCtx

func FlashesCtx(ctx context.Context) map[string]interface{}

FlashesCtx returns all flash messages as a map[string]interace{} for the given context.

This method is intended to be used with the https://github.com/a-h/templ library. It requires the use of the sessions.TemplMiddleware, which ensures that every incoming request has the session data decoded into the context.

When called, the flash messages are cleared on subsequent requests.

This method makes it possible to access session data in templ's global ctx instance, for example, you can use the sessions.FlashesCtx method:

for key, val := range sessions.FlashesCtx(ctx) {
	<div>{ key }: { fmt.Sprintf("%v", val) }</div>
}

func GenerateRandomKey

func GenerateRandomKey(length int) []byte

GenerateRandomKey creates a random key with the given length in bytes. On failure, returns nil.

Note that keys created using `GenerateRandomKey()` are not automatically persisted. New keys will be created when the application is restarted, and previously issued cookies will not be able to be decoded.

Callers should explicitly check for the possibility of a nil return, treat it as a failure of the system random number generator, and not continue.

This function is an alias of securecookie.GenerateRandomKey, and is provided as a convenience method to avoid the additional import of the securecookie library.

Types

type Options

type Options struct {
	// The name of the cookie (default is "_session").
	Name string

	// MaxAge of the cookie before expiry (default is 365 days). Set it to
	// -1 for no expiry.
	MaxAge int

	// Quiet defines whether or not to suppress all error and warning messages
	// from the library. Defaults to false, since when correctly used, these
	// messages should never appear. Setting to true may suppress critical
	// error and warning messages.
	Quiet bool
}

Options to customize the behaviour of the session.

type Session

type Session struct {
	// contains filtered or unexported fields
}

A Session manages setting and getting data from the cookie that stores the session data.

Example

// Create a new session manager.
session := New(GenerateRandomKey(32), Options{
	// Set a custom session name (default is "_session").
	Name: "_example_session_name",
})

// Get and set session data.
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
	if r.Method == http.MethodGet {
		name := session.Get(r, "name")
		fmt.Fprintf(w, "Your name is: %s\n", name)
		return
	}
	session.Set(w, r, "name", "Ben")
	http.Redirect(w, r, "/", http.StatusSeeOther)
})

// List and display all session data as JSON.
http.HandleFunc("/list", func(w http.ResponseWriter, r *http.Request) {
	values := session.List(r)

	data, err := json.MarshalIndent(values, "", "  ")
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	w.Write(data)
})

// Delete a flash message.
http.HandleFunc("/delete", func(w http.ResponseWriter, r *http.Request) {
	session.Delete(w, r, "name")
	http.Redirect(w, r, "/", http.StatusFound)
})

// List and set flash messages.
http.HandleFunc("/flash", func(w http.ResponseWriter, r *http.Request) {
	if r.Method == http.MethodGet {
		flashes := session.Flashes(w, r)

		data, err := json.MarshalIndent(flashes, "", "  ")
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}

		w.Write(data)
		return
	}

	if r.URL.Query().Has("flash") {
		session.Flash(w, r, "notice", "This is a flash message")
	}
	http.Redirect(w, r, "/flash", http.StatusSeeOther)
})

// Clear all session data.
http.HandleFunc("/reset", func(w http.ResponseWriter, r *http.Request) {
	session.Reset(w, r)
	http.Redirect(w, r, "/", http.StatusFound)
})

func New

func New(secret []byte, opts ...Options) *Session

New creates a new session manager with the given key.

func (*Session) Delete

func (s *Session) Delete(w http.ResponseWriter, r *http.Request, key string) interface{}

Delete deletes and returns the session value with the given key.

func (*Session) Flash

func (s *Session) Flash(w http.ResponseWriter, r *http.Request, key string, value interface{})

Flash sets a flash message on a request.

func (*Session) Flashes

func (s *Session) Flashes(w http.ResponseWriter, r *http.Request) map[string]interface{}

Flashes returns all flash messages, clearing all saved flashes.

func (*Session) FlashesCtx

func (s *Session) FlashesCtx(ctx context.Context) map[string]interface{}

FlashesCtx returns all flash messages as a map[string]interace{} for the given context.

This method is intended to be used with the https://github.com/a-h/templ library. It requires the use of the sessions.TemplMiddleware, which ensures that every incoming request has the session data decoded into the context.

When called, the flash messages are cleared on subsequent requests.

This method makes it possible to access session data in templ's global ctx instance, for example, you can use the sessions.FlashesCtx method:

for key, val := range session.FlashesCtx(ctx) {
	<div>{ key }: { fmt.Sprintf("%v", val) }</div>
}

func (*Session) Get

func (s *Session) Get(r *http.Request, key string) interface{}

Session creates a new session from the given HTTP request. If the request already has a cookie with an associated session, the session data is created from the cookie. If not, a new session is created.

func (*Session) List

func (s *Session) List(r *http.Request) map[string]interface{}

List returns all key value pairs of session data from the given request.

func (*Session) Reset

func (s *Session) Reset(w http.ResponseWriter, r *http.Request)

Reset resets the session, deleting all values.

func (*Session) Set

func (s *Session) Set(w http.ResponseWriter, r *http.Request, key string, value interface{})

Set sets or updates the given value on the session.

func (*Session) TemplMiddleware

func (s *Session) TemplMiddleware(next http.Handler, skipPaths ...string) http.Handler

TemplMiddleware ensures that the session data is always available on the request context for any handler wrapped by the middleware.

This is in contrast to the default behaviour of the library, which is to lazily extract the session data from the cookie into the request context whenever any session methods are called.

This method makes it possible to access session data in templ's global ctx instance, for example, you can use the sessions.FlashesCtx method:

for key, val := range session.FlashesCtx(ctx) {
	<div>{ key }: { fmt.Sprintf("%v", val) }</div>
}

If any `skipPaths` are provided, TemplMiddleware will not execute for those paths. These paths must begin with a `/` in order to match any requests. In general, having `TemplMiddleware` execute on every handler will not cause any issues, but in cases where your handler's `ResponseWriter` satisfies an additional interface (i.e., `http.Hijacker`), you should skip those paths, as the middleware inserts its own `http.ResponseWriter` that does not implement those additional interfaces.