session

package
v2.3.4 Latest Latest
Warning

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

 Go to latest Published: Dec 8, 2024 License: Apache-2.0, Apache-2.0 Imports: 27 Imported by: 44

README

session

session is a Go session manager. It can use many session providers. Just like the database/sql and database/sql/driver.

How to install?

go get github.com/beego/beego/v2/server/web/session

What providers are supported?

As of now this session manager support memory, file, Redis and MySQL.

How to use it?

First you must import it

import (
	"github.com/beego/beego/v2/server/web/session"
)

Then in you web app init the global session manager

var globalSessions *session.Manager

  • Use memory as provider:

    func init() { globalSessions, _ = session.NewManager("memory", {"cookieName":"gosessionid","gclifetime":3600}) go globalSessions.GC() }

  • Use file as provider, the last param is the path where you want file to be stored:

    func init() { globalSessions, _ = session.NewManager("file",{"cookieName":"gosessionid","gclifetime":3600,"ProviderConfig":"./tmp"}) go globalSessions.GC() }

  • Use Redis as provider, the last param is the Redis conn address,poolsize,password:

    func init() { globalSessions, _ = session.NewManager("redis", {"cookieName":"gosessionid","gclifetime":3600,"ProviderConfig":"127.0.0.1:6379,100,astaxie"}) go globalSessions.GC() }

  • Use MySQL as provider, the last param is the DSN, learn more from mysql:

    func init() { globalSessions, _ = session.NewManager( "mysql", {"cookieName":"gosessionid","gclifetime":3600,"ProviderConfig":"username:password@protocol(address)/dbname?param=value"}) go globalSessions.GC() }

  • Use Cookie as provider:

    func init() { globalSessions, _ = session.NewManager( "cookie", {"cookieName":"gosessionid","enableSetCookie":false,"gclifetime":3600,"ProviderConfig":"{\"cookieName\":\"gosessionid\",\"securityKey\":\"beegocookiehashkey\"}"}) go globalSessions.GC() }

Finally in the handlerfunc you can use it like this

func login(w http.ResponseWriter, r *http.Request) {
	sess := globalSessions.SessionStart(w, r)
	defer sess.SessionRelease(w)
	username := sess.Get("username")
	fmt.Println(username)
	if r.Method == "GET" {
		t, _ := template.ParseFiles("login.gtpl")
		t.Execute(w, nil)
	} else {
		fmt.Println("username:", r.Form["username"])
		sess.Set("username", r.Form["username"])
		fmt.Println("password:", r.Form["password"])
	}
}

How to write own provider?

When you develop a web app, maybe you want to write own provider because you must meet the requirements.

Writing a provider is easy. You only need to define two struct types (Store and Provider), which satisfy the interface definition. Maybe you will find the memory provider is a good example.

// Store contains all data for one session process with specific id.
type Store interface {
    Set(ctx context.Context, key, value interface{}) error              // Set set session value
    Get(ctx context.Context, key interface{}) interface{}               // Get get session value
    Delete(ctx context.Context, key interface{}) error                  // Delete delete session value
    SessionID(ctx context.Context) string                               // SessionID return current sessionID
    SessionReleaseIfPresent(ctx context.Context, w http.ResponseWriter) // SessionReleaseIfPresent release the resource & save data to provider & return the data when the session is present, not all implementation support this feature, you need to check if the specific implementation if support this feature.
    SessionRelease(ctx context.Context, w http.ResponseWriter)          // SessionRelease release the resource & save data to provider & return the data
    Flush(ctx context.Context) error                                    // Flush delete all data
}

type Provider interface {
	SessionInit(gclifetime int64, config string) error
	SessionRead(sid string) (SessionStore, error)
	SessionExist(sid string) (bool, error)
	SessionRegenerate(oldsid, sid string) (SessionStore, error)
	SessionDestroy(sid string) error
	SessionAll() int //get all active session
	SessionGC()
}

LICENSE

BSD License http://creativecommons.org/licenses/BSD/

Documentation

Overview

Package session provider

Usage: import( 

"github.com/beego/beego/v2/server/web/session"

) 

	func init() {
     globalSessions, _ = session.NewManager("memory", `{"cookieName":"gosessionid", "enableSetCookie,omitempty": true, "gclifetime":3600, "maxLifetime": 3600, "secure": false, "cookieLifeTime": 3600, "providerConfig": ""}`)
		go globalSessions.GC()
	}

Index

