Documentation ¶
Index ¶
- Variables
- func CookieName(n string) setter
- func DefaultGenID() string
- func DefaultReject(err error) http.Handler
- func Domain(d string) setter
- func ExpiresIn(e time.Duration) setter
- func GenID(g func() string) setter
- func HttpOnly(h bool) setter
- func NewContext(ctx context.Context, s Session) context.Context
- func Path(p string) setter
- func Reject(r func(error) http.Handler) setter
- func SameSite(s http.SameSite) setter
- func Secure(s bool) setter
- func Validate(v bool) setter
- func WithAgent(w bool) setter
- func WithIP(w bool) setter
- type Manager
- func (m *Manager) Auth(next http.Handler) http.Handler
- func (m *Manager) Clone(opts ...setter) *Manager
- func (m *Manager) Defaults()
- func (m *Manager) FetchAll(ctx context.Context) ([]Session, error)
- func (m *Manager) Init(w http.ResponseWriter, r *http.Request, key string, mm ...Meta) error
- func (m *Manager) Public(next http.Handler) http.Handler
- func (m *Manager) Revoke(ctx context.Context, w http.ResponseWriter) error
- func (m *Manager) RevokeAll(ctx context.Context, w http.ResponseWriter) error
- func (m *Manager) RevokeByID(ctx context.Context, id string) error
- func (m *Manager) RevokeByIDExt(ctx context.Context, id string) error
- func (m *Manager) RevokeByUserKey(ctx context.Context, key string) error
- func (m *Manager) RevokeOther(ctx context.Context) error
- type Meta
- type Session
- type Store
Constants ¶
This section is empty.
Variables ¶
var ( errors.New("unauthorized") // ErrNotOwner is returned when session's status is being modified // not by its owner. ErrNotOwner = errors.New("session can be managed only by its owner") )ErrUnauthorized =
var ( // ErrDuplicateID should be returned by Store implementations upon // ID collision. ErrDuplicateID = errors.New("duplicate ID") )
Functions ¶
func CookieName ¶
func CookieName(n string) setter
CookieName sets the name of the cookie. Defaults to the value stored in defaultName.
func DefaultGenID ¶
func DefaultGenID() string
DefaultGenID is the default ID generation function called during session creation.
func DefaultReject ¶
DefaultReject is the default rejection function called on error. It produces a response consisting of 401 status code and a JSON body with 'error' field.
func Domain ¶
func Domain(d string) setter
Domain sets the 'Domain' attribute on the session cookie. Defaults to empty string. More at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Scope_of_cookies
func ExpiresIn ¶
ExpiresIn sets the duration which will be used to calculate the value of 'Expires' attribute on the session cookie. If unset, 'Expires' attribute will be omitted during cookie creation. By default it is not set. More about Expires at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Session_cookies
func GenID ¶
func GenID(g func() string) setter
GenID sets the function which will be called when a new session is created and ID is being generated. Defaults to DefaultGenID function.
func HttpOnly ¶
func HttpOnly(h bool) setter
HttpOnly sets the 'HttpOnly' attribute on the session cookie. Defaults to true. More at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies
func NewContext ¶ added in v1.1.1
NewContext creates a new context with the provided Session set as a context value.
func Path ¶
func Path(p string) setter
Path sets the 'Path' attribute on the session cookie. Defaults to "/". More at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Scope_of_cookies
func Reject ¶
Reject sets the function which will be called on error in Auth middleware. Defaults to DefaultReject function.
func SameSite ¶
SameSite sets the 'SameSite' attribute on the session cookie. Defaults to http.SameSiteStrictMode. More at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#SameSite_cookies
func Secure ¶
func Secure(s bool) setter
Secure sets the 'Secure' attribute on the session cookie. Defaults to true. More at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies
func Validate ¶ added in v1.2.0
func Validate(v bool) setter
Validate determines whether IP and User-Agent data should be checked on each request to authenticated routes or not.
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager holds the data needed to properly create sessions and set them in http responses, extract them from http requests, validate them and directly communicate with the store.
func NewManager ¶
NewManager creates a new Manager with the provided store and options applied to it.
func (*Manager) Auth ¶
Auth wraps the provided handler, checks whether the session, associated to the ID stored in request's cookie, exists in the store or not and, if former is the case, adds it to the request's context. Wrapped handler will be activated only if there are no errors returned from the store, the session is found and its properties match the ones in the request (if validation is activated), otherwise, the manager's rejection function will be called.
func (*Manager) Defaults ¶
func (m *Manager) Defaults()
Defaults sets all configuration options to reasonable defaults.
func (*Manager) FetchAll ¶
FetchAll retrieves all sessions of the same user key as session stored in the context currently has. Session with the same ID as the one stored in the context will have its 'Current' field set to true. If no sessions are found or the context session is not set, both return values will be nil.
func (*Manager) Init ¶
Init creates a fresh session with the provided user key, inserts it in the store and sets the proper values of the cookie.
func (*Manager) Public ¶
Public wraps the provided handler, checks whether the session, associated to the ID stored in request's cookie, exists in the store or not and, if former is the case, adds it to the request's context. If no valid cookie is provided, session doesn't exist, the properties of the request don't match the ones associated to the session (if validation is activated) or the store returns an error, wrapped handler will be activated nonetheless. Rejection function will be called only for non-http side effects (like error logging), but response/request control will not be passed to it.
func (*Manager) Revoke ¶
Revoke deletes the current session, stored in the context, from the store and ensures cookie deletion. Function will be no-op and return nil, if context session is not set.
func (*Manager) RevokeAll ¶
RevokeAll deletes all sessions of the same user key as session stored in the context currently has. This includes context session as well. Function will be no-op and return nil, if context session is not set.
func (*Manager) RevokeByID ¶ added in v1.1.0
RevokeByID deletes session by its ID. Function will be no-op and return nil, if no session is found.
func (*Manager) RevokeByIDExt ¶ added in v1.3.0
RevokeByIDExt deletes session by its ID after checking if it belongs to the same user as the one in the context. Function will be no-op and return nil, if no session is found.
func (*Manager) RevokeByUserKey ¶ added in v1.1.0
RevokeByUserKey deletes all sessions under the provided user key. This includes context session as well. Function will be no-op and return nil, if no sessions are found.
type Session ¶
type Session struct { // Current specifies whether this session's ID // matches the ID stored in the request's cookie or not. // NOTE: this field should be omitted by Store interface // implementations when inserting session into the underlying // data store. Current bool `json:"current"` // CreatedAt specifies a point in time when this session // was created. CreatedAt time.Time `json:"created_at"` // ExpiresAt specifies a point in time when this // session should become invalid and be deleted // from the store. ExpiresAt time.Time `json:"-"` // ID specifies a unique ID used to find this session // in the store. ID string `json:"id"` // UserKey specifies a non-unique key used to find all // sessions of the same user. UserKey string `json:"-"` // IP specifies an IP address that was used to create // this session IP net.IP `json:"ip"` // Agent specifies the User-Agent data that was used // to create this session. Agent struct { OS string `json:"os"` Browser string `json:"browser"` } `json:"agent"` // Meta specifies a map of metadata associated with // the session. Meta map[string]string `json:"meta,omitempty"` }
Session holds all the data needed to identify a session.
func FromContext ¶
FromContext extracts Session from the context.
type Store ¶
type Store interface { // Create should insert the new provided session into the store and // ensure that it is deleted when expiration time due. // Error should be returned on ID collision or other system errors. Create(ctx context.Context, s Session) error // FetchByID should retrieve the session from the store by the // provided ID. // The second returned value indicates whether the session was found // or not (true == found), error should be nil if session is not found. // Error should be returned on system errors only. FetchByID(ctx context.Context, id string) (Session, bool, error) // FetchByUserKey should retrieve all sessions associated with the // provided user key. If none are found, both return values should // be nil. // Error should be returned on system errors only. FetchByUserKey(ctx context.Context, key string) ([]Session, error) // DeleteByID should delete the session from the store by the // provided ID. // If session is not found, this function should be no-op and // return nil. // Error should be returned on system errors only. DeleteByID(ctx context.Context, id string) error // DeleteByUserKey should delete all sessions associated with the // provided user key, except those whose IDs are provided as the // last argument. // If none are found, this function should be no-op and return nil. // Error should be returned on system errors only. DeleteByUserKey(ctx context.Context, key string, expID ...string) error }
Store provides an easy access to the underlying data store, without exposing any of its internal logic, but providing all the mandatory methods accordingly.