crowd

README

Crowd - User and Session Library for Go

User and session management library for Go web applications and other applications where users are identified by a session token.

Example

To see how you can use the package see this example.

Contributors

• mbertschler

License

Crowd is released under the Apache 2.0 license. See LICENSE.txt

Documentation

Overview

Package crowd provides user and session management for applications where users are identified by a session ID or HTTP cookie.

For a basic usage example see the file example/main.go.

This is how you would use the Store methods in net/http HandlerFuncs. (Code shortened for this example.)

import "github.com/mbertschler/users"

var userStore = users.NewMemoryStore()

func handler(w http.ResponseWriter, r *http.Request) {
	user, err := userStore.Get(w, r)
	if err != nil {
		log.Println(err)
	}
	// use user object and handle errors ...
}

func loginHandler(w http.ResponseWriter, r *http.Request) {
	user, err := userStore.Login(w, r,
		r.PostFormValue("user"),
		r.PostFormValue("pass"),
	)
	// use user object and handle errors ...
}

Index

• Variables
• type Store
  • func NewMemoryStore() *Store
  • func NewStore(s Storer) *Store
  • func (s *Store) CookieDelete(w http.ResponseWriter, r *http.Request) (*User, error)
  • func (s *Store) CookieGet(w http.ResponseWriter, r *http.Request) (*User, error)
  • func (s *Store) CookieLogin(w http.ResponseWriter, r *http.Request, username, pass string) (*User, error)
  • func (s *Store) CookieLogout(w http.ResponseWriter, r *http.Request) (*User, error)
  • func (s *Store) CookieRegister(w http.ResponseWriter, r *http.Request, username, pass string) (*User, error)
  • func (s *Store) CookieSaveData(w http.ResponseWriter, r *http.Request, data interface{}) (*User, error)
  • func (s *Store) CookieSetPassword(w http.ResponseWriter, r *http.Request, pass string) (*User, error)
  • func (s *Store) CookieSetUsername(w http.ResponseWriter, r *http.Request, nextusername string) (*User, error)
  • func (s *Store) CountUsers() int
  • func (s *Store) IDDelete(id string) (*User, error)
  • func (s *Store) IDGet(id string) (*User, error)
  • func (s *Store) IDLogin(id string, username, pass string) (*User, error)
  • func (s *Store) IDLogout(id string) (*User, error)
  • func (s *Store) IDRegister(id string, username, pass string) (*User, error)
  • func (s *Store) IDSaveData(id string, data interface{}) (*User, error)
  • func (s *Store) IDSetPassword(id string, pass string) (*User, error)
  • func (s *Store) IDSetUsername(id string, nextusername string) (*User, error)
  • func (s *Store) StartSessionGC() error
  • func (s *Store) StopSessionGC() error
  • func (s *Store) UserIDDelete(id uint64) (*User, error)
  • func (s *Store) UserIDGet(id uint64) (*User, error)
  • func (s *Store) UserIDSaveData(id uint64, data interface{}) (*User, error)
  • func (s *Store) UserIDSetPassword(id uint64, pass string) (*User, error)
  • func (s *Store) UserIDSetUsername(id uint64, nextusername string) (*User, error)
  • func (s *Store) UserNameDelete(username string) (*User, error)
  • func (s *Store) UserNameGet(username string) (*User, error)
  • func (s *Store) UserNameRegister(username, pass string) (*User, error)
  • func (s *Store) UserNameSaveData(username string, data interface{}) (*User, error)
  • func (s *Store) UserNameSetPassword(username, pass string) (*User, error)
  • func (s *Store) UserNameSetUsername(username, nextusername string) (*User, error)
• type StoredSession
• type StoredUser
• type Storer
• type User

Variables

var (
	// ErrUserNotFound is returned when a store can't find the given user.
	ErrUserNotFound = errors.New("User not found")

	// ErrSessionNotFound is returned when a store can't find the given session.
	ErrSessionNotFound = errors.New("Session not found")

	// ErrUserExists is returned when a new user with a username
	// that already exists is registered.
	ErrUserExists = errors.New("User already exists")

	// ErrLoginWrong is returned when login credentials are wrong.
	ErrLoginWrong = errors.New("Login is wrong")

	// ErrNotLoggedIn is returned when a logged in user is expected.
	ErrNotLoggedIn = errors.New("Not logged in")

	// ErrSessionGCRunning is returned when the session GC is already running.
	ErrSessionGCRunning = errors.New("Session GC already running")

	// ErrSessionGCStopped is returned when the session GC is already stopped.
	ErrSessionGCStopped = errors.New("Session GC already stopped")
)

Types

type Store

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

Store is the main type of this library. It has a backend which can store users and sessions and provides all the relevant methods for working with them.

func NewMemoryStore

