auth
auth/client.go
The great documentation and exported interface cleanup. Modify all our *Store interfaces to be unexported, as there's no real good reason they need to be exported, especially as they can be implemented without being exported. The interfaces shouldn't matter to 99% of users of the package, so let's not pollute our package API. Further, all methods of the interfaces are now unexported, for pretty much the same reasoning. Add a doc.go file with documentation explaining the choices the package is making and what it provides. Implement documentation on all our exported types and methods and functions, which makes golint happy. The only remaining golint warning is about NewMemstore, which will stay the way it is. The memstore type is useful outside tests for things like standing up a server quickly when we don't care about the storage, and because the type is unexported, we _need_ a New function to create an instance that can be passed to the Context.
1.1 --- a/client.go Wed Oct 22 00:30:28 2014 -0400 1.2 +++ b/client.go Sun Oct 26 00:53:36 2014 -0400 1.3 @@ -10,17 +10,28 @@ 1.4 ) 1.5 1.6 var ( 1.7 - ErrNoClientStore = errors.New("no ClientStore was specified for the Context") 1.8 - ErrClientNotFound = errors.New("client not found in ClientStore") 1.9 - ErrClientAlreadyExists = errors.New("client already exists in ClientStore") 1.10 + // ErrNoClientStore is returned when a Context tries to act on a clientStore without setting one first. 1.11 + ErrNoClientStore = errors.New("no clientStore was specified for the Context") 1.12 + // ErrClientNotFound is returned when a Client is requested but not found in a clientStore. 1.13 + ErrClientNotFound = errors.New("client not found in clientStore") 1.14 + // ErrClientAlreadyExists is returned when a Client is added to a clientStore, but another Client with 1.15 + // the same ID already exists in the clientStore. 1.16 + ErrClientAlreadyExists = errors.New("client already exists in clientStore") 1.17 1.18 - ErrEmptyChange = errors.New("change must have at least one change in it") 1.19 - ErrClientNameTooShort = errors.New("client name must be at least 2 characters") 1.20 - ErrClientNameTooLong = errors.New("client name must be at most 32 characters") 1.21 - ErrClientLogoTooLong = errors.New("client logo must be at most 1024 characters") 1.22 - ErrClientLogoNotURL = errors.New("client logo must be a valid absolute URL") 1.23 + // ErrEmptyChange is returned when a Change has all its properties set to nil. 1.24 + ErrEmptyChange = errors.New("change must have at least one property set") 1.25 + // ErrClientNameTooShort is returned when a Client's Name property is too short. 1.26 + ErrClientNameTooShort = errors.New("client name must be at least 2 characters") 1.27 + // ErrClientNameTooLong is returned when a Client's Name property is too long. 1.28 + ErrClientNameTooLong = errors.New("client name must be at most 32 characters") 1.29 + // ErrClientLogoTooLong is returned when a Client's Logo property is too long. 1.30 + ErrClientLogoTooLong = errors.New("client logo must be at most 1024 characters") 1.31 + // ErrClientLogoNotURL is returned when a Client's Logo property is not a valid absolute URL. 1.32 + ErrClientLogoNotURL = errors.New("client logo must be a valid absolute URL") 1.33 + // ErrClientWebsiteTooLong is returned when a Client's Website property is too long. 1.34 ErrClientWebsiteTooLong = errors.New("client website must be at most 1024 characters") 1.35 - ErrClientWebsiteNotURL = errors.New("client website must be a valid absolute URL") 1.36 + // ErrClientWebsiteNotURL is returned when a Client's Website property is not a valid absolute URL. 1.37 + ErrClientWebsiteNotURL = errors.New("client website must be a valid absolute URL") 1.38 ) 1.39 1.40 // Client represents a client that grants access 1.41 @@ -36,6 +47,8 @@ 1.42 Type string 1.43 } 1.44 1.45 +// ApplyChange applies the properties of the passed 1.46 +// ClientChange to the Client object it is called on. 1.47 func (c *Client) ApplyChange(change ClientChange) { 1.48 if change.Secret != nil { 1.49 c.Secret = *change.Secret 1.50 @@ -54,6 +67,8 @@ 1.51 } 1.52 } 1.53 1.54 +// ClientChange represents a bundle of options for 1.55 +// updating a Client's mutable data. 1.56 type ClientChange struct { 1.57 Secret *string 1.58 OwnerID uuid.ID 1.59 @@ -62,6 +77,8 @@ 1.60 Website *string 1.61 } 1.62 1.63 +// Validate checks the ClientChange it is called on 1.64 +// and asserts its internal validity, or lack thereof. 1.65 func (c ClientChange) Validate() error { 1.66 if c.Secret == nil && c.OwnerID == nil && c.Name == nil && c.Logo == nil && c.Website == nil { 1.67 return ErrEmptyChange 1.68 @@ -93,6 +110,10 @@ 1.69 return nil 1.70 } 1.71 1.72 +// Endpoint represents a single URI that a Client 1.73 +// controls. Users will be redirected to these URIs 1.74 +// following successful authorization grants and 1.75 +// exchanges for access tokens. 1.76 type Endpoint struct { 1.77 ID uuid.ID 1.78 ClientID uuid.ID 1.79 @@ -114,23 +135,21 @@ 1.80 s[i], s[j] = s[j], s[i] 1.81 } 1.82 1.83 -// ClientStore abstracts the storage interface for 1.84 -// storing and retrieving Clients. 1.85 -type ClientStore interface { 1.86 - GetClient(id uuid.ID) (Client, error) 1.87 - SaveClient(client Client) error 1.88 - UpdateClient(id uuid.ID, change ClientChange) error 1.89 - DeleteClient(id uuid.ID) error 1.90 - ListClientsByOwner(ownerID uuid.ID, num, offset int) ([]Client, error) 1.91 +type clientStore interface { 1.92 + getClient(id uuid.ID) (Client, error) 1.93 + saveClient(client Client) error 1.94 + updateClient(id uuid.ID, change ClientChange) error 1.95 + deleteClient(id uuid.ID) error 1.96 + listClientsByOwner(ownerID uuid.ID, num, offset int) ([]Client, error) 1.97 1.98 - AddEndpoint(client uuid.ID, endpoint Endpoint) error 1.99 - RemoveEndpoint(client, endpoint uuid.ID) error 1.100 - CheckEndpoint(client uuid.ID, endpoint string, strict bool) (bool, error) 1.101 - ListEndpoints(client uuid.ID, num, offset int) ([]Endpoint, error) 1.102 - CountEndpoints(client uuid.ID) (int64, error) 1.103 + addEndpoint(client uuid.ID, endpoint Endpoint) error 1.104 + removeEndpoint(client, endpoint uuid.ID) error 1.105 + checkEndpoint(client uuid.ID, endpoint string, strict bool) (bool, error) 1.106 + listEndpoints(client uuid.ID, num, offset int) ([]Endpoint, error) 1.107 + countEndpoints(client uuid.ID) (int64, error) 1.108 } 1.109 1.110 -func (m *Memstore) GetClient(id uuid.ID) (Client, error) { 1.111 +func (m *memstore) getClient(id uuid.ID) (Client, error) { 1.112 m.clientLock.RLock() 1.113 defer m.clientLock.RUnlock() 1.114 c, ok := m.clients[id.String()] 1.115 @@ -140,7 +159,7 @@ 1.116 return c, nil 1.117 } 1.118 1.119 -func (m *Memstore) SaveClient(client Client) error { 1.120 +func (m *memstore) saveClient(client Client) error { 1.121 m.clientLock.Lock() 1.122 defer m.clientLock.Unlock() 1.123 if _, ok := m.clients[client.ID.String()]; ok { 1.124 @@ -151,7 +170,7 @@ 1.125 return nil 1.126 } 1.127 1.128 -func (m *Memstore) UpdateClient(id uuid.ID, change ClientChange) error { 1.129 +func (m *memstore) updateClient(id uuid.ID, change ClientChange) error { 1.130 m.clientLock.Lock() 1.131 defer m.clientLock.Unlock() 1.132 c, ok := m.clients[id.String()] 1.133 @@ -163,8 +182,8 @@ 1.134 return nil 1.135 } 1.136 1.137 -func (m *Memstore) DeleteClient(id uuid.ID) error { 1.138 - client, err := m.GetClient(id) 1.139 +func (m *memstore) deleteClient(id uuid.ID) error { 1.140 + client, err := m.getClient(id) 1.141 if err != nil { 1.142 return err 1.143 } 1.144 @@ -184,7 +203,7 @@ 1.145 return nil 1.146 } 1.147 1.148 -func (m *Memstore) ListClientsByOwner(ownerID uuid.ID, num, offset int) ([]Client, error) { 1.149 +func (m *memstore) listClientsByOwner(ownerID uuid.ID, num, offset int) ([]Client, error) { 1.150 ids := m.lookupClientsByProfileID(ownerID.String()) 1.151 if len(ids) > num+offset { 1.152 ids = ids[offset : num+offset] 1.153 @@ -195,7 +214,7 @@ 1.154 } 1.155 clients := []Client{} 1.156 for _, id := range ids { 1.157 - client, err := m.GetClient(id) 1.158 + client, err := m.getClient(id) 1.159 if err != nil { 1.160 return []Client{}, err 1.161 } 1.162 @@ -204,14 +223,14 @@ 1.163 return clients, nil 1.164 } 1.165 1.166 -func (m *Memstore) AddEndpoint(client uuid.ID, endpoint Endpoint) error { 1.167 +func (m *memstore) addEndpoint(client uuid.ID, endpoint Endpoint) error { 1.168 m.endpointLock.Lock() 1.169 defer m.endpointLock.Unlock() 1.170 m.endpoints[client.String()] = append(m.endpoints[client.String()], endpoint) 1.171 return nil 1.172 } 1.173 1.174 -func (m *Memstore) RemoveEndpoint(client, endpoint uuid.ID) error { 1.175 +func (m *memstore) removeEndpoint(client, endpoint uuid.ID) error { 1.176 m.endpointLock.Lock() 1.177 defer m.endpointLock.Unlock() 1.178 pos := -1 1.179 @@ -227,7 +246,7 @@ 1.180 return nil 1.181 } 1.182 1.183 -func (m *Memstore) CheckEndpoint(client uuid.ID, endpoint string, strict bool) (bool, error) { 1.184 +func (m *memstore) checkEndpoint(client uuid.ID, endpoint string, strict bool) (bool, error) { 1.185 m.endpointLock.RLock() 1.186 defer m.endpointLock.RUnlock() 1.187 for _, candidate := range m.endpoints[client.String()] { 1.188 @@ -240,13 +259,13 @@ 1.189 return false, nil 1.190 } 1.191 1.192 -func (m *Memstore) ListEndpoints(client uuid.ID, num, offset int) ([]Endpoint, error) { 1.193 +func (m *memstore) listEndpoints(client uuid.ID, num, offset int) ([]Endpoint, error) { 1.194 m.endpointLock.RLock() 1.195 defer m.endpointLock.RUnlock() 1.196 return m.endpoints[client.String()], nil 1.197 } 1.198 1.199 -func (m *Memstore) CountEndpoints(client uuid.ID) (int64, error) { 1.200 +func (m *memstore) countEndpoints(client uuid.ID) (int64, error) { 1.201 m.endpointLock.RLock() 1.202 defer m.endpointLock.RUnlock() 1.203 return int64(len(m.endpoints[client.String()])), nil