Constants

This section is empty.

Variables

View Source 
var SLogger = NewSessionLog(os.Stderr)

SLogger a helpful variable to log information about session

Functions

func DecodeGob 

func DecodeGob(encoded []byte) (map[interface{}]interface{}, error)

DecodeGob decode data to map

func EncodeGob 

func EncodeGob(obj map[interface{}]interface{}) ([]byte, error)

EncodeGob encode the obj to gob

func Register 

func Register(name string, provide Provider)

Register makes a session provide available by the provided name. If provider is nil, it panic

Types

type CookieProvider 

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

CookieProvider Cookie session provider

func (*CookieProvider) SessionAll 

func (pder *CookieProvider) SessionAll(context.Context) int

SessionAll Implement method, return 0.

func (*CookieProvider) SessionDestroy 

func (pder *CookieProvider) SessionDestroy(ctx context.Context, sid string) error

SessionDestroy Implement method, no used.

func (*CookieProvider) SessionExist 

func (pder *CookieProvider) SessionExist(ctx context.Context, sid string) (bool, error)

SessionExist Cookie session is always existed

func (*CookieProvider) SessionGC 

func (pder *CookieProvider) SessionGC(context.Context)

SessionGC Implement method, no used.

func (*CookieProvider) SessionInit 

func (pder *CookieProvider) SessionInit(ctx context.Context, maxlifetime int64, config string) error

SessionInit Init cookie session provider with max lifetime and config json. maxlifetime is ignored. json config: 

securityKey - hash string
blockKey - gob encode hash string. it's saved as aes crypto.
securityName - recognized name in encoded cookie string
cookieName - cookie name
maxage - cookie max life time.

func (*CookieProvider) SessionRead 

func (pder *CookieProvider) SessionRead(ctx context.Context, sid string) (Store, error)

SessionRead Get SessionStore in cooke. decode cooke string to map and put into SessionStore with sid.

func (*CookieProvider) SessionRegenerate 

func (pder *CookieProvider) SessionRegenerate(ctx context.Context, oldsid, sid string) (Store, error)

SessionRegenerate Implement method, no used.

func (*CookieProvider) SessionUpdate 

func (pder *CookieProvider) SessionUpdate(ctx context.Context, sid string) error

SessionUpdate Implement method, no used.

type CookieSessionStore 

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

CookieSessionStore Cookie SessionStore

func (*CookieSessionStore) Delete 

func (st *CookieSessionStore) Delete(ctx context.Context, key interface{}) error

Delete value in cookie session

func (*CookieSessionStore) Flush 

func (st *CookieSessionStore) Flush(context.Context) error

Flush Clean all values in cookie session

func (*CookieSessionStore) Get 

func (st *CookieSessionStore) Get(ctx context.Context, key interface{}) interface{}

Get value from cookie session

func (*CookieSessionStore) SessionID 

func (st *CookieSessionStore) SessionID(context.Context) string

SessionID Return id of this cookie session

func (*CookieSessionStore) SessionRelease 

func (st *CookieSessionStore) SessionRelease(_ context.Context, w http.ResponseWriter)

SessionRelease Write cookie session to http response cookie

func (*CookieSessionStore) SessionReleaseIfPresent added in v2.3.0 

func (st *CookieSessionStore) SessionReleaseIfPresent(ctx context.Context, w http.ResponseWriter)

SessionReleaseIfPresent Write cookie session to http response cookie when it is present This is a no-op for cookie sessions, because they are always present.

func (*CookieSessionStore) Set 

func (st *CookieSessionStore) Set(ctx context.Context, key, value interface{}) error

Set value to cookie session. the value are encoded as gob with hash block string.

type FileProvider 

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

FileProvider File session provider

func (*FileProvider) SessionAll 

func (fp *FileProvider) SessionAll(context.Context) int

SessionAll Get active file session number. it walks save path to count files.

func (*FileProvider) SessionDestroy 

func (fp *FileProvider) SessionDestroy(ctx context.Context, sid string) error

SessionDestroy Remove all files in this save path

func (*FileProvider) SessionExist 

func (fp *FileProvider) SessionExist(ctx context.Context, sid string) (bool, error)

SessionExist Check file session exist. it checks the file named from sid exist or not.

func (*FileProvider) SessionGC 

func (fp *FileProvider) SessionGC(context.Context)

SessionGC Recycle files in save path

func (*FileProvider) SessionInit 

