sessions

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 16, 2016 License: BSD-3-Clause, MIT Imports: 16 Imported by: 3

README

Sessions package for Go(go programing language) fasthttp

GoDoc Build Status.

This repo fork from gorilla/sessions.

This package just support fasthttp, if you looking for a sessions package for net/http, the gorilla/sessions is better.

clevergo/sessions provides cookie, filesystem and redis 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, the filesystem or redis.
  • 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.
  • Interfaces and infrastructure for custom session backends: sessions from different stores can be retrieved and batch-saved using a common API.

Install

go get github.com/clevergo/sessions

Examples

go run $GOPATH/src/github.com/clevergo/sessions/examples/main.go

See also examples

License

BSD licensed. See the LICENSE file for details.

Documentation

Overview

Package 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: 

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, err := store.Get(r, "session-name")
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	// 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.

Note that in production code, we should check for errors when calling session.Save(r, w), and either display an error message or otherwise handle it.

Save must be called before writing to the response, otherwise the session cookie will not be sent to the client.

Important Note: If you aren't using gorilla/mux, you need to wrap your handlers with context.ClearHandler as or else you will leak memory! An easy way to do this is to wrap the top-level mux when calling http.ListenAndServe: 

http.ListenAndServe(":8080", context.ClearHandler(http.DefaultServeMux))

The ClearHandler function is provided by the gorilla/context package.

That's all you need to know for the basic usage. Let's take a look at other options, starting with flash messages.

Flash messages are session values that last until read. The term appeared with Ruby On Rails a few years back. When we request a flash message, it is removed from the session. To add a flash, call session.AddFlash(), and to get all flashes, call session.Flashes(). Here is an example: 

func MyHandler(w http.ResponseWriter, r *http.Request) {
	// Get a session.
	session, err := store.Get(r, "session-name")
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	// Get the previously flashes, if any.
	if flashes := session.Flashes(); len(flashes) > 0 {
		// Use the flash values.
	} else {
		// Set a new flash.
		session.AddFlash("Hello, flash messages world!")
	}
	session.Save(r, w)
}

Flash messages are useful to set information to be read after a redirection, like after form submissions.

There may also be cases where you want to store a complex datatype within a session, such as a struct. Sessions are serialised using the encoding/gob package, so it is easy to register new datatypes for storage in sessions: 

import(
	"encoding/gob"
	"github.com/gorilla/sessions"
)

type Person struct {
	FirstName	string
	LastName 	string
	Email		string
	Age			int
}

type M map[string]interface{}

func init() {

	gob.Register(&Person{})
	gob.Register(&M{})
}

As it's not possible to pass a raw type as a parameter to a function, gob.Register() relies on us passing it a value of the desired type. In the example above we've passed it a pointer to a struct and a pointer to a custom type representing a map[string]interface. (We could have passed non-pointer values if we wished.) 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(), http.StatusInternalServerError)
		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 configured and then all sessions saved using it will use that configuration. We access session.Options or store.Options to set a new configuration. The fields are basically a subset of http.Cookie fields. Let's change the maximum age of a session to one week: 

session.Options = &sessions.Options{
	Path:     "/",
	MaxAge:   86400 * 7,
	HttpOnly: true,
}

Sometimes we may want to change authentication and/or encryption keys without breaking existing sessions. The CookieStore supports key rotation, and to use it you just need to set multiple authentication and encryption keys, in pairs, to be tested in order: 

var store = sessions.NewCookieStore(
	[]byte("new-authentication-key"),
	[]byte("new-encryption-key"),
	[]byte("old-authentication-key"),
	[]byte("old-encryption-key"),
)

New sessions will be saved using the first pair. Old sessions can still be read because the first pair will fail, and the second will be tested. This makes it easy to "rotate" secret keys and still be able to validate existing sessions. Note: for all pairs the encryption key is optional; set it to nil or omit it and and encryption won't be used.

Multiple sessions can be used in the same request, even with different session backends. When this happens, calling Save() on each session individually would be cumbersome, so we have a way to save all sessions at once: it's sessions.Save(). Here's an example: 

var store = sessions.NewCookieStore([]byte("something-very-secret"))

func MyHandler(w http.ResponseWriter, r *http.Request) {
	// Get a session and set a value.
	session1, _ := store.Get(r, "session-one")
	session1.Values["foo"] = "bar"
	// Get another session and set another value.
	session2, _ := store.Get(r, "session-two")
	session2.Values[42] = 43
	// Save all sessions.
	sessions.Save(r, w)
}

This is possible because when we call Get() from a session store, it adds the session to a common registry. Save() uses it to save all registered sessions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewCookie 

func NewCookie(name, value string, options *Options) *fasthttp.Cookie

