sessions

package
v1.6.1 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2020 License: BSD-3-Clause, BSD-3-Clause Imports: 12 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	// DefaultCookieName the secret cookie's name for sessions
	DefaultCookieName = "irissessionid"
)

Variables

View Source 
var (
	// CookieExpireDelete may be set on Cookie.Expire for expiring the given cookie.
	CookieExpireDelete = time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)

	// CookieExpireUnlimited indicates that the cookie doesn't expire.
	CookieExpireUnlimited = time.Now().AddDate(24, 10, 10)
)

Functions

func AddCookie 

func AddCookie(ctx context.Context, cookie *http.Cookie, reclaim bool)

AddCookie adds a cookie

func GetCookie 

func GetCookie(ctx context.Context, name string) string

GetCookie returns cookie's value by it's name returns empty string if nothing was found

func IsValidCookieDomain 

func IsValidCookieDomain(domain string) bool

IsValidCookieDomain returns true if the receiver is a valid domain to set valid means that is recognised as 'domain' by the browser, so it(the cookie) can be shared with subdomains also

func RemoveCookie 

func RemoveCookie(ctx context.Context, name string, purge bool)

RemoveCookie deletes a cookie by it's name/key If "purge" is true then it removes the, temp, cookie from the request as well.

Types

type Action 

type Action uint32

Action reports the specific action that the memory store sends to the database. 

const (
	// ActionCreate occurs when add a key-value pair
	// on the database session entry for the first time.
	ActionCreate Action = iota
	// ActionInsert occurs when add a key-value pair
	// on the database session entry.
	ActionInsert
	// ActionUpdate occurs when modify an existing key-value pair
	// on the database session entry.
	ActionUpdate
	// ActionDelete occurs when delete a specific value from
	// a specific key from the database session entry.
	ActionDelete
	// ActionClear occurs when clear all values but keep the database session entry.
	ActionClear
	// ActionDestroy occurs when destroy,
	// destroy is the action when clear all and remove the session entry from the database.
	ActionDestroy
)

type Config 

type Config struct {
	// Cookie string, the session's client cookie name, for example: "mysessionid"
	//
	// Defaults to "irissessionid".
	Cookie string

	// CookieSecureTLS set to true if server is running over TLS
	// and you need the session's cookie "Secure" field to be setted true.
	//
	// Note: The user should fill the Decode configuation field in order for this to work.
	// Recommendation: You don't need this to be setted to true, just fill the Encode and Decode fields
	// with a third-party library like secure cookie, example is provided at the _examples folder.
	//
	// Defaults to false.
	CookieSecureTLS bool

	// AllowReclaim will allow to
	// Destroy and Start a session in the same request handler.
	// All it does is that it removes the cookie for both `Request` and `ResponseWriter` while `Destroy`
	// or add a new cookie to `Request` while `Start`.
	//
	// Defaults to false.
	AllowReclaim bool

	// Encode the cookie value if not nil.
	// Should accept as first argument the cookie name (config.Cookie)
	//         as second argument the server's generated session id.
	// Should return the new session id, if error the session id setted to empty which is invalid.
	//
	// Note: Errors are not printed, so you have to know what you're doing,
	// and remember: if you use AES it only supports key sizes of 16, 24 or 32 bytes.
	// You either need to provide exactly that amount or you derive the key from what you type in.
	//
	// Defaults to nil.
	Encode func(cookieName string, value interface{}) (string, error)
	// Decode the cookie value if not nil.
	// Should accept as first argument the cookie name (config.Cookie)
	//               as second second accepts the client's cookie value (the encoded session id).
	// Should return an error if decode operation failed.
	//
	// Note: Errors are not printed, so you have to know what you're doing,
	// and remember: if you use AES it only supports key sizes of 16, 24 or 32 bytes.
	// You either need to provide exactly that amount or you derive the key from what you type in.
	//
	// Defaults to nil.
	Decode func(cookieName string, cookieValue string, v interface{}) error

	// Encoding same as Encode and Decode but receives a single instance which
	// completes the "CookieEncoder" interface, `Encode` and `Decode` functions.
	//
	// Defaults to nil.
	Encoding Encoding

	// Expires the duration of which the cookie must expires (created_time.Add(Expires)).
	// If you want to delete the cookie when the browser closes, set it to -1.
	//
	// 0 means no expire, (24 years)
	// -1 means when browser closes
	// > 0 is the time.Duration which the session cookies should expire.
	//
	// Defaults to infinitive/unlimited life duration(0).
	Expires time.Duration

	// SessionIDGenerator should returns a random session id.
	// By default we will use a uuid impl package to generate
	// that, but developers can change that with simple assignment.
	SessionIDGenerator func() string

	// DisableSubdomainPersistence set it to true in order dissallow your subdomains to have access to the session cookie
	//
	// Defaults to false.
	DisableSubdomainPersistence bool
}