func (fp *FileProvider) SessionInit(ctx context.Context, maxlifetime int64, savePath string) error

SessionInit Init file session provider. savePath sets the session files path.

func (*FileProvider) SessionRead 

func (fp *FileProvider) SessionRead(ctx context.Context, sid string) (Store, error)

SessionRead Read file session by sid. if file is not exist, create it. the file path is generated from sid string.

func (*FileProvider) SessionRegenerate 

func (fp *FileProvider) SessionRegenerate(ctx context.Context, oldsid, sid string) (Store, error)

SessionRegenerate Generate new sid for file session. it deletes old file and create new file named from new sid.

type FileSessionStore 

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

FileSessionStore File session store

func (*FileSessionStore) Delete 

func (fs *FileSessionStore) Delete(ctx context.Context, key interface{}) error

Delete value in file session by given key

func (*FileSessionStore) Flush 

func (fs *FileSessionStore) Flush(context.Context) error

Flush Clean all values in file session

func (*FileSessionStore) Get 

func (fs *FileSessionStore) Get(ctx context.Context, key interface{}) interface{}

Get value from file session

func (*FileSessionStore) SessionID 

func (fs *FileSessionStore) SessionID(context.Context) string

SessionID Get file session store id

func (*FileSessionStore) SessionRelease 

func (fs *FileSessionStore) SessionRelease(ctx context.Context, w http.ResponseWriter)

SessionRelease Write file session to local file with Gob string

func (*FileSessionStore) SessionReleaseIfPresent added in v2.3.0 

func (fs *FileSessionStore) SessionReleaseIfPresent(ctx context.Context, w http.ResponseWriter)

SessionReleaseIfPresent Write file session to local file with Gob string when session exists

func (*FileSessionStore) Set 

func (fs *FileSessionStore) Set(ctx context.Context, key, value interface{}) error

Set value to file session

type Log 

type Log struct {
	*log.Logger
}

Log implement the log.Logger

func NewSessionLog 

func NewSessionLog(out io.Writer) *Log

NewSessionLog set io.Writer to create a Logger for session.

type Manager 

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

Manager contains Provider and its configuration.

func NewManager 

func NewManager(provideName string, cf *ManagerConfig) (*Manager, error)

NewManager Create new Manager with provider name and json config string. provider name: 1. cookie 2. file 3. memory 4. redis 5. mysql json config: 1. is https default false 2. hashfunc default sha1 3. hashkey default beegosessionkey 4. maxage default is none

func (*Manager) GC 

func (manager *Manager) GC()

GC Start session gc process. it can do gc in times after gc lifetime.

func (*Manager) GetActiveSession 

func (manager *Manager) GetActiveSession() int

GetActiveSession Get all active sessions count number.

func (*Manager) GetProvider 

func (manager *Manager) GetProvider() Provider

GetProvider return current manager's provider

func (*Manager) GetSessionStore 

func (manager *Manager) GetSessionStore(sid string) (sessions Store, err error)

GetSessionStore Get SessionStore by its id.

func (*Manager) SessionDestroy 

func (manager *Manager) SessionDestroy(w http.ResponseWriter, r *http.Request)

SessionDestroy Destroy session by its id in http request cookie.

func (*Manager) SessionRegenerateID 

func (manager *Manager) SessionRegenerateID(w http.ResponseWriter, r *http.Request) (Store, error)

SessionRegenerateID Regenerate a session id for this SessionStore whose id is saving in http request.

func (*Manager) SessionStart 

func (manager *Manager) SessionStart(w http.ResponseWriter, r *http.Request) (session Store, err error)

SessionStart generate or read the session id from http request. if session id exists, return SessionStore with this id.

func (*Manager) SetSecure 

func (manager *Manager) SetSecure(secure bool)

SetSecure Set cookie with https.

type ManagerConfig 

type ManagerConfig struct {
	EnableSetCookie         bool          `json:"enableSetCookie,omitempty"`
	DisableHTTPOnly         bool          `json:"disableHTTPOnly"`
	Secure                  bool          `json:"secure"`
	EnableSidInHTTPHeader   bool          `json:"EnableSidInHTTPHeader"`
	EnableSidInURLQuery     bool          `json:"EnableSidInURLQuery"`
	CookieName              string        `json:"cookieName"`
	Gclifetime              int64         `json:"gclifetime"`
	Maxlifetime             int64         `json:"maxLifetime"`
	CookieLifeTime          int           `json:"cookieLifeTime"`
	ProviderConfig          string        `json:"providerConfig"`
	Domain                  string        `json:"domain"`
	SessionIDLength         int64         `json:"sessionIDLength"`
	SessionNameInHTTPHeader string        `json:"SessionNameInHTTPHeader"`
	SessionIDPrefix         string        `json:"sessionIDPrefix"`
	CookieSameSite          http.SameSite `json:"cookieSameSite"`
}

