sessions

Documentation

Overview

Package session implements a simple session manager for token authentication.

This is not meant to be a generic session library, but to be used specifically as part of the software it comes with.

Index

• Constants
• Variables
• func DeleteSessionCookie(w http.ResponseWriter)
• func FromJson(json []byte, session *Session) error
• func GetJwtSignature(jwt string) (string, error)
• func GetSessionCookie(r *http.Request) (string, error)
• func SetSessionCookie(w http.ResponseWriter, sid string)
• type Manager
  • func NewManager(opts ...ManagerOption) *Manager
  • func (mgr *Manager) Count() int
  • func (mgr *Manager) Destroy(sid string) bool
  • func (mgr *Manager) DestroyWithCookie(w http.ResponseWriter, sid string) bool
  • func (mgr *Manager) Exists(sid string) bool
  • func (mgr *Manager) Get(sid string) (*Session, error)
  • func (mgr *Manager) GetRedis(conn redis.Conn, key string) ([]byte, error)
  • func (mgr *Manager) List(w io.Writer)
  • func (mgr *Manager) NewFromToken(token string, uid *uuid.UUID, user *models.User, opts ...SessionOption) error
  • func (mgr *Manager) NewLogin(uid *uuid.UUID, user *models.User, opts ...SessionOption) (string, error)
  • func (mgr *Manager) NewLoginWithCookie(w http.ResponseWriter, uid *uuid.UUID, user *models.User, ...) (string, error)
  • func (mgr *Manager) Save()
  • func (mgr *Manager) SessionFromRequest(r *http.Request) (*Session, error)
  • func (mgr *Manager) SetOnToken(on func(string) (string, error), gen sidGenerator)
  • func (mgr *Manager) UserSessionFromRequest(r *http.Request) (*Session, error)
• type ManagerOption
  • func WithRequireCSCUserName(require bool) ManagerOption
• type Session
  • func (session *Session) AsJson() ([]byte, error)
  • func (session *Session) HasUser() bool
  • func (session *Session) IsNil() bool
  • func (session *Session) MarshalJSONObject(enc *gojay.Encoder)
  • func (session *Session) MaybeUid() string
  • func (session *Session) NKeys() int
  • func (session Session) Public() *Session
  • func (session *Session) Uid() (uuid.UUID, error)
  • func (session *Session) UnmarshalJSONObject(dec *gojay.Decoder, key string) error
• type SessionOption
  • func WithDuration(exp time.Duration) SessionOption
  • func WithExpiration(expAt time.Time) SessionOption

Constants

const (
	// SessionCookieName is the name of the session cookie.
	SessionCookieName = "sid"

	// SessionCookiePath is the path for which the session cookie is valid.
	SessionCookiePath = "/"
)

const DefaultExpiration = 2 * 60 * time.Minute

DefaultExpiration is the default duration before a session expires

Variables

var (
	// ErrSessionNotFound is the error returned if we can't find a given session ID or no session ID has been given at all.
	ErrSessionNotFound = errors.New("expired or invalid session")

	// ErrUnknownUser occurs when the user successfully logs in with an external identity but we can't get our uid from the database.
	ErrUnknownUser = errors.New("unknown user")

	// ErrCreatingSid occurs when we can't read some random bytes from the system; this error is highly improbable.
	ErrCreatingSid = errors.New("error creating random session id")

	// ErrMalformedToken happens when we can't parse a bearer token.
	ErrMalformedToken = errors.New("malformed token")

	// ErrTokenConfigError is returned when trying to create a new session from token without having a token func defined.
	ErrTokenConfigError = errors.New("token session without token configuration")
)

Functions

func DeleteSessionCookie

func DeleteSessionCookie(w http.ResponseWriter)

DeleteSessionCookie tries to delete the session cookie from the browser.

func FromJson

func FromJson(json []byte, session *Session) error

FromJson returns a session deserialised from its JSON representation.

func GetJwtSignature

func GetJwtSignature(jwt string) (string, error)

GetJwtSignature returns the signature of JWT tokens. It is meant for HS* and RS* symmetrical and elliptical algorithms only with an encoded length of 186B; it is up to the caller to make sure this only gets called with relevant signatures. Here be dragons.

func GetSessionCookie

func GetSessionCookie(r *http.Request) (string, error)

GetSessionCookie tries to retrieve a session cookie from the request.

func SetSessionCookie