Config is the configuration for sessions. Please read it before using sessions.

func (Config) Validate 

func (c Config) Validate() Config

Validate corrects missing fields configuration fields and returns the right configuration

type Database 

type Database interface {
	Load(sid string) RemoteStore
	Sync(p SyncPayload)
}

Database is the interface which all session databases should implement By design it doesn't support any type of cookie session like other frameworks. I want to protect you, believe me. The scope of the database is to store somewhere the sessions in order to keep them after restarting the server, nothing more.

Synchronization are made automatically, you can register more than one session database but the first non-empty Load return data will be used as the session values.

Note: Expiration on Load is up to the database, meaning that: the database can decide how to retrieve and parse the expiration datetime

I'll try to explain you the flow:

.Start -> if session database attached then load from that storage and save to the memory, otherwise load from memory. The load from database is done once on the initialize of each session. .Get (important) -> load from memory, 

if database attached then it already loaded the values
from database on the .Start action, so it will
retrieve the data from the memory (fast)

.Set -> set to the memory, if database attached then update the storage .Delete -> clear from memory, if database attached then update the storage .Destroy -> destroy from memory and client cookie, 

if database attached then update the storage with empty values,
empty values means delete the storage with that specific session id.

Using everything else except memory is slower than memory but database is fetched once at each session and its updated on every Set, Delete, Destroy at call-time. All other external sessions managers out there work different than Iris one as far as I know, you may find them more suited to your application, it depends.

type Encoding 

type Encoding interface {
	// Encode the cookie value if not nil.
	// Should accept as first argument the cookie name (config.Name)
	//         as second argument the server's generated session id.
	// Should return the new session id, if error the session id setted to empty which is invalid.
	//
	// Note: Errors are not printed, so you have to know what you're doing,
	// and remember: if you use AES it only supports key sizes of 16, 24 or 32 bytes.
	// You either need to provide exactly that amount or you derive the key from what you type in.
	//
	// Defaults to nil
	Encode(cookieName string, value interface{}) (string, error)
	// Decode the cookie value if not nil.
	// Should accept as first argument the cookie name (config.Name)
	//               as second second accepts the client's cookie value (the encoded session id).
	// Should return an error if decode operation failed.
	//
	// Note: Errors are not printed, so you have to know what you're doing,
	// and remember: if you use AES it only supports key sizes of 16, 24 or 32 bytes.
	// You either need to provide exactly that amount or you derive the key from what you type in.
	//
	// Defaults to nil
	Decode(cookieName string, cookieValue string, v interface{}) error
}

Encoding is the Cookie Encoder/Decoder interface, which can be passed as configuration field alternatively to the `Encode` and `Decode` fields.

type LifeTime 

type LifeTime struct {
	// Remember, tip for the future:
	// No need of gob.Register, because we embed the time.Time.
	// And serious bug which has a result of me spending my whole evening:
	// Because of gob encoding it doesn't encodes/decodes the other fields if time.Time is embedded
	// (this should be a bug(go1.9-rc1) or not. We don't care atm)
	time.Time
	// contains filtered or unexported fields
}

LifeTime controls the session expiration datetime.

func (*LifeTime) Begin 

func (lt *LifeTime) Begin(d time.Duration, onExpire func())

Begin will begin the life based on the time.Now().Add(d). Use `Continue` to continue from a stored time(database-based session does that).

func (*LifeTime) ExpireNow 

func (lt *LifeTime) ExpireNow()

ExpireNow reduce the lifetime completely.

func (*LifeTime) HasExpired 

func (lt *LifeTime) HasExpired() bool

HasExpired reports whether "lt" represents is expired.

func (*LifeTime) Revive 

func (lt *LifeTime) Revive(onExpire func())

Revive will continue the life based on the stored Time. Other words that could be used for this func are: Continue, Restore, Resc.

func (*LifeTime) Shift 

func (lt *LifeTime) Shift(d time.Duration)

Shift resets the lifetime based on "d".

type RemoteStore 

type RemoteStore struct {
	// Values contains the whole memory store, this store
	// contains the current, updated from memory calls,
	// session data (keys and values). This way
	// the database has access to the whole session's data
	// every time.
	Values memstore.Store
	// on insert it contains the expiration datetime
	// on update it contains the new expiration datetime(if updated or the old one)
	// on delete it will be zero
	// on clear it will be zero
	// on destroy it will be zero
	Lifetime LifeTime
}

RemoteStore is a helper which is a wrapper for the store, it can be used as the session "table" which will be saved to the session database.

func DecodeRemoteStore 

func DecodeRemoteStore(b []byte) (store RemoteStore, err error)

DecodeRemoteStore accepts a series of bytes and returns the store.

func (RemoteStore) Serialize 

