session

README

Go Sessions

This package is expected to allow you to work with sessions in a Go application.

Get started

First, creates a storage. The package provides two storage types, one is based on memory and the other is based on files.

import "github.com/xandalm/go-session/memory"

...

storage := memory.Storage()

or

import "github.com/xandalm/go-session/filesystem"

...

storage := filesystem.Storage()
// or filesystem.Storage("foo/bar") to set the destination path

Now, it's necessary an adapter for the expired sessions checking step. The package provides an adapter based on seconds.

adapter := session.SecondsAgeCheckerAdapter

Ok, now we can get a provider. The package has a default provider that can be created via NewProvider(). This function wants two args, the first is the storage and the second is the adapter to be used at session expiration check.

provider := session.NewProvider(storage, adapter)

And finally, we can get manager. The manager can be created through NewManager(). Pass the provider, cookie name and the expiration time unit to the function.

manager := session.NewManager(provider, "[YOUR_COOKIE_NAME]", 3600)

Note: The expiration time unit will be adapted through the adapter, in this case,
the SecondsAgeCheckerAdapter was used, which means that the expiration time is 3600 seconds.

Now, make a call to manager.GC(), which will create a routine to check for expired sessions, accordingly to expiration time unit.

Alright, now sessions can be create or retrieved through manager.StartSession() and destroyed through manager.DestroySession().

The session exposes some methods, suppose sess holds a session:

• sess.SessionsID() to get its identifier;
• sess.Set() to define a key and its value;
• sess.Get() to get a key value;
• sess.Delete() to remove defined key and its value.

Note: Some arguments were hidden.

Documentation

Index

• Variables
• func NewProvider(storage Storage, adapter AgeCheckerAdapter) *defaultProvider
• type AgeChecker
• type AgeCheckerAdapter
• type Manager
  • func NewManager(provider Provider, cookieName string, maxAge int64) *Manager
  • func (m *Manager) DestroySession(w http.ResponseWriter, r *http.Request)
  • func (m *Manager) GC()
  • func (m *Manager) StartSession(w http.ResponseWriter, r *http.Request) (session Session)
• type Provider
• type Session
• type Storage

Variables

var (
	ErrEmptySessionId             error = errors.New("session: sid cannot be empty")
	ErrDuplicatedSessionId        error = errors.New("session: cannot duplicate sid")
	ErrUnableToRestoreSession     error = errors.New("session: unable to restore session (storage failure)")
	ErrUnableToEnsureNonDuplicity error = errors.New("session: unable to ensure non-duplicity of sid (storage failure)")
	ErrUnableToDestroySession     error = errors.New("session: unable to destroy session (storage failure)")
	ErrUnableToSaveSession        error = errors.New("session: unable to save session (storage failure)")
)

Functions

func NewProvider

func NewProvider(storage Storage, adapter AgeCheckerAdapter) *defaultProvider

Returns a new defaultProvider (address for pointer reference).

Types

type AgeChecker

type AgeChecker interface {
	ShouldReap(time.Time) bool
}

type AgeCheckerAdapter

type AgeCheckerAdapter func(int64) AgeChecker

var SecondsAgeCheckerAdapter AgeCheckerAdapter = func(maxAge int64) AgeChecker {
	return secondsAgeChecker(maxAge)
}

type Manager

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

Manager allows to work with sessions.

It can start or destroy one session. Both operations will manipulate a http cookie.

To start a session, it will: - Creates a new one, setting a http cookie; or - Retrieves, accordingly to the existent http cookie.

To destroys a session, it can be forced or after it expires. The expired session is removed through the GC routine, which checks this condition.

func NewManager

func NewManager(provider Provider, cookieName string, maxAge int64) *Manager

Returns a new Manager (address for pointer reference).

The provider cannot be nil and cookie name cannot be empty.

func (*Manager) DestroySession

func (m *Manager) DestroySession(w http.ResponseWriter, r *http.Request)

Destroys the session, finally cleaning up the http cookie.

func (*Manager) GC

func (m *Manager) GC()

Creates a routine to check for expired sessions and remove them.

func (*Manager) StartSession

func (m *Manager) StartSession(w http.ResponseWriter, r *http.Request) (session Session)

Creates or retrieve the session based on the http cookie.

type Provider

type Provider interface {
	SessionInit(sid string) (Session, error)
	SessionRead(sid string) (Session, error)
	SessionDestroy(sid string) error
	SessionGC(maxAge int64)
}

type Session

type Session interface {
	// Defines a value for the key.
	Set(key string, value any) error
	// Returns a value for the key, or nil if it doesn't exist.
	Get(key string) any
	// Removes the key and it's value.
	Delete(key string) error
	// Returns session identifier.
	SessionID() string
}

type Storage

type Storage interface {
	CreateSession(sid string) (Session, error)
	GetSession(sid string) (Session, error)
	ContainsSession(sid string) (bool, error)
	ReapSession(sid string) error
	Deadline(AgeChecker)
}