ManagerConfig define the session config

func NewManagerConfig added in v2.0.2 

func NewManagerConfig(opts ...ManagerConfigOpt) *ManagerConfig

func (*ManagerConfig) Opts added in v2.0.2 

func (c *ManagerConfig) Opts(opts ...ManagerConfigOpt)

type ManagerConfigOpt added in v2.0.2 

type ManagerConfigOpt func(config *ManagerConfig)

func CfgCookieLifeTime added in v2.0.2 

func CfgCookieLifeTime(lifeTime int) ManagerConfigOpt

CfgCookieLifeTime set cookie lift time

func CfgCookieName added in v2.0.2 

func CfgCookieName(cookieName string) ManagerConfigOpt

CfgCookieName set key of session id

func CfgDomain added in v2.0.2 

func CfgDomain(domain string) ManagerConfigOpt

CfgDomain set cookie domain

func CfgEnableSidInURLQuery added in v2.0.2 

func CfgEnableSidInURLQuery(enable bool) ManagerConfigOpt

EnableSidInURLQuery enable session id in query string

func CfgGcLifeTime added in v2.0.2 

func CfgGcLifeTime(lifeTime int64) ManagerConfigOpt

CfgGcLifeTime set session gc lift time

func CfgHTTPOnly added in v2.0.2 

func CfgHTTPOnly(HTTPOnly bool) ManagerConfigOpt

DisableHTTPOnly set HTTPOnly for http.Cookie

func CfgMaxLifeTime added in v2.0.2 

func CfgMaxLifeTime(lifeTime int64) ManagerConfigOpt

CfgMaxLifeTime set session lift time

func CfgProviderConfig added in v2.0.2 

func CfgProviderConfig(providerConfig string) ManagerConfigOpt

CfgProviderConfig configure session provider

func CfgSameSite added in v2.0.2 

func CfgSameSite(sameSite http.SameSite) ManagerConfigOpt

CfgSameSite set http.SameSite

func CfgSecure added in v2.0.2 

func CfgSecure(Enable bool) ManagerConfigOpt

CfgSecure set Secure for http.Cookie

func CfgSessionIdInHTTPHeader added in v2.0.2 

func CfgSessionIdInHTTPHeader(enable bool) ManagerConfigOpt

CfgSessionIdInHTTPHeader enable session id in http header

func CfgSessionIdLength added in v2.0.2 

func CfgSessionIdLength(length int64) ManagerConfigOpt

CfgSessionIdLength set len of session id

func CfgSessionIdPrefix added in v2.0.2 

func CfgSessionIdPrefix(prefix string) ManagerConfigOpt

CfgSessionIdPrefix set prefix of session id

func CfgSetCookie added in v2.0.2 

func CfgSetCookie(enable bool) ManagerConfigOpt

CfgSetCookie whether set `Set-Cookie` header in HTTP response

func CfgSetSessionNameInHTTPHeader added in v2.0.2 

func CfgSetSessionNameInHTTPHeader(name string) ManagerConfigOpt

CfgSetSessionNameInHTTPHeader set key of session id in http header

type MemProvider 

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

MemProvider Implement the provider interface

func (*MemProvider) SessionAll 

func (pder *MemProvider) SessionAll(context.Context) int

SessionAll get count number of memory session

func (*MemProvider) SessionDestroy 

func (pder *MemProvider) SessionDestroy(ctx context.Context, sid string) error

SessionDestroy delete session store in memory session by id

func (*MemProvider) SessionExist 

func (pder *MemProvider) SessionExist(ctx context.Context, sid string) (bool, error)

SessionExist check session store exist in memory session by sid

func (*MemProvider) SessionGC 

func (pder *MemProvider) SessionGC(context.Context)

SessionGC clean expired session stores in memory session

func (*MemProvider) SessionInit 

func (pder *MemProvider) SessionInit(ctx context.Context, maxlifetime int64, savePath string) error

SessionInit init memory session

func (*MemProvider) SessionRead 