func (s RemoteStore) Serialize() ([]byte, error)

Serialize returns the byte representation of this RemoteStore.

type Session 

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

Session should expose the Sessions's end-user API. It is the session's storage controller which you can save or retrieve values based on a key.

This is what will be returned when sess := sessions.Start().

func (*Session) Clear 

func (s *Session) Clear()

Clear removes all entries.

func (*Session) ClearFlashes 

func (s *Session) ClearFlashes()

ClearFlashes removes all flash messages.

func (*Session) Decrement added in v1.6.1 

func (s *Session) Decrement(key string, n int) (newValue int)

Decrement decrements the stored int value saved as "key" by -"n". If value doesn't exist on that "key" then it creates one with the "n" as its value. It returns the new, decremented, value even if it's less than zero.

func (*Session) Delete 

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

Delete removes an entry by its key, returns true if actually something was removed.

func (*Session) DeleteFlash 

func (s *Session) DeleteFlash(key string)

DeleteFlash removes a flash message by its key.

func (*Session) Destroy added in v1.6.1 

func (s *Session) Destroy()

Destroy destroys this session, it removes its session values and any flashes. This session entry will be removed from the server, the registered session databases will be notified for this deletion as well.

Note that this method does NOT remove the client's cookie, although it should be reseted if new session is attached to that (client).

Use the session's manager `Destroy(ctx)` in order to remove the cookie as well.

func (*Session) Get 

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

Get returns a value based on its "key".

func (*Session) GetAll 

func (s *Session) GetAll() map[string]interface{}

GetAll returns a copy of all session's values.

func (*Session) GetBoolean 

func (s *Session) GetBoolean(key string) (bool, error)

GetBoolean same as `Get` but returns its boolean representation, if key doesn't exist then it returns false.

func (*Session) GetBooleanDefault 

func (s *Session) GetBooleanDefault(key string, defaultValue bool) (bool, error)

GetBooleanDefault same as `Get` but returns its boolean representation, if key doesn't exist then it returns the "defaultValue".

func (*Session) GetFlash 

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

GetFlash returns a stored flash message based on its "key" which will be removed on the next request.

To check for flash messages we use the HasFlash() Method and to obtain the flash message we use the GetFlash() Method. There is also a method GetFlashes() to fetch all the messages.

Fetching a message deletes it from the session. This means that a message is meant to be displayed only on the first page served to the user.

func (*Session) GetFlashString 

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

GetFlashString same as `GetFlash` but returns its string representation, if key doesn't exist then it returns an empty string.

func (*Session) GetFlashStringDefault 

func (s *Session) GetFlashStringDefault(key string, defaultValue string) string

GetFlashStringDefault same as `GetFlash` but returns its string representation, if key doesn't exist then it returns the "defaultValue".

func (*Session) GetFlashes 

func (s *Session) GetFlashes() map[string]interface{}

GetFlashes returns all flash messages as map[string](key) and interface{} value NOTE: this will cause at remove all current flash messages on the next request of the same user.

func (*Session) GetFloat32 

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

GetFloat32 same as `Get` but returns its float32 representation, if key doesn't exist then it returns -1.

func (*Session) GetFloat32Default 

func (s *Session) GetFloat32Default(key string, defaultValue float32) (float32, error)

GetFloat32Default same as `Get` but returns its float32 representation, if key doesn't exist then it returns the "defaultValue".

func (*Session) GetFloat64 

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

GetFloat64 same as `Get` but returns its float64 representation, if key doesn't exist then it returns -1.

func (*Session) GetFloat64Default 

func (s *Session) GetFloat64Default(key string, defaultValue float64) (float64, error)

GetFloat64Default same as `Get` but returns its float64 representation, if key doesn't exist then it returns the "defaultValue".

func (*Session) GetInt 

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

GetInt same as `Get` but returns its int representation, if key doesn't exist then it returns -1.

func (*Session) GetInt64 

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

GetInt64 same as `Get` but returns its int64 representation, if key doesn't exist then it returns -1.

func (*Session) GetInt64Default 

func (s *Session) GetInt64Default(key string, defaultValue int64) (int64, error)

GetInt64Default same as `Get` but returns its int64 representation, if key doesn't exist it returns the "defaultValue".

func (*Session) GetIntDefault 

func (s *Session) GetIntDefault(key string, defaultValue int) (int, error)

GetIntDefault same as `Get` but returns its int representation, if key doesn't exist then it returns the "defaultValue".

func (*Session) GetString 

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

GetString same as Get but returns its string representation, if key doesn't exist then it returns an empty string.

func (*Session) GetStringDefault 

func (s *Session) GetStringDefault(key string, defaultValue string) string

GetStringDefault same as Get but returns its string representation, if key doesn't exist then it returns the "defaultValue".

func (*Session) HasFlash 

