sessions

package
v12.2.0-alpha3 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2021 License: BSD-3-Clause Imports: 14 Imported by: 145

Documentation

Index

Constants

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

Variables

View Source 
var ErrNotFound = errors.New("session not found")

ErrNotFound may be returned from `UpdateExpiration` of a non-existing or invalid session entry from memory storage or databases. Usage: 

if err != nil && err.Is(err, sessions.ErrNotFound) {
    [handle error...]
}
View Source 
var ErrNotImplemented = errors.New("not implemented yet")

ErrNotImplemented is returned when a particular feature is not yet implemented yet. It can be matched directly, i.e: `isNotImplementedError := sessions.ErrNotImplemented.Equal(err)`.

Functions

This section is empty.

Types

type Config 

type Config struct {
	// Logger instance for sessions usage, e.g. { Logger: app.Logger() }.
	// Defaults to a child of "sessions" of the latest Iris Application's main Logger.
	Logger *golog.Logger
	// 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 set true.
	// 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

	// Encoding should encodes and decodes
	// authenticated and optionally encrypted cookie values.
	//
	// Defaults to nil.
	Encoding context.SecureCookie

	// 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 can be set to a function which
	// return a unique session id.
	// By default we will use a uuid impl package to generate
	// that, but developers can change that with simple assignment.
	SessionIDGenerator func(ctx *context.Context) 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 {
	// SetLogger should inject a logger to this Database.
	SetLogger(*golog.Logger)
	// Acquire receives a session's lifetime from the database,
	// if the return value is LifeTime{} then the session manager sets the life time based on the expiration duration lives in configuration.
	Acquire(sid string, expires time.Duration) LifeTime
	// OnUpdateExpiration should re-set the expiration (ttl) of the session entry inside the database,
	// it is fired on `ShiftExpiration` and `UpdateExpiration`.
	// If the database does not support change of ttl then the session entry will be cloned to another one
	// and the old one will be removed, it depends on the chosen database storage.
	//
	// Check of error is required, if error returned then the rest session's keys are not proceed.
	//
	// If a database does not support this feature then an `ErrNotImplemented` will be returned instead.
	OnUpdateExpiration(sid string, newExpires time.Duration) error
	// Set sets a key value of a specific session.
	// The "immutable" input argument depends on the store, it may not implement it at all.
	Set(sid string, key string, value interface{}, ttl time.Duration, immutable bool) error
	// Get retrieves a session value based on the key.
	Get(sid string, key string) interface{}
	// Decode binds the "outPtr" to the value associated to the provided "key".
	Decode(sid, key string, outPtr interface{}) error
	// Visit loops through all session keys and values.
	Visit(sid string, cb func(key string, value interface{})) error
	// Len returns the length of the session's entries (keys).
	Len(sid string) int
	// Delete removes a session key value based on its key.
	Delete(sid string, key string) (deleted bool)
	// Clear removes all session key values but it keeps the session entry.
	Clear(sid string) error
	// Release destroys the session, it clears and removes the session entry,
	// session manager will create a new session ID on the next request after this call.
	Release(sid string) error
	// Close should terminate the database connection. It's called automatically on interrupt signals.
	Close() error
}

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 one using `UseDatabase`.

Look the `sessiondb` folder for databases implementations.

type DestroyListener 

type DestroyListener func(sid string)

DestroyListener is the form of a destroy listener. Look `OnDestroy` for more.

type ErrEntryNotFound 

type ErrEntryNotFound struct {
	Err   *memstore.ErrEntryNotFound
	Value interface{}
}

ErrEntryNotFound similar to core/memstore#ErrEntryNotFound but adds the value (if found) matched to the requested key-value pair of the session's memory storage.

func (*ErrEntryNotFound) As 

func (e *ErrEntryNotFound) As(target interface{}) bool

As method implements the dynamic As interface of the std errors package. As should be NOT used directly, use `errors.As` instead.

func (*ErrEntryNotFound) Error 

func (e *ErrEntryNotFound) Error() string

func (*ErrEntryNotFound) Unwrap 

func (e *ErrEntryNotFound) Unwrap() error

Unwrap method implements the dynamic Unwrap interface of the std errors package.

type GobTranscoder added in v12.2.0 

type GobTranscoder struct{}

GobTranscoder can be set to `DefaultTranscoder` to modify the database(s) transcoder.

func (GobTranscoder) Marshal added in v12.2.0 

func (GobTranscoder) Marshal(value interface{}) ([]byte, error)

Marshal returns the gob encoding of "value".

func (GobTranscoder) Unmarshal added in v12.2.0 

func (GobTranscoder) Unmarshal(b []byte, outPtr interface{}) error

Unmarshal parses the gob-encoded data "b" and stores the result in the value pointed to by "outPtr".

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) DurationUntilExpiration 

func (lt *LifeTime) DurationUntilExpiration() time.Duration

DurationUntilExpiration returns the duration until expires, it can return negative number if expired, a call to `HasExpired` may be useful before calling this `Dur` function.

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 Marshaler 

type Marshaler interface {
	Marshal(interface{}) ([]byte, error)
}

Marshaler is the common marshaler interface, used by transcoder.

type Session 

type Session struct {

	// Lifetime it contains the expiration data, use it for read-only information.
	// See `Sessions.UpdateExpiration` too.
	Lifetime *LifeTime
	// Man is the sessions manager that this session created of.
	Man *Sessions
	// 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 Get 

func Get(ctx *context.Context) *Session

Get returns a *Session from the same request life cycle, can be used inside a chain of handlers of a route.

The `Sessions.Start` should be called previously, e.g. register the `Sessions.Handler` as middleware. Then call `Get` package-level function as many times as you want. Note: It will return nil if the session got destroyed by the same request. If you need to destroy and start a new session in the same request you need to call sessions manager's `Start` method after Destroy.

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) Decode added in v12.2.0 