func NewMemoryStore() *Store

NewMemoryStore returns a Store with a memory backend.

func NewStore

func NewStore(s Storer) *Store

NewStore creates a new store with a specified Storer backend. Only other libraries should call this function. Use New[...]Store() functions such as NewMemoryStore() instead. This function also starts a session GC that regularly deletes expired sessions.

func (*Store) CookieDelete

func (s *Store) CookieDelete(w http.ResponseWriter, r *http.Request) (*User, error)

CookieDelete deletes the user that is associated with this client. It returns ErrNotLoggedIn if no user is currently logged in.

func (*Store) CookieGet

func (s *Store) CookieGet(w http.ResponseWriter, r *http.Request) (*User, error)

CookieGet gets the User associated with the current client. If there is no session cookie set in the request or the session is expired or not valid anymore, a new session cookie is created and set. If no user is logged in with this session the nil value of User with the embedded Session is returned.

func (*Store) CookieLogin

func (s *Store) CookieLogin(w http.ResponseWriter, r *http.Request, username, pass string) (*User, error)

CookieLogin logs a user in with a username and password. If the credentials for the login are wrong, ErrLoginWrong is returned.

func (*Store) CookieLogout

func (s *Store) CookieLogout(w http.ResponseWriter, r *http.Request) (*User, error)

CookieLogout logs the user that is associated with this client. It returns ErrNotLoggedIn if no user is currently logged in.

func (*Store) CookieRegister

func (s *Store) CookieRegister(w http.ResponseWriter, r *http.Request, username, pass string) (*User, error)

CookieRegister registers a new user with a username and password. If the given username already exists ErrUserExists is returned.

func (*Store) CookieSaveData

func (s *Store) CookieSaveData(w http.ResponseWriter, r *http.Request, data interface{}) (*User, error)

CookieSaveData saves the passed data into the Data field of the User object linked to the current session. If no user is currently logged in ErrNotLoggedIn is returned.

func (*Store) CookieSetPassword

func (s *Store) CookieSetPassword(w http.ResponseWriter, r *http.Request, pass string) (*User, error)

CookieSetPassword sets the password of the current user to a new one. If there is no current user logged in ErrNotLoggedIn is returned.

func (*Store) CookieSetUsername

func (s *Store) CookieSetUsername(w http.ResponseWriter, r *http.Request, nextusername string) (*User, error)

CookieSetUsername renames the current user to the new name. If the new username already exists ErrUserExists is returned. If there is no current user logged in ErrNotLoggedIn is returned.

func (*Store) CountUsers

func (s *Store) CountUsers() int

CountUsers returns the number of saved users

func (*Store) IDDelete

func (s *Store) IDDelete(id string) (*User, error)

IDDelete deltes the user that is associated with this session id. It returns ErrNotLoggedIn if no user is currently logged in.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) IDGet

func (s *Store) IDGet(id string) (*User, error)

IDGet gets the User associated with a session ID. If there is no session with this ID or the session expired, a new session is created. If no user is logged in with this session the nil value of User with the embedded Session is returned.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) IDLogin

func (s *Store) IDLogin(id string, username, pass string) (*User, error)

IDLogin logs a user in with a username and password. If the credentials for the login are wrong, ErrLoginWrong is returned.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) IDLogout

func (s *Store) IDLogout(id string) (*User, error)

IDLogout logs the user that is associated with this session id out. It returns ErrNotLoggedIn if no user is currently logged in.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) IDRegister

func (s *Store) IDRegister(id string, username, pass string) (*User, error)

IDRegister registers a new user with a username and password. If the given username already exists ErrUserExists is returned.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) IDSaveData

func (s *Store) IDSaveData(id string, data interface{}) (*User, error)

IDSaveData saves the passed data into the Data field of the User object linked to the specified session. If no user is currently logged in ErrNotLoggedIn is returned.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) IDSetPassword

func (s *Store) IDSetPassword(id string, pass string) (*User, error)

IDSetPassword sets the password of the current user to a new one. If there is no current user logged in ErrNotLoggedIn is returned.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) IDSetUsername

func (s *Store) IDSetUsername(id string, nextusername string) (*User, error)

IDSetUsername renames the current user to the new name. If the new username already exists ErrUserExists is returned. If there is no current user logged in ErrNotLoggedIn is returned.

It is the callers responsibility to pass the session token (User.ID) back to the client.

func (*Store) StartSessionGC

func (s *Store) StartSessionGC() error

StartSessionGC starts the session GC that regularly deletes expired sessions. It returns ErrSessionGCRunning if the GC is already running. When a new Store is created the sessionGC is automatically started.

func (*Store) StopSessionGC

func (s *Store) StopSessionGC() error

StopSessionGC stops the session GC that regularly deletes expired sessions. It returns ErrSessionGCStopped if the GC is already stopped.

