Documentation
¶
Overview ¶
Package session provides tooling for storing of user session data in cookies for handling user sessions. This package provides some boilerplate around the gorilla/sessions package to provide some common functionality that is typically reused in web apps.
Data stored in a sessions is stored in a cookie. The cookie data is encrypted and hashed to prevent tampering and viewing of the data client side. This data can be read, altered, and added to as needed on the server side using this package. While gorilla/sessions allows for alternative "stores", ex.: storing sessions on disk, we only support cookies since this is typically how sessions are handled.
To use, you will need to initialize your session store using NewConfig() or DefaultConfig() and then call Init(). Once this has been done, you can get a session for a request using GetSession(), add data to the session using AddValue(), and read data from the session in subsequent requests using GetValue().
We allow storing the session config globally using the package-level config variable, or you can store your Config elsewhere and pass it to requests. Most use cases will store the config in the package-level config variable just for ease of use.
Index ¶
- Variables
- func AddSessionID(w http.ResponseWriter, r *http.Request, value int64) error
- func AddToken(w http.ResponseWriter, r *http.Request, value string) error
- func AddUserID(w http.ResponseWriter, r *http.Request, value int64) error
- func AddUsername(w http.ResponseWriter, r *http.Request, value string) error
- func AddValue(w http.ResponseWriter, r *http.Request, key, value string) (err error)
- func CookieName(cookieName string)
- func DefaultConfig()
- func Destroy(w http.ResponseWriter, r *http.Request) (err error)
- func Domain(domain string)
- func Extend(w http.ResponseWriter, r *http.Request) (err error)
- func GetSession(r *http.Request) (*sessions.Session, error)
- func GetSessionID(r *http.Request) (value int64, err error)
- func GetToken(r *http.Request) (value string, err error)
- func GetUserID(r *http.Request) (value int64, err error)
- func GetUsername(r *http.Request) (value string, err error)
- func GetValue(r *http.Request, key string) (value string, err error)
- func HTTPOnly(yes bool)
- func Init() (err error)
- func Keys(authKey, encryptkey string)
- func MaxAge(maxAge time.Duration)
- func Path(path string)
- func SameSite(sameSite http.SameSite)
- func Secure(yes bool)
- type Config
- func (c *Config) AddSessionID(w http.ResponseWriter, r *http.Request, value int64) error
- func (c *Config) AddToken(w http.ResponseWriter, r *http.Request, value string) error
- func (c *Config) AddUserID(w http.ResponseWriter, r *http.Request, value int64) error
- func (c *Config) AddUsername(w http.ResponseWriter, r *http.Request, value string) error
- func (c *Config) AddValue(w http.ResponseWriter, r *http.Request, key, value string) (err error)
- func (c *Config) Destroy(w http.ResponseWriter, r *http.Request) (err error)
- func (c *Config) Extend(w http.ResponseWriter, r *http.Request) (err error)
- func (c *Config) GetAllValues(r *http.Request) (kv map[string]string, err error)
- func (c *Config) GetSession(r *http.Request) (*sessions.Session, error)
- func (c *Config) GetSessionID(r *http.Request) (value int64, err error)
- func (c *Config) GetToken(r *http.Request) (value string, err error)
- func (c *Config) GetUserID(r *http.Request) (value int64, err error)
- func (c *Config) GetUsername(r *http.Request) (value string, err error)
- func (c *Config) GetValue(r *http.Request, key string) (value string, err error)
- func (c *Config) Init() (err error)
Constants ¶
This section is empty.
Variables ¶
var ( //ErrAuthKeyWrongSize is returned when user provided an AuthKey value that isn't 64 characters. ErrAuthKeyWrongSize = errors.New("session: auth key is invalid, must be exactly 64 characters") //ErrEncyptKeyWrongSize is returned when user provided an EncryptKey value that isn't 32 characters. ErrEncyptKeyWrongSize = errors.New("session: encrypt key is invalid, must be exactly 32 characters") //ErrLifetimeTooShort is returned when user provided a MaxAge value less that 1 second. ErrMaxAgeTooShort = errors.New("session: max age is invalid, must be greater than 1 second") //ErrKeyNotFound is returned when a desired key is not found in the session. ErrKeyNotFound = errors.New("session: key not found in session data") )
errors
Functions ¶
func AddSessionID ¶
AddSessionID adds the session ID value to the session using the session ID key and the default package level config. We assume session IDs are provided as integers.
func AddToken ¶
AddToken adds the token value to the session using the token key and the default package level config. We assume user IDs are provided as integers.
func AddUserID ¶
AddUserID adds the user ID value to the session using the user ID key and the default package level config. We assume user IDs are provided as integers.
func AddUsername ¶
AddUsername adds the username value to the session using the username key and the default package level config.
func CookieName ¶
func CookieName(cookieName string)
CookieName sets the CookieName field on the package level config.
func DefaultConfig ¶
func DefaultConfig()
DefaultConfig initializes the package level config with some defaults set. This wraps NewConfig() and saves the config to the package.
func Destroy ¶
func Destroy(w http.ResponseWriter, r *http.Request) (err error)
Destroy deletes a session using the default package level config.
func Extend ¶
func Extend(w http.ResponseWriter, r *http.Request) (err error)
Extend handles expiration for sessions using the package level config.
func GetSession ¶
GetSession returns the session using the default package level config.
func GetSessionID ¶
GetSessionID looks up the sessionID key from the session using the default package level confing.
func GetToken ¶
GetToken looks up the token key from the session using the default package level confing.
func GetUserID ¶
GetUserID looks up the userID key from the session using the default package level confing.
func GetUsername ¶
GetUsername looks up the username key from the session using the default package level config.
func GetValue ¶
GetValue retrieves a value for a key in the session using the default package level config.
func HTTPOnly ¶
func HTTPOnly(yes bool)
HTTPOnly sets the HTTPOnly field on the package level config.
func Init ¶
func Init() (err error)
Init initializes the session using the defaul package level config.
func Keys ¶
func Keys(authKey, encryptkey string)
Keys sets the AuthKey and EncryptKey fields on the package level config.
Types ¶
type Config ¶
type Config struct { //Domain is the domain to serve the cookie under. The default is ".". Domain string //Path is the path off the domain to serve the cookie under. The default is "/" //so that the cookie is served on any path for the domain. Path string //MaxAge is the time until the session cookie will expire. MaxAge time.Duration //HTTPOnly stops client side scripts form having access to the cookie. The default //value is true. There really is not need for client side scripts to access the cookie //since it will be encrypted anyway. HTTPOnly bool //Secure sets the cookie that stores the session data to only be served over HTTPS. //The default value is false since we want to support HTTP requests as well. Secure bool //SameSite sets the SameSite value for the cookie to reduce leaking information during //requests. This is a privacy setting. The default is http.SameSiteStrictMode. SameSite http.SameSite //CookieName is the name of the cookie used for storing session data. The default is //"session_cookie". CookieName string //AuthKey is a 64 character long string used for authenticating the cookie stored value. //If this is not provided, a random value is assigned upon app start up. AuthKey string //EncryptKey is a 32 character long string used for encrypting the cookie stored value. If //this is not provided, a random value is assigned upon app start up. This makes the cookie //stored value unusable by anthing (i.e: client side scripts) other than your app. EncryptKey string // contains filtered or unexported fields }
Config is the set of configuration settings for working with templates.
func GetConfig ¶
func GetConfig() (c *Config)
GetConfig returns the current state of the package level config.
func NewConfig ¶
func NewConfig() *Config
NewConfig returns a config for managing your session setup with some defaults set.
func (*Config) AddSessionID ¶
AddSessionID adds the session ID value to the session using the session ID key. We assume session IDs are provided as integers.
func (*Config) AddToken ¶
AddToken adds the token value to the session using the token key. We assume user IDs are provided as integers.
func (*Config) AddUserID ¶
AddUserID adds the user ID value to the session using the user ID key. We assume user IDs are provided as integers.
func (*Config) AddUsername ¶
AddUsername adds the username value to the session using the username key.
func (*Config) Destroy ¶
Destroy delete a session for a request. This is typically used when you log a user out.
func (*Config) Extend ¶
Extend extends the expiration of a session and cookie. This is typically used for keeping a used logged in by reseting the expiration each time a user visits a page.
func (*Config) GetAllValues ¶
GetAllValues retrieves all key value pairs stored in the session.
func (*Config) GetSession ¶
GetSession returns an existing session for a request or a new session if none existed. The field IsNew of the returned sessions.Session will be true if session was just created.
func (*Config) GetSessionID ¶
GetSessionID looks up the sessionID key from the session. We assume session IDs are integers and try to convert the value stored in the session accordingly.
func (*Config) GetUserID ¶
GetUserID looks up the userID key from the session. We assume user IDs are integers and try to convert the value stored in the session accordingly.
func (*Config) GetUsername ¶
GetUsername looks up the username key from the session.