func (s *Session) Decode(key string, outPtr interface{}) error

Decode binds the given "outPtr" to the value associated to the provided "key".

func (*Session) Decrement 

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 

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 instead.

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 and a non-nil error.

func (*Session) GetBooleanDefault 

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

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 and a non-nil error.

func (*Session) GetFloat32Default 

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

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 and a non-nil error.

func (*Session) GetFloat64Default 

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

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 and a non-nil error.

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 and a non-nil error.

func (*Session) GetInt64Default 

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

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

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) GetUint64 added in v12.2.0 

func (s *Session) GetUint64(key string) (uint64, error)

GetUint64 same as `Get` but returns as uint64, if key doesn't exist then it returns 0 and a non-nil error.

func (*Session) GetUint64Default added in v12.2.0 

func (s *Session) GetUint64Default(key string, defaultValue uint64) uint64

GetUint64Default same as `Get` but returns as uint64, if key doesn't exist 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 

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 just created by the current application's process.

func (*Session) Len 

func (s *Session) Len() int

Len returns the total number of stored values in this session.

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) Visit 

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

Visit loops each of the entries 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/Get a sesion, based on a Context, which returns a *Session, type. It performs automatic memory cleanup on expired sessions. It can accept a `Database` for persistence across server restarts. A session can set temporary values (flash messages).

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 removes the session data, the associated cookie and the Context's session value. Next calls of `sessions.Get` will occur to a nil Session, use `Sessions#Start` method for renewal or use the Session's Destroy method which does keep the session entry with its values cleared.

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) GetCookieOptions added in v12.2.0 

func (s *Sessions) GetCookieOptions() []context.CookieOption

GetCookieOptions returns the cookie options registered for this sessions manager based on the configuration.

func (*Sessions) Handler 

func (s *Sessions) Handler(requestOptions ...context.CookieOption) context.Handler

Handler returns a sessions middleware to register on application routes. To return the request's Session call the `Get(ctx)` package-level function.

Call `Handler()` once per sessions manager.

func (*Sessions) OnDestroy 

func (s *Sessions) OnDestroy(listeners ...DestroyListener)

OnDestroy registers one or more destroy listeners. A destroy listener is fired when a session has been removed entirely from the server (the entry) and client-side (the cookie). Note that if a destroy listener is blocking, then the session manager will delay respectfully, use a goroutine inside the listener to avoid that behavior.

func (*Sessions) ShiftExpiration 

func (s *Sessions) ShiftExpiration(ctx *context.Context, cookieOptions ...context.CookieOption) error

ShiftExpiration move the expire date of a session to a new date by using session default timeout configuration. It will return `ErrNotImplemented` if a database is used and it does not support this feature, yet.

func (*Sessions) Start 

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

Start creates or retrieves an existing session for the particular request. Note that `Start` method will not respect configuration's `AllowReclaim`, `DisableSubdomainPersistence`, `CookieSecureTLS`, and `Encoding` settings. Register sessions as a middleware through the `Handler` method instead, which provides automatic resolution of a *sessions.Session input argument on MVC and APIContainer as well.

NOTE: Use `app.Use(sess.Handler())` instead, avoid using `Start` manually.

func (*Sessions) StartWithPath 

func (s *Sessions) StartWithPath(ctx *context.Context, path string) *Session

StartWithPath same as `Start` but it explicitly accepts the cookie path option.

func (*Sessions) UpdateExpiration 

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

UpdateExpiration change expire date of a session to a new date by using timeout value passed by `expires` receiver. It will return `ErrNotFound` when trying to update expiration on a non-existence or not valid session entry. It will return `ErrNotImplemented` if a database is used and it does not support this feature, yet.

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 Transcoder 

type Transcoder interface {
	Marshaler
	Unmarshaler
}

Transcoder is the interface that transcoders should implement, it includes just the `Marshaler` and the `Unmarshaler`. 

var (

	// DefaultTranscoder is the default transcoder across databases (when `UseDatabase` is used).
	//
	// The default database's values encoder and decoder
	// calls the value's `Marshal/Unmarshal` methods (if any)
	// otherwise JSON is selected,
	// the JSON format can be stored to any database and
	// it supports both builtin language types(e.g. string, int) and custom struct values.
	// Also, and the most important, the values can be
	// retrieved/logged/monitored by a third-party program
	// written in any other language as well.
	//
	// You can change this behavior by registering a custom `Transcoder`.
	// Iris provides a `GobTranscoder` which is mostly suitable
	// if your session values are going to be custom Go structs.
	// Select this if you always retrieving values through Go.
	// Don't forget to initialize a call of gob.Register when necessary.
	// Read https://golang.org/pkg/encoding/gob/ for more.
	//
	// You can also implement your own `sessions.Transcoder` and use it,
	// i.e: a transcoder which will allow(on Marshal: return its byte representation and nil error)
	// or dissalow(on Marshal: return non nil error) certain types.
	//
	// sessions.DefaultTranscoder = sessions.GobTranscoder{}
	DefaultTranscoder Transcoder = defaultTranscoder{}
)

type Unmarshaler 

type Unmarshaler interface {
	Unmarshal([]byte, interface{}) error
}

Unmarshaler is the common unmarshaler interface, used by transcoder.

Source Files

View all Source files

Directories

Path Synopsis
sessiondb
badger
boltdb
redis

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.