func (*Store) UserIDDelete

func (s *Store) UserIDDelete(id uint64) (*User, error)

UserIDDelete deletes the user with the given user ID. It returns ErrUserNotFound if there is no such user stored.

func (*Store) UserIDGet

func (s *Store) UserIDGet(id uint64) (*User, error)

UserIDGet gets the User by its ID. If the user does not exist ErrUserNotFound is returned.

func (*Store) UserIDSaveData

func (s *Store) UserIDSaveData(id uint64, data interface{}) (*User, error)

UserIDSaveData saves the passed data into the Data field of the User object with the id specified in id. If the user does not exist ErrUserNotFound is returned.

func (*Store) UserIDSetPassword

func (s *Store) UserIDSetPassword(id uint64, pass string) (*User, error)

UserIDSetPassword sets the password of the user to a new one.

func (*Store) UserIDSetUsername

func (s *Store) UserIDSetUsername(id uint64, nextusername string) (*User, error)

UserIDSetUsername renames the user to the new name. If the new username already exists ErrUserExists is returned.

func (*Store) UserNameDelete

func (s *Store) UserNameDelete(username string) (*User, error)

UserNameDelete deletes the user with the given username. It returns ErrUserNotFound if there is no such user stored.

func (*Store) UserNameGet

func (s *Store) UserNameGet(username string) (*User, error)

UserNameGet gets the User by its name. If the user does not exist ErrUserNotFound is returned.

func (*Store) UserNameRegister

func (s *Store) UserNameRegister(username, pass string) (*User, error)

UserNameRegister registers a new user with a username and password. If the given username already exists ErrUserExists is returned.

func (*Store) UserNameSaveData

func (s *Store) UserNameSaveData(username string, data interface{}) (*User, error)

UserNameSaveData saves the passed data into the Data field of the User object with the name specified in username. If the user does not exist ErrUserNotFound is returned.

func (*Store) UserNameSetPassword

func (s *Store) UserNameSetPassword(username, pass string) (*User, error)

UserNameSetPassword sets the password of the current user to a new one.

func (*Store) UserNameSetUsername

func (s *Store) UserNameSetUsername(username, nextusername string) (*User, error)

UserNameSetUsername renames the user to the new name. If the new username already exists ErrUserExists is returned.

type StoredSession

type StoredSession struct {
	ID         string
	Expires    time.Time
	LastAccess time.Time
	LoggedIn   bool
	UserID     uint64
}

StoredSession is embedded into the User object. It is identified by its random ID token which is base64 encoded. It also tracks expiration time and last access time. If a user is logged in with this session, LoggedIn is true and User holds a username. After a logout User still holds the username.

type StoredUser

type StoredUser struct {
	ID   uint64
	Name string
	Pass []byte
	Salt []byte
	Data interface{}
	*StoredSession
}

StoredUser is the type that is retuned from most Store methods. It contains the Name of the user, which is also the identification when it is stored. Salt is randomly generated on registration and used to salt the password hash which is then stored in Pass. The session that was used to retrieve this user is also embedded into the struct.

The Data field can hold arbitrary application data which is saved using the Store.Save() method. To work with it use a type assertion.

type Storer

type Storer interface {
	// Get a Session from the store
	// If Session is not found, error needs to be ErrSessionNotFound
	GetSession(id string) (*StoredSession, error)
	// Put a Session into the store
	PutSession(s *StoredSession) error
	// Delete a Session from the store
	DeleteSession(id string) error
	// Run fn for each session and delete if true is returned
	ForEachSession(fn func(s *StoredSession) (del bool)) error

	// Get a User from the store
	// If User is not found, error needs to be ErrUserNotFound
	GetUser(id uint64) (*StoredUser, error)
	// If User is not found, error needs to be ErrUserNotFound
	GetUserID(username string) (uint64, error)
	// Put a User into the store
	PutUser(u *StoredUser) error
	// Add a User to the store and return the new user ID
	AddUser(u *StoredUser) (uint64, error)
	// Rename a User while keeping the ID the same
	RenameUser(id uint64, newname string) error
	// Delete a User from the store
	DeleteUser(id uint64) error
	// Run fn for each user and delete if true is returned
	ForEachUser(fn func(u *StoredUser) (del bool)) error
	// Return the number of saved users
	CountUsers() int
}

Storer is implemented for different storage backends. The Get and Put methods need to be safe for use by multiple goroutines simultaneously. User IDs need to start at index 1, because 0 is reserved for errors.

type User

type User struct {
	LoggedIn bool
	Name     string
	Data     interface{}

	Session struct {
		ID         string
		Expires    time.Time
		LastAccess time.Time
		UserID     uint64
	}
}

User maybe will be retuned in the future to not leak unneeded information.