user

README

mediocre-api/user

This package provides both basic user functionality (creation, modification, authentication, etc....). Check the godocs for more information on how to use the go methods when building your own api.

Documentation

Overview

Package user implements an abstraction for a basic user system. Users can be created, have properties set on them, disabled, deleted, and more. All data is persisted to a redis instance or cluster, and all methods are compeletely thread-safe. No data is sanitized by this package, and no authentication is done (although authentication mechanisims are provided)

Index

• Variables
• type Field
• type FieldFlag
• type Info
• type System
  • func New(c util.Cmder) *System
  • func (s *System) AddField(f Field)
  • func (s *System) Authenticate(user, password string) error
  • func (s *System) ChangePassword(user, newPassword string) error
  • func (s *System) Create(user, email, password string) error
  • func (s *System) Disable(user string) error
  • func (s *System) Enable(user string) error
  • func (s *System) Get(user string, filters FieldFlag) (Info, error)
  • func (s *System) Key(user string, extra ...string) string
  • func (s *System) Set(user string, i Info) error

Variables

var (
	ErrUserExists      = common.ExpectedErr{Code: 400, Err: "user exists"}
	ErrNotFound        = common.ExpectedErr{Code: 404, Err: "user not found"}
	ErrBadAuth         = common.ExpectedErr{Code: 400, Err: "could not authenticate user"}
	ErrDisabled        = common.ExpectedErr{Code: 400, Err: "user account is disabled"}
	ErrInvalidUsername = common.ExpectedErr{Code: 400, Err: "invalid username"}
)

Errors which can be expected from various methods in this package

var (
	ErrFieldUnknown = func(f string) error {
		return common.ExpectedErrf(400, "unknown field %q", f)
	}
	ErrFieldUneditable = func(f string) error {
		return common.ExpectedErrf(400, "field %q not editable", f)
	}
)

Functions which return errors based on the related field names

Types

type Field

type Field struct {

	// The name of the field. This is the key it will appear under in the user
	// map
	Name string

	// If optionally specified this will be the key the field is stored as in
	// redis (can be shorter than Name to save space)
	Key string

	// Used to determine the behavior of this field. This *must* be set to a
	// value greater than zero
	Flags FieldFlag
}

Field is a struct which describes a single field of a user map. A field's value is inherently a string.

type FieldFlag

type FieldFlag uint64

FieldFlag is used to indicate different behaviors for different fields, such as preventing them from being returned in certain circumstances, and allowing them to be manually edited.

const (
	// Public fields will always be returned when calling Get
	Public FieldFlag = 1 << iota

	// Private fields are those that should only be shown to a verified entity,
	// and may contain private user information. Generally, only shown to the
	// logged in user
	Private

	// Hidden fields are never shown anywhere except in specific circumstances.
	Hidden

	// Editable indicates that this field is allowed to be modified manually
	Editable
)

type Info

type Info map[string]string

Info represents information for a single user in the system. The fields in the map correspond to the fields added by AddField

type System

type System struct {

	// The cost parameter to use when creating new password hashes. This
	// defaults to 11 and can be set right after instantiation
	BCryptCost int

	// A list of usernames which are not allowed to be created. Defaults to
	// []string{"new-user", "root"}
	BannedUsernames []string
	// contains filtered or unexported fields
}

System holds on to a Cmder and uses it to implement a basic user system. By default user maps have the following fields: * Name * TSCreated * Email (private, editable) * TSModified (private) * Disabled (private) * PasswordHash (hidden)

func New

func New(c util.Cmder) *System

New returns a new System which will use the given Cmder as its persistence layer

func (*System) AddField

func (s *System) AddField(f Field)

AddField can be used just after calling New to add more fields for a single user map. For example, if you'd like user maps to include an image field the field should be added here and it will appear for appropriate Get commands

func (*System) Authenticate

func (s *System) Authenticate(user, password string) error

Authenticate attempts to authenticate the user with the given password. Returns nil on success. Can return ErrDisabled or ErrBadAuth

func (*System) ChangePassword

func (s *System) ChangePassword(user, newPassword string) error

ChangePassword changes an existing user's password to be the given one

func (*System) Create

func (s *System) Create(user, email, password string) error

Create attempts to create a new user with the given email and password. If the user already exists ErrUserExists will be returned. If not the password will be hashed and stored

func (*System) Disable

func (s *System) Disable(user string) error

Disable marks the user as being disabled, meaning they have effectively deleted their account without actually deleting any data. They cannot log in and do not show up anywhere

func (*System) Enable

func (s *System) Enable(user string) error

Enable marks the user as having an account enabled. Accounts are enabled by default when created, this only really has an effect when an accound was previously Disable'd

func (*System) Get

func (s *System) Get(user string, filters FieldFlag) (Info, error)

Get returns the Info for the given user, or ErrNotFound if the user couldn't be found

func (*System) Key

func (s *System) Key(user string, extra ...string) string

Key returns a key which can be used to interact with some arbitrary user data directly in redis. This is useful if more complicated, lower level operations are needed to be done

func (*System) Set

func (s *System) Set(user string, i Info) error

Set is used to manually modify a user's fields. The Info argument need only be filled with the fields which are desired to be changed. All fields given in that argument must be Editable.