NewCookie returns an http.Cookie with the options set. It also sets the Expires field calculated based on the MaxAge value, for Internet Explorer compatibility.

Types

type CookieStore 

type CookieStore struct {
	Codecs  []securecookie.Codec
	Options *Options // default configuration
}

CookieStore stores sessions using secure cookies.

func NewCookieStore 

func NewCookieStore(keyPairs ...[]byte) *CookieStore

NewCookieStore returns a new CookieStore.

Keys are defined in pairs to allow key rotation, but the common case is to set a single authentication key and optionally an encryption key.

The first key in a pair is used for authentication and the second for encryption. The encryption key can be set to nil or omitted in the last pair, but the authentication key is required in all pairs.

It is recommended to use an authentication key with 32 or 64 bytes. The encryption key, if set, must be either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 modes.

Use the convenience function securecookie.GenerateRandomKey() to create strong keys.

func (*CookieStore) Get 

func (s *CookieStore) Get(ctx *fasthttp.RequestCtx, name string) (*Session, error)

Get returns a session for the given name after adding it to the registry.

It returns a new session if the sessions doesn't exist. Access IsNew on the session to check if it is an existing session or a new one.

It returns a new session and an error if the session exists but could not be decoded.

func (*CookieStore) MaxAge 

func (s *CookieStore) MaxAge(age int)

MaxAge sets the maximum age for the store and the underlying cookie implementation. Individual sessions can be deleted by setting Options.MaxAge = -1 for that session.

func (*CookieStore) Save 

func (s *CookieStore) Save(ctx *fasthttp.RequestCtx, session *Session) error

Save adds a single session to the response.

type FilesystemStore 

type FilesystemStore struct {
	Codecs  []securecookie.Codec
	Options *Options // default configuration
	// contains filtered or unexported fields
}

FilesystemStore stores sessions in the filesystem.

It also serves as a reference for custom stores.

This store is still experimental and not well tested. Feedback is welcome.

func NewFilesystemStore 

func NewFilesystemStore(path string, keyPairs ...[]byte) *FilesystemStore

NewFilesystemStore returns a new FilesystemStore.

The path argument is the directory where sessions will be saved. If empty it will use os.TempDir().

See NewCookieStore() for a description of the other parameters.

func (*FilesystemStore) Get 

func (s *FilesystemStore) Get(ctx *fasthttp.RequestCtx, name string) (*Session, error)

Get returns a session for the given name after adding it to the registry.

See CookieStore.Get().

func (*FilesystemStore) MaxAge 

func (s *FilesystemStore) MaxAge(age int)

MaxAge sets the maximum age for the store and the underlying cookie implementation. Individual sessions can be deleted by setting Options.MaxAge = -1 for that session.

func (*FilesystemStore) MaxLength 

func (s *FilesystemStore) MaxLength(l int)

MaxLength restricts the maximum length of new sessions to l. If l is 0 there is no limit to the size of a session, use with caution. The default for a new FilesystemStore is 4096.

func (*FilesystemStore) Save 

func (s *FilesystemStore) Save(ctx *fasthttp.RequestCtx, session *Session) error

Save adds a single session to the response.

type GobSerializer 

type GobSerializer struct{}

GobSerializer uses gob package to encode the session map

func (GobSerializer) Deserialize 

func (s GobSerializer) Deserialize(d []byte, ss *Session) error

Deserialize back to map[interface{}]interface{}

func (GobSerializer) Serialize 

func (s GobSerializer) Serialize(ss *Session) ([]byte, error)

Serialize using gob

type JSONSerializer 

type JSONSerializer struct{}

JSONSerializer encode the session map to JSON.

func (JSONSerializer) Deserialize 

func (s JSONSerializer) Deserialize(d []byte, ss *Session) error

Deserialize back to map[string]interface{}

func (JSONSerializer) Serialize 

func (s JSONSerializer) Serialize(ss *Session) ([]byte, error)

Serialize to JSON. Will err if there are unmarshalable key values

type MultiError 

type MultiError []error

MultiError stores multiple errors.

Borrowed from the App Engine SDK.

func (MultiError) Error 

func (m MultiError) Error() string

type Options 

type Options struct {
	Path   string
	Domain string
	// MaxAge=0 means no 'Max-Age' attribute specified.
	// MaxAge<0 means delete cookie now, equivalently 'Max-Age: 0'.
	// MaxAge>0 means Max-Age attribute present and given in seconds.
	MaxAge   int
	Secure   bool
	HttpOnly bool
}

Options stores configuration for a session or session store.

Fields are a subset of http.Cookie fields.

type RediStore 

type RediStore struct {
	Pool          *redis.Pool
	Codecs        []securecookie.Codec
	Options       *Options // default configuration
	DefaultMaxAge int      // default Redis TTL for a MaxAge == 0 session
	// contains filtered or unexported fields
}

