Update config documentation.

- Fix aarondl#47: Remove ModuleAttrMeta from Storers. Rename to ModuleAttributes.
- Add some additional deafult values to config.

Author: aarondl

authboss.go

@@ -56,10 +56,10 @@ func CurrentUser(w http.ResponseWriter, r *http.Request) (interface{}, error) {
 	}
 
 	if index := strings.IndexByte(key, ';'); index > 0 {
-		return Cfg.OAuth2Storer.GetOAuth(key[:index], key[index+1:], ModuleAttrMeta)
-	} else {
-		return Cfg.Storer.Get(key, ModuleAttrMeta)
+		return Cfg.OAuth2Storer.GetOAuth(key[:index], key[index+1:])
 	}
+
+	return Cfg.Storer.Get(key)
 }
 
 // CurrentUserP retrieves the current user but panics if it's not available for

callbacks.go

@@ -81,6 +81,7 @@ type Callbacks struct {
 	after  map[Event][]After
 }
 
+// NewCallbacks creates a new set of before and after callbacks.
 func NewCallbacks() *Callbacks {
 	return &Callbacks{
 		make(map[Event][]Before),

config.go

@@ -12,7 +12,7 @@ import (
 )
 
 // Cfg is the singleton instance of Config
-var Cfg *Config = NewConfig()
+var Cfg = NewConfig()
 
 // Config holds all the configuration for both authboss and it's modules.
 type Config struct {
@@ -50,36 +50,66 @@ type Config struct {
 	RecoverOKPath        string
 	RecoverTokenDuration time.Duration
 
-	Policies      []Validator
+	// Policies control validation of form fields and are automatically run
+	// against form posts that include the fields.
+	Policies []Validator
+	// ConfirmFields are fields that are supposed to be submitted with confirmation
+	// fields alongside them, passwords, emails etc.
 	ConfirmFields []string
 
+	// ExpireAfter controls the time an account is idle before being logged out
+	// by the ExpireMiddleware.
 	ExpireAfter time.Duration
 
-	LockAfter    int
-	LockWindow   time.Duration
+	// LockAfter this many tries.
+	LockAfter int
+	// LockWindow is the waiting time before the number of attemps are reset.
+	LockWindow time.Duration
+	// LockDuration is how long an account is locked for.
 	LockDuration time.Duration
 
-	EmailFrom          string
+	// EmailFrom is the email address authboss e-mails come from.
+	EmailFrom string
+	// EmailSubjectPrefix is used to add something to the front of the authboss
+	// email subjects.
 	EmailSubjectPrefix string
-	SMTPAddress        string
-	SMTPAuth           smtp.Auth
-
-	XSRFName  string
+	// SMTPAddress is the address of the SMTP server.
+	SMTPAddress string
+	// SMTPAuth is authentication details for the SMTP server, can be nil and if not
+	// will repeat the SMTPAddress, this is intentional.
+	SMTPAuth smtp.Auth
+
+	// XSRFName is the name of the xsrf token to put in the hidden form fields.
+	XSRFName string
+	// XSRFMaker is a function that returns an xsrf token for the current non-POST request.
 	XSRFMaker XSRF
 
-	Storer            Storer
-	OAuth2Storer      OAuth2Storer
-	CookieStoreMaker  CookieStoreMaker
+	// Storer is the interface through which Authboss accesses the web apps database.
+	Storer Storer
+	// OAuth2Storer is a different kind of storer only meant for OAuth2.
+	OAuth2Storer OAuth2Storer
+	// CookieStoreMaker must be defined to provide an interface capapable of storing cookies
+	// for the given response, and reading them from the request.
+	CookieStoreMaker CookieStoreMaker
+	// SessionStoreMaker must be defined to provide an interface capable of storing session-only
+	// values for the given response, and reading them from the request.
 	SessionStoreMaker SessionStoreMaker
-	LogWriter         io.Writer
-	Callbacks         *Callbacks
-	Mailer            Mailer
+	// LogWriter is written to when errors occur, as well as on startup to show which modules are loaded
+	// and which routes they registered. By default writes to io.Discard.
+	LogWriter io.Writer
+	// Callbacks is an internal mechanism that can be used by implementers and will be set automatically.
+	Callbacks *Callbacks
+	// Mailer is the mailer being used to send e-mails out. Authboss defines two loggers for use
+	// LogMailer and SMTPMailer, the default is a LogMailer to io.Discard.
+	Mailer Mailer
 }
 
+// NewConfig creates a config full of healthy default values.
+// Notable exceptions to default values are the Storers.
 func NewConfig() *Config {
 	return &Config{
 		MountPath:  "/",
-		ViewsPath:  "/",
+		ViewsPath:  "./",
 		RootURL:    "http://localhost:8080",
 		BCryptCost: bcrypt.DefaultCost,
 
@@ -116,6 +146,10 @@ func NewConfig() *Config {
 
 		ExpireAfter: 60 * time.Minute,
 
+		LockAfter:    3,
+		LockWindow:   5 * time.Minute,
+		LockDuration: 5 * time.Hour,
+
 		RecoverOKPath:        "/",
 		RecoverTokenDuration: time.Duration(24) * time.Hour,
 

context.go

@@ -109,9 +109,9 @@ func (c *Context) LoadUser(key string) error {
 	var err error
 
 	if index := strings.IndexByte(key, ';'); index > 0 {
-		user, err = Cfg.OAuth2Storer.GetOAuth(key[:index], key[index+1:], ModuleAttrMeta)
+		user, err = Cfg.OAuth2Storer.GetOAuth(key[:index], key[index+1:])
 	} else {
-		user, err = Cfg.Storer.Get(key, ModuleAttrMeta)
+		user, err = Cfg.Storer.Get(key)
 	}
 	if err != nil {
 		return err

internal/mocks/mocks.go

@@ -73,7 +73,7 @@ func (m *MockStorer) Put(key string, attr authboss.Attributes) error {
 	return nil
 }
 
-func (m *MockStorer) Get(key string, attrMeta authboss.AttributeMeta) (result interface{}, err error) {
+func (m *MockStorer) Get(key string) (result interface{}, err error) {
 	if len(m.GetErr) > 0 {
 		return nil, errors.New(m.GetErr)
 	}
@@ -106,7 +106,7 @@ func (m *MockStorer) PutOAuth(uid, provider string, attr authboss.Attributes) er
 	return nil
 }
 
-func (m *MockStorer) GetOAuth(uid, provider string, attrMeta authboss.AttributeMeta) (result interface{}, err error) {
+func (m *MockStorer) GetOAuth(uid, provider string) (result interface{}, err error) {
 	if len(m.GetErr) > 0 {
 		return nil, errors.New(m.GetErr)
 	}
@@ -217,7 +217,7 @@ func (_ MockFailStorer) Create(_ string, _ authboss.Attributes) error {
 func (_ MockFailStorer) Put(_ string, _ authboss.Attributes) error {
 	return errors.New("fail storer: put")
 }
-func (_ MockFailStorer) Get(_ string, _ authboss.AttributeMeta) (interface{}, error) {
+func (_ MockFailStorer) Get(_ string) (interface{}, error) {
 	return nil, errors.New("fail storer: get")
 }
 

lock/lock.go

@@ -118,7 +118,7 @@ func (l *Lock) AfterAuthFail(ctx *authboss.Context) error {
 
 // Lock a user manually.
 func (l *Lock) Lock(key string) error {
-	user, err := authboss.Cfg.Storer.Get(key, authboss.ModuleAttrMeta)
+	user, err := authboss.Cfg.Storer.Get(key)
 	if err != nil {
 		return err
 	}
@@ -128,14 +128,14 @@ func (l *Lock) Lock(key string) error {
 		return err
 	}
 
-	attr[StoreLocked] = true
+	attr[StoreLocked] = time.Now().UTC().Add(authboss.Cfg.LockDuration)
 
 	return authboss.Cfg.Storer.Put(key, attr)
 }
 
 // Unlock a user that was locked by this module.
 func (l *Lock) Unlock(key string) error {
-	user, err := authboss.Cfg.Storer.Get(key, authboss.ModuleAttrMeta)
+	user, err := authboss.Cfg.Storer.Get(key)
 	if err != nil {
 		return err
 	}

mocks_test.go

@@ -23,7 +23,7 @@ func (m mockStorer) Put(key string, attr Attributes) error {
 	return nil
 }
 
-func (m mockStorer) Get(key string, attrMeta AttributeMeta) (result interface{}, err error) {
+func (m mockStorer) Get(key string) (result interface{}, err error) {
 	return &mockUser{
 		m[key]["email"].(string), m[key]["password"].(string),
 	}, nil
@@ -34,7 +34,7 @@ func (m mockStorer) PutOAuth(uid, provider string, attr Attributes) error {
 	return nil
 }
 
-func (m mockStorer) GetOAuth(uid, provider string, attrMeta AttributeMeta) (result interface{}, err error) {
+func (m mockStorer) GetOAuth(uid, provider string) (result interface{}, err error) {
 	return &mockUser{
 		m[uid+provider]["email"].(string), m[uid+provider]["password"].(string),
 	}, nil

module.go

@@ -2,7 +2,10 @@ package authboss
 
 var modules = make(map[string]Modularizer)
 
-var ModuleAttrMeta = make(AttributeMeta)
+// ModuleAttributes is the list of attributes required by all the loaded modules.
+// Authboss implementers can use this at runtime to determine what data is necessary
+// to store.
+var ModuleAttributes = make(AttributeMeta)
 
 // Modularizer should be implemented by all the authboss modules.
 type Modularizer interface {
@@ -17,7 +20,7 @@ func RegisterModule(name string, m Modularizer) {
 	modules[name] = m
 
 	for k, v := range m.Storage() {
-		ModuleAttrMeta[k] = v
+		ModuleAttributes[k] = v
 	}
 }
 

register/register_test.go

@@ -112,7 +112,7 @@ func TestRegisterPostValidationErrs(t *testing.T) {
 		t.Error("Confirm password should have an error:", str)
 	}
 
-	if _, err := authboss.Cfg.Storer.Get(email, authboss.AttributeMeta(reg.Storage())); err != authboss.ErrUserNotFound {
+	if _, err := authboss.Cfg.Storer.Get(email); err != authboss.ErrUserNotFound {
 		t.Error("The user should not have been saved.")
 	}
 }
@@ -145,7 +145,7 @@ func TestRegisterPostSuccess(t *testing.T) {
 		t.Error("Redirected to the wrong location", loc)
 	}
 
-	user, err := authboss.Cfg.Storer.Get(email, authboss.AttributeMeta(reg.Storage()))
+	user, err := authboss.Cfg.Storer.Get(email)
 	if err == authboss.ErrUserNotFound {
 		t.Error("The user have been saved.")
 	}

storer.go

@@ -48,7 +48,7 @@ type Storer interface {
 	// must be a struct that contains all fields with the correct types as shown
 	// by attrMeta. If the key is not found in the data store simply
 	// return nil, ErrUserNotFound.
-	Get(key string, attrMeta AttributeMeta) (interface{}, error)
+	Get(key string) (interface{}, error)
 }
 
 // OAuth2Storer is a replacement (or addition) to the Storer interface.
@@ -57,7 +57,7 @@ type OAuth2Storer interface {
 	// PutOAuth creates or updates an existing record (unlike Storer.Put)
 	// because in the OAuth flow there is no separate create/update.
 	PutOAuth(uid, provider string, attr Attributes) error
-	GetOAuth(uid, provider string, attrMeta AttributeMeta) (interface{}, error)
+	GetOAuth(uid, provider string) (interface{}, error)
 }
 
 // DataType represents the various types that clients must be able to store.