func (pder *MemProvider) SessionRead(ctx context.Context, sid string) (Store, error)

SessionRead get memory session store by sid

func (*MemProvider) SessionRegenerate 

func (pder *MemProvider) SessionRegenerate(ctx context.Context, oldsid, sid string) (Store, error)

SessionRegenerate generate new sid for session store in memory session

func (*MemProvider) SessionUpdate 

func (pder *MemProvider) SessionUpdate(ctx context.Context, sid string) error

SessionUpdate expand time of session store by id in memory session

type MemSessionStore 

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

MemSessionStore memory session store. it saved sessions in a map in memory.

func (*MemSessionStore) Delete 

func (st *MemSessionStore) Delete(ctx context.Context, key interface{}) error

Delete in memory session by key

func (*MemSessionStore) Flush 

func (st *MemSessionStore) Flush(context.Context) error

Flush clear all values in memory session

func (*MemSessionStore) Get 

func (st *MemSessionStore) Get(ctx context.Context, key interface{}) interface{}

Get value from memory session by key

func (*MemSessionStore) SessionID 

func (st *MemSessionStore) SessionID(context.Context) string

SessionID get this id of memory session store

func (*MemSessionStore) SessionRelease 

func (st *MemSessionStore) SessionRelease(_ context.Context, _ http.ResponseWriter)

SessionRelease Implement method, no used.

func (*MemSessionStore) SessionReleaseIfPresent added in v2.3.0 

func (*MemSessionStore) SessionReleaseIfPresent(_ context.Context, _ http.ResponseWriter)

SessionReleaseIfPresent Implement method, no used.

func (*MemSessionStore) Set 

func (st *MemSessionStore) Set(ctx context.Context, key, value interface{}) error

Set value to memory session

type Provider 

type Provider interface {
	SessionInit(ctx context.Context, gclifetime int64, config string) error
	SessionRead(ctx context.Context, sid string) (Store, error)
	SessionExist(ctx context.Context, sid string) (bool, error)
	SessionRegenerate(ctx context.Context, oldsid, sid string) (Store, error)
	SessionDestroy(ctx context.Context, sid string) error
	SessionAll(ctx context.Context) int // get all active session
	SessionGC(ctx context.Context)
}

Provider contains global session methods and saved SessionStores. it can operate a SessionStore by its id.

func GetProvider 

func GetProvider(name string) (Provider, error)

GetProvider

type ProviderType added in v2.0.2 

type ProviderType string
const (
	ProviderCookie        ProviderType = `cookie`
	ProviderFile          ProviderType = `file`
	ProviderMemory        ProviderType = `memory`
	ProviderCouchbase     ProviderType = `couchbase`
	ProviderLedis         ProviderType = `ledis`
	ProviderMemcache      ProviderType = `memcache`
	ProviderMysql         ProviderType = `mysql`
	ProviderPostgresql    ProviderType = `postgresql`
	ProviderRedis         ProviderType = `redis`
	ProviderRedisCluster  ProviderType = `redis_cluster`
	ProviderRedisSentinel ProviderType = `redis_sentinel`
	ProviderSsdb          ProviderType = `ssdb`
)

type Store 

type Store interface {
	Set(ctx context.Context, key, value interface{}) error              // Set set session value
	Get(ctx context.Context, key interface{}) interface{}               // Get get session value
	Delete(ctx context.Context, key interface{}) error                  // Delete delete session value
	SessionID(ctx context.Context) string                               // SessionID return current sessionID
	SessionReleaseIfPresent(ctx context.Context, w http.ResponseWriter) // SessionReleaseIfPresent release the resource & save data to provider & return the data when the session is present, not all implementation support this feature, you need to check if the specific implementation if support this feature.
	SessionRelease(ctx context.Context, w http.ResponseWriter)          // SessionRelease release the resource & save data to provider & return the data
	Flush(ctx context.Context) error                                    // Flush delete all data
}

Store contains all data for one session process with specific id.

Source Files

View all Source files

Directories

Path Synopsis
Package couchbase for session provider
 Package couchbase for session provider
Package ledis provide session Provider
 Package ledis provide session Provider
Package memcache for session provider
 Package memcache for session provider
Package mysql for session provider
 Package mysql for session provider
Package postgres for session provider
 Package postgres for session provider
Package redis for session provider
 Package redis for session provider
Package redis for session provider
 Package redis for session provider
Package redis for session provider
 Package redis for session provider

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.