func (s *Session) HasFlash() bool

HasFlash returns true if this session has available flash messages.

func (*Session) ID 

func (s *Session) ID() string

ID returns the session's ID.

func (*Session) Increment added in v1.6.1 

func (s *Session) Increment(key string, n int) (newValue int)

Increment increments the stored int value saved as "key" by +"n". If value doesn't exist on that "key" then it creates one with the "n" as its value. It returns the new, incremented, value.

func (*Session) IsNew 

func (s *Session) IsNew() bool

IsNew returns true if this session is created by the current application's process.

func (*Session) PeekFlash 

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

PeekFlash returns a stored flash message based on its "key". Unlike GetFlash, this will keep the message valid for the next requests, until GetFlashes or GetFlash("key").

func (*Session) Set 

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

Set fills the session with an entry "value", based on its "key".

func (*Session) SetFlash 

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

SetFlash sets a flash message by its key.

A flash message is used in order to keep a message in session through one or several requests of the same user. It is removed from session after it has been displayed to the user. Flash messages are usually used in combination with HTTP redirections, because in this case there is no view, so messages can only be displayed in the request that follows redirection.

A flash message has a name and a content (AKA key and value). It is an entry of an associative array. The name is a string: often "notice", "success", or "error", but it can be anything. The content is usually a string. You can put HTML tags in your message if you display it raw. You can also set the message value to a number or an array: it will be serialized and kept in session like a string.

Flash messages can be set using the SetFlash() Method For example, if you would like to inform the user that his changes were successfully saved, you could add the following line to your Handler:

SetFlash("success", "Data saved!");

In this example we used the key 'success'. If you want to define more than one flash messages, you will have to use different keys.

func (*Session) SetImmutable 

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

SetImmutable fills the session with an entry "value", based on its "key". Unlike `Set`, the output value cannot be changed by the caller later on (when .Get) An Immutable entry should be only changed with a `SetImmutable`, simple `Set` will not work if the entry was immutable, for your own safety. Use it consistently, it's far slower than `Set`. Read more about muttable and immutable go types: https://stackoverflow.com/a/8021081

func (*Session) VisitAll 

func (s *Session) VisitAll(cb func(k string, v interface{}))

VisitAll loop each one entry and calls the callback function func(key,value)

type Sessions 

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

A Sessions manager should be responsible to Start a sesion, based on a Context, which should return a compatible Session interface, type. If the external session manager doesn't qualifies, then the user should code the rest of the functions with empty implementation.

Sessions should be responsible to Destroy a session based on the Context.

func New 

func New(cfg Config) *Sessions

New returns a new fast, feature-rich sessions manager it can be adapted to an iris station

func (*Sessions) Destroy 

func (s *Sessions) Destroy(ctx context.Context)

Destroy remove the session data and remove the associated cookie.

func (*Sessions) DestroyAll 

func (s *Sessions) DestroyAll()

DestroyAll removes all sessions from the server-side memory (and database if registered). Client's session cookie will still exist but it will be reseted on the next request.

func (*Sessions) DestroyByID 

func (s *Sessions) DestroyByID(sid string)

DestroyByID removes the session entry from the server-side memory (and database if registered). Client's session cookie will still exist but it will be reseted on the next request.

It's safe to use it even if you are not sure if a session with that id exists.

Note: the sid should be the original one (i.e: fetched by a store ) it's not decoded.

func (*Sessions) ShiftExpiration 

func (s *Sessions) ShiftExpiration(ctx context.Context)

ShiftExpiration move the expire date of a session to a new date by using session default timeout configuration.

func (*Sessions) Start 

func (s *Sessions) Start(ctx context.Context) *Session

Start should start the session for the particular request.

func (*Sessions) UpdateExpiration 

func (s *Sessions) UpdateExpiration(ctx context.Context, expires time.Duration)

UpdateExpiration change expire date of a session to a new date by using timeout value passed by `expires` receiver.

func (*Sessions) UseDatabase 

func (s *Sessions) UseDatabase(db Database)

UseDatabase adds a session database to the manager's provider, a session db doesn't have write access

type SyncPayload 

type SyncPayload struct {
	SessionID string

	Action Action
	// on insert it contains the new key and the value
	// on update it contains the existing key and the new value
	// on delete it contains the key (the value is nil)
	// on clear it contains nothing (empty key, value is nil)
	// on destroy it contains nothing (empty key, value is nil)
	Value memstore.Entry
	// Store contains the whole memory store, this store
	// contains the current, updated from memory calls,
	// session data (keys and values). This way
	// the database has access to the whole session's data
	// every time.
	Store RemoteStore
}

SyncPayload reports the state of the session inside a database sync action.

Source Files

View all Source files

Directories

Path Synopsis
sessiondb
badger
boltdb
file
leveldb
redis
redis/service

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.