RediStore stores sessions in a redis backend.

func NewRediStore 

func NewRediStore(size int, network, address, password string, keyPairs ...[]byte) (*RediStore, error)

NewRediStore returns a new RediStore. size: maximum number of idle connections.

func NewRediStoreWithDB 

func NewRediStoreWithDB(size int, network, address, password, DB string, keyPairs ...[]byte) (*RediStore, error)

NewRediStoreWithDB - like NewRedisStore but accepts `DB` parameter to select redis DB instead of using the default one ("0")

func NewRediStoreWithPool 

func NewRediStoreWithPool(pool *redis.Pool, keyPairs ...[]byte) (*RediStore, error)

NewRediStoreWithPool instantiates a RediStore with a *redis.Pool passed in.

func (*RediStore) Close 

func (s *RediStore) Close() error

Close closes the underlying *redis.Pool

func (*RediStore) Delete 

func (s *RediStore) Delete(ctx *fasthttp.RequestCtx, session *Session) error

Delete removes the session from redis, and sets the cookie to expire.

WARNING: This method should be considered deprecated since it is not exposed via the gorilla/sessions interface. Set session.Options.MaxAge = -1 and call Save instead. - July 18th, 2013

func (*RediStore) Get 

func (s *RediStore) Get(ctx *fasthttp.RequestCtx, name string) (*Session, error)

Get returns a session for the given name after adding it to the registry.

func (*RediStore) Save 

func (s *RediStore) Save(ctx *fasthttp.RequestCtx, session *Session) error

Save adds a single session to the response.

func (*RediStore) SetKeyPrefix 

func (s *RediStore) SetKeyPrefix(p string)

SetKeyPrefix set the prefix

func (*RediStore) SetMaxAge 

func (s *RediStore) SetMaxAge(v int)

SetMaxAge restricts the maximum age, in seconds, of the session record both in database and a browser. This is to change session storage configuration. If you want just to remove session use your session `s` object and change it's `Options.MaxAge` to -1, as specified in 

http://godoc.org/github.com/gorilla/sessions#Options

Default is the one provided by this package value - `sessionExpire`. Set it to 0 for no restriction. Because we use `MaxAge` also in SecureCookie crypting algorithm you should use this function to change `MaxAge` value.

func (*RediStore) SetMaxLength 

func (s *RediStore) SetMaxLength(l int)

SetMaxLength sets RediStore.maxLength if the `l` argument is greater or equal 0 maxLength restricts the maximum length of new sessions to l. If l is 0 there is no limit to the size of a session, use with caution. The default for a new RediStore is 4096. Redis allows for max. value sizes of up to 512MB (http://redis.io/topics/data-types) Default: 4096,

func (*RediStore) SetSerializer 

func (s *RediStore) SetSerializer(ss SessionSerializer)

SetSerializer sets the serializer

type Session 

type Session struct {
	// The ID of the session, generated by stores. It should not be used for
	// user data.
	ID string
	// Values contains the user-data for the session.
	Values  map[interface{}]interface{}
	Options *Options
	IsNew   bool
	// contains filtered or unexported fields
}

Session stores the values and optional configuration for a session.

func NewSession 

func NewSession(store Store, name string) *Session

NewSession is called by session stores to create a new session instance.

func (*Session) AddFlash 

func (s *Session) AddFlash(value interface{}, vars ...string)

AddFlash adds a flash message to the session.

A single variadic argument is accepted, and it is optional: it defines the flash key. If not defined "_flash" is used by default.

func (*Session) Flashes 

func (s *Session) Flashes(vars ...string) []interface{}

Flashes returns a slice of flash messages from the session.

A single variadic argument is accepted, and it is optional: it defines the flash key. If not defined "_flash" is used by default.

func (*Session) Name 

func (s *Session) Name() string

Name returns the name used to register the session.

func (*Session) Save 

func (s *Session) Save(ctx *fasthttp.RequestCtx) error

Save is a convenience method to save this session. It is the same as calling store.Save(request, response, session). You should call Save before writing to the response or returning from the handler.

func (*Session) Store 

func (s *Session) Store() Store

Store returns the session store used to register the session.

type SessionSerializer 

type SessionSerializer interface {
	Deserialize(d []byte, ss *Session) error
	Serialize(ss *Session) ([]byte, error)
}

SessionSerializer provides an interface hook for alternative serializers

type Store 

type Store interface {
	// Get should return a session.
	Get(ctx *fasthttp.RequestCtx, name string) (*Session, error)

	// Save should persist session to the underlying store implementation.
	Save(ctx *fasthttp.RequestCtx, s *Session) error
}

Store is an interface for custom session stores.

See CookieStore and FilesystemStore for examples.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.