Adding documentation
diff --git a/openstack/db/v1/users/doc.go b/openstack/db/v1/users/doc.go
index 82abcb9..cf07832 100644
--- a/openstack/db/v1/users/doc.go
+++ b/openstack/db/v1/users/doc.go
@@ -1 +1,3 @@
+// Package users provides information and interaction with the user API
+// resource in the OpenStack Database service.
package users
diff --git a/openstack/db/v1/users/requests.go b/openstack/db/v1/users/requests.go
index e596739..e0616db 100644
--- a/openstack/db/v1/users/requests.go
+++ b/openstack/db/v1/users/requests.go
@@ -1,11 +1,14 @@
package users
import (
+ "errors"
+
"github.com/rackspace/gophercloud"
db "github.com/rackspace/gophercloud/openstack/db/v1/databases"
"github.com/rackspace/gophercloud/pagination"
)
+// CreateOptsBuilder is the top-level interface for creating JSON maps.
type CreateOptsBuilder interface {
ToUserCreateMap() (map[string]interface{}, error)
}
@@ -13,31 +16,46 @@
// CreateOpts is the struct responsible for configuring a new user; often in the
// context of an instance.
type CreateOpts struct {
- // Specifies a name for the user.
+ // [REQUIRED] Specifies a name for the user. Valid names can be composed
+ // of the following characters: letters (either case); numbers; these
+ // characters '@', '?', '#', ' ' but NEVER beginning a name string; '_' is
+ // permitted anywhere. Prohibited characters that are forbidden include:
+ // single quotes, double quotes, back quotes, semicolons, commas, backslashes,
+ // and forward slashes. Spaces at the front or end of a user name are also
+ // not permitted.
Name string
- // Specifies a password for the user.
+ // [REQUIRED] Specifies a password for the user.
Password string
- // An array of databases that this user will connect to. The `name` field is
- // the only requirement for each option.
+ // [OPTIONAL] An array of databases that this user will connect to. The
+ // "name" field is the only requirement for each option.
Databases db.BatchCreateOpts
- // Specifies the host from which a user is allowed to connect to the database.
- // Possible values are a string containing an IPv4 address or "%" to allow
- // connecting from any host. Optional; the default is "%".
+ // [OPTIONAL] Specifies the host from which a user is allowed to connect to
+ // the database. Possible values are a string containing an IPv4 address or
+ // "%" to allow connecting from any host. Optional; the default is "%".
Host string
}
+// ToMap is a convenience function for creating sub-maps for individual users.
func (opts CreateOpts) ToMap() (map[string]interface{}, error) {
- user := map[string]interface{}{}
- if opts.Name != "" {
- user["name"] = opts.Name
+ if opts.Name == "root" {
+ return nil, errors.New("root is a reserved user name and cannot be used")
}
- if opts.Password != "" {
- user["password"] = opts.Password
+ if opts.Name == "" {
+ return nil, errors.New("Name is a required field")
}
+ if opts.Password == "" {
+ return nil, errors.New("Password is a required field")
+ }
+
+ user := map[string]interface{}{
+ "name": opts.Name,
+ "password": opts.Password,
+ }
+
if opts.Host != "" {
user["host"] = opts.Host
}
@@ -53,8 +71,10 @@
return user, nil
}
+// BatchCreateOpts allows multiple users to be created at once.
type BatchCreateOpts []CreateOpts
+// ToUserCreateMap will generate a JSON map.
func (opts BatchCreateOpts) ToUserCreateMap() (map[string]interface{}, error) {
var users []map[string]interface{}
for _, opt := range opts {
@@ -67,6 +87,10 @@
return map[string]interface{}{"users": users}, nil
}
+// Create asynchronously provisions a new user for the specified database
+// instance based on the configuration defined in CreateOpts. If databases are
+// assigned for a particular user, the user will be granted all privileges
+// for those specified databases. "root" is a reserved name and cannot be used.
func Create(client *gophercloud.ServiceClient, instanceID string, opts CreateOptsBuilder) CreateResult {
var res CreateResult
@@ -84,6 +108,9 @@
return res
}
+// List will list all the users associated with a specified database instance,
+// along with their associated databases. This operation will not return any
+// system users or administrators for a database.
func List(client *gophercloud.ServiceClient, instanceID string) pagination.Pager {
createPageFn := func(r pagination.PageResult) pagination.Page {
return UserPage{pagination.LinkedPageBase{PageResult: r}}
@@ -92,6 +119,7 @@
return pagination.NewPager(client, baseURL(client, instanceID), createPageFn)
}
+// Delete will permanently delete a user from a specified database instance.
func Delete(client *gophercloud.ServiceClient, instanceID, userName string) DeleteResult {
var res DeleteResult
diff --git a/openstack/db/v1/users/results.go b/openstack/db/v1/users/results.go
index ce07e76..217ddd8 100644
--- a/openstack/db/v1/users/results.go
+++ b/openstack/db/v1/users/results.go
@@ -19,10 +19,16 @@
Databases []db.Database
}
+// CreateResult represents the result of a create operation.
type CreateResult struct {
gophercloud.ErrResult
}
+// DeleteResult represents the result of a delete operation.
+type DeleteResult struct {
+ gophercloud.ErrResult
+}
+
// UserPage represents a single page of a paginated user collection.
type UserPage struct {
pagination.LinkedPageBase
@@ -65,7 +71,3 @@
return response.Users, err
}
-
-type DeleteResult struct {
- gophercloud.ErrResult
-}