session

Documentation

Overview

Package session provides HTTP state management library for aah framework. Default store is `Cookie` and framework provides `FileStore` and extensible `session.Storer` interface. Using store interface you can write any key-value Database, NoSQL Database, and RDBMS for storing encoded session data.

Features:

• Extensible session store interface
• Signed session data
• Encrypted session data

Non-cookie store session data is maintained via store interface. Only Session ID is transmitted over the wire in the Cookie. Please refer `session.FileStore` for sample, its very easy.

If you would like to store custom types in session then Register your custom types using `gob.Register(...)`.

Secure cookie code is inspired from Gorilla secure cookie library.

Know more: https://www.owasp.org/index.php/Session_Management_Cheat_Sheet

Index

• Variables
• func AddStore(name string, store Storer) error
• func ReleaseSession(s *Session)
• type FileStore
  • func (f *FileStore) Cleanup(m *Manager)
  • func (f *FileStore) Delete(id string) error
  • func (f *FileStore) Init(cfg *config.Config) error
  • func (f *FileStore) IsExists(id string) bool
  • func (f *FileStore) Read(id string) string
  • func (f *FileStore) Save(id, value string) error
• type Manager
  • func NewManager(appCfg *config.Config) (*Manager, error)
  • func (m *Manager) Decode(value string, dst interface{}) error
  • func (m *Manager) DecodeToSession(encodedStr string) (*Session, error)
  • func (m *Manager) DecodeToString(encodedStr string) (string, error)
  • func (m *Manager) DeleteSession(w http.ResponseWriter, s *Session) error
  • func (m *Manager) Encode(value interface{}) (string, error)
  • func (m *Manager) GetSession(r *http.Request) *Session
  • func (m *Manager) IsCookieStore() bool
  • func (m *Manager) IsStateful() bool
  • func (m *Manager) NewSession() *Session
  • func (m *Manager) SaveSession(w http.ResponseWriter, s *Session) error
• type Session
  • func (s *Session) Clear()
  • func (s *Session) Del(key string)
  • func (s *Session) Get(key string) interface{}
  • func (s *Session) GetBool(key string) bool
  • func (s *Session) GetFlash(key string) interface{}
  • func (s *Session) GetFloat32(key string) float32
  • func (s *Session) GetFloat64(key string) float64
  • func (s *Session) GetInt(key string) int
  • func (s *Session) GetInt64(key string) int64
  • func (s *Session) GetString(key string) string
  • func (s *Session) IsKeyExists(key string) bool
  • func (s *Session) Reset()
  • func (s *Session) Set(key string, value interface{})
  • func (s *Session) SetFlash(key string, value interface{})
  • func (s Session) String() string
• type Storer

Variables

var (
	// ErrSessionStoreIsNil returned when suppiled store is nil.
	ErrSessionStoreIsNil = errors.New("security/session: store value is nil")
)

Functions

func AddStore

func AddStore(name string, store Storer) error

AddStore method allows you to add user created session store for aah framework application.

func ReleaseSession

func ReleaseSession(s *Session)

ReleaseSession method puts session object back to pool.

Types

type FileStore

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

FileStore is the aah framework session store implementation.

func (*FileStore) Cleanup

func (f *FileStore) Cleanup(m *Manager)

Cleanup method deletes the expired session file.

func (*FileStore) Delete

func (f *FileStore) Delete(id string) error

Delete method deletes the session file for given id.

func (*FileStore) Init

func (f *FileStore) Init(cfg *config.Config) error

Init method initialize the file store using given application config.

func (*FileStore) IsExists

func (f *FileStore) IsExists(id string) bool

IsExists method returns true if the session file exists otherwise false.

func (*FileStore) Read

func (f *FileStore) Read(id string) string

Read method reads the encoded cookie value from file.

func (*FileStore) Save

func (f *FileStore) Save(id, value string) error

Save method saves the given session id with encoded cookie value.

type Manager

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

Manager is a session manager to manage sessions.

func NewManager

func NewManager(appCfg *config.Config) (*Manager, error)

NewManager method initializes the session manager and store based on configuration from aah.conf section `session { ... }`.

func (*Manager) Decode

func (m *Manager) Decode(value string, dst interface{}) error

Decode method decodes given value with name.

It performs:

1. Decrypts the value (size check, decode base64, sign verify, timestamp verify, decrypt)
2. Decode into result object using `Gob`

func (*Manager) DecodeToSession

