Documentation ¶
Index ¶
- type Codec
- type CtxStore
- type GobCodec
- type IterableCtxStore
- type IterableStore
- type Sessiondeprecated
- type SessionCookie
- type SessionManager
- func (s *SessionManager) Clear(ctx context.Context) error
- func (s *SessionManager) Commit(ctx context.Context) (string, time.Time, error)
- func (s *SessionManager) Deadline(ctx context.Context) time.Time
- func (s *SessionManager) Destroy(ctx context.Context) error
- func (s *SessionManager) Exists(ctx context.Context, key string) bool
- func (s *SessionManager) Get(ctx context.Context, key string) interface{}
- func (s *SessionManager) GetBool(ctx context.Context, key string) bool
- func (s *SessionManager) GetBytes(ctx context.Context, key string) []byte
- func (s *SessionManager) GetFloat(ctx context.Context, key string) float64
- func (s *SessionManager) GetInt(ctx context.Context, key string) int
- func (s *SessionManager) GetInt32(ctx context.Context, key string) int32
- func (s *SessionManager) GetInt64(ctx context.Context, key string) int64
- func (s *SessionManager) GetString(ctx context.Context, key string) string
- func (s *SessionManager) GetTime(ctx context.Context, key string) time.Time
- func (s *SessionManager) Iterate(ctx context.Context, fn func(context.Context) error) error
- func (s *SessionManager) Keys(ctx context.Context) []string
- func (s *SessionManager) Load(ctx context.Context, token string) (context.Context, error)
- func (s *SessionManager) LoadAndSave(next http.Handler) http.Handler
- func (s *SessionManager) MergeSession(ctx context.Context, token string) error
- func (s *SessionManager) Pop(ctx context.Context, key string) interface{}
- func (s *SessionManager) PopBool(ctx context.Context, key string) bool
- func (s *SessionManager) PopBytes(ctx context.Context, key string) []byte
- func (s *SessionManager) PopFloat(ctx context.Context, key string) float64
- func (s *SessionManager) PopInt(ctx context.Context, key string) int
- func (s *SessionManager) PopString(ctx context.Context, key string) string
- func (s *SessionManager) PopTime(ctx context.Context, key string) time.Time
- func (s *SessionManager) Put(ctx context.Context, key string, val interface{})
- func (s *SessionManager) RememberMe(ctx context.Context, val bool)
- func (s *SessionManager) Remove(ctx context.Context, key string)
- func (s *SessionManager) RenewToken(ctx context.Context) error
- func (s *SessionManager) SetDeadline(ctx context.Context, expire time.Time)
- func (s *SessionManager) Status(ctx context.Context) Status
- func (s *SessionManager) Token(ctx context.Context) string
- func (s *SessionManager) WriteSessionCookie(ctx context.Context, w http.ResponseWriter, token string, expiry time.Time)
- type Status
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Codec ¶ added in v2.2.0
type Codec interface { Encode(deadline time.Time, values map[string]interface{}) ([]byte, error) Decode([]byte) (deadline time.Time, values map[string]interface{}, err error) }
Codec is the interface for encoding/decoding session data to and from a byte slice for use by the session store.
type CtxStore ¶ added in v2.5.0
type CtxStore interface { Store // DeleteCtx is the same as Store.Delete, except it takes a context.Context. DeleteCtx(ctx context.Context, token string) (err error) // FindCtx is the same as Store.Find, except it takes a context.Context. FindCtx(ctx context.Context, token string) (b []byte, found bool, err error) // CommitCtx is the same as Store.Commit, except it takes a context.Context. CommitCtx(ctx context.Context, token string, b []byte, expiry time.Time) (err error) }
CtxStore is an interface for session stores which take a context.Context parameter.
type GobCodec ¶ added in v2.3.1
type GobCodec struct{}
GobCodec is used for encoding/decoding session data to and from a byte slice using the encoding/gob package.
type IterableCtxStore ¶ added in v2.5.0
type IterableCtxStore interface { // AllCtx is the same as IterableStore.All, expect it takes a // context.Context. AllCtx(ctx context.Context) (map[string][]byte, error) }
IterableCtxStore is the interface for session stores which support iteration and which take a context.Context parameter.
type IterableStore ¶ added in v2.5.0
type IterableStore interface { // All should return a map containing data for all active sessions (i.e. // sessions which have not expired). The map key should be the session // token and the map value should be the session data. If no active // sessions exist this should return an empty (not nil) map. All() (map[string][]byte, error) }
IterableStore is the interface for session stores which support iteration.
type Session
deprecated
type Session = SessionManager
Deprecated: Session is a backwards-compatible alias for SessionManager.
type SessionCookie ¶
type SessionCookie struct { // Name sets the name of the session cookie. It should not contain // whitespace, commas, colons, semicolons, backslashes, the equals sign or // control characters as per RFC6265. The default cookie name is "session". // If your application uses two different sessions, you must make sure that // the cookie name for each is unique. Name string // Domain sets the 'Domain' attribute on the session cookie. By default // it will be set to the domain name that the cookie was issued from. Domain string // HttpOnly sets the 'HttpOnly' attribute on the session cookie. The // default value is true. HttpOnly bool // Path sets the 'Path' attribute on the session cookie. The default value // is "/". Passing the empty string "" will result in it being set to the // path that the cookie was issued from. Path string // Persist sets whether the session cookie should be persistent or not // (i.e. whether it should be retained after a user closes their browser). // The default value is true, which means that the session cookie will not // be destroyed when the user closes their browser and the appropriate // 'Expires' and 'MaxAge' values will be added to the session cookie. If you // want to only persist some sessions (rather than all of them), then set this // to false and call the RememberMe() method for the specific sessions that you // want to persist. Persist bool // SameSite controls the value of the 'SameSite' attribute on the session // cookie. By default this is set to 'SameSite=Lax'. If you want no SameSite // attribute or value in the session cookie then you should set this to 0. SameSite http.SameSite // Secure sets the 'Secure' attribute on the session cookie. The default // value is false. It's recommended that you set this to true and serve all // requests over HTTPS in production environments. // See https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Session_Management_Cheat_Sheet.md#transport-layer-security. Secure bool }
SessionCookie contains the configuration settings for session cookies.
type SessionManager ¶ added in v2.1.0
type SessionManager struct { // IdleTimeout controls the maximum length of time a session can be inactive // before it expires. For example, some applications may wish to set this so // there is a timeout after 20 minutes of inactivity. By default IdleTimeout // is not set and there is no inactivity timeout. IdleTimeout time.Duration // Lifetime controls the maximum length of time that a session is valid for // before it expires. The lifetime is an 'absolute expiry' which is set when // the session is first created and does not change. The default value is 24 // hours. Lifetime time.Duration // Store controls the session store where the session data is persisted. Store Store // Cookie contains the configuration settings for session cookies. Cookie SessionCookie // Codec controls the encoder/decoder used to transform session data to a // byte slice for use by the session store. By default session data is // encoded/decoded using encoding/gob. Codec Codec // ErrorFunc allows you to control behavior when an error is encountered by // the LoadAndSave middleware. The default behavior is for a HTTP 500 // "Internal Server Error" message to be sent to the client and the error // logged using Go's standard logger. If a custom ErrorFunc is set, then // control will be passed to this instead. A typical use would be to provide // a function which logs the error and returns a customized HTML error page. ErrorFunc func(http.ResponseWriter, *http.Request, error) // HashTokenInStore controls whether or not to store the session token or a hashed version in the store. HashTokenInStore bool // contains filtered or unexported fields }
SessionManager holds the configuration settings for your sessions.
func New ¶ added in v2.1.0
func New() *SessionManager
New returns a new session manager with the default options. It is safe for concurrent use.
func NewSession
deprecated
func NewSession() *SessionManager
Deprecated: NewSession is a backwards-compatible alias for New. Use the New function instead.
func (*SessionManager) Clear ¶ added in v2.1.0
func (s *SessionManager) Clear(ctx context.Context) error
Clear removes all data for the current session. The session token and lifetime are unaffected. If there is no data in the current session this is a no-op.
func (*SessionManager) Commit ¶ added in v2.1.0
Commit saves the session data to the session store and returns the session token and expiry time.
Most applications will use the LoadAndSave() middleware and will not need to use this method.
func (*SessionManager) Deadline ¶ added in v2.5.0
func (s *SessionManager) Deadline(ctx context.Context) time.Time
Deadline returns the 'absolute' expiry time for the session. Please note that if you are using an idle timeout, it is possible that a session will expire due to non-use before the returned deadline.
func (*SessionManager) Destroy ¶ added in v2.1.0
func (s *SessionManager) Destroy(ctx context.Context) error
Destroy deletes the session data from the session store and sets the session status to Destroyed. Any further operations in the same request cycle will result in a new session being created.
func (*SessionManager) Exists ¶ added in v2.1.0
func (s *SessionManager) Exists(ctx context.Context, key string) bool
Exists returns true if the given key is present in the session data.
func (*SessionManager) Get ¶ added in v2.1.0
func (s *SessionManager) Get(ctx context.Context, key string) interface{}
Get returns the value for a given key from the session data. The return value has the type interface{} so will usually need to be type asserted before you can use it. For example:
foo, ok := session.Get(r, "foo").(string) if !ok { return errors.New("type assertion to string failed") }
Also see the GetString(), GetInt(), GetBytes() and other helper methods which wrap the type conversion for common types.
func (*SessionManager) GetBool ¶ added in v2.1.0
func (s *SessionManager) GetBool(ctx context.Context, key string) bool
GetBool returns the bool value for a given key from the session data. The zero value for a bool (false) is returned if the key does not exist or the value could not be type asserted to a bool.
func (*SessionManager) GetBytes ¶ added in v2.1.0
func (s *SessionManager) GetBytes(ctx context.Context, key string) []byte
GetBytes returns the byte slice ([]byte) value for a given key from the session data. The zero value for a slice (nil) is returned if the key does not exist or could not be type asserted to []byte.
func (*SessionManager) GetFloat ¶ added in v2.1.0
func (s *SessionManager) GetFloat(ctx context.Context, key string) float64
GetFloat returns the float64 value for a given key from the session data. The zero value for an float64 (0) is returned if the key does not exist or the value could not be type asserted to a float64.
func (*SessionManager) GetInt ¶ added in v2.1.0
func (s *SessionManager) GetInt(ctx context.Context, key string) int
GetInt returns the int value for a given key from the session data. The zero value for an int (0) is returned if the key does not exist or the value could not be type asserted to an int.
func (*SessionManager) GetInt32 ¶ added in v2.5.0
func (s *SessionManager) GetInt32(ctx context.Context, key string) int32
GetInt32 returns the int value for a given key from the session data. The zero value for an int32 (0) is returned if the key does not exist or the value could not be type asserted to an int32.
func (*SessionManager) GetInt64 ¶ added in v2.5.0
func (s *SessionManager) GetInt64(ctx context.Context, key string) int64
GetInt64 returns the int64 value for a given key from the session data. The zero value for an int64 (0) is returned if the key does not exist or the value could not be type asserted to an int64.
func (*SessionManager) GetString ¶ added in v2.1.0
func (s *SessionManager) GetString(ctx context.Context, key string) string
GetString returns the string value for a given key from the session data. The zero value for a string ("") is returned if the key does not exist or the value could not be type asserted to a string.
func (*SessionManager) GetTime ¶ added in v2.1.0
GetTime returns the time.Time value for a given key from the session data. The zero value for a time.Time object is returned if the key does not exist or the value could not be type asserted to a time.Time. This can be tested with the time.IsZero() method.
func (*SessionManager) Iterate ¶ added in v2.5.0
Iterate retrieves all active (i.e. not expired) sessions from the store and executes the provided function fn for each session. If the session store being used does not support iteration then Iterate will panic.
func (*SessionManager) Keys ¶ added in v2.1.0
func (s *SessionManager) Keys(ctx context.Context) []string
Keys returns a slice of all key names present in the session data, sorted alphabetically. If the data contains no data then an empty slice will be returned.
func (*SessionManager) Load ¶ added in v2.1.0
Load retrieves the session data for the given token from the session store, and returns a new context.Context containing the session data. If no matching token is found then this will create a new session.
Most applications will use the LoadAndSave() middleware and will not need to use this method.
func (*SessionManager) LoadAndSave ¶ added in v2.1.0
func (s *SessionManager) LoadAndSave(next http.Handler) http.Handler
LoadAndSave provides middleware which automatically loads and saves session data for the current request, and communicates the session token to and from the client in a cookie.
func (*SessionManager) MergeSession ¶ added in v2.5.0
func (s *SessionManager) MergeSession(ctx context.Context, token string) error
MergeSession is used to merge in data from a different session in case strict session tokens are lost across an oauth or similar redirect flows. Use Clear() if no values of the new session are to be used.
func (*SessionManager) Pop ¶ added in v2.1.0
func (s *SessionManager) Pop(ctx context.Context, key string) interface{}
Pop acts like a one-time Get. It returns the value for a given key from the session data and deletes the key and value from the session data. The session data status will be set to Modified. The return value has the type interface{} so will usually need to be type asserted before you can use it.
func (*SessionManager) PopBool ¶ added in v2.1.0
func (s *SessionManager) PopBool(ctx context.Context, key string) bool
PopBool returns the bool value for a given key and then deletes it from the session data. The session data status will be set to Modified. The zero value for a bool (false) is returned if the key does not exist or the value could not be type asserted to a bool.
func (*SessionManager) PopBytes ¶ added in v2.1.0
func (s *SessionManager) PopBytes(ctx context.Context, key string) []byte
PopBytes returns the byte slice ([]byte) value for a given key and then deletes it from the from the session data. The session data status will be set to Modified. The zero value for a slice (nil) is returned if the key does not exist or could not be type asserted to []byte.
func (*SessionManager) PopFloat ¶ added in v2.1.0
func (s *SessionManager) PopFloat(ctx context.Context, key string) float64
PopFloat returns the float64 value for a given key and then deletes it from the session data. The session data status will be set to Modified. The zero value for an float64 (0) is returned if the key does not exist or the value could not be type asserted to a float64.
func (*SessionManager) PopInt ¶ added in v2.1.0
func (s *SessionManager) PopInt(ctx context.Context, key string) int
PopInt returns the int value for a given key and then deletes it from the session data. The session data status will be set to Modified. The zero value for an int (0) is returned if the key does not exist or the value could not be type asserted to an int.
func (*SessionManager) PopString ¶ added in v2.1.0
func (s *SessionManager) PopString(ctx context.Context, key string) string
PopString returns the string value for a given key and then deletes it from the session data. The session data status will be set to Modified. The zero value for a string ("") is returned if the key does not exist or the value could not be type asserted to a string.
func (*SessionManager) PopTime ¶ added in v2.1.0
PopTime returns the time.Time value for a given key and then deletes it from the session data. The session data status will be set to Modified. The zero value for a time.Time object is returned if the key does not exist or the value could not be type asserted to a time.Time.
func (*SessionManager) Put ¶ added in v2.1.0
func (s *SessionManager) Put(ctx context.Context, key string, val interface{})
Put adds a key and corresponding value to the session data. Any existing value for the key will be replaced. The session data status will be set to Modified.
func (*SessionManager) RememberMe ¶ added in v2.5.0
func (s *SessionManager) RememberMe(ctx context.Context, val bool)
RememberMe controls whether the session cookie is persistent (i.e whether it is retained after a user closes their browser). RememberMe only has an effect if you have set SessionManager.Cookie.Persist = false (the default is true) and you are using the standard LoadAndSave() middleware.
func (*SessionManager) Remove ¶ added in v2.1.0
func (s *SessionManager) Remove(ctx context.Context, key string)
Remove deletes the given key and corresponding value from the session data. The session data status will be set to Modified. If the key is not present this operation is a no-op.
func (*SessionManager) RenewToken ¶ added in v2.1.0
func (s *SessionManager) RenewToken(ctx context.Context) error
RenewToken updates the session data to have a new session token while retaining the current session data. The session lifetime is also reset and the session data status will be set to Modified.
The old session token and accompanying data are deleted from the session store.
To mitigate the risk of session fixation attacks, it's important that you call RenewToken before making any changes to privilege levels (e.g. login and logout operations). See https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Session_Management_Cheat_Sheet.md#renew-the-session-id-after-any-privilege-level-change for additional information.
func (*SessionManager) SetDeadline ¶ added in v2.7.0
func (s *SessionManager) SetDeadline(ctx context.Context, expire time.Time)
SetDeadline updates the 'absolute' expiry time for the session. Please note that if you are using an idle timeout, it is possible that a session will expire due to non-use before the set deadline.
func (*SessionManager) Status ¶ added in v2.1.0
func (s *SessionManager) Status(ctx context.Context) Status
Status returns the current status of the session data.
func (*SessionManager) Token ¶ added in v2.5.0
func (s *SessionManager) Token(ctx context.Context) string
Token returns the session token. Please note that this will return the empty string "" if it is called before the session has been committed to the store.
func (*SessionManager) WriteSessionCookie ¶ added in v2.3.0
func (s *SessionManager) WriteSessionCookie(ctx context.Context, w http.ResponseWriter, token string, expiry time.Time)
WriteSessionCookie writes a cookie to the HTTP response with the provided token as the cookie value and expiry as the cookie expiry time. The expiry time will be included in the cookie only if the session is set to persist or has had RememberMe(true) called on it. If expiry is an empty time.Time struct (so that it's IsZero() method returns true) the cookie will be marked with a historical expiry time and negative max-age (so the browser deletes it).
Most applications will use the LoadAndSave() middleware and will not need to use this method.
type Status ¶
type Status int
Status represents the state of the session data during a request cycle.
const ( // Unmodified indicates that the session data hasn't been changed in the // current request cycle. Unmodified Status = iota // Modified indicates that the session data has been changed in the current // request cycle. Modified // Destroyed indicates that the session data has been destroyed in the // current request cycle. Destroyed )
type Store ¶
type Store interface { // Delete should remove the session token and corresponding data from the // session store. If the token does not exist then Delete should be a no-op // and return nil (not an error). Delete(token string) (err error) // Find should return the data for a session token from the store. If the // session token is not found or is expired, the found return value should // be false (and the err return value should be nil). Similarly, tampered // or malformed tokens should result in a found return value of false and a // nil err value. The err return value should be used for system errors only. Find(token string) (b []byte, found bool, err error) // Commit should add the session token and data to the store, with the given // expiry time. If the session token already exists, then the data and // expiry time should be overwritten. Commit(token string, b []byte, expiry time.Time) (err error) }
Store is the interface for session stores.