func SetSessionCookie(w http.ResponseWriter, sid string)

SetSessionCookie writes the session id cookie to the response.

Types

type Manager

type Manager struct {
	RequireCSCUserName bool
	// contains filtered or unexported fields
}

Manager handles the actual storage and retrieval of sessions.

func NewManager

func NewManager(opts ...ManagerOption) *Manager

NewManager creates a new session storage.

func (*Manager) Count

func (mgr *Manager) Count() int

func (*Manager) Destroy

func (mgr *Manager) Destroy(sid string) bool

func (*Manager) DestroyWithCookie

func (mgr *Manager) DestroyWithCookie(w http.ResponseWriter, sid string) bool

func (*Manager) Exists

func (mgr *Manager) Exists(sid string) bool

func (*Manager) Get

func (mgr *Manager) Get(sid string) (*Session, error)

func (*Manager) GetRedis

func (mgr *Manager) GetRedis(conn redis.Conn, key string) ([]byte, error)

func (*Manager) List

func (mgr *Manager) List(w io.Writer)

func (*Manager) NewFromToken

func (mgr *Manager) NewFromToken(token string, uid *uuid.UUID, user *models.User, opts ...SessionOption) error

NewFromToken creates a session from a token. The session manager needs to have been configured for tokens by SetOnToken().

func (*Manager) NewLogin

func (mgr *Manager) NewLogin(uid *uuid.UUID, user *models.User, opts ...SessionOption) (string, error)

NewLogin logs in a user by creating a session.

func (*Manager) NewLoginWithCookie

func (mgr *Manager) NewLoginWithCookie(w http.ResponseWriter, uid *uuid.UUID, user *models.User, opts ...SessionOption) (string, error)

NewLoginWithCookie wraps NewLogin to set a session cookie.

func (*Manager) Save

func (mgr *Manager) Save()

func (*Manager) SessionFromRequest

func (mgr *Manager) SessionFromRequest(r *http.Request) (*Session, error)

SessionFromRequest returns the existing session for the request or, failing that, an error.

func (*Manager) SetOnToken

func (mgr *Manager) SetOnToken(on func(string) (string, error), gen sidGenerator)

SetOnToken takes a function that can create a session from a token, and optionally a second function that can securily shorten a token to generate a session identifier. This function is not safe to run after the session manager has been taken into use.

func (*Manager) UserSessionFromRequest

func (mgr *Manager) UserSessionFromRequest(r *http.Request) (*Session, error)

UserSessionFromRequest gets the session for the current request if one exists and checks if it has a valid user. This is a shortcut that calls SessionFromRequest followed by HasUser.

type ManagerOption

type ManagerOption func(*Manager)

func WithRequireCSCUserName

func WithRequireCSCUserName(require bool) ManagerOption

type Session

type Session struct {

	// Expiration is the maximum expiration time for the session.
	Expiration time.Time

	// User is the application user object.
	User *models.User
	// contains filtered or unexported fields
}

Session contains user session information.

func (*Session) AsJson

func (session *Session) AsJson() ([]byte, error)

AsJson returns a byte slice containing the JSON representation of the session. See also the Public() method that removes private information.

func (*Session) HasUser

func (session *Session) HasUser() bool

HasUser returns true if the session is an end user session with a valid user object.

func (*Session) IsNil

func (session *Session) IsNil() bool

IsNil returns a boolean indicating whether the session is nil (method required by gojay JSON library).

func (*Session) MarshalJSONObject

func (session *Session) MarshalJSONObject(enc *gojay.Encoder)

func (*Session) MaybeUid

func (session *Session) MaybeUid() string

MaybeUid is a convenience function that returns the user id as a string or empty string if not set.

func (*Session) NKeys

func (session *Session) NKeys() int

func (Session) Public

func (session Session) Public() *Session

Public makes a chainable copy of a session and removes fields that should not be shown to the outside world.

func (*Session) Uid

func (session *Session) Uid() (uuid.UUID, error)

Uid returns the user id or an error if the session doesn't have a valid (application) user.

func (*Session) UnmarshalJSONObject

func (session *Session) UnmarshalJSONObject(dec *gojay.Decoder, key string) error

type SessionOption

type SessionOption func(*Session)

func WithDuration

func WithDuration(exp time.Duration) SessionOption

func WithExpiration

func WithExpiration(expAt time.Time) SessionOption