func (m *Manager) DecodeToSession(encodedStr string) (*Session, error)

DecodeToSession method decodes the encoded string into session object.

func (*Manager) DecodeToString

func (m *Manager) DecodeToString(encodedStr string) (string, error)

DecodeToString method decodes the encoded string into original string.

func (*Manager) DeleteSession

func (m *Manager) DeleteSession(w http.ResponseWriter, s *Session) error

DeleteSession method deletes the session from store and sets deletion for browser cookie.

func (*Manager) Encode

func (m *Manager) Encode(value interface{}) (string, error)

Encode method encodes given value with name.

It performs:

1. Encodes the value using `Gob`
2. Encodes value into Base64 (encrypt, sign, cookie size check)

func (*Manager) GetSession

func (m *Manager) GetSession(r *http.Request) *Session

GetSession method returns the session for given request instance otherwise it returns nil.

func (*Manager) IsCookieStore

func (m *Manager) IsCookieStore() bool

IsCookieStore method returns true if session store is cookie otherwise false.

func (*Manager) IsStateful

func (m *Manager) IsStateful() bool

IsStateful methdo returns true if session mode is stateful otherwise false.

func (*Manager) NewSession

func (m *Manager) NewSession() *Session

NewSession method creates a new session for the request.

func (*Manager) SaveSession

func (m *Manager) SaveSession(w http.ResponseWriter, s *Session) error

SaveSession method saves the given session into store. Add writes the cookie into response.

type Session

type Session struct {
	// ID method return session ID. It is dynamically generated while new session
	// creation. ID length is 32.
	//
	//Note: Do not use this value for any/derving user relation, not recommended.
	ID string

	// Values is values that stored in session object.
	Values map[string]interface{}

	// IsNew indicates whether sesison is newly created or restore from the
	// request which was already created.
	IsNew bool

	// IsAuthenticated is helpful to identify user session already authenicated or
	// not. Don't forget to set it true after successful authentication.
	IsAuthenticated bool

	// CreatedTime is when the session was created.
	CreatedTime *time.Time
	// contains filtered or unexported fields
}

Session hold the information for particular HTTP request.

func (*Session) Clear

func (s *Session) Clear()

Clear method marks the session for deletion. It triggers the deletion at the end of the request for cookie and session store data.

func (*Session) Del

func (s *Session) Del(key string)

Del method deletes the value for the given key if exists.

func (*Session) Get

func (s *Session) Get(key string) interface{}

Get method returns the value for given key otherwise nil.

func (*Session) GetBool

func (s *Session) GetBool(key string) bool

GetBool method returns the `bool` value from otherwise false.

func (*Session) GetFlash

func (s *Session) GetFlash(key string) interface{}

GetFlash method returns the flash messages from the session object and deletes it from session.

func (*Session) GetFloat32

func (s *Session) GetFloat32(key string) float32

GetFloat32 method returns the `float32` value from session otherwise 0.

func (*Session) GetFloat64

func (s *Session) GetFloat64(key string) float64

GetFloat64 method returns the `float64` value from session otherwise 0.

func (*Session) GetInt

func (s *Session) GetInt(key string) int

GetInt method returns the `int` value from session otherwise 0.

func (*Session) GetInt64

func (s *Session) GetInt64(key string) int64

GetInt64 method returns the `int64` value from session otherwise 0.

func (*Session) GetString

func (s *Session) GetString(key string) string

GetString method returns the `string` value from session otherwise empty string.

func (*Session) IsKeyExists

func (s *Session) IsKeyExists(key string) bool

IsKeyExists method returns true if given key is exists in session object otherwise false.

func (*Session) Reset

func (s *Session) Reset()

Reset method resets the instance values for repurpose.

func (*Session) Set

func (s *Session) Set(key string, value interface{})

Set method set the value for the given key, if key already exists it updates the value.

Note: For any complex/custom structure you would like to store in session. Please register those types using `gob.Register(...)`.

func (*Session) SetFlash

func (s *Session) SetFlash(key string, value interface{})

SetFlash method adds flash message into session object.

func (Session) String

func (s Session) String() string

String method is stringer interface implementation.

type Storer

type Storer interface {
	Init(appCfg *config.Config) error
	Read(id string) string
	Save(id, value string) error
	Delete(id string) error
	IsExists(id string) bool
	Cleanup(m *Manager)
}

Storer is interface for implementing pluggable storage implementation.